diff --git a/src/types/borrowed_value.rs b/src/types/borrowed_value.rs index cbbb977..f8e5068 100644 --- a/src/types/borrowed_value.rs +++ b/src/types/borrowed_value.rs @@ -2,15 +2,27 @@ use ::Result; use ::error::Error; use super::Value; +/// A non-owning [dynamic type value](http://sqlite.org/datatype3.html). Typically the +/// memory backing this value is owned by SQLite. +/// +/// See [`Value`](enum.Value.html) for an owning dynamic type value. +#[derive(Copy,Clone,Debug,PartialEq)] pub enum BorrowedValue<'a> { + /// The value is a `NULL` value. Null, + /// The value is a signed integer. Integer(i64), + /// The value is a floating point number. Real(f64), + /// The value is a text string. Text(&'a str), + /// The value is a blob of data Blob(&'a [u8]), } impl<'a> BorrowedValue<'a> { + /// If `self` is case `Integer`, returns the integral value. Otherwise, returns + /// `Err(Error::InvalidColumnType)`. pub fn as_i64(&self) -> Result { match *self { BorrowedValue::Integer(i) => Ok(i), @@ -18,6 +30,8 @@ impl<'a> BorrowedValue<'a> { } } + /// If `self` is case `Real`, returns the floating point value. Otherwise, returns + /// `Err(Error::InvalidColumnType)`. pub fn as_f64(&self) -> Result { match *self { BorrowedValue::Real(f) => Ok(f), @@ -25,6 +39,8 @@ impl<'a> BorrowedValue<'a> { } } + /// If `self` is case `Text`, returns the string value. Otherwise, returns + /// `Err(Error::InvalidColumnType)`. pub fn as_str(&self) -> Result<&str> { match *self { BorrowedValue::Text(ref t) => Ok(t), @@ -32,6 +48,8 @@ impl<'a> BorrowedValue<'a> { } } + /// If `self` is case `Blob`, returns the byte slice. Otherwise, returns + /// `Err(Error::InvalidColumnType)`. pub fn as_blob(&self) -> Result<&[u8]> { match *self { BorrowedValue::Blob(ref b) => Ok(b), diff --git a/src/types/from_sql.rs b/src/types/from_sql.rs index c733f07..cddf287 100644 --- a/src/types/from_sql.rs +++ b/src/types/from_sql.rs @@ -1,6 +1,7 @@ use super::{BorrowedValue, Value}; use ::Result; +/// A trait for types that can be created from a SQLite value. pub trait FromSql: Sized { fn column_result(value: BorrowedValue) -> Result; } diff --git a/src/types/mod.rs b/src/types/mod.rs index f8c8fba..d00693e 100644 --- a/src/types/mod.rs +++ b/src/types/mod.rs @@ -4,7 +4,9 @@ //! the `ToSql` and `FromSql` traits are provided for the basic types that SQLite provides methods //! for: //! -//! * C integers and doubles (`c_int` and `c_double`) +//! * Integers (`i32` and `i64`; SQLite uses `i64` internally, so getting an `i32` will truncate +//! if the value is too large or too small). +//! * Reals (`f64`) //! * Strings (`String` and `&str`) //! * Blobs (`Vec` and `&[u8]`) //! @@ -15,12 +17,6 @@ //! truncates timespecs to the nearest second. If you want different storage for timespecs, you can //! use a newtype. For example, to store timespecs as doubles: //! -//! `ToSql` and `FromSql` are also implemented for `Option` where `T` implements `ToSql` or -//! `FromSql` for the cases where you want to know if a value was NULL (which gets translated to -//! `None`). If you get a value that was NULL in SQLite but you store it into a non-`Option` value -//! in Rust, you will get a "sensible" zero value - 0 for numeric types (including timespecs), an -//! empty string, or an empty vector of bytes. -//! //! ```rust,ignore //! extern crate rusqlite; //! extern crate libc; @@ -51,6 +47,10 @@ //! } //! } //! ``` +//! +//! `ToSql` and `FromSql` are also implemented for `Option` where `T` implements `ToSql` or +//! `FromSql` for the cases where you want to know if a value was NULL (which gets translated to +//! `None`). pub use ffi::sqlite3_stmt; pub use ffi::sqlite3_column_type; @@ -88,8 +88,10 @@ mod serde_json; #[derive(Copy,Clone)] pub struct Null; -/// Dynamic type value (http://sqlite.org/datatype3.html) -/// Value's type is dictated by SQLite (not by the caller). +/// Owning [dynamic type value](http://sqlite.org/datatype3.html). Value's type is typically +/// dictated by SQLite (not by the caller). +/// +/// See [`BorrowedValue`](enum.BorrowedValue.html) for a non-owning dynamic type value. #[derive(Clone,Debug,PartialEq)] pub enum Value { /// The value is a `NULL` value.