Enum Seq 

pub enum Seq {
    Boxed(Vec<Value>),
    Ints(Vec<i64>),
    Floats(Vec<f64>),
}

A list’s elements. See the module docs for what a caller may not be able to tell.

Variants

Boxed(Vec<Value>)

Any elements at all.

Ints(Vec<i64>)

Int elements, dense.

Floats(Vec<f64>)

Float elements, dense and as f64.

Implementations

impl Seq

pub fn pack(values: Vec<Value>) -> Seq

The elements a primitive produced, in whatever layout they fit.

One pass over a list that has just been built by a pass over something else, so this is a constant on a cost the caller was already paying — and it stops at the first element that does not fit, so a list of records pays a single comparison.

pub fn to_vec(&self) -> Vec<Value>

The elements, unpacked — what a caller that wants a Vec<Value> gets.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn get(&self, i: usize) -> Option<Value>

One element, as a Value. By value rather than by reference, because a column has no Value to lend — and an Int or a Float is two words, so there is nothing to save.

pub fn iter(&self) -> Iter<'_>

Every element, in order.

pub fn ints(&self) -> Option<&[i64]>

The elements as a dense i64 run, if that is what this list is.

pub fn floats(&self) -> Option<&[f64]>

The elements as a dense f64 run, if that is what this list is — the pointer a kernel and an Arrow Float64Array both take, and the reason this module exists (105 §105.8).

None for a boxed list rather than a copy of one: a caller that gets a slice knows it cost nothing, and a caller that gets None can decide whether a copy is worth it. Handing back a materialised buffer here would make the cheap case and the expensive one look alike, which is the shape of every “why is this slow” question a zero-copy interface exists to prevent.

pub fn for_each(&self, f: impl FnMut(&Value))

Every element, borrowed where the layout has one to lend.

Seq::iter yields by value, which is right for a caller that wanted an owned Value and wrong for one that only wanted to look: cloning a Value::Data is an atomic increment and a later decrement, and the digest, the wire format and to_json each walk every element of every list without keeping any of them. Those walk through here, so the boxed layout — which is every list that is not a column — pays exactly what it paid before this module existed.

A column has no Value to lend, so one is built on the stack and lent; it is two words and no allocation.

pub fn try_for_each<E>( &self, f: impl FnMut(&Value) -> Result<(), E>, ) -> Result<(), E>

Seq::for_each for a walk that can fail, which is what a wire encoder is.

pub fn as_values(&self) -> Cow<'_, [Value]>

The elements as a slice, borrowed when the layout allows and materialised when it does not.

pub fn min(&self) -> Option<Value>

The smallest element, and the largest — over the dense buffer where there is one.

This is the half of 105 §105.10’s aggregate row that costs nothing to take: min over an Ints column is a pass over i64s with no Value built at all, where the boxed form builds one per element to compare it.

pub fn max(&self) -> Option<Value>

pub fn is_column(&self) -> bool

Whether this list is stored as a column — for a gate and for a report, never for a decision about what a program means.

pub fn heap_bytes(&self) -> usize

What this list occupies on the heap, in bytes, not counting anything its elements point at.

The number the second layout exists to move, so it is readable rather than inferred.

pub fn push(&mut self, value: Value)

Add one element to the end.

An empty list promotes to the layout its first element fits, which is what gives the accumulator idiom a column; a list that already has elements keeps its layout, or falls back to Seq::Boxed once for an element that does not fit. Both are O(1) amortised. What is deliberately not here is a re-examination of a boxed list on every push: that would be the quadratic 70 removed from this idiom, put straight back.

pub fn extend(&mut self, other: &Seq)

Add every element of another list to the end.

pub fn slice(&self, from: usize, to: usize) -> Seq

A range of the elements, as a list of its own.

pub fn set(&mut self, i: usize, value: Value)

Replace one element, keeping the layout where the new element fits it.

Trait Implementations

impl Clone for Seq

fn clone(&self) -> Seq

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Seq

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

Formats the value using the given formatter.

impl Default for Seq

fn default() -> Seq

Returns the “default value” for a type.

impl From<Vec<Value>> for Seq

fn from(v: Vec<Value>) -> Seq

Converts to this type from the input type.

impl FromIterator<Value> for Seq

fn from_iter<I: IntoIterator<Item = Value>>(iter: I) -> Seq

Creates a value from an iterator.

impl<'a> IntoIterator for &'a Seq

type Item = Value

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Iter<'a>

Creates an iterator from a value.

impl Ord for Seq

fn cmp(&self, other: &Seq) -> Ordering

Lexicographic over the elements, which is what Vec<Value>’s derived order was.

A Floats column is compared through Value::float, not as raw f64. The two agree on every ordinary number because the order key is monotone, and disagree on exactly the two IEEE values Value::float exists to canonicalise — NaN, which has no partial_cmp, and -0.0, which compares equal to 0.0 and hashes differently. Going through the constructor is how those two stay the one value the language says they are.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Seq

fn eq(&self, other: &Seq) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialOrd for Seq

fn partial_cmp(&self, other: &Seq) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl Eq for Seq