Struct RowPacker

pub struct RowPacker<'a> {
    row: &'a mut Row,
}

Packs datums into a Row.

Creating a RowPacker via Row::packer starts a packing operation on the row. A packing operation always starts from scratch: the existing contents of the underlying row are cleared.

To complete a packing operation, drop the RowPacker.

Fields

row: &'a mut Row

Implementations

impl RowPacker<'_>

pub(crate) fn try_push_proto(&mut self, x: &ProtoDatum) -> Result<(), String>

impl RowPacker<'_>

pub fn for_existing_row(row: &mut Row) -> RowPacker<'_>

Constructs a row packer that will pack additional datums into the provided row.

This function is intentionally somewhat inconvenient to call. You usually want to call Row::packer instead to start packing from scratch.

pub fn push<'a, D>(&mut self, datum: D)

where D: Borrow<Datum<'a>>,

Extend an existing Row with a Datum.

pub fn extend<'a, I, D>(&mut self, iter: I)

where I: IntoIterator<Item = D>, D: Borrow<Datum<'a>>,

Extend an existing Row with additional Datums.

pub fn try_extend<'a, I, E, D>(&mut self, iter: I) -> Result<(), E>

where I: IntoIterator<Item = Result<D, E>>, D: Borrow<Datum<'a>>,

Extend an existing Row with additional Datums.

In the case the iterator produces an error, the pushing of datums in terminated and the error returned. The Row will be incomplete, but it will be safe to read datums from it.

pub fn extend_by_row(&mut self, row: &Row)

Appends the datums of an entire Row.

pub unsafe fn extend_by_slice_unchecked(&mut self, data: &[u8])

Appends the slice of data representing an entire Row. The data is not validated.

Safety

The requirements from Row::from_bytes_unchecked apply here, too: This method relies on data being an appropriate row encoding, and can result in unsafety if this is not the case.

pub fn push_list_with<F, R>(&mut self, f: F) -> R

where F: FnOnce(&mut RowPacker<'_>) -> R,

Pushes a DatumList that is built from a closure.

The supplied closure will be invoked once with a Row that can be used to populate the list. It is valid to call any method on the RowPacker except for RowPacker::clear, RowPacker::truncate, or RowPacker::truncate_datums.

Returns the value returned by the closure, if any.

let mut row = Row::default();
row.packer().push_list_with(|row| {
    row.push(Datum::String("age"));
    row.push(Datum::Int64(42));
});
assert_eq!(
    row.unpack_first().unwrap_list().iter().collect::<Vec<_>>(),
    vec![Datum::String("age"), Datum::Int64(42)],
);

pub fn push_dict_with<F, R>(&mut self, f: F) -> R

where F: FnOnce(&mut RowPacker<'_>) -> R,

Pushes a DatumMap that is built from a closure.

The supplied closure will be invoked once with a Row that can be used to populate the dict.

The closure must alternate pushing string keys and arbitrary values, otherwise reading the dict will cause a panic.

The closure must push keys in ascending order, otherwise equality checks on the resulting Row may be wrong and reading the dict IN DEBUG MODE will cause a panic.

The closure must not call RowPacker::clear, RowPacker::truncate, or RowPacker::truncate_datums.

Example

let mut row = Row::default();
row.packer().push_dict_with(|row| {

    // key
    row.push(Datum::String("age"));
    // value
    row.push(Datum::Int64(42));

    // key
    row.push(Datum::String("name"));
    // value
    row.push(Datum::String("bob"));
});
assert_eq!(
    row.unpack_first().unwrap_map().iter().collect::<Vec<_>>(),
    vec![("age", Datum::Int64(42)), ("name", Datum::String("bob"))]
);

pub fn try_push_array<'a, I, D>( &mut self, dims: &[ArrayDimension], iter: I, ) -> Result<(), InvalidArrayError>

where I: IntoIterator<Item = D>, D: Borrow<Datum<'a>>,

Convenience function to construct an array from an iter of Datums.

Returns an error if the number of elements in iter does not match the cardinality of the array as described by dims, or if the number of dimensions exceeds MAX_ARRAY_DIMENSIONS. If an error occurs, the packer’s state will be unchanged.

pub unsafe fn push_array_with_unchecked<F, E>( &mut self, dims: &[ArrayDimension], f: F, ) -> Result<(), E>

where F: FnOnce(&mut RowPacker<'_>) -> Result<usize, E>, E: From<InvalidArrayError>,

Convenience function to construct an array from a function. The function must return the number of elements it pushed into the array. It is undefined behavior if the function returns a number different to the number of elements it pushed.

Returns an error if the number of elements pushed by f does not match the cardinality of the array as described by dims, or if the number of dimensions exceeds MAX_ARRAY_DIMENSIONS, or if f errors. If an error occurs, the packer’s state will be unchanged.

pub fn push_array_with_row_major<F, I>( &mut self, dims: I, f: F, ) -> Result<(), InvalidArrayError>

where I: IntoIterator<Item = ArrayDimension>, F: FnOnce(&mut RowPacker<'_>) -> usize,

Pushes an Array that is built from a closure.

WARNING: This is fairly “sharp” tool that is easy to get wrong. You should prefer RowPacker::try_push_array when possible.

Returns an error if the number of elements pushed does not match the cardinality of the array as described by dims, or if the number of dimensions exceeds MAX_ARRAY_DIMENSIONS. If an error occurs, the packer’s state will be unchanged.

pub fn push_list<'a, I, D>(&mut self, iter: I)

where I: IntoIterator<Item = D>, D: Borrow<Datum<'a>>,

Convenience function to push a DatumList from an iter of Datums

See RowPacker::push_dict_with if you need to be able to handle errors

pub fn push_dict<'a, I, D>(&mut self, iter: I)

where I: IntoIterator<Item = (&'a str, D)>, D: Borrow<Datum<'a>>,

Convenience function to push a DatumMap from an iter of (&str, Datum) pairs

pub fn push_range<'a>( &mut self, range: Range<Datum<'a>>, ) -> Result<(), InvalidRangeError>

Pushes a Datum::Range derived from the Range<Datum<'a>.

Panics

• If lower and upper express finite values and they are datums of different types.
• If lower or upper express finite values and are equal to Datum::Null. To handle Datum::Null properly, use RangeBound::new.

Notes

• This function canonicalizes the range before pushing it to the row.
• Prefer this function over push_range_with because of its canonicaliztion.
• Prefer creating RangeBounds using RangeBound::new, which handles Datum::Null in a SQL-friendly way.

pub fn push_range_with<L, U, E>( &mut self, lower: RangeLowerBound<L>, upper: RangeUpperBound<U>, ) -> Result<(), E>

where L: FnOnce(&mut RowPacker<'_>) -> Result<(), E>, U: FnOnce(&mut RowPacker<'_>) -> Result<(), E>, E: From<InvalidRangeError>,

Pushes a DatumRange built from the specified arguments.

Warning

Unlike push_range, push_range_with does not canonicalize its inputs. Consequentially, this means it’s possible to generate ranges that will not reflect the proper ordering and equality.

Panics

• If lower or upper expresses a finite value and does not push exactly one value into the RowPacker.
• If lower and upper express finite values and they are datums of different types.
• If lower or upper express finite values and push Datum::Null.

Notes

• Prefer push_range_with over this function. This function should be used only when you are not pushing Datums to the inner row.
• Range encoding is [<flag bytes>,<lower>?,<upper>?], where lower and upper are optional, contingent on the flag value expressing an empty range (where neither will be present) or infinite bounds (where each infinite bound will be absent).
• To push an emtpy range, use push_range using Range { inner: None }.

pub fn clear(&mut self)

Clears the contents of the packer without de-allocating its backing memory.

pub unsafe fn truncate(&mut self, pos: usize)

Truncates the underlying storage to the specified byte position.

Safety

pos MUST specify a byte offset that lies on a datum boundary. If pos specifies a byte offset that is within a datum, the row packer will produce an invalid row, the unpacking of which may trigger undefined behavior!

To find the byte offset of a datum boundary, inspect the packer’s byte length by calling packer.data().len() after pushing the desired number of datums onto the packer.

pub fn truncate_datums(&mut self, n: usize)

Truncates the underlying row to contain at most the first n datums.

pub fn byte_len(&self) -> usize

Returns the total amount of bytes used by the underlying row.

Trait Implementations

impl<'a> Debug for RowPacker<'a>

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

Formats the value using the given formatter.