Indexing

This file covers the indexing operations supported by slap. All of these functions are low-level and low-overhead functions that implement little to no error checking, so must be used with care. It is the responsibility of the user to perform the correct checks beforehand to avoid undefined behavior (like indexing out of bounds or de-referencing a NULL pointer).

Note

Most of these methods are implemented as static inline functions so avoid the cost of the function call (and object copy).

Getters

Use the following functions to obtain a pointer to an element of the matrix:

static inline sfloat *slap_GetElement(Matrix mat, int row, int col)

Get a pointer to matrix element given row, column indices.

Note that this method does NOT perform any bounds checking so can be used unsafely! Passing an index that is out of bounds is undefined behavior.

Example

The following gets a pointer to the 1st element in the 2nd column, and then modifies it. 

sfloat *x = slap_GetElement(A, 0, 1);
*x = 10;

To get the data directly, just de-reference the pointer at the call site: The following reads the data in the 2nd element of the 1st column. 

sfloat y = *slap_GetElement(A, 1, 0);

Parameters:

  • mat – Matrix of nonzero size

  • row – Row index

  • col – Column index

Returns:

A pointer to the element of the matrix. NULL for invalid input.

static inline const sfloat *slap_GetElementConst(const Matrix mat, int row, int col)

Get a const pointer to matrix element given row, column indices.

Example

The following gets a pointer to the 1st element in the 2nd column. 

const sfloat *x = slap_GetElementConst(A, 0, 1);

To get the data directly, just de-reference the pointer at the call site: The following reads the data in the 2nd element of the 1st column. 

sfloat y = *slap_GetElementConst(A, 1, 0);

Parameters:

  • mat – Matrix of nonzero size

  • row – Row index

  • col – Column index

Returns:

A pointer to the element of the matrix. NULL for invalid input.

Tip

The pointer from the first (non-const) function can be used to modify the element.

Setters

Use the following function to directly set elements directly.

static inline void slap_SetElement(Matrix mat, int row, int col, sfloat val)

Set an matrix element to a given value.

This is a low-level function with no error checking. As such, it should be used carefully, as it can easily result in undefined behavior.

The user should make sure the indices are within bounds and that the data pointer is valid.

Example

Set the 1st element of the 2nd column to 10.1; 

slap_SetElement(A, 0, 1, 10.1);

Parameters:

  • mat – Matrix with nonzero size and initialized data

  • row – Row index

  • col – Column index

  • val – Value to which the element should be set

Index Manipulation

Use the following methods to switch between linear and Cartesian indexing.

Terminology:

  • Cart: Cartesian, i.e. row and column

  • Linear Column-based linear index from 0 to N-1, where N is the output of slap_NumElements()

  • Index: Index into the underlying array in memory

Note that Linear and Index are the same for a “dense” matrix, and different for a strided matrix.

static inline int slap_Cart2Index(const Matrix mat, int row, int col)

Get the linear index for a given row and column in the matrix.

Converts a cartesian index of row and column into a linear index for accessing an element of the underlying data.

Supports both strided and dense matrices.

Parameters:

  • mat – Matrix with nonzero size and initialized data

  • row – Row index

  • col – Column index

Returns:

Linear index corresponding to row and col. Returns -1 for a bad input.

static inline int slap_Linear2Index(const Matrix mat, int k)

Converts a linear index to the index into the underlying array.

If the matrix is Dense (stored contiguously in memory, see slap_IsDense()), the output is the same as the input. This method is most helpful for strided matrices.

Note that for strided arrays, this method is fairly expensive since it converts the linear index into a Cartesian index, and then to the array index.

Parameters:

  • mat – A dense or strided matrix

  • k – The linear index, ranging from 0 to slap_NumElements()

Returns:

The index into mat.data corresponding the kth element of mat

void slap_Linear2Cart(Matrix mat, int k, int *row, int *col)

Converts a linear index to a Cartesian index.

This is moderately expensive, since it relies on modulus and division operations.

Passing null pointers to row and col results in undefined behavior, since this method does not check that these are valid.

Parameters:

  • mat – [in] Any matrix

  • k – [in] Linear index, from 0 to slap_NumElements()

  • row – [out] Destination for row index

  • col – [out] Destination for column index

Error Checking

static inline bool slap_CheckInbounds(Matrix mat, int row, int col)

Check if the row and column index is in the bounds of the matrix.

Parameters:

  • mat – Matrix to be indexed

  • row – Row index

  • col – Column index

Returns:

true if the row and column index is in bounds for the matrix