Struct odbc_api::buffers::TextColumnWriter

pub struct TextColumnWriter<'a, C> { /* private fields */ }

Fills a text column buffer with elements from an Iterator.

Implementations

impl<'a, C> TextColumnWriter<'a, C> where
    C: Default + Copy, 

pub fn write<'b>(&mut self, it: impl Iterator<Item = Option<&'b [C]>>) where
    C: 'b, 

Fill the text column with values by consuming the iterator and copying its items into the buffer. It will not extract more items from the iterator than the buffer may hold. This method panics if strings returned by the iterator are larger than the maximum element length of the buffer.

pub fn max_len(&self) -> usize

Maximum string length without terminating zero

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

Changes the maximum string 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 rebind(&mut self, new_max_str_len: usize, num_rows: usize)

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: Rows up to this index will be copied from the old memory to the newly allocated memory. This is used as an optimization as to not copy all values. If the buffer contained values after num_rows their indicator values remain, but their values will be all zeroes.

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

Change a single value in the column at the specified index.

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

Inserts a new element to the column buffer. Rebinds the buffer to increase maximum string length should the text be larger than the maximum allowed string size. The number of rows the column buffer can hold stays constant, but during rebind only values before index would be copied to the new memory location. Therefore this method is intended to be used to fill the buffer element-wise and in order. Hence the name append.

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.

Example

let desc = BufferDescription {
    // Buffer size purposefully chosen too small, so we need to increase the buffer size if we
    // encounter larger inputs.
    kind: BufferKind::Text { max_str_len: 1 },
    nullable: true,
};

// Input values to insert.
let input = [
    Some(&b"Hi"[..]),
    Some(&b"Hello"[..]),
    Some(&b"World"[..]),
    None,
    Some(&b"Hello, World!"[..]),
];

let mut buffer = buffer_from_description(input.len(), iter::once(desc));

buffer.set_num_rows(input.len());
if let AnyColumnViewMut::Text(mut writer) = buffer.column_mut(0) {
    for (index, &text) in input.iter().enumerate() {
        writer.append(index, text)
    }
} else {
    panic!("Expected text column writer");
};

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

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::TextColumnWriter;
use std::io::Write;

/// Writes times formatted as hh::mm::ss.fff
fn write_time(
    col: &mut TextColumnWriter<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();
}

Trait Implementations

impl<'a, C: Debug> Debug for TextColumnWriter<'a, C>

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

Formats the value using the given formatter.