diff --git a/Changelog.md b/Changelog.md index e76d415..85e04df 100644 --- a/Changelog.md +++ b/Changelog.md @@ -6,6 +6,7 @@ * `SqliteResult` is now `Result` * `SqliteStatement` is now `Statement` * `SqliteRows` is now `Rows` + * `SqliteRow` is now `Row` The old, prefixed names are still exported should be considered deprecated. * Adds a variety of `..._named` methods for executing queries using named placeholder parameters. * Adds `backup` feature that exposes SQLite's online backup API. diff --git a/README.md b/README.md index 05c8d98..9d78640 100644 --- a/README.md +++ b/README.md @@ -56,7 +56,7 @@ fn main() { } ``` -### Design of SqliteRows and SqliteRow +### Design of Rows and Row To retrieve the result rows from a query, SQLite requires you to call [sqlite3_step()](https://www.sqlite.org/c3ref/step.html) on a prepared statement. You can only @@ -67,7 +67,7 @@ satisfy the [Iterator](http://doc.rust-lang.org/std/iter/trait.Iterator.html) tr you cannot (as easily) loop over the rows, or use many of the helpful Iterator methods like `map` and `filter`. -Instead, Rusqlite's `SqliteRows` handle does conform to `Iterator`. It ensures safety by +Instead, Rusqlite's `Rows` handle does conform to `Iterator`. It ensures safety by performing checks at runtime to ensure you do not try to retrieve the values of a "stale" row, and will panic if you do so. A specific example that will panic: @@ -88,7 +88,7 @@ fn bad_function_will_panic(conn: &Connection) -> Result { ``` There are other, less obvious things that may result in a panic as well, such as calling -`collect()` on a `SqliteRows` and then trying to use the collected rows. +`collect()` on a `Rows` and then trying to use the collected rows. Strongly consider using the method `query_map()` instead, if you can. `query_map()` returns an iterator over rows-mapped-to-some-type. This diff --git a/src/lib.rs b/src/lib.rs index a639fce..2e7d78b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -379,7 +379,7 @@ impl Connection { /// Will return `Err` if `sql` cannot be converted to a C-compatible string or if the /// underlying SQLite call fails. pub fn query_row(&self, sql: &str, params: &[&ToSql], f: F) -> Result - where F: FnOnce(SqliteRow) -> T + where F: FnOnce(Row) -> T { let mut stmt = try!(self.prepare(sql)); let mut rows = try!(stmt.query(params)); @@ -409,7 +409,7 @@ impl Connection { /// Will return `Err` if `sql` cannot be converted to a C-compatible string or if the /// underlying SQLite call fails. pub fn query_row_and_then(&self, sql: &str, params: &[&ToSql], f: F) -> result::Result - where F: FnOnce(SqliteRow) -> result::Result, + where F: FnOnce(Row) -> result::Result, E: convert::From { let mut stmt = try!(self.prepare(sql)); @@ -438,7 +438,7 @@ impl Connection { /// This method should be considered deprecated. Use `query_row` instead, which now /// does exactly the same thing. pub fn query_row_safe(&self, sql: &str, params: &[&ToSql], f: F) -> Result - where F: FnOnce(SqliteRow) -> T + where F: FnOnce(Row) -> T { self.query_row(sql, params, f) } @@ -865,7 +865,7 @@ impl<'conn> Statement<'conn> { params: &[&ToSql], f: F) -> Result> - where F: FnMut(&SqliteRow) -> T + where F: FnMut(&Row) -> T { let row_iter = try!(self.query(params)); @@ -890,7 +890,7 @@ impl<'conn> Statement<'conn> { f: F) -> Result> where E: convert::From, - F: FnMut(&SqliteRow) -> result::Result + F: FnMut(&Row) -> result::Result { let row_iter = try!(self.query(params)); @@ -968,7 +968,7 @@ pub struct MappedRows<'stmt, F> { map: F, } -impl<'stmt, T, F> Iterator for MappedRows<'stmt, F> where F: FnMut(&SqliteRow) -> T +impl<'stmt, T, F> Iterator for MappedRows<'stmt, F> where F: FnMut(&Row) -> T { type Item = Result; @@ -986,7 +986,7 @@ pub struct AndThenRows<'stmt, F> { impl<'stmt, T, E, F> Iterator for AndThenRows<'stmt, F> where E: convert::From, - F: FnMut(&SqliteRow) -> result::Result + F: FnMut(&Row) -> result::Result { type Item = result::Result; @@ -1051,7 +1051,7 @@ impl<'stmt> Rows<'stmt> { } } - fn get_expected_row(&mut self) -> Result> { + fn get_expected_row(&mut self) -> Result> { match self.next() { Some(row) => row, None => { @@ -1065,9 +1065,9 @@ impl<'stmt> Rows<'stmt> { } impl<'stmt> Iterator for Rows<'stmt> { - type Item = Result>; + type Item = Result>; - fn next(&mut self) -> Option>> { + fn next(&mut self) -> Option>> { if self.failed { return None; } @@ -1075,7 +1075,7 @@ impl<'stmt> Iterator for Rows<'stmt> { ffi::SQLITE_ROW => { let current_row = self.current_row.get() + 1; self.current_row.set(current_row); - Some(Ok(SqliteRow { + Some(Ok(Row { stmt: self.stmt, current_row: self.current_row.clone(), row_idx: current_row, @@ -1090,17 +1090,20 @@ impl<'stmt> Iterator for Rows<'stmt> { } } +/// Old name for `Row`. `SqliteRow` is deprecated. +pub type SqliteRow<'stmt> = Row<'stmt>; + /// A single result row of a query. -pub struct SqliteRow<'stmt> { +pub struct Row<'stmt> { stmt: &'stmt Statement<'stmt>, current_row: Rc>, row_idx: c_int, } -impl<'stmt> SqliteRow<'stmt> { +impl<'stmt> Row<'stmt> { /// Get the value of a particular column of the result row. /// - /// Note that `SqliteRow` can panic at runtime if you use it incorrectly. When you are + /// Note that `Row` can panic at runtime if you use it incorrectly. When you are /// retrieving the rows of a query, a row becomes stale once you have requested the next row, /// and the values can no longer be retrieved. In general (when using looping over the rows, /// for example) this isn't an issue, but it means you cannot do something like this: diff --git a/src/named_params.rs b/src/named_params.rs index dccb531..d1dcdc9 100644 --- a/src/named_params.rs +++ b/src/named_params.rs @@ -2,7 +2,7 @@ use libc::c_int; use super::ffi; -use {Result, Error, Connection, Statement, Rows, SqliteRow, str_to_cstring}; +use {Result, Error, Connection, Statement, Rows, Row, str_to_cstring}; use types::ToSql; impl Connection { @@ -42,7 +42,7 @@ impl Connection { params: &[(&str, &ToSql)], f: F) -> Result - where F: FnOnce(SqliteRow) -> T + where F: FnOnce(Row) -> T { let mut stmt = try!(self.prepare(sql)); let mut rows = try!(stmt.query_named(params));