From 8cb5b2e58599ccf3e33c254b61f66b2dcbd81ae5 Mon Sep 17 00:00:00 2001
From: gwenn <gtreguier@gmail.com>
Date: Sun, 24 May 2020 20:42:54 +0200
Subject: [PATCH] Document Rows::map and FallibleStreamingIterator impl

See
https://www.reddit.com/r/rust/comments/gov817/rusqlite_only_getting_ok_entries_from_query_map/
```
let mut stmt = self
    .db
    .prepare("SELECT tag FROM tags WHERE tags.entry_id = ?1")?;

let tags = stmt.query(params![id])?;

tags
    .map(|res| res.get(0))
    .collect()
```
---
 src/row.rs | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/src/row.rs b/src/row.rs
index 1f8b1be..d880efd 100644
--- a/src/row.rs
+++ b/src/row.rs
@@ -37,6 +37,15 @@ impl<'stmt> Rows<'stmt> {
 
     /// Map over this `Rows`, converting it to a [`Map`], which
     /// implements `FallibleIterator`.
+    /// ```rust,no_run
+    /// use fallible_iterator::FallibleIterator;
+    /// # use rusqlite::{Result, Statement, NO_PARAMS};
+    /// fn query(stmt: &mut Statement) -> Result<Vec<i64>> {
+    ///     let rows = stmt.query(NO_PARAMS)?;
+    ///     rows.map(|r| r.get(0)).collect()
+    /// }
+    /// ```
+    // FIXME Hide FallibleStreamingIterator::map
     pub fn map<F, B>(self, f: F) -> Map<'stmt, F>
     where
         F: FnMut(&Row<'_>) -> Result<B>,
@@ -168,6 +177,24 @@ where
     }
 }
 
+/// `FallibleStreamingIterator` differs from the standard library's `Iterator`
+/// in two ways:
+/// * each call to `next` (sqlite3_step) can fail.
+/// * returned `Row` is valid until `next` is called again or `Statement` is
+///   reset or finalized.
+///
+/// While these iterators cannot be used with Rust `for` loops, `while let`
+/// loops offer a similar level of ergonomics:
+/// ```rust,no_run
+/// # use rusqlite::{Result, Statement, NO_PARAMS};
+/// fn query(stmt: &mut Statement) -> Result<()> {
+///     let mut rows = stmt.query(NO_PARAMS)?;
+///     while let Some(row) = rows.next()? {
+///         // scan columns value
+///     }
+///     Ok(())
+/// }
+/// ```
 impl<'stmt> FallibleStreamingIterator for Rows<'stmt> {
     type Error = Error;
     type Item = Row<'stmt>;