Struct VarCell

pub struct VarCell<B, K> { /* private fields */ }

Binds a byte array as Variadic sized character data. It can not be used for columnar bulk fetches, but if the buffer type is stack allocated it can be utilized in row wise bulk fetches.

Meaningful instantiations of this type are:

• self::VarCharSlice - immutable borrowed narrow character strings
• self::VarCharSliceMut - mutable borrowed input / output narrow character strings
• self::VarCharArray - stack allocated owned input / output narrow character strings
• self::VarCharBox - heap allocated owned input /output narrow character strings
• self::VarWCharSlice - immutable borrowed wide character string
• self::VarWCharSliceMut - mutable borrowed input / output wide character string
• self::VarWCharArray - stack allocated owned input / output wide character string
• self::VarWCharBox - heap allocated owned input /output wide character string
• self::VarBinarySlice - immutable borrowed parameter.
• self::VarBinarySliceMut - mutable borrowed input / output parameter
• self::VarBinaryArray - stack allocated owned input / output parameter
• self::VarBinaryBox - heap allocated owned input /output parameter

Implementations

impl<K> VarCell<Box<[K::Element]>, K>

where K: VarKind,

pub fn null() -> Self

Constructs a ‘missing’ value.

pub fn from_vec(val: Vec<K::Element>) -> Self

Create a VarChar box from a Vec.

impl<K> VarCell<Box<[u8]>, K>

where K: VarKind<Element = u8>,

pub fn from_string(val: String) -> Self

Create an owned parameter containing the character data from the passed string.

impl<K> VarCell<Box<[u16]>, K>

where K: VarKind<Element = u16>,

pub fn from_u16_string(val: U16String) -> Self

Create an owned parameter containing the character data from the passed string.

pub fn from_str_slice(val: &str) -> Self

Create an owned parameter containing the character data from the passed string. Converts it to UTF-16 and allocates it.

impl<B, K> VarCell<B, K>

where K: VarKind, B: Borrow<[K::Element]>,

pub fn from_buffer(buffer: B, indicator: Indicator) -> Self

Creates a new instance from an existing buffer. For text should the indicator be NoTotal or indicate a length longer than buffer, the last element in the buffer must be nul (\0).

pub fn is_complete(&self) -> bool

Call this method to ensure that the entire field content did fit into the buffer. If you retrieve a field using crate::CursorRow::get_data, you can repeat the call until this method is false to read all the data.

use odbc_api::{CursorRow, parameter::VarCharArray, Error, handles::Statement};

fn process_large_text(
    col_index: u16,
    row: &mut CursorRow<'_>
) -> Result<(), Error>{
    let mut buf = VarCharArray::<512>::NULL;
    row.get_data(col_index, &mut buf)?;
    while !buf.is_complete() {
        // Process bytes in stream without allocation. We can assume repeated calls to
        // get_data do not return `None` since it would have done so on the first call.
        process_text_slice(buf.as_bytes().unwrap());
    }
    Ok(())
}

fn process_text_slice(text: &[u8]) { /*...*/}

use odbc_api::{CursorRow, parameter::VarBinaryArray, Error, handles::Statement};

fn process_large_binary(
    col_index: u16,
    row: &mut CursorRow<'_>
) -> Result<(), Error>{
    let mut buf = VarBinaryArray::<512>::NULL;
    row.get_data(col_index, &mut buf)?;
    while !buf.is_complete() {
        // Process bytes in stream without allocation. We can assume repeated calls to
        // get_data do not return `None` since it would have done so on the first call.
        process_slice(buf.as_bytes().unwrap());
    }
    Ok(())
}

fn process_slice(text: &[u8]) { /*...*/}

pub fn indicator(&self) -> Indicator

Read access to the underlying ODBC indicator. After data has been fetched the indicator value is set to the length the buffer should have had to hold the entire value. It may also be Indicator::Null to indicate NULL or Indicator::NoTotal which tells us the data source does not know how big the buffer must be to hold the complete value. Indicator::NoTotal implies that the content of the current buffer is valid up to its maximum capacity.

pub fn hide_truncation(&mut self)

Call this method to reset the indicator to a value which matches the length returned by the Self::as_bytes method. This is useful if you want to insert values into the database despite the fact, that they might have been truncated. Otherwise the behaviour of databases in this situation is driver specific. Some drivers insert up to the terminating zero, others detect the truncation and throw an error.

pub fn len_in_bytes(&self) -> Option<usize>

Length of the (potentially truncated) value within the cell in bytes. Excluding terminating zero.

pub fn capacity_in_bytes(&self) -> usize

The payload in bytes the buffer can hold including terminating zeroes

impl<B, K> VarCell<B, K>

where B: Borrow<[K::Element]>, K: VarKind,

pub fn as_slice(&self) -> Option<&[K::Element]>

Valid payload of the buffer (excluding terminating zeroes) returned as slice or None in case the indicator is NULL_DATA.

impl<B, K> VarCell<B, K>

where B: Borrow<[u8]>, K: VarKind<Element = u8>,

pub fn as_bytes(&self) -> Option<&[u8]>

Valid payload of the buffer (excluding terminating zeroes) returned as slice or None in case the indicator is NULL_DATA.

impl<B> VarCell<B, Text>

where B: Borrow<[u8]>,

pub fn as_str(&self) -> Result<Option<&str>, Utf8Error>

impl<B> VarCell<B, WideText>

where B: Borrow<[u16]>,

pub fn as_utf16(&self) -> Option<&U16Str>

impl<'a, K> VarCell<&'a [u8], K>

pub const NULL: Self = _

Indicates missing data

impl<'a, K> VarCell<&'a [u16], K>

pub const NULL: Self = _

Indicates missing data

impl<'a, K> VarCell<&'a [K::Element], K>

where K: VarKind,

pub fn new(value: &'a [K::Element]) -> Self

Constructs a new VarChar containing the text in the specified buffer.

Caveat: This constructor is going to create a truncated value in case the input slice ends with nul. Should you want to insert an actual string those payload ends with nul into the database you need a buffer one byte longer than the string. You can instantiate such a value using Self::from_buffer.

impl<const LENGTH: usize, K: VarKind> VarCell<[K::Element; LENGTH], K>

pub const NULL: Self = _

Indicates a missing value.

pub fn new(elements: &[K::Element]) -> Self

Construct from a slice. If value is longer than LENGTH it will be truncated. In that case the last byte will be set to 0.

Trait Implementations

impl<B, K> CData for VarCell<B, K>

where B: Borrow<[K::Element]>, K: VarKind,

fn cdata_type(&self) -> CDataType

The identifier of the C data type of the value buffer. When it is retrieving data from the data source with fetch, the driver converts the data to this type. When it sends data to the source, the driver converts the data from this type.

fn indicator_ptr(&self) -> *const isize

Indicates the length of variable sized types. May be zero for fixed sized types. Used to determine the size or existence of input parameters.

fn value_ptr(&self) -> *const c_void

Pointer to a value corresponding to the one described by cdata_type.

fn buffer_length(&self) -> isize

Maximum length of the type in bytes (not characters). It is required to index values in bound buffers, if more than one parameter is bound. Can be set to zero for types not bound as parameter arrays, i.e. CStr.

impl<B, K> CDataMut for VarCell<B, K>

where B: BorrowMut<[K::Element]>, K: VarKind,

fn mut_indicator_ptr(&mut self) -> *mut isize

Indicates the length of variable sized types. May be zero for fixed sized types.

fn mut_value_ptr(&mut self) -> *mut c_void

Pointer to a value corresponding to the one described by cdata_type.

impl<K: VarKind> CElement for VarCell<&[K::Element], K>

fn assert_completness(&self)

Must panic if the parameter is not complete. I.e. the indicator of a variable length parameter indicates a value larger than what is present in the value buffer.

impl<K: VarKind> CElement for VarCell<&mut [K::Element], K>

fn assert_completness(&self)

Must panic if the parameter is not complete. I.e. the indicator of a variable length parameter indicates a value larger than what is present in the value buffer.

impl<const LENGTH: usize, K: VarKind> CElement for VarCell<[K::Element; LENGTH], K>

fn assert_completness(&self)

Must panic if the parameter is not complete. I.e. the indicator of a variable length parameter indicates a value larger than what is present in the value buffer.

impl<K: VarKind> CElement for VarCell<Box<[K::Element]>, K>

fn assert_completness(&self)

Must panic if the parameter is not complete. I.e. the indicator of a variable length parameter indicates a value larger than what is present in the value buffer.

impl<B: Clone, K: Clone> Clone for VarCell<B, K>

fn clone(&self) -> VarCell<B, K>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<B: Debug, K: Debug> Debug for VarCell<B, K>

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

Formats the value using the given formatter.

impl<const LENGTH: usize, K, E> Default for VarCell<[E; LENGTH], K>

where E: Default + Copy,

fn default() -> Self

Returns the “default value” for a type.

impl<B, K> HasDataType for VarCell<B, K>

where B: Borrow<[K::Element]>, K: VarKind,

fn data_type(&self) -> DataType

The SQL data as which the parameter is bound to ODBC.

impl<B: Copy, K: Copy> Copy for VarCell<B, K>

impl<K: VarKind> OutputParameter for VarCell<&mut [K::Element], K>

impl<const LENGTH: usize, K: VarKind> OutputParameter for VarCell<[K::Element; LENGTH], K>

impl<K: VarKind> OutputParameter for VarCell<Box<[K::Element]>, K>