Struct odbc_api::buffers::ColumnarBuffer
source · pub struct ColumnarBuffer<C> { /* private fields */ }
Expand description
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§
source§impl ColumnarBuffer<AnyBuffer>
impl ColumnarBuffer<AnyBuffer>
sourcepub fn from_description(
capacity: usize,
descs: impl IntoIterator<Item = BufferDescription>
) -> Self
👎Deprecated: Use from_descs instead
pub fn from_description(
capacity: usize,
descs: impl IntoIterator<Item = BufferDescription>
) -> Self
Allocates a ColumnarBuffer
fitting the buffer descriptions.
sourcepub fn from_descs(
capacity: usize,
descs: impl IntoIterator<Item = BufferDesc>
) -> Self
pub fn from_descs(
capacity: usize,
descs: impl IntoIterator<Item = BufferDesc>
) -> Self
Allocates a ColumnarBuffer
fitting the buffer descriptions.
sourcepub fn try_from_description(
capacity: usize,
descs: impl Iterator<Item = BufferDescription>
) -> Result<Self, Error>
👎Deprecated: Use try from descs
pub fn try_from_description(
capacity: usize,
descs: impl Iterator<Item = BufferDescription>
) -> Result<Self, Error>
Allocates a ColumnarBuffer
fitting the buffer descriptions. If not enough memory is
available to allocate the buffers this function fails with
Error::TooLargeColumnBufferSize
. This function is slower than Self::from_description
which would just panic if not enough memory is available for allocation.
sourcepub fn try_from_descs(
capacity: usize,
descs: impl IntoIterator<Item = BufferDesc>
) -> Result<Self, Error>
pub fn try_from_descs(
capacity: usize,
descs: impl IntoIterator<Item = BufferDesc>
) -> Result<Self, Error>
Allocates a ColumnarBuffer
fitting the buffer descriptions. If not enough memory is
available to allocate the buffers this function fails with
Error::TooLargeColumnBufferSize
. This function is slower than Self::from_description
which would just panic if not enough memory is available for allocation.
sourcepub fn from_description_and_indices(
max_rows: usize,
description: impl Iterator<Item = (u16, BufferDescription)>
) -> ColumnarBuffer<AnyBuffer>
👎Deprecated: use from_descs_and_indices
pub fn from_description_and_indices(
max_rows: usize,
description: impl Iterator<Item = (u16, BufferDescription)>
) -> ColumnarBuffer<AnyBuffer>
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.
sourcepub fn from_descs_and_indices(
max_rows: usize,
description: impl Iterator<Item = (u16, BufferDesc)>
) -> ColumnarBuffer<AnyBuffer>
pub fn from_descs_and_indices(
max_rows: usize,
description: impl Iterator<Item = (u16, BufferDesc)>
) -> ColumnarBuffer<AnyBuffer>
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.
source§impl<C: ColumnBuffer> ColumnarBuffer<C>
impl<C: ColumnBuffer> ColumnarBuffer<C>
sourcepub fn new(columns: Vec<(u16, C)>) -> Self
pub fn new(columns: Vec<(u16, C)>) -> Self
Create a new instance from columns with unique indicies. Capacity of the buffer will be the minimum capacity of the columns. The constructed buffer is always empty (i.e. the number of valid rows is considered to be zero).
You do not want to call this constructor directly unless you want to provide your own buffer
implentation. Most users of this crate may want to use the constructors like
crate::buffers::ColumnarAnyBuffer::from_description
or
crate::buffers::TextRowSet::from_max_str_lens
instead.
sourcepub unsafe fn new_unchecked(capacity: usize, columns: Vec<(u16, C)>) -> Self
pub unsafe fn new_unchecked(capacity: usize, columns: Vec<(u16, C)>) -> Self
Safety
- Indices must be unique
- Columns all must have enough
capacity
.
sourcepub fn column(&self, buffer_index: usize) -> C::View<'_>
pub fn column(&self, buffer_index: usize) -> C::View<'_>
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 isbuffer_index = column_index - 1
.
source§impl ColumnarBuffer<TextColumn<u8>>
impl ColumnarBuffer<TextColumn<u8>>
sourcepub fn for_cursor(
batch_size: usize,
cursor: &mut impl ResultSetMetadata,
max_str_limit: Option<usize>
) -> Result<TextRowSet, Error>
pub fn for_cursor(
batch_size: usize,
cursor: &mut impl ResultSetMetadata,
max_str_limit: Option<usize>
) -> Result<TextRowSet, Error>
The resulting text buffer is not in any way tied to the cursor, other than that its buffer sizes a tailor fitted to result set the cursor is iterating over.
This method performs faliable buffer allocations, if no upper bound is set, so you may see
a speedup, by setting an upper bound using max_str_limit
.
Parameters
batch_size
: The maximum number of rows the buffer is able to hold.cursor
: Used to query the display size for each column of the row set. For character data the length in characters is multiplied by 4 in order to have enough space for 4 byte utf-8 characters. This is a pessimization for some data sources (e.g. SQLite 3) which do interpret the size of aVARCHAR(5)
column as 5 bytes rather than 5 characters.max_str_limit
: Some queries make it hard to estimate a sensible upper bound and sometimes drivers are just not that good at it. This argument allows you to specify an upper bound for the length of character data. Any size reported by the driver is capped to this value. In case the database returns a size of 0 (which some systems used to indicate) arbitrariely large values, the element size is set to upper bound.
sourcepub fn from_max_str_lens(
row_capacity: usize,
max_str_lengths: impl IntoIterator<Item = usize>
) -> Result<Self, Error>
pub fn from_max_str_lens(
row_capacity: usize,
max_str_lengths: impl IntoIterator<Item = usize>
) -> Result<Self, Error>
Creates a text buffer large enough to hold batch_size
rows with one column for each item
max_str_lengths
of respective size.
sourcepub fn at(&self, buffer_index: usize, row_index: usize) -> Option<&[u8]>
pub fn at(&self, buffer_index: usize, row_index: usize) -> Option<&[u8]>
Access the element at the specified position in the row set.
sourcepub fn at_as_str(
&self,
col_index: usize,
row_index: usize
) -> Result<Option<&str>, Utf8Error>
pub fn at_as_str(
&self,
col_index: usize,
row_index: usize
) -> Result<Option<&str>, Utf8Error>
Access the element at the specified position in the row set.
sourcepub fn indicator_at(&self, buf_index: usize, row_index: usize) -> Indicator
pub fn indicator_at(&self, buf_index: usize, row_index: usize) -> Indicator
Indicator value at the specified position. Useful to detect truncation of data.
Example
use odbc_api::buffers::{Indicator, TextRowSet};
fn is_truncated(buffer: &TextRowSet, col_index: usize, row_index: usize) -> bool {
match buffer.indicator_at(col_index, row_index) {
// There is no value, therefore there is no value not fitting in the column buffer.
Indicator::Null => false,
// The value did not fit into the column buffer, we do not even know, by how much.
Indicator::NoTotal => true,
Indicator::Length(total_length) => {
// If the maximum string length is shorter than the values total length, the
// has been truncated to fit into the buffer.
buffer.max_len(col_index) < total_length
}
}
}
Trait Implementations§
source§impl<C> RowSetBuffer for ColumnarBuffer<C>where
C: ColumnBuffer,
impl<C> RowSetBuffer for ColumnarBuffer<C>where
C: ColumnBuffer,
source§fn bind_type(&self) -> usize
fn bind_type(&self) -> usize
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. Read more