Labels

struct mts_labels_t

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

This is similar to a list of count 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.

mts_labels_t with a non-NULL internal_ptr_ correspond to a reference-counted Rust data structure, which allow for fast lookup inside the labels with mts_labels_positions.

Public Members

void *internal_ptr_

internal: pointer to the rust Labels struct if any, null otherwise

const char *const *names

Names of the dimensions composing this set of labels. There are size elements in this array, each being a NULL terminated UTF-8 string.

const int32_t *values

Pointer to the first element of a 2D row-major array of 32-bit signed integer containing the values taken by the different dimensions in names. Each row has size elements, and there are count rows in total.

uintptr_t size

Number of dimensions/size of a single entry in the set of labels

uintptr_t count

Number entries in the set of labels

The following functions operate on mts_labels_t:

mts_status_t mts_labels_create(struct mts_labels_t *labels)

Finish the creation of mts_labels_t by associating it to Rust-owned labels.

This allows using the mts_labels_positions and mts_labels_clone functions on the mts_labels_t.

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

Parameters:

  • labels – new set of labels containing pointers to user-managed memory on input, and pointers to Rust-managed memory on output.

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_clone(struct mts_labels_t labels, struct mts_labels_t *clone)

Make a copy of labels inside clone.

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 clone to decrease the reference count and release the memory when you don’t need it anymore.

Parameters:

  • labels – set of labels with an associated Rust data structure

  • clone – empty labels, on output will contain a copy of labels

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_free(struct mts_labels_t *labels)

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

Parameters:

  • labels – set of labels with an associated Rust data structure

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(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. This operation is only available if the labels correspond to a set of Rust Labels (i.e. labels.internal_ptr_ is not NULL).

Parameters:

  • labels – set of labels with an associated Rust data structure

  • 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(struct mts_labels_t first, struct mts_labels_t second, 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 mts_labels_t.

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

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

Parameters:

  • first – first set of labels

  • second – second set of labels

  • result – empty labels, on output will contain the union of first and second

  • 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(struct mts_labels_t first, struct mts_labels_t second, 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 mts_labels_t.

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

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

Parameters:

  • first – first set of labels

  • second – second set of labels

  • result – empty labels, on output will contain the union of first and second

  • 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 first 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_select(struct mts_labels_t labels, 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 – Labels on which to run the selection

  • 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.

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_set_user_data(struct mts_labels_t labels, void *user_data, void (*user_data_delete)(void*))

Update the registered user data in labels

This function changes the registered user data in the Rust Labels to be user_data; and store the corresponding user_data_delete function to be called once the labels go out of scope.

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

Parameters:

  • labels – set of labels where we want to add user data

  • user_data – pointer to the data

  • user_data_delete – function pointer that will be used (if not NULL) to free the memory associated with data when the labels are freed.

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_user_data(struct mts_labels_t labels, void **user_data)

Get the registered user data in labels in *user_data.

If no data has been registered, *user_data will be NULL.

Parameters:

  • labels – set of labels containing user data

  • user_data – this will be set to the pointer than was registered with these labels

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.