Struct odbc_api::buffers::TextColumn

pub struct TextColumn<C> { /* private fields */ }

A buffer intended to be bound to a column of a cursor. Elements of the buffer will contain a variable amount of characters up to a maximum string length. Since most SQL types have a string representation this buffer can be bound to a column of almost any type, ODBC driver and driver manager should take care of the conversion. Since elements of this type have variable length an indicator buffer needs to be bound, whether the column is nullable or not, and therefore does not matter for this buffer.

Character type C is intended to be either u8 or u16.

Implementations

impl<C> TextColumn<C>

pub fn new(batch_size: usize, max_str_len: usize) -> Self where
    C: Default + Copy, 

This will allocate a value and indicator buffer for batch_size elements. Each value may have a maximum length of max_str_len. This implies that max_str_len is increased by one in order to make space for the null terminating zero at the end of strings.

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

Bytes of string at the specified position. Includes interior nuls, but excludes the terminating nul.

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 max_len(&self) -> usize

Maximum length of elements

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 resize_max_str(&mut self, new_max_str_len: usize, num_rows: usize) where
    C: Default + Copy, 

Changes the maximum string length the buffer can hold. This operation is useful if you find an unexpected large input string 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 string length, which would truncate strings in the process.

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

Parameters

• new_max_str_len: New maximum string length without terminating zero.
• num_rows: Number of valid rows currently stored in this buffer.

pub fn set_max_len(&mut self, new_max_len: usize) where
    C: Default + Copy, 

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 append(&mut self, index: usize, text: Option<&[C]>) where
    C: Default + Copy, 

Appends a new element to the column buffer. Rebinds the buffer to increase maximum string length should text 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.
• text: Text to store without terminating zero.

pub fn set_value(&mut self, index: usize, input: Option<&[C]>) where
    C: Default + Copy, 

Sets the value of the buffer at index at Null or the specified binary Text. This method will panic on out of bounds index, or if input holds a text which is larger than the maximum allowed element length. input must be specified without the terminating zero.

pub fn set_mut(&mut self, index: usize, length: usize) -> &mut [C] where
    C: Default, 

Can be used to set a value at a specific row index without performing a memcopy on an input slice and instead provides direct access to the underlying buffer.

In situations there the memcopy can not be avoided anyway Self::set_value is likely to be more convenient. This method is very useful if you want to write! a string value to the buffer and the binary (!) length of the formatted string is known upfront.

Example: Write timestamp to text column.

use odbc_api::buffers::TextColumn;
use std::io::Write;

/// Writes times formatted as hh::mm::ss.fff
fn write_time(
    col: &mut TextColumn<u8>,
    index: usize,
    hours: u8,
    minutes: u8,
    seconds: u8,
    milliseconds: u16)
{
    write!(
        col.set_mut(index, 12),
        "{:02}:{:02}:{:02}.{:03}",
        hours, minutes, seconds, milliseconds
    ).unwrap();
}

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

Fills the column with NULL, between From and To

pub fn writer_n(&mut self, n: usize) -> TextColumnWriter<'_, C>

A writer able to fill the first n elements of the buffer, from an iterator.

pub fn raw_value_buffer(&self, num_valid_rows: usize) -> &[C]

Provides access to the raw underlying value buffer. Normal applications should have little reason to call this method. Yet it may be useful for writing bindings which copy directly from the ODBC in memory representation into other kinds of buffers.

The buffer contains the bytes for every non null valid element, padded to the maximum string length. The content of the padding bytes is undefined. Usually ODBC drivers write a terminating zero at the end of each string. For the actual value length call [Self::conten_length_at]. Any element starts at index * (Self::max_len + 1).

impl TextColumn<u16>

pub unsafe fn ustr_at(&self, row_index: usize) -> Option<&U16Str>

The string slice at the specified position as U16Str. Includes interior nuls, but excludes the terminating nul.

Safety

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.

Trait Implementations

impl<C: 'static> ColumnBuffer for TextColumn<C> where
    TextColumn<C>: CDataMut + HasDataType, 

fn capacity(&self) -> usize

Maximum number of text strings this column may hold.

fn view(&self, valid_rows: usize) -> TextColumnView<'_, C>

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.

unsafe fn view_mut(&mut self, valid_rows: usize) -> TextColumnWriter<'_, C>

Safety

fn fill_default(&mut self, from: usize, to: usize)

Fills the column with the default representation of values, between from and to index.

impl<'a, C: 'static> ColumnProjections<'a> for TextColumn<C>

type View = TextColumnView<'a, C>

Immutable view on the column data. Used in safe abstractions. User must not be able to access uninitialized or invalid memory of the buffer through this interface.

type ViewMut = TextColumnWriter<'a, C>

Used to gain access to the buffer, if bound as a parameter for inserting.

impl<C: Debug> Debug for TextColumn<C>

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

Formats the value using the given formatter.