Labels

typedef struct mts_labels_t mts_labels_t

Opaque type representing a set of labels used to carry metadata associated with an mts_block_t or an mts_tensor_t.

This is similar to a list of named tuples, but stored as a 2D array with a set of dimension 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 following functions operate on mts_labels_t:

const struct mts_labels_t *mts_labels(const char *const *dimensions, uintptr_t dimensions_count, struct mts_array_t array)

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

The array can be on any device. Data is moved to CPU internally to verify uniqueness of the labels entries.

This function allocates memory which must be released with mts_labels_free when you don’t need it anymore.

Parameters:

  • dimensions – array of NULL-terminated UTF-8 strings containing the name of each dimensions of the new labels

  • dimensions_count – number of entries in the dimensions array

  • array – the values array (2D, i32, row-major). The labels take ownership of this array.

Returns:

A pointer to the newly allocated labels, or a NULL pointer in case of error. In case of error, you can use mts_last_error() to get the error message.

const struct mts_labels_t *mts_labels_assume_unique(const char *const *names, uintptr_t names_count, struct mts_array_t array)

Create a new set of Labels from the given dimension names and values array, without checking for uniqueness of the entries.

The array can be on any device (CPU or GPU). The caller must ensure that the labels entries are unique; passing non-unique entries is invalid and can lead to crashes or infinite loops.

This function allocates memory which must be released with mts_labels_free when you don’t need it anymore.

Parameters:

  • names – array of NULL-terminated UTF-8 strings containing the names of each dimension

  • names_count – number of entries in the names array

  • array – the values array (2D, i32, row-major). The labels take ownership of this array.

Returns:

A pointer to the newly allocated labels, or a NULL pointer in case of error. In case of error, you can use mts_last_error() to get the error message.

const struct mts_labels_t *mts_labels_clone(const struct mts_labels_t *labels)

Make a copy of labels, incrementing the internal reference count.

Since mts_labels_t are immutable, the copy is actually just a reference count increase, and as such should not be an expensive operation.

mts_labels_free must be used with the returned pointer to decrease the reference count and release the memory when you don’t need it anymore.

Parameters:

  • labels – pointer to an existing set of labels

Returns:

A pointer to the newly allocated (cloned) labels, or a NULL pointer in case of error. In case of error, you can use mts_last_error() to get the error message.

mts_status_t mts_labels_free(const struct mts_labels_t *labels)

Decrease the reference count of labels, and release the corresponding memory once the reference count reaches 0.

Parameters:

  • labels – pointer to an existing set of labels, or NULL

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_dimensions(const struct mts_labels_t *labels, const char *const **names, uintptr_t *count)

Get the dimension names for the given set of labels.

Parameters:

  • labels – pointer to an existing set of labels

  • names – on output, will be set to a pointer to an array of NULL-terminated UTF-8 strings containing the names of each dimension. The array contains *count elements.

  • count – on output, will be set to the number of dimensions

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_values(const struct mts_labels_t *labels, struct mts_array_t *array)

Get the values for the given set of labels as an mts_array_t.

Parameters:

  • labels – pointer to an existing set of labels

  • array – on output, will be set to the values array. This is a non-owning view (destroy is NULL) valid as long as the labels are alive.

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_values_cpu(const struct mts_labels_t *labels, const int32_t **values, uintptr_t *count, uintptr_t *size)

Get the values for the given set of labels as an mts_array_t.

Parameters:

  • labels – pointer to an existing set of labels

  • values – on output, will be set to a pointer to the values array on CPU. The pointer is valid as long as the labels are alive, and points to the first element of a 2D array of shape (count, size) stored in row-major order.

  • count – on output, will be set to the number of entries (rows) in the labels

  • size – on output, will be set to the size of each entry in the labels (number of dimensions)

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_position(const struct mts_labels_t *labels, const int32_t *values, uintptr_t values_count, int64_t *result)

Get the position of the entry defined by the values array in the given set of labels.

Parameters:

  • labels – pointer to an existing set of labels

  • values – array containing the label to lookup

  • values_count – size of the values array

  • result – position of the values in the labels or -1 if the values were not found

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_union(const struct mts_labels_t *first, const struct mts_labels_t *second, const struct mts_labels_t **result, int64_t *first_mapping, uintptr_t first_mapping_count, int64_t *second_mapping, uintptr_t second_mapping_count)

Take the union of two sets of labels.

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

This function allocates memory for *result which must be released with mts_labels_free when you don’t need it anymore.

Parameters:

  • first – pointer to the first set of labels

  • second – pointer to the second set of labels

  • result – on output, will be set to a pointer to the newly allocated labels containing the union

  • first_mapping – if you want the mapping from the positions of entries in first to the positions in result, this should be a pointer to an array containing first.count elements, to be filled by this function. Otherwise it should be a NULL pointer.

  • first_mapping_count – number of elements in the first_mapping array

  • second_mapping – if you want the mapping from the positions of entries in second to the positions in result, this should be a pointer to an array containing second.count elements, to be filled by this function. Otherwise it should be a NULL pointer.

  • second_mapping_count – number of elements in the second_mapping array

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_intersection(const struct mts_labels_t *first, const struct mts_labels_t *second, const struct mts_labels_t **result, int64_t *first_mapping, uintptr_t first_mapping_count, int64_t *second_mapping, uintptr_t second_mapping_count)

Take the intersection of two sets of labels.

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

This function allocates memory for *result which must be released with mts_labels_free when you don’t need it anymore.

Parameters:

  • first – pointer to the first set of labels

  • second – pointer to the second set of labels

  • result – on output, will be set to a pointer to the newly allocated labels containing the intersection

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

  • first_mapping_count – number of elements in the first_mapping array

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

  • second_mapping_count – number of elements in the second_mapping array

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_difference(const struct mts_labels_t *first, const struct mts_labels_t *second, const struct mts_labels_t **result, int64_t *first_mapping, uintptr_t first_mapping_count)

Take the difference of two sets of labels.

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

This function allocates memory for *result which must be released with mts_labels_free when you don’t need it anymore.

Parameters:

  • first – pointer to the first set of labels

  • second – pointer to the second set of labels

  • result – on output, will be set to a pointer to the newly allocated labels containing the difference

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

  • first_mapping_count – number of elements in the first_mapping array

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.

mts_status_t mts_labels_select(const struct mts_labels_t *labels, const struct mts_labels_t *selection, int64_t *selected, uintptr_t *selected_count)

Select entries in the labels that match the selection.

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

All entries in the 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 the labels will be ignored.

Parameters:

  • labels – pointer to an existing set of labels

  • selection – pointer to labels defining 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.

Returns:

The status code of this operation. If the status is not MTS_SUCCESS, you can use mts_last_error() to get the full error message.