Struct Labels

pub struct Labels { /* private fields */ }

A set of labels used to carry metadata associated with a tensor map.

This is similar to a list of named tuples, but stored as a 2D array of shape (labels.count(), labels.size()), with a of set names associated with the columns of this array. Each row/entry in this array is unique, and they are often (but not always) sorted in lexicographic order.

The main way to construct a new set of labels is to use a LabelsBuilder.

Labels are internally reference counted and immutable, so cloning a Labels should be a cheap operation.

Implementations

impl Labels

pub fn new<T, const N: usize>(names: [&str; N], values: &[[T; N]]) -> Labels

where T: Copy + Into<LabelValue>,

Create a new set of Labels with the given names and values.

This is a convenience function replacing the manual use of LabelsBuilder. If you need more flexibility or incremental Labels construction, use LabelsBuilder.

Panics

If the set of names is not valid, or any of the value is duplicated

pub fn empty(names: Vec<&str>) -> Labels

Create a set of Labels with the given names, containing no entries.

pub fn single() -> Labels

Create a set of Labels containing a single entry, to be used when there is no relevant information to store.

pub fn load(path: impl AsRef<Path>) -> Result<Labels, Error>

Load Labels from the file at path

This is a convenience function calling crate::io::load_labels

pub fn load_buffer(buffer: &[u8]) -> Result<Labels, Error>

Load a TensorMap from an in-memory buffer

This is a convenience function calling crate::io::load_buffer

pub fn save(&self, path: impl AsRef<Path>) -> Result<(), Error>

Save the given tensor to the file at path

This is a convenience function calling crate::io::save

pub fn save_buffer(&self, buffer: &mut Vec<u8>) -> Result<(), Error>

Save the given tensor to an in-memory buffer

This is a convenience function calling crate::io::save_buffer

pub fn size(&self) -> usize

Get the number of entries/named values in a single label

pub fn names(&self) -> Vec<&str>

Get the names of the entries/columns in this set of labels

pub fn count(&self) -> usize

Get the total number of entries in this set of labels

pub fn is_empty(&self) -> bool

Check if this set of Labels is empty (contains no entry)

pub fn contains(&self, label: &[LabelValue]) -> bool

Check whether the given label is part of this set of labels

pub fn position(&self, value: &[LabelValue]) -> Option<usize>

Get the position (i.e. row index) of the given label in the full labels array, or None.

pub fn union( &self, other: &Labels, first_mapping: Option<&mut [i64]>, second_mapping: Option<&mut [i64]>, ) -> Result<Labels, Error>

Take the union of self with other.

If requested, this function can also give the positions in the union where each entry of the input Labels ended up.

If first_mapping (respectively second_mapping) is Some, it should contain a slice of length self.count() (respectively other.count()) that will be filled with the position of the entries in self (respectively other) in the union.

pub fn intersection( &self, other: &Labels, first_mapping: Option<&mut [i64]>, second_mapping: Option<&mut [i64]>, ) -> Result<Labels, Error>

Take the intersection of self with other.

If requested, this function can also give the positions in the intersection where each entry of the input Labels ended up.

If first_mapping (respectively second_mapping) is Some, it should contain a slice of length self.count() (respectively other.count()) that will be filled by with the position of the entries in self (respectively other) in the intersection. If an entry in self or other are not used in the intersection, the mapping for this entry will be set to -1.

pub fn difference( &self, other: &Labels, mapping: Option<&mut [i64]>, ) -> Result<Labels, Error>

Take the set difference of self with other.

If requested, this function can also give the positions in the difference where each entry of self ended up.

If mapping is Some, it should contain a slice of length self.count() that will be filled by with the position of the entries in self in the difference. If an entry is not used in the difference, the mapping for this entry will be set to -1.

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

Iterate over the entries in this set of labels

pub fn iter_fixed_size<const N: usize>(&self) -> LabelsFixedSizeIter<'_, N>

Iterate over the entries in this set of labels as fixed-size arrays

pub fn select(&self, selection: &Labels) -> Result<Vec<i64>, Error>

Select entries in these Labels that match the selection.

The selection’s names must be a subset of the names of these labels.

All entries in these Labels that match one of the entry in the selection for all the selection’s dimension will be picked. Any entry in the selection but not in these Labels will be ignored.

impl Labels

pub unsafe fn from_raw(raw: mts_labels_t) -> Labels

Create a new set of Labels from a raw mts_labels_t.

This function takes ownership of the mts_labels_t and will call mts_labels_free on it.

Safety

The raw mts_labels_t must have been returned by one of the function returning mts_labels_t in metatensor-core

Trait Implementations

impl Clone for Labels

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Labels

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

Formats the value using the given formatter.

impl Drop for Labels

fn drop(&mut self)

Executes the destructor for this type.

impl Index<usize> for Labels

type Output = [LabelValue]

The returned type after indexing.

fn index(&self, i: usize) -> &[LabelValue]

Performs the indexing (container[index]) operation.

impl<'a> IntoIterator for &'a Labels

type IntoIter = LabelsIter<'a>

Which kind of iterator are we turning this into?

type Item = &'a [LabelValue]

The type of the elements being iterated over.

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Labels

fn eq(&self, other: &Labels) -> 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 Send for Labels

impl Sync for Labels