Refine the language of statements and iterators

README.md

@@ -42,19 +42,19 @@ let mut statement = connection.prepare("
 
 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());
 }
@@ -75,11 +75,11 @@ let mut iterator = connection.prepare("
     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/iterator.rs

@@ -9,30 +9,24 @@ pub struct Iterator<'l> {
 }
 
 impl<'l> Iterator<'l> {
-    /// Bind parameters and start iterating over the resulting rows.
+    /// Bind values to all parameters.
-    ///
+    pub fn bind(&mut self, values: &[Value]) -> Result<()> {
-    /// 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<()> {
         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.next()));
-                self.state = Some(try!(self.statement.step()));
                 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)

tests/lib.rs

@@ -59,7 +59,7 @@ fn connection_set_busy_handler() {
             ok!(statement.bind(2, "Bob"));
             ok!(statement.bind(3, 69.42));
             ok!(statement.bind(4, &[0x69u8, 0x42u8][..]));
-            assert_eq!(ok!(statement.step()), State::Done);
+            assert_eq!(ok!(statement.next()), State::Done);
             true
         })
     }).collect::<Vec<_>>();
@@ -75,12 +75,12 @@ fn iterator() {
     let statement = "SELECT id, name FROM users WHERE id = ?";
     let mut iterator = ok!(connection.prepare(statement)).into_iter().unwrap();
 
-    ok!(iterator.start(&[Value::Integer(1)]));
+    ok!(iterator.bind(&[Value::Integer(1)]));
     assert_eq!(ok!(ok!(iterator.next())), &[Value::Integer(1),
                                             Value::String("Alice".to_string())]);
     assert_eq!(ok!(iterator.next()), None);
 
-    ok!(iterator.start(&[Value::Integer(42)]));
+    ok!(iterator.bind(&[Value::Integer(42)]));
     assert_eq!(ok!(iterator.next()), None);
 }
 
@@ -92,7 +92,7 @@ fn statement_columns() {
 
     assert_eq!(statement.columns(), 4);
 
-    assert_eq!(ok!(statement.step()), State::Row);
+    assert_eq!(ok!(statement.next()), State::Row);
 
     assert_eq!(statement.columns(), 4);
 }
@@ -108,7 +108,7 @@ fn statement_kind() {
     assert_eq!(statement.kind(2), Type::Null);
     assert_eq!(statement.kind(3), Type::Null);
 
-    assert_eq!(ok!(statement.step()), State::Row);
+    assert_eq!(ok!(statement.next()), State::Row);
 
     assert_eq!(statement.kind(0), Type::Integer);
     assert_eq!(statement.kind(1), Type::String);
@@ -126,7 +126,7 @@ fn statement_bind() {
     ok!(statement.bind(2, "Bob"));
     ok!(statement.bind(3, 69.42));
     ok!(statement.bind(4, &[0x69u8, 0x42u8][..]));
-    assert_eq!(ok!(statement.step()), State::Done);
+    assert_eq!(ok!(statement.next()), State::Done);
 }
 
 #[test]
@@ -135,12 +135,12 @@ fn statement_read() {
     let statement = "SELECT * FROM users";
     let mut statement = ok!(connection.prepare(statement));
 
-    assert_eq!(ok!(statement.step()), State::Row);
+    assert_eq!(ok!(statement.next()), State::Row);
     assert_eq!(ok!(statement.read::<i64>(0)), 1);
     assert_eq!(ok!(statement.read::<String>(1)), String::from("Alice"));
     assert_eq!(ok!(statement.read::<f64>(2)), 42.69);
     assert_eq!(ok!(statement.read::<Vec<u8>>(3)), vec![0x42, 0x69]);
-    assert_eq!(ok!(statement.step()), State::Done);
+    assert_eq!(ok!(statement.next()), State::Done);
 }
 
 fn setup<T: AsRef<Path>>(path: T) -> Connection {