Struct odbc_api::buffers::ColumnarRowSet

pub struct ColumnarRowSet { /* fields omitted */ }

A columnar buffer intended to be bound with crate::Cursor::bind_buffer in order to obtain results from a cursor.

This buffer is designed to be versatile. It supports a wide variety of usage scenarios. It is efficient in retrieving data, but expensive to allocate, as columns are allocated separately. This is required in order to efficiently allow for rebinding columns, if this buffer is used to provide array input parameters those maximum size is not known in advance.

Most applications should find the overhead negligible, especially if instances are reused.

Implementations

impl ColumnarRowSet

pub fn new(
    max_rows: usize,
    description: impl Iterator<Item = BufferDescription>
) -> Self

Allocates for each buffer description a buffer large enough to hold max_rows.

pub fn with_column_indices(
    max_rows: usize,
    description: impl Iterator<Item = (u16, BufferDescription)>
) -> Self

Allows you to pass the buffer descriptions together with a one based column index referring the column, the buffer is supposed to bind to. This allows you also to ignore columns in a result set, by not binding them at all. There is no restriction on the order of column indices passed, but the function will panic, if the indices are not unique.

pub fn column(&self, buffer_index: usize) -> AnyColumnView<'_>

Use this method to gain read access to the actual column data.

Parameters

• buffer_index: Please note that the buffer index is not identical to the ODBC column index. For once it is zero based. It also indexes the buffer bound, and not the columns of the output result set. This is important, because not every column needs to be bound. Some columns may simply be ignored. That being said, if every column of the output is bound in the buffer, in the same order in which they are enumerated in the result set, the relationship between column index and buffer index is buffer_index = column_index - 1.

pub fn column_mut(&mut self, buffer_index: usize) -> AnyColumnViewMut<'_>

Use this method to gain write access to the actual column data.

Parameters

• buffer_index: Please note that the buffer index is not identical to the ODBC column index. For once it is zero based. It also indexes the buffer bound, and not the columns of the output result set. This is important, because not every column needs to be bound. Some columns may simply be ignored. That being said, if every column of the output is bound in the buffer, in the same order in which they are enumerated in the result set, the relationship between column index and buffer index is buffer_index = column_index - 1.

Example

This method is intend to be called if using ColumnarRowSet for column wise bulk inserts.

use odbc_api::{
    Connection, Error, IntoParameter,
    buffers::{ColumnarRowSet, BufferDescription, BufferKind, AnyColumnViewMut}
};

fn insert_birth_years(conn: &Connection, names: &[&str], years: &[i16])
    -> Result<(), Error>
{

    // All columns must have equal length.
    assert_eq!(names.len(), years.len());

    // Create a columnar buffer which fits the input parameters.
    let buffer_description = [
        BufferDescription {
            kind: BufferKind::Text { max_str_len: 255 },
            nullable: false,
        },
        BufferDescription {
            kind: BufferKind::I16,
            nullable: false,
        },
    ];
    let mut buffer = ColumnarRowSet::new(
        names.len(),
        buffer_description.iter().copied()
    );

    // Fill the buffer with values column by column
    match buffer.column_mut(0) {
        AnyColumnViewMut::Text(mut col) => {
            col.write(names.iter().map(|s| Some(s.as_bytes())))
        }
        _ => panic!("We know the name column to hold text.")
    }

    match buffer.column_mut(1) {
        AnyColumnViewMut::I16(mut col) => {
            col.copy_from_slice(years)
        }
        _ => panic!("We know the year column to hold i16.")
    }

    conn.execute(
        "INSERT INTO Birthdays (name, year) VALUES (?, ?)",
        &buffer
    )?;
    Ok(())
}

pub fn num_rows(&self) -> usize

Number of valid rows in the buffer.

pub fn set_num_rows(&mut self, num_rows: usize)

Set number of valid rows in the buffer. May not be larger than the batch size. If the specified number should be larger than the number of valid rows currently held by the buffer additional rows with the default value are going to be created.

Trait Implementations

impl ParameterCollection for &ColumnarRowSet

fn parameter_set_size(&self) -> usize

Number of values per parameter in the collection. This can be different from the maximum batch size a buffer may be able to hold. Returning 0 will cause the the query not to be executed.

unsafe fn bind_parameters_to(
    self,
    stmt: &mut impl Statement
) -> Result<(), Error>

Safety

impl RowSetBuffer for ColumnarRowSet

fn bind_type(&self) -> usize

Declares the bind type of the Row set buffer. 0 Means a columnar binding is used. Any non zero number is interpreted as the size of a single row in a row wise binding style.

fn row_array_size(&self) -> usize

The batch size for bulk cursors, if retrieving many rows at once.

fn mut_num_fetch_rows(&mut self) -> &mut usize

Mutable reference to the number of fetched rows.

unsafe fn bind_to_cursor(
    &mut self,
    cursor: &mut impl Cursor
) -> Result<(), Error>

Binds the buffer either column or row wise to the cursor.