Struct rerun::log::DataCell

pub struct DataCell {
    pub inner: Arc<DataCellInner>,
}

A cell’s worth of data, i.e. a uniform array of values for a given component type. This is the leaf type in our data model.

A DataCell can be constructed from either an iterable of native Components or directly from a slice of arrow data.

Behind the scenes, a DataCell is backed by an erased arrow array living on the heap, which is likely to point into a larger batch of contiguous memory that it shares with its peers. Cloning a DataCell is thus cheap (shallow, ref-counted).

Layout

A cell is an array of component instances: [C, C, C, …].

Consider this example:

let points: &[MyPoint] = &[[10.0, 10.0].into(), [20.0, 20.0].into(), [30.0, 30.0].into()];
let cell = DataCell::from(points);
// Or, alternatively:
let cell = DataCell::from_component::<MyPoint>([[10.0, 10.0], [20.0, 20.0], [30.0, 30.0]]);

The cell’s datatype is now a StructArray:

Struct([
   Field { name: "x", data_type: Float32, is_nullable: false, metadata: {} },
   Field { name: "y", data_type: Float32, is_nullable: false, metadata: {} },
])

Or, visualized as a cell within a larger table:

┌──────────────────────────────────────────────────┐
│ rerun.components.Point2D                                    │
╞══════════════════════════════════════════════════╡
│ [{x: 10, y: 10}, {x: 20, y: 20}, {x: 30, y: 30}] │
└──────────────────────────────────────────────────┘

Example

let points: &[MyPoint] = &[
    MyPoint { x: 10.0, y: 10.0 },
    MyPoint { x: 20.0, y: 20.0 },
    MyPoint { x: 30.0, y: 30.0 },
];
let _cell = DataCell::from(points);

// Or, alternatively:
let cell = DataCell::from_component::<MyPoint>([
    MyPoint { x: 10.0, y: 10.0 },
    MyPoint { x: 20.0, y: 20.0 },
    MyPoint { x: 30.0, y: 30.0 },
]);

eprintln!("{:#?}", cell.datatype());
eprintln!("{cell}");

Fields

inner: Arc<DataCellInner>

While the arrow data is already refcounted, the contents of the DataCell still have to be wrapped in an Arc to work around performance issues in arrow2.

See DataCellInner for more information.

Implementations

impl DataCell

pub fn as_ptr(&self) -> *const DataCellInner

impl DataCell

pub fn from_component_batch( batch: &dyn ComponentBatch<Name = ComponentName> ) -> Result<DataCell, SerializationError>

Builds a new DataCell from a component batch.

pub fn try_from_native<'a, C>( values: impl IntoIterator<Item = impl Into<Cow<'a, C>>> ) -> Result<DataCell, DataCellError>

where C: Component + Clone + 'a,

Builds a new DataCell from a uniform iterable of native component values.

Fails if the given iterable cannot be serialized to arrow, which should never happen when using Rerun’s built-in components.

pub fn try_from_native_sparse<'a, C>( values: impl IntoIterator<Item = Option<impl Into<Cow<'a, C>>>> ) -> Result<DataCell, DataCellError>

where C: Component + Clone + 'a,

Builds a new DataCell from a uniform iterable of native component values.

Fails if the given iterable cannot be serialized to arrow, which should never happen when using Rerun’s built-in components.

pub fn from_native<'a, C>( values: impl IntoIterator<Item = impl Into<Cow<'a, C>>> ) -> DataCell

where C: Component + Clone + 'a,

Builds a new DataCell from a uniform iterable of native component values.

Panics if the given iterable cannot be serialized to arrow, which should never happen when using Rerun’s built-in components. See Self::try_from_native for the fallible alternative.

pub fn from_native_sparse<'a, C>( values: impl IntoIterator<Item = Option<impl Into<Cow<'a, C>>>> ) -> DataCell

where C: Component + Clone + 'a,

Builds a new DataCell from a uniform iterable of native component values.

Panics if the given iterable cannot be serialized to arrow, which should never happen when using Rerun’s built-in components. See Self::try_from_native for the fallible alternative.

pub fn from_component<'a, C>( values: impl IntoIterator<Item = impl Into<C>> ) -> DataCell

where C: Component + Clone + 'a + Into<Cow<'a, C>>,

Builds a cell from an iterable of items that can be turned into a Component.

pub fn from_component_sparse<'a, C>( values: impl IntoIterator<Item = Option<impl Into<C>>> ) -> DataCell

where C: Component + Clone + 'a + Into<Cow<'a, C>>,

Builds a cell from an iterable of items that can be turned into a Component.

pub fn try_from_arrow( name: ComponentName, values: Box<dyn Array> ) -> Result<DataCell, DataCellError>

Builds a new DataCell from an arrow array.

Fails if the array is not a valid list of components.

pub fn from_arrow(name: ComponentName, values: Box<dyn Array>) -> DataCell

Builds a new DataCell from an arrow array.

Panics if the array is not a valid list of components. See Self::try_from_arrow for the fallible alternative.

pub fn from_native_empty<C>() -> DataCell

where C: Component,

Builds an empty DataCell from a native component type.

pub fn try_from_arrow_empty( name: ComponentName, datatype: DataType ) -> Result<DataCell, DataCellError>

Builds an empty DataCell from an arrow datatype.

Fails if the datatype is not a valid component type.

pub fn from_arrow_empty(name: ComponentName, datatype: DataType) -> DataCell

Builds an empty DataCell from an arrow datatype.

Panics if the datatype is not a valid component type. See Self::try_from_arrow_empty for a fallible alternative.

pub fn to_arrow(&self) -> Box<dyn Array>

Returns the contents of the cell as an arrow array (shallow clone).

Avoid using raw arrow arrays unless you absolutely have to: prefer working directly with DataCells, DataRows & DataTables instead. If you do use them, try to keep the scope as short as possible: holding on to a raw array might prevent the datastore from releasing memory from garbage collected data.

pub fn as_arrow_ref(&self) -> &(dyn Array + 'static)

Returns the contents of the cell as a reference to an arrow array.

Avoid using raw arrow arrays unless you absolutely have to: prefer working directly with DataCells, DataRows & DataTables instead. If you do use them, try to keep the scope as short as possible: holding on to a raw array might prevent the datastore from releasing memory from garbage collected data.

pub fn try_to_native<'a, C>(&'a self) -> Result<Vec<C>, DataCellError>

where C: Component + 'a,

Returns the contents of the cell as an iterator of native components.

Fails if the underlying arrow data cannot be deserialized into C.

pub fn try_to_native_mono<'a, C>(&'a self) -> Result<Option<C>, DataCellError>

where C: Component + 'a,

Returns the contents of an expected mono-component as an Option<C>.

Fails if the underlying arrow data cannot be deserialized into C.

pub fn to_native<'a, C>(&'a self) -> Vec<C>

where C: Component + 'a,

Returns the contents of the cell as an iterator of native components.

Panics if the underlying arrow data cannot be deserialized into C. See Self::try_to_native for a fallible alternative.

pub fn try_to_native_opt<'a, C>( &'a self ) -> Result<Vec<Option<C>>, DataCellError>

where C: Component + 'a,

Returns the contents of the cell as an iterator of native optional components.

Fails if the underlying arrow data cannot be deserialized into C.

pub fn to_native_opt<'a, C>(&'a self) -> Vec<Option<C>>

where C: Component + 'a,

Returns the contents of the cell as an iterator of native optional components.

Panics if the underlying arrow data cannot be deserialized into C. See Self::try_to_native_opt for a fallible alternative.

impl DataCell

pub fn component_name(&self) -> ComponentName

The name of the component type stored in the cell.

pub fn datatype(&self) -> &DataType

The type of the component stored in the cell, i.e. the cell is an array of that type.

pub fn num_instances(&self) -> u32

The length of the cell’s array, i.e. how many component instances are in the cell?

pub fn is_empty(&self) -> bool

pub fn is_dense(&self) -> bool

Returns true if the underlying array is dense (no nulls).

pub fn is_sorted_and_unique(&self) -> Result<bool, DataCellError>

Returns true if the underlying array is both sorted (increasing order) and contains only unique values.

The cell must be dense, otherwise the result of this method is undefined.

impl DataCell

pub fn compute_size_bytes(&mut self) -> bool

Compute and cache the total size (stack + heap) of the inner cell and its underlying arrow array, in bytes. This does nothing if the size has already been computed and cached before.

The caller must the sole owner of this cell, as this requires mutating an Arc under the hood. Returns false otherwise.

Beware: this is very costly!

Trait Implementations

impl Clone for DataCell

fn clone(&self) -> DataCell

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for DataCell

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

Formats the value using the given formatter.

impl Display for DataCell

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

Formats the value using the given formatter.

impl<'a, C> From<&'a [C]> for DataCell

where C: Component + Clone + 'a, &'a C: Into<Cow<'a, C>>,

fn from(values: &'a [C]) -> DataCell

Converts to this type from the input type.

impl<'a, C> From<&'a Vec<C>> for DataCell

where C: Component + Clone + 'a, &'a C: Into<Cow<'a, C>>,

fn from(c: &'a Vec<C>) -> DataCell

Converts to this type from the input type.

impl<'a, C> From<[C; 1]> for DataCell

where C: Component + Clone + 'a + Into<Cow<'a, C>>,

fn from(values: [C; 1]) -> DataCell

Converts to this type from the input type.

impl<'a, C> From<Vec<C>> for DataCell

where C: Component + Clone + 'a + Into<Cow<'a, C>>,

fn from(c: Vec<C>) -> DataCell

Converts to this type from the input type.

impl PartialEq for DataCell

fn eq(&self, rhs: &DataCell) -> bool

This method tests for self and other values to be equal, and is used by ==.

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

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

impl SizeBytes for DataCell

fn heap_size_bytes(&self) -> u64

Returns the total size of self on the heap, in bytes.

fn total_size_bytes(&self) -> u64

Returns the total size of self in bytes, accounting for both stack and heap space.

fn stack_size_bytes(&self) -> u64

Returns the total size of self on the stack, in bytes.

fn is_pod() -> bool

Is Self just plain old data?