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 try_new(
    batch_size: usize,
    max_str_len: usize
) -> Result<Self, TooLargeBufferSize>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. Uses a fallibale allocation for creating the buffer. In applications often the max_str_len 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 VARCHAR(MAX)

Examples found in repository

src/buffers/columnar.rs (line 303)

    pub fn for_cursor(
        batch_size: usize,
        cursor: &mut impl ResultSetMetadata,
        max_str_limit: Option<usize>,
    ) -> Result<TextRowSet, Error> {
        let buffers = utf8_display_sizes(cursor)?
            .enumerate()
            .map(|(buffer_index, reported_len)| {
                let buffer_index = buffer_index as u16;
                let col_index = buffer_index + 1;
                let max_str_len = reported_len?;
                let buffer = if let Some(upper_bound) = max_str_limit {
                    let max_str_len = if max_str_len == 0 {
                        upper_bound
                    } else {
                        min(max_str_len, upper_bound)
                    };
                    TextColumn::new(batch_size, max_str_len)
                } else {
                    TextColumn::try_new(batch_size, max_str_len).map_err(|source| {
                        Error::TooLargeColumnBufferSize {
                            buffer_index,
                            num_elements: source.num_elements,
                            element_size: source.element_size,
                        }
                    })?
                };

                Ok((col_index, buffer))
            })
            .collect::<Result<_, _>>()?;
        Ok(TextRowSet {
            row_capacity: batch_size,
            num_rows: Box::new(0),
            columns: buffers,
        })
    }

    /// Creates a text buffer large enough to hold `batch_size` rows with one column for each item
    /// `max_str_lengths` of respective size.
    pub fn from_max_str_lens(
        row_capacity: usize,
        max_str_lengths: impl IntoIterator<Item = usize>,
    ) -> Result<Self, Error> {
        let buffers = max_str_lengths
            .into_iter()
            .enumerate()
            .map(|(index, max_str_len)| {
                Ok((
                    (index + 1).try_into().unwrap(),
                    TextColumn::try_new(row_capacity, max_str_len)
                        .map_err(|source| source.add_context(index.try_into().unwrap()))?,
                ))
            })
            .collect::<Result<_, _>>()?;
        Ok(TextRowSet {
            row_capacity,
            num_rows: Box::new(0),
            columns: buffers,
        })
    }

src/buffers/any_buffer.rs (line 93)

    fn impl_from_desc(
        max_rows: usize,
        desc: BufferDesc,
        fallible_allocations: bool,
    ) -> Result<Self, TooLargeBufferSize> {
        let buffer = match desc {
            BufferDesc::Binary { length } => {
                if fallible_allocations {
                    AnyBuffer::Binary(BinColumn::try_new(max_rows, length)?)
                } else {
                    AnyBuffer::Binary(BinColumn::new(max_rows, length))
                }
            }
            BufferDesc::Text { max_str_len } => {
                if fallible_allocations {
                    AnyBuffer::Text(TextColumn::try_new(max_rows, max_str_len)?)
                } else {
                    AnyBuffer::Text(TextColumn::new(max_rows, max_str_len))
                }
            }
            BufferDesc::WText { max_str_len } => {
                if fallible_allocations {
                    AnyBuffer::WText(TextColumn::try_new(max_rows, max_str_len)?)
                } else {
                    AnyBuffer::WText(TextColumn::new(max_rows, max_str_len))
                }
            }
            BufferDesc::Date { nullable: false } => {
                AnyBuffer::Date(vec![Date::default(); max_rows])
            }
            BufferDesc::Time { nullable: false } => {
                AnyBuffer::Time(vec![Time::default(); max_rows])
            }
            BufferDesc::Timestamp { nullable: false } => {
                AnyBuffer::Timestamp(vec![Timestamp::default(); max_rows])
            }
            BufferDesc::F64 { nullable: false } => AnyBuffer::F64(vec![f64::default(); max_rows]),
            BufferDesc::F32 { nullable: false } => AnyBuffer::F32(vec![f32::default(); max_rows]),
            BufferDesc::I8 { nullable: false } => AnyBuffer::I8(vec![i8::default(); max_rows]),
            BufferDesc::I16 { nullable: false } => AnyBuffer::I16(vec![i16::default(); max_rows]),
            BufferDesc::I32 { nullable: false } => AnyBuffer::I32(vec![i32::default(); max_rows]),
            BufferDesc::I64 { nullable: false } => AnyBuffer::I64(vec![i64::default(); max_rows]),
            BufferDesc::U8 { nullable: false } => AnyBuffer::U8(vec![u8::default(); max_rows]),
            BufferDesc::Bit { nullable: false } => AnyBuffer::Bit(vec![Bit::default(); max_rows]),
            BufferDesc::Date { nullable: true } => {
                AnyBuffer::NullableDate(OptDateColumn::new(max_rows))
            }
            BufferDesc::Time { nullable: true } => {
                AnyBuffer::NullableTime(OptTimeColumn::new(max_rows))
            }
            BufferDesc::Timestamp { nullable: true } => {
                AnyBuffer::NullableTimestamp(OptTimestampColumn::new(max_rows))
            }
            BufferDesc::F64 { nullable: true } => {
                AnyBuffer::NullableF64(OptF64Column::new(max_rows))
            }
            BufferDesc::F32 { nullable: true } => {
                AnyBuffer::NullableF32(OptF32Column::new(max_rows))
            }
            BufferDesc::I8 { nullable: true } => AnyBuffer::NullableI8(OptI8Column::new(max_rows)),
            BufferDesc::I16 { nullable: true } => {
                AnyBuffer::NullableI16(OptI16Column::new(max_rows))
            }
            BufferDesc::I32 { nullable: true } => {
                AnyBuffer::NullableI32(OptI32Column::new(max_rows))
            }
            BufferDesc::I64 { nullable: true } => {
                AnyBuffer::NullableI64(OptI64Column::new(max_rows))
            }
            BufferDesc::U8 { nullable: true } => AnyBuffer::NullableU8(OptU8Column::new(max_rows)),
            BufferDesc::Bit { nullable: true } => {
                AnyBuffer::NullableBit(OptBitColumn::new(max_rows))
            }
        };
        Ok(buffer)
    }

pub fn new(batch_size: usize, max_str_len: usize) -> Selfwhere
    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. All indicators are set to crate::sys::NULL_DATA by default.

Examples found in repository

src/prepared.rs (line 166)

    pub fn into_text_inserter(
        self,
        capacity: usize,
        max_str_len: impl IntoIterator<Item = usize>,
    ) -> Result<ColumnarBulkInserter<S, TextColumn<u8>>, Error> {
        let max_str_len = max_str_len.into_iter();
        let parameter_buffers = max_str_len
            .map(|max_str_len| TextColumn::new(capacity, max_str_len))
            .collect();
        // Text Columns are created with NULL as default, which is valid for insertion.
        unsafe { self.unchecked_bind_columnar_array_parameters(parameter_buffers) }
    }

src/buffers/columnar.rs (line 301)

    pub fn for_cursor(
        batch_size: usize,
        cursor: &mut impl ResultSetMetadata,
        max_str_limit: Option<usize>,
    ) -> Result<TextRowSet, Error> {
        let buffers = utf8_display_sizes(cursor)?
            .enumerate()
            .map(|(buffer_index, reported_len)| {
                let buffer_index = buffer_index as u16;
                let col_index = buffer_index + 1;
                let max_str_len = reported_len?;
                let buffer = if let Some(upper_bound) = max_str_limit {
                    let max_str_len = if max_str_len == 0 {
                        upper_bound
                    } else {
                        min(max_str_len, upper_bound)
                    };
                    TextColumn::new(batch_size, max_str_len)
                } else {
                    TextColumn::try_new(batch_size, max_str_len).map_err(|source| {
                        Error::TooLargeColumnBufferSize {
                            buffer_index,
                            num_elements: source.num_elements,
                            element_size: source.element_size,
                        }
                    })?
                };

                Ok((col_index, buffer))
            })
            .collect::<Result<_, _>>()?;
        Ok(TextRowSet {
            row_capacity: batch_size,
            num_rows: Box::new(0),
            columns: buffers,
        })
    }

src/buffers/any_buffer.rs (line 95)

    fn impl_from_desc(
        max_rows: usize,
        desc: BufferDesc,
        fallible_allocations: bool,
    ) -> Result<Self, TooLargeBufferSize> {
        let buffer = match desc {
            BufferDesc::Binary { length } => {
                if fallible_allocations {
                    AnyBuffer::Binary(BinColumn::try_new(max_rows, length)?)
                } else {
                    AnyBuffer::Binary(BinColumn::new(max_rows, length))
                }
            }
            BufferDesc::Text { max_str_len } => {
                if fallible_allocations {
                    AnyBuffer::Text(TextColumn::try_new(max_rows, max_str_len)?)
                } else {
                    AnyBuffer::Text(TextColumn::new(max_rows, max_str_len))
                }
            }
            BufferDesc::WText { max_str_len } => {
                if fallible_allocations {
                    AnyBuffer::WText(TextColumn::try_new(max_rows, max_str_len)?)
                } else {
                    AnyBuffer::WText(TextColumn::new(max_rows, max_str_len))
                }
            }
            BufferDesc::Date { nullable: false } => {
                AnyBuffer::Date(vec![Date::default(); max_rows])
            }
            BufferDesc::Time { nullable: false } => {
                AnyBuffer::Time(vec![Time::default(); max_rows])
            }
            BufferDesc::Timestamp { nullable: false } => {
                AnyBuffer::Timestamp(vec![Timestamp::default(); max_rows])
            }
            BufferDesc::F64 { nullable: false } => AnyBuffer::F64(vec![f64::default(); max_rows]),
            BufferDesc::F32 { nullable: false } => AnyBuffer::F32(vec![f32::default(); max_rows]),
            BufferDesc::I8 { nullable: false } => AnyBuffer::I8(vec![i8::default(); max_rows]),
            BufferDesc::I16 { nullable: false } => AnyBuffer::I16(vec![i16::default(); max_rows]),
            BufferDesc::I32 { nullable: false } => AnyBuffer::I32(vec![i32::default(); max_rows]),
            BufferDesc::I64 { nullable: false } => AnyBuffer::I64(vec![i64::default(); max_rows]),
            BufferDesc::U8 { nullable: false } => AnyBuffer::U8(vec![u8::default(); max_rows]),
            BufferDesc::Bit { nullable: false } => AnyBuffer::Bit(vec![Bit::default(); max_rows]),
            BufferDesc::Date { nullable: true } => {
                AnyBuffer::NullableDate(OptDateColumn::new(max_rows))
            }
            BufferDesc::Time { nullable: true } => {
                AnyBuffer::NullableTime(OptTimeColumn::new(max_rows))
            }
            BufferDesc::Timestamp { nullable: true } => {
                AnyBuffer::NullableTimestamp(OptTimestampColumn::new(max_rows))
            }
            BufferDesc::F64 { nullable: true } => {
                AnyBuffer::NullableF64(OptF64Column::new(max_rows))
            }
            BufferDesc::F32 { nullable: true } => {
                AnyBuffer::NullableF32(OptF32Column::new(max_rows))
            }
            BufferDesc::I8 { nullable: true } => AnyBuffer::NullableI8(OptI8Column::new(max_rows)),
            BufferDesc::I16 { nullable: true } => {
                AnyBuffer::NullableI16(OptI16Column::new(max_rows))
            }
            BufferDesc::I32 { nullable: true } => {
                AnyBuffer::NullableI32(OptI32Column::new(max_rows))
            }
            BufferDesc::I64 { nullable: true } => {
                AnyBuffer::NullableI64(OptI64Column::new(max_rows))
            }
            BufferDesc::U8 { nullable: true } => AnyBuffer::NullableU8(OptU8Column::new(max_rows)),
            BufferDesc::Bit { nullable: true } => {
                AnyBuffer::NullableBit(OptBitColumn::new(max_rows))
            }
        };
        Ok(buffer)
    }

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.

Examples found in repository

src/buffers/text_column.rs (line 293)

    pub unsafe fn ustr_at(&self, row_index: usize) -> Option<&U16Str> {
        self.value_at(row_index).map(U16Str::from_slice)
    }
}

unsafe impl<C: 'static> ColumnBuffer for TextColumn<C>
where
    TextColumn<C>: CDataMut + HasDataType,
{
    type View<'a> = TextColumnView<'a, C>;

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

    fn fill_default(&mut self, from: usize, to: usize) {
        self.fill_null(from, to)
    }

    /// Maximum number of text strings this column may hold.
    fn capacity(&self) -> usize {
        self.indicators.len()
    }
}

/// Allows read only access to the valid part of a text column.
///
/// You may ask, why is this type required, should we not just be able to use `&TextColumn`? The
/// problem with `TextColumn` is, that it is a buffer, but it has no idea how many of its members
/// are actually valid, and have been returned with the last row group of the the result set. That
/// number is maintained on the level of the entire column buffer. So a text column knows the number
/// of valid rows, in addition to holding a reference to the buffer, in order to guarantee, that
/// every element acccessed through it, is valid.
#[derive(Debug, Clone, Copy)]
pub struct TextColumnView<'c, C> {
    num_rows: usize,
    col: &'c TextColumn<C>,
}

impl<'c, C> TextColumnView<'c, C> {
    /// The number of valid elements in the text column.
    pub fn len(&self) -> usize {
        self.num_rows
    }

    /// True if, and only if there are no valid rows in the column buffer.
    pub fn is_empty(&self) -> bool {
        self.num_rows == 0
    }

    /// Slice of text at the specified row index without terminating zero.
    pub fn get(&self, index: usize) -> Option<&'c [C]> {
        self.col.value_at(index)
    }

    /// Iterator over the valid elements of the text buffer
    pub fn iter(&self) -> TextColumnIt<'c, C> {
        TextColumnIt {
            pos: 0,
            num_rows: self.num_rows,
            col: self.col,
        }
    }

    /// 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 content_length_at(&self, row_index: usize) -> Option<usize> {
        if row_index >= self.num_rows {
            panic!("Row index points beyond the range of valid values.")
        }
        self.col.content_length_at(row_index)
    }

    /// 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::content_length_at`]. Any element starts at index * ([`Self::max_len`] + 1).
    pub fn raw_value_buffer(&self) -> &'c [C] {
        self.col.raw_value_buffer(self.num_rows)
    }

    pub fn max_len(&self) -> usize {
        self.col.max_len()
    }
}

unsafe impl<'a, C: 'static> BoundInputSlice<'a> for TextColumn<C> {
    type SliceMut = TextColumnSliceMut<'a, C>;

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

/// A view to a mutable array parameter text buffer, which allows for filling the buffer with
/// values.
pub struct TextColumnSliceMut<'a, C> {
    column: &'a mut TextColumn<C>,
    // Needed to rebind the column in case of resize
    stmt: StatementRef<'a>,
    // Also needed to rebind the column in case of resize
    parameter_index: u16,
}

impl<'a, C> TextColumnSliceMut<'a, 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. `element` must be specified without the terminating zero.
    pub fn set_cell(&mut self, row_index: usize, element: Option<&[C]>) {
        self.column.set_value(row_index, element)
    }

    /// Ensures that the buffer is large enough to hold elements of `element_length`. Does nothing
    /// if the buffer is already large enough. Otherwise it will reallocate and rebind the buffer.
    /// The first `num_rows_to_copy_elements` will be copied from the old value buffer to the new
    /// one. This makes this an extremly expensive operation.
    pub fn ensure_max_element_length(
        &mut self,
        element_length: usize,
        num_rows_to_copy: usize,
    ) -> Result<(), Error>
    where
        TextColumn<C>: HasDataType + CData,
    {
        // Column buffer is not large enough to hold the element. We must allocate a larger buffer
        // in order to hold it. This invalidates the pointers previously bound to the statement. So
        // we rebind them.
        if element_length > self.column.max_len() {
            let new_max_str_len = element_length;
            self.column
                .resize_max_str(new_max_str_len, num_rows_to_copy);
            unsafe {
                self.stmt
                    .bind_input_parameter(self.parameter_index, self.column)
                    .into_result(&self.stmt)?
            }
        }
        Ok(())
    }

    /// 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_cell`] 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::TextColumnSliceMut;
    /// use std::io::Write;
    ///
    /// /// Writes times formatted as hh::mm::ss.fff
    /// fn write_time(
    ///     col: &mut TextColumnSliceMut<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 set_mut(&mut self, index: usize, length: usize) -> &mut [C] {
        self.column.set_mut(index, length)
    }
}

/// Iterator over a text column. See [`TextColumnView::iter`]
#[derive(Debug)]
pub struct TextColumnIt<'c, C> {
    pos: usize,
    num_rows: usize,
    col: &'c TextColumn<C>,
}

impl<'c, C> TextColumnIt<'c, C> {
    fn next_impl(&mut self) -> Option<Option<&'c [C]>> {
        if self.pos == self.num_rows {
            None
        } else {
            let ret = Some(self.col.value_at(self.pos));
            self.pos += 1;
            ret
        }
    }

src/buffers/columnar.rs (line 349)

    pub fn at(&self, buffer_index: usize, row_index: usize) -> Option<&[u8]> {
        assert!(row_index < *self.num_rows);
        self.columns[buffer_index].1.value_at(row_index)
    }

pub fn max_len(&self) -> usize

Maximum length of elements

Examples found in repository

src/buffers/text_column.rs (line 382)

    pub fn max_len(&self) -> usize {
        self.col.max_len()
    }
}

unsafe impl<'a, C: 'static> BoundInputSlice<'a> for TextColumn<C> {
    type SliceMut = TextColumnSliceMut<'a, C>;

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

/// A view to a mutable array parameter text buffer, which allows for filling the buffer with
/// values.
pub struct TextColumnSliceMut<'a, C> {
    column: &'a mut TextColumn<C>,
    // Needed to rebind the column in case of resize
    stmt: StatementRef<'a>,
    // Also needed to rebind the column in case of resize
    parameter_index: u16,
}

impl<'a, C> TextColumnSliceMut<'a, 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. `element` must be specified without the terminating zero.
    pub fn set_cell(&mut self, row_index: usize, element: Option<&[C]>) {
        self.column.set_value(row_index, element)
    }

    /// Ensures that the buffer is large enough to hold elements of `element_length`. Does nothing
    /// if the buffer is already large enough. Otherwise it will reallocate and rebind the buffer.
    /// The first `num_rows_to_copy_elements` will be copied from the old value buffer to the new
    /// one. This makes this an extremly expensive operation.
    pub fn ensure_max_element_length(
        &mut self,
        element_length: usize,
        num_rows_to_copy: usize,
    ) -> Result<(), Error>
    where
        TextColumn<C>: HasDataType + CData,
    {
        // Column buffer is not large enough to hold the element. We must allocate a larger buffer
        // in order to hold it. This invalidates the pointers previously bound to the statement. So
        // we rebind them.
        if element_length > self.column.max_len() {
            let new_max_str_len = element_length;
            self.column
                .resize_max_str(new_max_str_len, num_rows_to_copy);
            unsafe {
                self.stmt
                    .bind_input_parameter(self.parameter_index, self.column)
                    .into_result(&self.stmt)?
            }
        }
        Ok(())
    }

src/buffers/columnar.rs (line 385)

    pub fn max_len(&self, buf_index: usize) -> usize {
        self.columns[buf_index].1.max_len()
    }

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.

Examples found in repository

src/buffers/columnar.rs (line 380)

    pub fn indicator_at(&self, buf_index: usize, row_index: usize) -> Indicator {
        assert!(row_index < *self.num_rows);
        self.columns[buf_index].1.indicator_at(row_index)
    }

src/buffers/text_column.rs (line 126)

    pub fn content_length_at(&self, row_index: usize) -> Option<usize> {
        match self.indicator_at(row_index) {
            Indicator::Null => None,
            // Seen no total in the wild then binding shorter buffer to fixed sized CHAR in MSSQL.
            Indicator::NoTotal => Some(self.max_str_len),
            Indicator::Length(length_in_bytes) => {
                let length_in_chars = length_in_bytes / size_of::<C>();
                let length = min(self.max_str_len, length_in_chars);
                Some(length)
            }
        }
    }

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.

Examples found in repository

src/buffers/text_column.rs (line 101)

    pub fn value_at(&self, row_index: usize) -> Option<&[C]> {
        self.content_length_at(row_index).map(|length| {
            let offset = row_index * (self.max_str_len + 1);
            &self.values[offset..offset + length]
        })
    }

    /// Maximum length of elements
    pub fn max_len(&self) -> usize {
        self.max_str_len
    }

    /// 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 indicator_at(&self, row_index: usize) -> Indicator {
        Indicator::from_isize(self.indicators[row_index])
    }

    /// 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 content_length_at(&self, row_index: usize) -> Option<usize> {
        match self.indicator_at(row_index) {
            Indicator::Null => None,
            // Seen no total in the wild then binding shorter buffer to fixed sized CHAR in MSSQL.
            Indicator::NoTotal => Some(self.max_str_len),
            Indicator::Length(length_in_bytes) => {
                let length_in_chars = length_in_bytes / size_of::<C>();
                let length = min(self.max_str_len, length_in_chars);
                Some(length)
            }
        }
    }

    /// 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 resize_max_str(&mut self, new_max_str_len: usize, num_rows: usize)
    where
        C: Default + Copy,
    {
        debug!(
            "Rebinding text column buffer with {} elements. Maximum string length {} => {}",
            num_rows, self.max_str_len, new_max_str_len
        );

        let batch_size = self.indicators.len();
        // Allocate a new buffer large enough to hold a batch of strings with maximum length.
        let mut new_values = vec![C::default(); (new_max_str_len + 1) * batch_size];
        // Copy values from old to new buffer.
        let max_copy_length = min(self.max_str_len, new_max_str_len);
        for ((&indicator, old_value), new_value) in self
            .indicators
            .iter()
            .zip(self.values.chunks_exact_mut(self.max_str_len + 1))
            .zip(new_values.chunks_exact_mut(new_max_str_len + 1))
            .take(num_rows)
        {
            match Indicator::from_isize(indicator) {
                Indicator::Null => (),
                Indicator::NoTotal => {
                    // There is no good choice here in case we are expanding the buffer. Since
                    // NO_TOTAL indicates that we use the entire buffer, but in truth it would now
                    // be padded with 0. I currently cannot think of any use case there it would
                    // matter.
                    new_value[..max_copy_length].clone_from_slice(&old_value[..max_copy_length]);
                }
                Indicator::Length(num_bytes_len) => {
                    let num_bytes_to_copy = min(num_bytes_len / size_of::<C>(), max_copy_length);
                    new_value[..num_bytes_to_copy].copy_from_slice(&old_value[..num_bytes_to_copy]);
                }
            }
        }
        self.values = new_values;
        self.max_str_len = new_max_str_len;
    }

    /// 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_value(&mut self, index: usize, input: Option<&[C]>)
    where
        C: Default + Copy,
    {
        if let Some(input) = input {
            self.set_mut(index, input.len()).copy_from_slice(input);
        } else {
            self.indicators[index] = NULL_DATA;
        }
    }

    /// 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 set_mut(&mut self, index: usize, length: usize) -> &mut [C]
    where
        C: Default,
    {
        if length > self.max_str_len {
            panic!(
                "Tried to insert a value into a text buffer which is larger than the maximum \
                allowed string length for the buffer."
            );
        }
        self.indicators[index] = (length * size_of::<C>()).try_into().unwrap();
        let start = (self.max_str_len + 1) * index;
        let end = start + length;
        // Let's insert a terminating zero at the end to be on the safe side, in case the ODBC
        // driver would not care about the value in the index buffer and only look for the
        // terminating zero.
        self.values[end] = C::default();
        &mut self.values[start..end]
    }

    /// Fills the column with NULL, between From and To
    pub fn fill_null(&mut self, from: usize, to: usize) {
        for index in from..to {
            self.indicators[index] = NULL_DATA;
        }
    }

    /// 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::content_length_at`]. Any element starts at index * ([`Self::max_len`] + 1).
    pub fn raw_value_buffer(&self, num_valid_rows: usize) -> &[C] {
        &self.values[..(self.max_str_len + 1) * num_valid_rows]
    }

    /// The maximum number of rows the TextColumn can hold.
    pub fn row_capacity(&self) -> usize {
        self.values.len()
    }
}

impl WCharColumn {
    /// 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.
    pub unsafe fn ustr_at(&self, row_index: usize) -> Option<&U16Str> {
        self.value_at(row_index).map(U16Str::from_slice)
    }
}

unsafe impl<C: 'static> ColumnBuffer for TextColumn<C>
where
    TextColumn<C>: CDataMut + HasDataType,
{
    type View<'a> = TextColumnView<'a, C>;

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

    fn fill_default(&mut self, from: usize, to: usize) {
        self.fill_null(from, to)
    }

    /// Maximum number of text strings this column may hold.
    fn capacity(&self) -> usize {
        self.indicators.len()
    }
}

/// Allows read only access to the valid part of a text column.
///
/// You may ask, why is this type required, should we not just be able to use `&TextColumn`? The
/// problem with `TextColumn` is, that it is a buffer, but it has no idea how many of its members
/// are actually valid, and have been returned with the last row group of the the result set. That
/// number is maintained on the level of the entire column buffer. So a text column knows the number
/// of valid rows, in addition to holding a reference to the buffer, in order to guarantee, that
/// every element acccessed through it, is valid.
#[derive(Debug, Clone, Copy)]
pub struct TextColumnView<'c, C> {
    num_rows: usize,
    col: &'c TextColumn<C>,
}

impl<'c, C> TextColumnView<'c, C> {
    /// The number of valid elements in the text column.
    pub fn len(&self) -> usize {
        self.num_rows
    }

    /// True if, and only if there are no valid rows in the column buffer.
    pub fn is_empty(&self) -> bool {
        self.num_rows == 0
    }

    /// Slice of text at the specified row index without terminating zero.
    pub fn get(&self, index: usize) -> Option<&'c [C]> {
        self.col.value_at(index)
    }

    /// Iterator over the valid elements of the text buffer
    pub fn iter(&self) -> TextColumnIt<'c, C> {
        TextColumnIt {
            pos: 0,
            num_rows: self.num_rows,
            col: self.col,
        }
    }

    /// 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 content_length_at(&self, row_index: usize) -> Option<usize> {
        if row_index >= self.num_rows {
            panic!("Row index points beyond the range of valid values.")
        }
        self.col.content_length_at(row_index)
    }

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.

Examples found in repository

src/buffers/text_column.rs (line 441)

    pub fn ensure_max_element_length(
        &mut self,
        element_length: usize,
        num_rows_to_copy: usize,
    ) -> Result<(), Error>
    where
        TextColumn<C>: HasDataType + CData,
    {
        // Column buffer is not large enough to hold the element. We must allocate a larger buffer
        // in order to hold it. This invalidates the pointers previously bound to the statement. So
        // we rebind them.
        if element_length > self.column.max_len() {
            let new_max_str_len = element_length;
            self.column
                .resize_max_str(new_max_str_len, num_rows_to_copy);
            unsafe {
                self.stmt
                    .bind_input_parameter(self.parameter_index, self.column)
                    .into_result(&self.stmt)?
            }
        }
        Ok(())
    }

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.

Examples found in repository

src/buffers/text_column.rs (line 420)

    pub fn set_cell(&mut self, row_index: usize, element: Option<&[C]>) {
        self.column.set_value(row_index, element)
    }

src/columnar_bulk_inserter.rs (line 254)

    pub fn append<'b>(
        &mut self,
        mut row: impl Iterator<Item = Option<&'b [u8]>>,
    ) -> Result<(), Error>
    where
        S: AsStatementRef,
    {
        if self.capacity == self.parameter_set_size {
            panic!("Trying to insert elements into TextRowSet beyond batch size.")
        }

        let mut col_index = 1;
        for column in &mut self.parameters {
            let text = row.next().expect(
                "Row passed to TextRowSet::append must contain one element for each column.",
            );
            if let Some(text) = text {
                unsafe {
                    column
                        .as_view_mut(col_index, self.statement.as_stmt_ref())
                        .ensure_max_element_length(text.len(), self.parameter_set_size)?;
                }
                column.set_value(self.parameter_set_size, Some(text));
            } else {
                column.set_value(self.parameter_set_size, None);
            }
            col_index += 1;
        }

        self.parameter_set_size += 1;

        Ok(())
    }

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();
}

Examples found in repository

src/buffers/text_column.rs (line 202)

    pub fn set_value(&mut self, index: usize, input: Option<&[C]>)
    where
        C: Default + Copy,
    {
        if let Some(input) = input {
            self.set_mut(index, input.len()).copy_from_slice(input);
        } else {
            self.indicators[index] = NULL_DATA;
        }
    }

    /// 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 set_mut(&mut self, index: usize, length: usize) -> &mut [C]
    where
        C: Default,
    {
        if length > self.max_str_len {
            panic!(
                "Tried to insert a value into a text buffer which is larger than the maximum \
                allowed string length for the buffer."
            );
        }
        self.indicators[index] = (length * size_of::<C>()).try_into().unwrap();
        let start = (self.max_str_len + 1) * index;
        let end = start + length;
        // Let's insert a terminating zero at the end to be on the safe side, in case the ODBC
        // driver would not care about the value in the index buffer and only look for the
        // terminating zero.
        self.values[end] = C::default();
        &mut self.values[start..end]
    }

    /// Fills the column with NULL, between From and To
    pub fn fill_null(&mut self, from: usize, to: usize) {
        for index in from..to {
            self.indicators[index] = NULL_DATA;
        }
    }

    /// 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::content_length_at`]. Any element starts at index * ([`Self::max_len`] + 1).
    pub fn raw_value_buffer(&self, num_valid_rows: usize) -> &[C] {
        &self.values[..(self.max_str_len + 1) * num_valid_rows]
    }

    /// The maximum number of rows the TextColumn can hold.
    pub fn row_capacity(&self) -> usize {
        self.values.len()
    }
}

impl WCharColumn {
    /// 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.
    pub unsafe fn ustr_at(&self, row_index: usize) -> Option<&U16Str> {
        self.value_at(row_index).map(U16Str::from_slice)
    }
}

unsafe impl<C: 'static> ColumnBuffer for TextColumn<C>
where
    TextColumn<C>: CDataMut + HasDataType,
{
    type View<'a> = TextColumnView<'a, C>;

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

    fn fill_default(&mut self, from: usize, to: usize) {
        self.fill_null(from, to)
    }

    /// Maximum number of text strings this column may hold.
    fn capacity(&self) -> usize {
        self.indicators.len()
    }
}

/// Allows read only access to the valid part of a text column.
///
/// You may ask, why is this type required, should we not just be able to use `&TextColumn`? The
/// problem with `TextColumn` is, that it is a buffer, but it has no idea how many of its members
/// are actually valid, and have been returned with the last row group of the the result set. That
/// number is maintained on the level of the entire column buffer. So a text column knows the number
/// of valid rows, in addition to holding a reference to the buffer, in order to guarantee, that
/// every element acccessed through it, is valid.
#[derive(Debug, Clone, Copy)]
pub struct TextColumnView<'c, C> {
    num_rows: usize,
    col: &'c TextColumn<C>,
}

impl<'c, C> TextColumnView<'c, C> {
    /// The number of valid elements in the text column.
    pub fn len(&self) -> usize {
        self.num_rows
    }

    /// True if, and only if there are no valid rows in the column buffer.
    pub fn is_empty(&self) -> bool {
        self.num_rows == 0
    }

    /// Slice of text at the specified row index without terminating zero.
    pub fn get(&self, index: usize) -> Option<&'c [C]> {
        self.col.value_at(index)
    }

    /// Iterator over the valid elements of the text buffer
    pub fn iter(&self) -> TextColumnIt<'c, C> {
        TextColumnIt {
            pos: 0,
            num_rows: self.num_rows,
            col: self.col,
        }
    }

    /// 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 content_length_at(&self, row_index: usize) -> Option<usize> {
        if row_index >= self.num_rows {
            panic!("Row index points beyond the range of valid values.")
        }
        self.col.content_length_at(row_index)
    }

    /// 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::content_length_at`]. Any element starts at index * ([`Self::max_len`] + 1).
    pub fn raw_value_buffer(&self) -> &'c [C] {
        self.col.raw_value_buffer(self.num_rows)
    }

    pub fn max_len(&self) -> usize {
        self.col.max_len()
    }
}

unsafe impl<'a, C: 'static> BoundInputSlice<'a> for TextColumn<C> {
    type SliceMut = TextColumnSliceMut<'a, C>;

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

/// A view to a mutable array parameter text buffer, which allows for filling the buffer with
/// values.
pub struct TextColumnSliceMut<'a, C> {
    column: &'a mut TextColumn<C>,
    // Needed to rebind the column in case of resize
    stmt: StatementRef<'a>,
    // Also needed to rebind the column in case of resize
    parameter_index: u16,
}

impl<'a, C> TextColumnSliceMut<'a, 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. `element` must be specified without the terminating zero.
    pub fn set_cell(&mut self, row_index: usize, element: Option<&[C]>) {
        self.column.set_value(row_index, element)
    }

    /// Ensures that the buffer is large enough to hold elements of `element_length`. Does nothing
    /// if the buffer is already large enough. Otherwise it will reallocate and rebind the buffer.
    /// The first `num_rows_to_copy_elements` will be copied from the old value buffer to the new
    /// one. This makes this an extremly expensive operation.
    pub fn ensure_max_element_length(
        &mut self,
        element_length: usize,
        num_rows_to_copy: usize,
    ) -> Result<(), Error>
    where
        TextColumn<C>: HasDataType + CData,
    {
        // Column buffer is not large enough to hold the element. We must allocate a larger buffer
        // in order to hold it. This invalidates the pointers previously bound to the statement. So
        // we rebind them.
        if element_length > self.column.max_len() {
            let new_max_str_len = element_length;
            self.column
                .resize_max_str(new_max_str_len, num_rows_to_copy);
            unsafe {
                self.stmt
                    .bind_input_parameter(self.parameter_index, self.column)
                    .into_result(&self.stmt)?
            }
        }
        Ok(())
    }

    /// 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_cell`] 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::TextColumnSliceMut;
    /// use std::io::Write;
    ///
    /// /// Writes times formatted as hh::mm::ss.fff
    /// fn write_time(
    ///     col: &mut TextColumnSliceMut<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 set_mut(&mut self, index: usize, length: usize) -> &mut [C] {
        self.column.set_mut(index, length)
    }

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

Fills the column with NULL, between From and To

Examples found in repository

src/buffers/text_column.rs (line 311)

    fn fill_default(&mut self, from: usize, to: usize) {
        self.fill_null(from, to)
    }

src/buffers/any_buffer.rs (line 609)

    fn fill_default(&mut self, from: usize, to: usize) {
        match self {
            AnyBuffer::Binary(col) => col.fill_null(from, to),
            AnyBuffer::Text(col) => col.fill_null(from, to),
            AnyBuffer::WText(col) => col.fill_null(from, to),
            AnyBuffer::Date(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::Time(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::Timestamp(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::F64(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::F32(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::I8(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::I16(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::I32(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::I64(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::U8(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::Bit(col) => Self::fill_default_slice(&mut col[from..to]),
            AnyBuffer::NullableDate(col) => col.fill_null(from, to),
            AnyBuffer::NullableTime(col) => col.fill_null(from, to),
            AnyBuffer::NullableTimestamp(col) => col.fill_null(from, to),
            AnyBuffer::NullableF64(col) => col.fill_null(from, to),
            AnyBuffer::NullableF32(col) => col.fill_null(from, to),
            AnyBuffer::NullableI8(col) => col.fill_null(from, to),
            AnyBuffer::NullableI16(col) => col.fill_null(from, to),
            AnyBuffer::NullableI32(col) => col.fill_null(from, to),
            AnyBuffer::NullableI64(col) => col.fill_null(from, to),
            AnyBuffer::NullableU8(col) => col.fill_null(from, to),
            AnyBuffer::NullableBit(col) => col.fill_null(from, to),
        }
    }

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::content_length_at. Any element starts at index * (Self::max_len + 1).

Examples found in repository

src/buffers/text_column.rs (line 378)

    pub fn raw_value_buffer(&self) -> &'c [C] {
        self.col.raw_value_buffer(self.num_rows)
    }

pub fn row_capacity(&self) -> usize

The maximum number of rows the TextColumn can hold.

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<'a, C: 'static> BoundInputSlice<'a> for TextColumn<C>

type SliceMut = TextColumnSliceMut<'a, C>

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<C: 'static> ColumnBuffer for TextColumn<C>where
    TextColumn<C>: CDataMut + HasDataType,

fn capacity(&self) -> usize

Maximum number of text strings this column may hold.

type View<'a> = 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.

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.

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

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

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

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

Formats the value using the given formatter.