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