Struct ValueRef

pub struct ValueRef { /* private fields */ }

A protected SQL value.

SQLite always owns all value objects. Consequently, this struct is never owned by Rust code, but instead always borrowed. A “protected” value means that SQLite holds a mutex for the lifetime of the reference.

SQLite automatically converts data to any requested type where possible. This conversion is typically done in-place, which is why many of the conversion methods of this type require &mut.

Implementations

impl ValueRef

pub unsafe fn as_ptr(&self) -> *mut sqlite3_value

Get the underlying SQLite handle.

Safety

Invoking SQLite methods on the returned value may invalidate existing references previously returned by this object. This is safe as long as a mutable reference to this ValueRef is held.

pub fn numeric_type(&mut self) -> ValueType

Attempt to convert the ValueRef to a numeric data type, and return the resulting data type. This conversion will only happen if it is losles, otherwise the underlying value will remain its original type.

pub fn is_from_bind(&self) -> bool

Returns true if this ValueRef originated from one of the sqlite3_bind interfaces. If it comes from an SQL literal value, or a table column, or an expression, then this method returns false.

Requires SQLite 3.28.0. On earlier versions, this method always returns false.

pub fn nochange(&self) -> bool

Return true if the value is unchanged by an UPDATE operation. Specifically, this method is guaranteed to return true if all of the following are true:

• this ValueRef is a parameter to an UpdateVTab method;
• during the corresponding call to VTabCursor::column, ColumnContext::nochange returned true; and
• the column method failed with Error::NoChange.

If this method returns true under these circumstances, then the value will appear to be SQL NULL, and the UpdateVTab method must not change the underlying value.

Requires SQLite 3.22.0. On earlier versions of SQLite, this function will always return false.

pub fn get_ref<T: 'static>(&self) -> Option<&T>

Get the PassedRef stored in this value.

This is a safe way of passing arbitrary Rust objects through SQLite, however it requires SQLite 3.20.0 to work. On older versions of SQLite, this function will always return None.

Requires SQLite 3.20.0. On earlier versions of SQLite, this function will always return None.

Trait Implementations

impl AsMut<ValueRef> for Column

fn as_mut(&mut self) -> &mut ValueRef

Converts this type into a mutable reference of the (usually inferred) input type.

impl AsRef<ValueRef> for Column

fn as_ref(&self) -> &ValueRef

Converts this type into a shared reference of the (usually inferred) input type.

impl Debug for ValueRef

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl FromValue for ValueRef

fn value_type(&self) -> ValueType

Returns the data type of the ValueRef. Note that calling get methods on the ValueRef may cause a conversion to a different data type, but this is not guaranteed.

fn get_i32(&self) -> i32

Interpret this value as i32.

fn get_i64(&self) -> i64

Interpret this value as i64.

fn get_f64(&self) -> f64

Interpret this value as f64.

unsafe fn get_blob_unchecked(&self) -> &[u8]

Get the bytes of this BLOB value.

fn get_blob(&mut self) -> Result<&[u8]>

Interpret this value as a BLOB.

fn is_null(&self) -> bool

Convenience method equivalent to self.value_type() == ValueType::Null.

fn try_get_blob(&self) -> Result<&[u8]>

Attempt to interpret this value as a BLOB, without converting. If the underlying data type is not a BLOB, this function will fail with Err(SQLITE_MISMATCH).

unsafe fn get_str_unchecked(&self) -> Result<&str>

Get the underlying TEXT value.

fn get_str(&mut self) -> Result<&str>

Interpret the value as TEXT.

fn try_get_str(&self) -> Result<&str>

Attempt to interpret this value as TEXT, without converting. If the underlying data type is not TEXT, this function will fail with Err(SQLITE_MISMATCH). This function can also fail if the string has invalid UTF-8.

fn to_owned(&self) -> Result<Value>

Clone the value, returning a Value.

impl PartialEq for ValueRef

fn eq(&self, other: &Self) -> bool

Compare the underlying values of two ValueRefs. This function follows SQL equality semantics, meaning that NULL != NULL.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<'a> ToParam for &'a ValueRef

fn bind_param(self, stmt: &mut Statement, pos: i32) -> Result<()>

Bind this value to the prepared Statement at the provided position.

impl ToParam for &mut ValueRef

fn bind_param(self, stmt: &mut Statement, pos: i32) -> Result<()>

Bind this value to the prepared Statement at the provided position.

impl<'a> ToContextResult for &'a ValueRef

Sets the context result to the contained value.

impl<'a> ToContextResult for &'a mut ValueRef

Sets the context result to the contained value.