Struct odbc_api::buffers::BinColumn

pub struct BinColumn { /* private fields */ }

A buffer intended to be bound to a column of a cursor. Elements of the buffer will contain a variable amount of bytes up to a maximum length. Since elements of this type have variable length an additional indicator buffer is also maintained, whether the column is nullable or not. Therefore this buffer type is used for variable sized binary data whether it is nullable or not.

Implementations

impl BinColumn

pub fn try_new( batch_size: usize, element_size: usize ) -> Result<Self, TooLargeBufferSize>

This will allocate a value and indicator buffer for batch_size elements. Each value may have a maximum length of element_size. Uses a fallibale allocation for creating the buffer. In applications often the element_size of the buffer, might be directly inspired by the maximum size of the type, as reported, by ODBC. Which might get exceedingly large for types like VARBINARY(MAX), or IMAGE. On the downside, this method is potentially slower than new.

pub fn new(batch_size: usize, element_size: usize) -> Self

This will allocate a value and indicator buffer for batch_size elements. Each value may have a maximum length of max_len.

pub fn value_at(&self, row_index: usize) -> Option<&[u8]>

Return the value for the given row index.

The column buffer does not know how many elements were in the last row group, and therefore can not guarantee the accessed element to be valid and in a defined state. It also can not panic on accessing an undefined element. It will panic however if row_index is larger or equal to the maximum number of elements in the buffer.

pub fn indicator_at(&self, row_index: usize) -> Indicator

Indicator value at the specified position. Useful to detect truncation of data.

The column buffer does not know how many elements were in the last row group, and therefore can not guarantee the accessed element to be valid and in a defined state. It also can not panic on accessing an undefined element. It will panic however if row_index is larger or equal to the maximum number of elements in the buffer.

pub fn content_length_at(&self, row_index: usize) -> Option<usize>

Length of value at the specified position. This is different from an indicator as it refers to the length of the value in the buffer, not to the length of the value in the datasource. The two things are different for truncated values.

pub fn has_truncated_values(&self, num_rows: usize) -> bool

true if any value is truncated in the range [0, num_rows).

After fetching data we may want to know if any value has been truncated due to the buffer not being able to hold elements of that size. This method checks the indicator buffer element wise.

pub fn set_max_len(&mut self, new_max_len: usize)

Changes the maximum element length the buffer can hold. This operation is useful if you find an unexpected large input during insertion. All values in the buffer will be set to NULL.

Parameters

• new_max_len: New maximum string length without terminating zero.

pub fn max_len(&self) -> usize

Maximum length of elements in bytes.

pub fn view(&self, num_rows: usize) -> BinColumnView<'_>

View of the first num_rows values of a binary column.

Num rows may not exceed the actually amount of valid num_rows filled be the ODBC API. The column buffer does not know how many elements were in the last row group, and therefore can not guarantee the accessed element to be valid and in a defined state. It also can not panic on accessing an undefined element. It will panic however if row_index is larger or equal to the maximum number of elements in the buffer.

pub fn set_value(&mut self, index: usize, input: Option<&[u8]>)

Sets the value of the buffer at index to NULL or the specified bytes. This method will panic on out of bounds index, or if input holds a value which is longer than the maximum allowed element length.

pub fn fill_null(&mut self, from: usize, to: usize)

Fills the column with NULL, between From and To

pub fn resize_max_element_length(&mut self, new_max_len: usize, num_rows: usize)

Changes the maximum number of bytes per row the buffer can hold. This operation is useful if you find an unexpected large input during insertion.

This is however costly, as not only does the new buffer have to be allocated, but all values have to copied from the old to the new buffer.

This method could also be used to reduce the maximum length, which would truncate values in the process.

This method does not adjust indicator buffers as these might hold values larger than the maximum length.

Parameters

• new_max_len: New maximum element length in bytes.
• num_rows: Number of valid rows currently stored in this buffer.

pub fn append(&mut self, index: usize, bytes: Option<&[u8]>)

Appends a new element to the column buffer. Rebinds the buffer to increase maximum element length should the input be to large.

Parameters

• index: Zero based index of the new row position. Must be equal to the number of rows currently in the buffer.
• bytes: Value to store.

pub fn capacity(&self) -> usize

Maximum number of elements this buffer can hold.

Trait Implementations

impl<'a> BoundInputSlice<'a> for BinColumn

type SliceMut = BinColumnSliceMut<'a>

Intended to allow for modifying buffer contents, while leaving the bound parameter buffers valid.

unsafe fn as_view_mut( &'a mut self, parameter_index: u16, stmt: StatementRef<'a> ) -> Self::SliceMut

Obtain a mutable view on a parameter buffer in order to change the parameter value(s) submitted when executing the statement.

impl CData for BinColumn

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 CDataMut for BinColumn

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 Debug for BinColumn

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

Formats the value using the given formatter.

impl HasDataType for BinColumn

fn data_type(&self) -> DataType

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