Refine the language of statements and iterators

src/iterator.rs

@@ -9,30 +9,24 @@ pub struct Iterator<'l> {
 }
 
 impl<'l> Iterator<'l> {
-    /// Bind parameters and start iterating over the resulting rows.
-    ///
-    /// The function assigns values to the parameters of the underlaying
-    /// prepared statement, execute it, and start iterating over the resulting
-    /// rows.
-    pub fn start(&mut self, values: &[Value]) -> Result<()> {
+    /// Bind values to all parameters.
+    pub fn bind(&mut self, values: &[Value]) -> Result<()> {
         try!(self.statement.reset());
         for (i, value) in values.iter().enumerate() {
             try!(self.statement.bind(i + 1, value));
         }
-        self.state = Some(try!(self.statement.step()));
         Ok(())
     }
 
-    /// Read the next row.
+    /// Advance to the next row and read all columns.
     pub fn next(&mut self) -> Result<Option<&[Value]>> {
         match self.state {
+            Some(State::Row) => {},
             Some(State::Done) => return Ok(None),
-            None => {
-                try!(self.statement.reset());
-                self.state = Some(try!(self.statement.step()));
+            _ => {
+                self.state = Some(try!(self.statement.next()));
                 return self.next();
             },
-            _ => {},
         }
         let values = match self.values.take() {
             Some(mut values) => {
@@ -50,7 +44,7 @@ impl<'l> Iterator<'l> {
                 values
             },
         };
-        self.state = Some(try!(self.statement.step()));
+        self.state = Some(try!(self.statement.next()));
         self.values = Some(values);
         Ok(Some(self.values.as_ref().unwrap()))
     }

src/lib.rs

@@ -38,19 +38,19 @@
 //!
 //! statement.bind(1, "Alice").unwrap();
 //! statement.bind(2, 42).unwrap();
-//! assert_eq!(statement.step().unwrap(), State::Done);
+//! assert_eq!(statement.next().unwrap(), State::Done);
 //!
 //! statement.reset().unwrap();
 //!
 //! statement.bind(1, "Bob").unwrap();
 //! statement.bind(2, 69).unwrap();
-//! assert_eq!(statement.step().unwrap(), State::Done);
+//! assert_eq!(statement.next().unwrap(), State::Done);
 //!
 //! let mut statement = connection.prepare("
 //!     SELECT * FROM users WHERE age > 50
 //! ").unwrap();
 //!
-//! while let State::Row = statement.step().unwrap() {
+//! while let State::Row = statement.next().unwrap() {
 //!     println!("name = {}", statement.read::<String>(0).unwrap());
 //!     println!("age = {}", statement.read::<i64>(1).unwrap());
 //! }
@@ -71,11 +71,11 @@
 //!     INSERT INTO users (name, age) VALUES (?, ?)
 //! ").unwrap().into_iter().unwrap();
 //!
-//! iterator.start(&[
+//! iterator.bind(&[
 //!     Value::String("Alice".to_string()), Value::Integer(42),
 //! ]).unwrap();
 //!
-//! iterator.start(&[
+//! iterator.bind(&[
 //!     Value::String("Bob".to_string()), Value::Integer(69),
 //! ]).unwrap();
 //!

src/statement.rs

@@ -51,11 +51,11 @@ impl<'l> Statement<'l> {
         unsafe { ffi::sqlite3_column_count(self.raw.0) as usize }
     }
 
-    /// Advance the statement to the next state.
+    /// Advance to the next state.
     ///
     /// The function should be called multiple times until `State::Done` is
     /// reached in order to evaluate the statement entirely.
-    pub fn step(&mut self) -> Result<State> {
+    pub fn next(&mut self) -> Result<State> {
         let state = match unsafe { ffi::sqlite3_step(self.raw.0) } {
             ffi::SQLITE_ROW => State::Row,
             ffi::SQLITE_DONE => State::Done,
@@ -101,7 +101,7 @@ impl<'l> Statement<'l> {
         Ok(())
     }
 
-    /// Upgrade the statement to an iterator.
+    /// Upgrade to an iterator.
     #[inline]
     pub fn into_iter(self) -> Result<Iterator<'l>> {
         ::iterator::new(self)