pub struct Row { /* private fields */ }
Expand description
A packed representation for Datum
s.
Datum
is easy to work with but very space inefficient. A Datum::Int32(42)
is laid out in memory like this:
tag: 3 padding: 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 data: 0 0 0 42 padding: 0 0 0 0 0 0 0 0 0 0 0 0
For a total of 32 bytes! The second set of padding is needed in case we were to write a 16-byte datum into this location. The first set of padding is needed to align that hypothetical decimal to a 16 bytes boundary.
A Row
stores zero or more Datum
s without any padding. We avoid the need
for the first set of padding by only providing access to the Datum
s via
calls to ptr::read_unaligned
, which on modern x86 is barely penalized. We
avoid the need for the second set of padding by not providing mutable access
to the Datum
. Instead, Row
is append-only.
A Row
can be built from a collection of Datum
s using Row::pack
, but it
is more efficient to use Row::pack_slice
so that a right-sized allocation
can be created. If that is not possible, consider using the row buffer
pattern: allocate one row, pack into it, and then call Row::clone
to
receive a copy of that row, leaving behind the original allocation to pack
future rows.
Creating a row via Row::pack_slice
:
let row = Row::pack_slice(&[Datum::Int32(0), Datum::Int32(1), Datum::Int32(2)]);
assert_eq!(row.unpack(), vec![Datum::Int32(0), Datum::Int32(1), Datum::Int32(2)])
Row
s can be unpacked by iterating over them:
let row = Row::pack_slice(&[Datum::Int32(0), Datum::Int32(1), Datum::Int32(2)]);
assert_eq!(row.iter().nth(1).unwrap(), Datum::Int32(1));
If you want random access to the Datum
s in a Row
, use Row::unpack
to create a Vec<Datum>
let row = Row::pack_slice(&[Datum::Int32(0), Datum::Int32(1), Datum::Int32(2)]);
let datums = row.unpack();
assert_eq!(datums[1], Datum::Int32(1));
§Performance
Rows are dynamically sized, but up to a fixed size their data is stored in-line.
It is best to re-use a Row
across multiple Row
creation calls, as this
avoids the allocations involved in Row::new()
.
Implementations§
source§impl Row
impl Row
sourcepub fn with_capacity(cap: usize) -> Self
pub fn with_capacity(cap: usize) -> Self
Allocate an empty Row
with a pre-allocated capacity.
sourcepub unsafe fn from_bytes_unchecked(data: Vec<u8>) -> Self
pub unsafe fn from_bytes_unchecked(data: Vec<u8>) -> Self
Creates a new row from supplied bytes.
§Safety
This method relies on data
being an appropriate row encoding, and can
result in unsafety if this is not the case.
sourcepub fn packer(&mut self) -> RowPacker<'_>
pub fn packer(&mut self) -> RowPacker<'_>
Constructs a RowPacker
that will pack datums into this row’s
allocation.
This method clears the existing contents of the row, but retains the allocation.
sourcepub fn pack<'a, I, D>(iter: I) -> Row
pub fn pack<'a, I, D>(iter: I) -> Row
Take some Datum
s and pack them into a Row
.
This method builds a Row
by repeatedly increasing the backing
allocation. If the contents of the iterator are known ahead of
time, consider Row::with_capacity
to right-size the allocation
first, and then RowPacker::extend
to populate it with Datum
s.
This avoids the repeated allocation resizing and copying.
sourcepub fn pack_using<'a, I, D>(&mut self, iter: I) -> Row
pub fn pack_using<'a, I, D>(&mut self, iter: I) -> Row
Use self
to pack iter
, and then clone the result.
This is a convenience method meant to reduce boilerplate around row formation.
sourcepub fn try_pack<'a, I, D, E>(iter: I) -> Result<Row, E>
pub fn try_pack<'a, I, D, E>(iter: I) -> Result<Row, E>
Like Row::pack
, but the provided iterator is allowed to produce an
error, in which case the packing operation is aborted and the error
returned.
sourcepub fn pack_slice<'a>(slice: &[Datum<'a>]) -> Row
pub fn pack_slice<'a>(slice: &[Datum<'a>]) -> Row
Pack a slice of Datum
s into a Row
.
This method has the advantage over pack
that it can determine the required
allocation before packing the elements, ensuring only one allocation and no
redundant copies required.
sourcepub fn byte_capacity(&self) -> usize
pub fn byte_capacity(&self) -> usize
Returns the total capacity in bytes used by this row.
sourcepub fn unpack(&self) -> Vec<Datum<'_>>
pub fn unpack(&self) -> Vec<Datum<'_>>
Unpack self
into a Vec<Datum>
for efficient random access.
sourcepub fn unpack_first(&self) -> Datum<'_>
pub fn unpack_first(&self) -> Datum<'_>
Return the first Datum
in self
Panics if the Row
is empty.
Trait Implementations§
source§impl Arbitrary for Row
impl Arbitrary for Row
§type Parameters = SizeRange
type Parameters = SizeRange
arbitrary_with
accepts for configuration
of the generated Strategy
. Parameters must implement Default
.§type Strategy = BoxedStrategy<Row>
type Strategy = BoxedStrategy<Row>
Strategy
used to generate values of type Self
.source§fn arbitrary_with(size: Self::Parameters) -> Self::Strategy
fn arbitrary_with(size: Self::Parameters) -> Self::Strategy
source§impl Codec for Row
impl Codec for Row
source§fn encode<B>(&self, buf: &mut B)where
B: BufMut,
fn encode<B>(&self, buf: &mut B)where
B: BufMut,
Encodes a row into the permanent storage format.
This perfectly round-trips through Row::decode. It’s guaranteed to be readable by future versions of Materialize through v(TODO: Figure out our policy).
source§fn decode(buf: &[u8]) -> Result<Row, String>
fn decode(buf: &[u8]) -> Result<Row, String>
Decodes a row from the permanent storage format.
This perfectly round-trips through Row::encode. It can read rows encoded by historical versions of Materialize back to v(TODO: Figure out our policy).
§type Storage = ProtoRow
type Storage = ProtoRow
()
if unnecessary.§type Schema = RelationDesc
type Schema = RelationDesc
source§fn codec_name() -> String
fn codec_name() -> String
source§impl Columnation for Row
impl Columnation for Row
§type InnerRegion = RowStack
type InnerRegion = RowStack
Self
type. Note: not allocations of Self
, but of the
things that it owns.source§impl<'de> Deserialize<'de> for Row
impl<'de> Deserialize<'de> for Row
source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
source§impl FromDatumIter for Row
impl FromDatumIter for Row
source§fn from_datum_iter<'a, I, D>(&mut self, datum_iter: I) -> Self
fn from_datum_iter<'a, I, D>(&mut self, datum_iter: I) -> Self
Packs into self
the given iterator of datums and returns a clone.
source§fn try_from_datum_iter<'a, I, D, E>(&mut self, datum_iter: I) -> Result<Self, E>
fn try_from_datum_iter<'a, I, D, E>(&mut self, datum_iter: I) -> Result<Self, E>
Packs into self
by using the packer’s try_extend
method on the given iterator
and returns a clone.
source§impl<'a> IntoIterator for &'a Row
impl<'a> IntoIterator for &'a Row
source§impl Ord for Row
impl Ord for Row
source§impl PartDecoder<Row> for RowDecoder
impl PartDecoder<Row> for RowDecoder
source§impl PartEncoder<Row> for RowEncoder
impl PartEncoder<Row> for RowEncoder
source§impl PartialOrd for Row
impl PartialOrd for Row
These implementations order first by length, and then by slice contents. This allows many comparisons to complete without dereferencing memory. Warning: These order by the u8 array representation, and NOT by Datum::cmp.
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl RustType<ProtoRow> for Row
impl RustType<ProtoRow> for Row
source§fn into_proto(&self) -> ProtoRow
fn into_proto(&self) -> ProtoRow
Self
into a Proto
value.source§fn from_proto(proto: ProtoRow) -> Result<Self, TryFromProtoError>
fn from_proto(proto: ProtoRow) -> Result<Self, TryFromProtoError>
source§impl Schema<Row> for RelationDesc
impl Schema<Row> for RelationDesc
§type Encoder = RowEncoder
type Encoder = RowEncoder
§type Decoder = RowDecoder
type Decoder = RowDecoder
source§fn columns(&self) -> DynStructCfg
fn columns(&self) -> DynStructCfg
source§fn decoder(&self, part: ColumnsRef) -> Result<Self::Decoder, String>
fn decoder(&self, part: ColumnsRef) -> Result<Self::Decoder, String>
Self::Decoder
for the given columns.source§fn encoder<'a>(&self, part: ColumnsMut) -> Result<Self::Encoder, String>
fn encoder<'a>(&self, part: ColumnsMut) -> Result<Self::Encoder, String>
source§impl ToDatumIter for Row
impl ToDatumIter for Row
impl Eq for Row
impl StructuralPartialEq for Row
Auto Trait Implementations§
impl Freeze for Row
impl RefUnwindSafe for Row
impl Send for Row
impl Sync for Row
impl Unpin for Row
impl UnwindSafe for Row
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
source§impl<R, O, T> CopyOnto<ConsecutiveOffsetPairs<R, O>> for T
impl<R, O, T> CopyOnto<ConsecutiveOffsetPairs<R, O>> for T
source§fn copy_onto(
self,
target: &mut ConsecutiveOffsetPairs<R, O>
) -> <ConsecutiveOffsetPairs<R, O> as Region>::Index
fn copy_onto( self, target: &mut ConsecutiveOffsetPairs<R, O> ) -> <ConsecutiveOffsetPairs<R, O> as Region>::Index
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.source§impl<T> FutureExt for T
impl<T> FutureExt for T
source§fn with_context(self, otel_cx: Context) -> WithContext<Self>
fn with_context(self, otel_cx: Context) -> WithContext<Self>
source§fn with_current_context(self) -> WithContext<Self>
fn with_current_context(self) -> WithContext<Self>
source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoRequest<T> for T
impl<T> IntoRequest<T> for T
source§fn into_request(self) -> Request<T>
fn into_request(self) -> Request<T>
T
in a tonic::Request
source§impl<T, U> OverrideFrom<Option<&T>> for Uwhere
U: OverrideFrom<T>,
impl<T, U> OverrideFrom<Option<&T>> for Uwhere
U: OverrideFrom<T>,
source§impl<T> Pointable for T
impl<T> Pointable for T
source§impl<T> PreferredContainer for T
impl<T> PreferredContainer for T
source§impl<T> ProgressEventTimestamp for T
impl<T> ProgressEventTimestamp for T
source§impl<P, R> ProtoType<R> for Pwhere
R: RustType<P>,
impl<P, R> ProtoType<R> for Pwhere
R: RustType<P>,
source§fn into_rust(self) -> Result<R, TryFromProtoError>
fn into_rust(self) -> Result<R, TryFromProtoError>
RustType::from_proto
.source§fn from_rust(rust: &R) -> P
fn from_rust(rust: &R) -> P
RustType::into_proto
.