rusqlite/types/
value_ref.rs

1use super::{Type, Value};
2use crate::types::{FromSqlError, FromSqlResult};
3
4/// A non-owning [dynamic type value](http://sqlite.org/datatype3.html). Typically, the
5/// memory backing this value is owned by SQLite.
6///
7/// See [`Value`](Value) for an owning dynamic type value.
8#[derive(Copy, Clone, Debug, PartialEq)]
9pub enum ValueRef<'a> {
10    /// The value is a `NULL` value.
11    Null,
12    /// The value is a signed integer.
13    Integer(i64),
14    /// The value is a floating point number.
15    Real(f64),
16    /// The value is a text string.
17    Text(&'a [u8]),
18    /// The value is a blob of data
19    Blob(&'a [u8]),
20}
21
22impl ValueRef<'_> {
23    /// Returns SQLite fundamental datatype.
24    #[inline]
25    #[must_use]
26    pub fn data_type(&self) -> Type {
27        match *self {
28            ValueRef::Null => Type::Null,
29            ValueRef::Integer(_) => Type::Integer,
30            ValueRef::Real(_) => Type::Real,
31            ValueRef::Text(_) => Type::Text,
32            ValueRef::Blob(_) => Type::Blob,
33        }
34    }
35}
36
37impl<'a> ValueRef<'a> {
38    /// If `self` is case `Integer`, returns the integral value. Otherwise,
39    /// returns [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
40    #[inline]
41    pub fn as_i64(&self) -> FromSqlResult<i64> {
42        match *self {
43            ValueRef::Integer(i) => Ok(i),
44            _ => Err(FromSqlError::InvalidType),
45        }
46    }
47
48    /// If `self` is case `Null` returns None.
49    /// If `self` is case `Integer`, returns the integral value.
50    /// Otherwise, returns [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
51    #[inline]
52    pub fn as_i64_or_null(&self) -> FromSqlResult<Option<i64>> {
53        match *self {
54            ValueRef::Null => Ok(None),
55            ValueRef::Integer(i) => Ok(Some(i)),
56            _ => Err(FromSqlError::InvalidType),
57        }
58    }
59
60    /// If `self` is case `Real`, returns the floating point value. Otherwise,
61    /// returns [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
62    #[inline]
63    pub fn as_f64(&self) -> FromSqlResult<f64> {
64        match *self {
65            ValueRef::Real(f) => Ok(f),
66            _ => Err(FromSqlError::InvalidType),
67        }
68    }
69
70    /// If `self` is case `Null` returns None.
71    /// If `self` is case `Real`, returns the floating point value.
72    /// Otherwise, returns [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
73    #[inline]
74    pub fn as_f64_or_null(&self) -> FromSqlResult<Option<f64>> {
75        match *self {
76            ValueRef::Null => Ok(None),
77            ValueRef::Real(f) => Ok(Some(f)),
78            _ => Err(FromSqlError::InvalidType),
79        }
80    }
81
82    /// If `self` is case `Text`, returns the string value. Otherwise, returns
83    /// [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
84    #[inline]
85    pub fn as_str(&self) -> FromSqlResult<&'a str> {
86        match *self {
87            ValueRef::Text(t) => std::str::from_utf8(t).map_err(FromSqlError::other),
88            _ => Err(FromSqlError::InvalidType),
89        }
90    }
91
92    /// If `self` is case `Null` returns None.
93    /// If `self` is case `Text`, returns the string value.
94    /// Otherwise, returns [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
95    #[inline]
96    pub fn as_str_or_null(&self) -> FromSqlResult<Option<&'a str>> {
97        match *self {
98            ValueRef::Null => Ok(None),
99            ValueRef::Text(t) => std::str::from_utf8(t)
100                .map_err(FromSqlError::other)
101                .map(Some),
102            _ => Err(FromSqlError::InvalidType),
103        }
104    }
105
106    /// If `self` is case `Blob`, returns the byte slice. Otherwise, returns
107    /// [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
108    #[inline]
109    pub fn as_blob(&self) -> FromSqlResult<&'a [u8]> {
110        match *self {
111            ValueRef::Blob(b) => Ok(b),
112            _ => Err(FromSqlError::InvalidType),
113        }
114    }
115
116    /// If `self` is case `Null` returns None.
117    /// If `self` is case `Blob`, returns the byte slice.
118    /// Otherwise, returns [`Err(FromSqlError::InvalidType)`](crate::types::from_sql::FromSqlError::InvalidType).
119    #[inline]
120    pub fn as_blob_or_null(&self) -> FromSqlResult<Option<&'a [u8]>> {
121        match *self {
122            ValueRef::Null => Ok(None),
123            ValueRef::Blob(b) => Ok(Some(b)),
124            _ => Err(FromSqlError::InvalidType),
125        }
126    }
127
128    /// Returns the byte slice that makes up this `ValueRef` if it's either
129    /// [`ValueRef::Blob`] or [`ValueRef::Text`].
130    #[inline]
131    pub fn as_bytes(&self) -> FromSqlResult<&'a [u8]> {
132        match self {
133            ValueRef::Text(s) | ValueRef::Blob(s) => Ok(s),
134            _ => Err(FromSqlError::InvalidType),
135        }
136    }
137
138    /// If `self` is case `Null` returns None.
139    /// If `self` is [`ValueRef::Blob`] or [`ValueRef::Text`] returns the byte
140    /// slice that makes up this value
141    #[inline]
142    pub fn as_bytes_or_null(&self) -> FromSqlResult<Option<&'a [u8]>> {
143        match *self {
144            ValueRef::Null => Ok(None),
145            ValueRef::Text(s) | ValueRef::Blob(s) => Ok(Some(s)),
146            _ => Err(FromSqlError::InvalidType),
147        }
148    }
149}
150
151impl From<ValueRef<'_>> for Value {
152    #[inline]
153    #[track_caller]
154    fn from(borrowed: ValueRef<'_>) -> Self {
155        match borrowed {
156            ValueRef::Null => Self::Null,
157            ValueRef::Integer(i) => Self::Integer(i),
158            ValueRef::Real(r) => Self::Real(r),
159            ValueRef::Text(s) => {
160                let s = std::str::from_utf8(s).expect("invalid UTF-8");
161                Self::Text(s.to_string())
162            }
163            ValueRef::Blob(b) => Self::Blob(b.to_vec()),
164        }
165    }
166}
167
168impl<'a> From<&'a str> for ValueRef<'a> {
169    #[inline]
170    fn from(s: &str) -> ValueRef<'_> {
171        ValueRef::Text(s.as_bytes())
172    }
173}
174
175impl<'a> From<&'a [u8]> for ValueRef<'a> {
176    #[inline]
177    fn from(s: &[u8]) -> ValueRef<'_> {
178        ValueRef::Blob(s)
179    }
180}
181
182impl<'a> From<&'a Value> for ValueRef<'a> {
183    #[inline]
184    fn from(value: &'a Value) -> Self {
185        match *value {
186            Value::Null => ValueRef::Null,
187            Value::Integer(i) => ValueRef::Integer(i),
188            Value::Real(r) => ValueRef::Real(r),
189            Value::Text(ref s) => ValueRef::Text(s.as_bytes()),
190            Value::Blob(ref b) => ValueRef::Blob(b),
191        }
192    }
193}
194
195impl<T> From<Option<T>> for ValueRef<'_>
196where
197    T: Into<Self>,
198{
199    #[inline]
200    fn from(s: Option<T>) -> Self {
201        match s {
202            Some(x) => x.into(),
203            None => ValueRef::Null,
204        }
205    }
206}
207
208#[cfg(any(
209    feature = "functions",
210    feature = "session",
211    feature = "vtab",
212    feature = "preupdate_hook"
213))]
214impl ValueRef<'_> {
215    pub(crate) unsafe fn from_value(value: *mut crate::ffi::sqlite3_value) -> Self {
216        use crate::ffi;
217        use std::slice::from_raw_parts;
218
219        match ffi::sqlite3_value_type(value) {
220            ffi::SQLITE_NULL => ValueRef::Null,
221            ffi::SQLITE_INTEGER => ValueRef::Integer(ffi::sqlite3_value_int64(value)),
222            ffi::SQLITE_FLOAT => ValueRef::Real(ffi::sqlite3_value_double(value)),
223            ffi::SQLITE_TEXT => {
224                let text = ffi::sqlite3_value_text(value);
225                let len = ffi::sqlite3_value_bytes(value);
226                assert!(
227                    !text.is_null(),
228                    "unexpected SQLITE_TEXT value type with NULL data"
229                );
230                let s = from_raw_parts(text.cast::<u8>(), len as usize);
231                ValueRef::Text(s)
232            }
233            ffi::SQLITE_BLOB => {
234                let (blob, len) = (
235                    ffi::sqlite3_value_blob(value),
236                    ffi::sqlite3_value_bytes(value),
237                );
238
239                assert!(
240                    len >= 0,
241                    "unexpected negative return from sqlite3_value_bytes"
242                );
243                if len > 0 {
244                    assert!(
245                        !blob.is_null(),
246                        "unexpected SQLITE_BLOB value type with NULL data"
247                    );
248                    ValueRef::Blob(from_raw_parts(blob.cast::<u8>(), len as usize))
249                } else {
250                    // The return value from sqlite3_value_blob() for a zero-length BLOB
251                    // is a NULL pointer.
252                    ValueRef::Blob(&[])
253                }
254            }
255            _ => unreachable!("sqlite3_value_type returned invalid value"),
256        }
257    }
258
259    // TODO sqlite3_value_nochange // 3.22.0 & VTab xUpdate
260    // TODO sqlite3_value_frombind // 3.28.0
261}
262
263#[cfg(test)]
264mod test {
265    use super::ValueRef;
266    use crate::types::FromSqlResult;
267
268    #[test]
269    fn as_i64() -> FromSqlResult<()> {
270        assert!(ValueRef::Real(1.0).as_i64().is_err());
271        assert_eq!(ValueRef::Integer(1).as_i64(), Ok(1));
272        Ok(())
273    }
274    #[test]
275    fn as_i64_or_null() -> FromSqlResult<()> {
276        assert_eq!(ValueRef::Null.as_i64_or_null(), Ok(None));
277        assert!(ValueRef::Real(1.0).as_i64_or_null().is_err());
278        assert_eq!(ValueRef::Integer(1).as_i64_or_null(), Ok(Some(1)));
279        Ok(())
280    }
281    #[test]
282    fn as_f64() -> FromSqlResult<()> {
283        assert!(ValueRef::Integer(1).as_f64().is_err());
284        assert_eq!(ValueRef::Real(1.0).as_f64(), Ok(1.0));
285        Ok(())
286    }
287    #[test]
288    fn as_f64_or_null() -> FromSqlResult<()> {
289        assert_eq!(ValueRef::Null.as_f64_or_null(), Ok(None));
290        assert!(ValueRef::Integer(1).as_f64_or_null().is_err());
291        assert_eq!(ValueRef::Real(1.0).as_f64_or_null(), Ok(Some(1.0)));
292        Ok(())
293    }
294    #[test]
295    fn as_str() -> FromSqlResult<()> {
296        assert!(ValueRef::Null.as_str().is_err());
297        assert_eq!(ValueRef::Text(b"").as_str(), Ok(""));
298        Ok(())
299    }
300    #[test]
301    fn as_str_or_null() -> FromSqlResult<()> {
302        assert_eq!(ValueRef::Null.as_str_or_null(), Ok(None));
303        assert!(ValueRef::Integer(1).as_str_or_null().is_err());
304        assert_eq!(ValueRef::Text(b"").as_str_or_null(), Ok(Some("")));
305        Ok(())
306    }
307    #[test]
308    fn as_blob() -> FromSqlResult<()> {
309        assert!(ValueRef::Null.as_blob().is_err());
310        assert_eq!(ValueRef::Blob(b"").as_blob(), Ok(&b""[..]));
311        Ok(())
312    }
313    #[test]
314    fn as_blob_or_null() -> FromSqlResult<()> {
315        assert_eq!(ValueRef::Null.as_blob_or_null(), Ok(None));
316        assert!(ValueRef::Integer(1).as_blob_or_null().is_err());
317        assert_eq!(ValueRef::Blob(b"").as_blob_or_null(), Ok(Some(&b""[..])));
318        Ok(())
319    }
320    #[test]
321    fn as_bytes() -> FromSqlResult<()> {
322        assert!(ValueRef::Null.as_bytes().is_err());
323        assert_eq!(ValueRef::Blob(b"").as_bytes(), Ok(&b""[..]));
324        Ok(())
325    }
326    #[test]
327    fn as_bytes_or_null() -> FromSqlResult<()> {
328        assert_eq!(ValueRef::Null.as_bytes_or_null(), Ok(None));
329        assert!(ValueRef::Integer(1).as_bytes_or_null().is_err());
330        assert_eq!(ValueRef::Blob(b"").as_bytes_or_null(), Ok(Some(&b""[..])));
331        Ok(())
332    }
333    #[test]
334    fn from_value() {
335        use crate::types::Value;
336        assert_eq!(
337            ValueRef::from(&Value::Text("".to_owned())),
338            ValueRef::Text(b"")
339        );
340        assert_eq!(ValueRef::from(&Value::Blob(vec![])), ValueRef::Blob(b""));
341    }
342    #[test]
343    fn from_option() {
344        assert_eq!(ValueRef::from(None as Option<&str>), ValueRef::Null);
345        assert_eq!(ValueRef::from(Some("")), ValueRef::Text(b""));
346    }
347}
rusqlite/types/value_ref.rs

rusqlite/types/
value_ref.rs
