Labels

class Labels

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

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

Public Functions

inline Labels(const std::vector<std::string> &names, const std::vector<std::initializer_list<int32_t>> &values)

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

Each entry in the values must contain names.size() elements.

auto labels = Labels({"first", "second"}, {
   {0, 1},
   {1, 4},
   {2, 1},
   {2, 3},
});

inline explicit Labels(const std::vector<std::string> &names)

Create an empty set of Labels with the given names.

inline Labels(const std::vector<std::string> &names, const int32_t *values, size_t count)

Create labels with the given names and values. values must be an array with count x names.size() elements.

inline Labels(const Labels &other)

Labels is copy-constructible.

inline Labels &operator=(const Labels &other)

Labels can be copy-assigned.

inline Labels(Labels &&other) noexcept

Labels is move-constructible.

inline Labels &operator=(Labels &&other) noexcept

Labels can be move-assigned.

inline const std::vector<const char*> &names() const

Get the names of the dimensions used in these Labels.

inline size_t count() const

Get the number of entries in this set of Labels.

This is the same as shape()[0] for the corresponding values array

inline size_t size() const

Get the number of dimensions in this set of Labels.

This is the same as shape()[1] for the corresponding values array

inline mts_labels_t as_mts_labels_t() const

Convert from this set of Labels to the C mts_labels_t

inline void *user_data() &

Get the user data pointer registered with these Labels.

If no user data have been registered, this function will return nullptr.

inline void set_user_data(LabelsUserData user_data)

Register some user data pointer with these Labels.

Any existing user data will be released (by calling the provided delete function) before overwriting with the new data.

inline int64_t position(std::initializer_list<int32_t> entry) const

Get the position of the entry in this set of Labels, or -1 if the entry is not part of these Labels.

template<size_t N>
inline int64_t position(const std::array<int32_t, N> &entry) const

Variant of Labels::position taking a fixed-size array as input.

inline int64_t position(const std::vector<int32_t> &entry) const

Variant of Labels::position taking a vector as input.

inline int64_t position(const int32_t *entry, size_t length) const

Variant of Labels::position taking a pointer and length as input.

inline const NDArray<int32_t> &values() const &

Get the array of values for these Labels.

inline Labels set_union(const Labels &other, int64_t *first_mapping = nullptr, size_t first_mapping_count = 0, int64_t *second_mapping = nullptr, size_t second_mapping_count = 0) const

Take the union of these Labels with other.

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

No user data pointer is registered with the output, even if the inputs have some.

Parameters:

• other – the Labels we want to take the union with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the union, this should be a pointer to an array containing this->count() elements, to be filled by this function. Otherwise it should be a nullptr.

• first_mapping_count – number of elements in first_mapping

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the union, this should be a pointer to an array containing other.count() elements, to be filled by this function. Otherwise it should be a nullptr.

• second_mapping_count – number of elements in second_mapping

inline Labels set_union(const Labels &other, std::vector<int64_t> &first_mapping, std::vector<int64_t> &second_mapping) const

Take the union of these Labels with other.

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

No user data pointer is registered with the output, even if the inputs have some.

Parameters:

• other – the Labels we want to take the union with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the union, this should be a vector containing this->count() elements, to be filled by this function. Otherwise it should be an empty vector.

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the union, this should be a vector containing other.count() elements, to be filled by this function. Otherwise it should be an empty vector.

inline Labels set_intersection(const Labels &other, int64_t *first_mapping = nullptr, size_t first_mapping_count = 0, int64_t *second_mapping = nullptr, size_t second_mapping_count = 0) const

Take the intersection of these Labels with other.

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

No user data pointer is registered with the output, even if the inputs have some.

Parameters:

• other – the Labels we want to take the intersection with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the intersection, this should be a pointer to an array containing this->count() elements, to be filled by this function. Otherwise it should be a nullptr. If an entry in this is not used in the intersection, the mapping will be set to -1.

• first_mapping_count – number of elements in first_mapping

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the intersection, this should be a pointer to an array containing other.count() elements, to be filled by this function. Otherwise it should be a nullptr. If an entry in other is not used in the intersection, the mapping will be set to -1.

• second_mapping_count – number of elements in second_mapping

inline Labels set_intersection(const Labels &other, std::vector<int64_t> &first_mapping, std::vector<int64_t> &second_mapping) const

Take the intersection of this Labels with other.

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

No user data pointer is registered with the output, even if the inputs have some.

Parameters:

• other – the Labels we want to take the intersection with

• first_mapping – if you want the mapping from the positions of entries in this to the positions in the intersection, this should be a vector containing this->count() elements, to be filled by this function. Otherwise it should be an empty vector. If an entry in this is not used in the intersection, the mapping will be set to -1.

• second_mapping – if you want the mapping from the positions of entries in other to the positions in the intersection, this should be a vector containing other.count() elements, to be filled by this function. Otherwise it should be an empty vector. If an entry in other is not used in the intersection, the mapping will be set to -1.

inline void select(const Labels &selection, int64_t *selected, size_t *selected_count) const

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.

Parameters:

• selection – definition of the selection criteria. Multiple entries are interpreted as a logical or operation.

• selected – on input, a pointer to an array with space for *selected_count entries. On output, the first *selected_count values will contain the index in labels of selected entries.

• selected_count – on input, size of the selected array. On output, this will contain the number of selected entries.

inline std::vector<int64_t> select(const Labels &selection) const

Select entries in these Labels that match the selection.

This function does the same thing as the one above, but allocates and return the list of selected indexes in a std::vector

inline void save(const std::string &path) const

Save Labels to the given path.

This is identical to metatensor::io::save(), and provided as a convenience API.

inline std::vector<uint8_t> save_buffer() const

Save Labels to an in-memory buffer.

This is identical to metatensor::io::save_buffer(), and provided as a convenience API.

template<typename Buffer>
inline Buffer save_buffer() const

Save Labels to an in-memory buffer.

This is identical to metatensor::io::save_buffer(), and provided as a convenience API.

Public Static Functions

static inline Labels load(const std::string &path)

Load previously saved Labels from the given path.

This is identical to metatensor::io::load_labels(), and provided as a convenience API.

static inline Labels load_buffer(const uint8_t *buffer, size_t buffer_count)

Load previously saved Labels from a in-memory buffer.

This is identical to metatensor::io::load_labels_buffer(), and provided as a convenience API.

template<typename Buffer>
static inline Labels load_buffer(const Buffer &buffer)

Load previously saved Labels from a in-memory buffer.

This is identical to metatensor::io::load_labels_buffer(), and provided as a convenience API.

---

class LabelsUserData

It is possible to store some user-provided data inside Labels, and access it later. This class is used to take ownership of the data and corresponding delete function before giving the data to metatensor.

User data inside Labels is an advanced functionality, that most users should not need to interact with.

Public Functions

inline LabelsUserData(void *data, void (*deleter)(void*))

Create LabelsUserData containing the given data.

deleter will be called when the data is dropped, and should free the corresponding memory.

LabelsUserData(const LabelsUserData &other) = delete

LabelsUserData is not copy-constructible.

LabelsUserData &operator=(const LabelsUserData &other) = delete

LabelsUserData can not be copy-assigned.

inline LabelsUserData(LabelsUserData &&other) noexcept

LabelsUserData is move-constructible.

inline LabelsUserData &operator=(LabelsUserData &&other) noexcept

LabelsUserData be move-assigned.