Sparse Matrix

Typedefs | Functions
Sparse Matrix
Eina » Data Types » Containers

These functions manage sparse matrices. More...

## Typedefs
typedef struct _Eina_Matrixsparse | Eina_Matrixsparse
| Type for a generic sparse matrix.
typedef struct _Eina_Matrixsparse_Row | Eina_Matrixsparse_Row
| Type for a generic sparse matrix row, opaque for users.
typedef struct _Eina_Matrixsparse_Cell | Eina_Matrixsparse_Cell
| Type for a generic sparse matrix cell, opaque for users.

## Functions
EINA_API Eina_Matrixsparse * | eina_matrixsparse_new (unsigned long rows, unsigned long cols, void(*free_func)(void *user_data, void *cell_data), const void *user_data)
| Creates a new Sparse Matrix. More...
EINA_API void | eina_matrixsparse_free (Eina_Matrixsparse *m)
| Frees resources allocated for a Sparse Matrix. More...
EINA_API void | eina_matrixsparse_size_get (const Eina_Matrixsparse *m, unsigned long *rows, unsigned long *cols)
| Gets the current size of a Sparse Matrix. More...
EINA_API Eina_Bool | eina_matrixsparse_size_set (Eina_Matrixsparse *m, unsigned long rows, unsigned long cols)
| Resizes the Sparse Matrix. More...
EINA_API Eina_Bool | eina_matrixsparse_cell_idx_get (const Eina_Matrixsparse *m, unsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell)
| Gets the cell reference inside the Sparse Matrix. More...
EINA_API void * | eina_matrixsparse_cell_data_get (const Eina_Matrixsparse_Cell *cell)
| Gets data associated with given cell reference. More...
EINA_API void * | eina_matrixsparse_data_idx_get (const Eina_Matrixsparse *m, unsigned long row, unsigned long col)
| Gets data associated with given cell given its indexes. More...
EINA_API Eina_Bool | eina_matrixsparse_cell_position_get (const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col)
| Gets the row and column position of the given cell. More...
EINA_API Eina_Bool | eina_matrixsparse_cell_data_replace (Eina_Matrixsparse_Cell *cell, const void *data, void **p_old)
| Changes cell reference value without freeing the possibly existing old value. More...
EINA_API Eina_Bool | eina_matrixsparse_cell_data_set (Eina_Matrixsparse_Cell *cell, const void *data)
| Changes cell value, freeing any previously existing value. More...
EINA_API Eina_Bool | eina_matrixsparse_data_idx_replace (Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old)
| Changes cell value at a given row and column position, without freeing previously existing values. More...
EINA_API Eina_Bool | eina_matrixsparse_data_idx_set (Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data)
| Changes cell value at a given row and column position, freeing any previously existing value. More...
EINA_API Eina_Bool | eina_matrixsparse_row_idx_clear (Eina_Matrixsparse *m, unsigned long row)
| Clears (erases all cells) of a given row number. More...
EINA_API Eina_Bool | eina_matrixsparse_column_idx_clear (Eina_Matrixsparse *m, unsigned long col)
| Clears (erases all cells) of column given its index. More...
EINA_API Eina_Bool | eina_matrixsparse_cell_idx_clear (Eina_Matrixsparse *m, unsigned long row, unsigned long col)
| Clears (erases) cell at a given row, column position. More...
EINA_API Eina_Bool | eina_matrixsparse_cell_clear (Eina_Matrixsparse_Cell *cell)
| Clears (erases) cell given its reference. More...
EINA_API Eina_Iterator * | eina_matrixsparse_iterator_new (const Eina_Matrixsparse *m)
| Creates a new iterator over only the existing matrix cells. More...
EINA_API Eina_Iterator * | eina_matrixsparse_iterator_complete_new (const Eina_Matrixsparse *m)
| Creates a new iterator over all matrix cells. More...

## Detailed Description

These functions manage sparse matrices.

A sparse matrix stores data objects in cells within a row / column tabular structure, where the majority of cells will be empty. The sparse matrix takes advantage of this emptiness by allocating memory only for non-empty cells and, in this implementation, storing them internally in linked lists.

For more information, you can look at the Sparse Matrix Tutorial.

## Function Documentation

## ◆ eina_matrixsparse_new()

EINA_API Eina_Matrixsparse* eina_matrixsparse_new | ( | unsigned long | rows,
|  | unsigned long | cols,
|  | void(*)(void *user_data, void *cell_data) | free_func,
|  | const void * | user_data
| ) |  |

Creates a new Sparse Matrix.

Parameters

  [in] | rows | Number of rows in matrix. Operations with rows greater than this value will fail.
  [in] | cols | Number of columns in matrix. Operations with columns greater than this value will fail.
  [in] | free_func | Used to delete cell data contents, used by eina_matrixsparse_free(), eina_matrixsparse_size_set(), eina_matrixsparse_row_idx_clear(), eina_matrixsparse_column_idx_clear(), eina_matrixsparse_cell_idx_clear() and possible others.
  [in] | user_data | Given to free_func as first parameter.

Returns
  Newly allocated matrix, or `NULL` if allocation failed.

References EINA_MAGIC_SET, and EINA_SAFETY_ON_FALSE_RETURN_VAL.

## ◆ eina_matrixsparse_free()

EINA_API void eina_matrixsparse_free | ( | Eina_Matrixsparse * | m | ) |

Frees resources allocated for a Sparse Matrix.

Parameters

  [in] | m | The Sparse Matrix instance to free; must not be `NULL`.

References EINA_MAGIC_NONE, and EINA_MAGIC_SET.

## ◆ eina_matrixsparse_size_get()

EINA_API void eina_matrixsparse_size_get | ( | const Eina_Matrixsparse * | m,
|  | unsigned long * | rows,
|  | unsigned long * | cols
| ) |  |

Gets the current size of a Sparse Matrix.

The given parameters are guaranteed to be set if they're not `NULL`, even if this function fails (i.e.: m is not a valid matrix instance).

Parameters

  [in] | m | The sparse matrix to operate on.
  [out] | rows | Returns the number of rows; may be `NULL`. If m is invalid, returned value is zero, otherwise it's a positive integer.
  [out] | cols | Returns the number of columns; may be `NULL`. If m is invalid, returned value is zero, otherwise it's a positive integer.

## ◆ eina_matrixsparse_size_set()

EINA_API Eina_Bool eina_matrixsparse_size_set | ( | Eina_Matrixsparse * | m,
|  | unsigned long | rows,
|  | unsigned long | cols
| ) |  |

Resizes the Sparse Matrix.

This will resize the sparse matrix, potentially freeing cells on rows and columns that will no longer exist.

Parameters

  [in,out] | m | The sparse matrix to operate on.
  [in] | rows | The new number of rows; must be greater than zero.
  [in] | cols | The new number of columns; must be greater than zero.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

Warning
  Cells, rows or columns are not reference counted and thus references to freed instances may become invalid.

References EINA_SAFETY_ON_FALSE_RETURN_VAL.

## ◆ eina_matrixsparse_cell_idx_get()

EINA_API Eina_Bool eina_matrixsparse_cell_idx_get | ( | const Eina_Matrixsparse * | m,
|  | unsigned long | row,
|  | unsigned long | col,
|  | Eina_Matrixsparse_Cell ** | cell
| ) |  |

Gets the cell reference inside the Sparse Matrix.

Parameters

  [in] | m | The sparse matrix.
  [in] | row | The new number of row to clear.
  [in] | col | The new number of column to clear.
  [out] | cell | Pointer to return cell reference, if any exists.

Returns
  `1` on success, `0` on failure. It is considered successful if did not exist but index is inside matrix size, in this case `*cell` == NULL

See also
  eina_matrixsparse_cell_data_get()
  eina_matrixsparse_data_idx_get()

References EINA_SAFETY_ON_FALSE_RETURN_VAL, and EINA_SAFETY_ON_NULL_RETURN_VAL.

## ◆ eina_matrixsparse_cell_data_get()

EINA_API void* eina_matrixsparse_cell_data_get | ( | const Eina_Matrixsparse_Cell * | cell | ) |

Gets data associated with given cell reference.

Parameters

  [in] | cell | Given cell reference, must not be `NULL`.

Returns
  Data associated with given cell.

See also
  eina_matrixsparse_cell_idx_get()
  eina_matrixsparse_data_idx_get()

## ◆ eina_matrixsparse_data_idx_get()

EINA_API void* eina_matrixsparse_data_idx_get | ( | const Eina_Matrixsparse * | m,
|  | unsigned long | row,
|  | unsigned long | col
| ) |  |

Gets data associated with given cell given its indexes.

Parameters

  [in] | m | The sparse matrix to operate on.
  [in] | row | The row number.
  [in] | col | The column number.

Returns
  Data associated with given cell or `NULL` if nothing is associated.

See also
  eina_matrixsparse_cell_idx_get()
  eina_matrixsparse_cell_data_get()

## ◆ eina_matrixsparse_cell_position_get()

EINA_API Eina_Bool eina_matrixsparse_cell_position_get | ( | const Eina_Matrixsparse_Cell * | cell,
|  | unsigned long * | row,
|  | unsigned long * | col
| ) |  |

Gets the row and column position of the given cell.

Parameters

  [in] | cell | The cell reference; must not be `NULL`.
  [out] | row | The returned row number; may be `NULL`.
  [out] | col | The returned column number; may be `NULL`.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise (`cell` is `NULL`).

## ◆ eina_matrixsparse_cell_data_replace()

EINA_API Eina_Bool eina_matrixsparse_cell_data_replace | ( | Eina_Matrixsparse_Cell * | cell,
|  | const void * | data,
|  | void ** | p_old
| ) |  |

Changes cell reference value without freeing the possibly existing old value.

Parameters

  [in,out] | cell | The cell reference; must not be `NULL`.
  [in] | data | New data to set.
  [out] | p_old | Returns the old value intact (not freed).

Returns
  EINA_TRUE on success, EINA_FALSE otherwise (cell is `NULL`).

See also
  eina_matrixsparse_cell_data_set()
  eina_matrixsparse_data_idx_replace()

## ◆ eina_matrixsparse_cell_data_set()

EINA_API Eina_Bool eina_matrixsparse_cell_data_set | ( | Eina_Matrixsparse_Cell * | cell,
|  | const void * | data
| ) |  |

Changes cell value, freeing any previously existing value.

Parameters

  [in,out] | cell | The cell reference; must not be `NULL`.
  [in] | data | New data to set.

In contrast to eina_matrixsparse_cell_data_replace(), this function will call `free_func()` on the existing value, if one exists.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise (cell is `NULL`).

See also
  eina_matrixsparse_cell_data_replace()
  eina_matrixsparse_data_idx_set()

## ◆ eina_matrixsparse_data_idx_replace()

EINA_API Eina_Bool eina_matrixsparse_data_idx_replace | ( | Eina_Matrixsparse * | m,
|  | unsigned long | row,
|  | unsigned long | col,
|  | const void * | data,
|  | void ** | p_old
| ) |  |

Changes cell value at a given row and column position, without freeing previously existing values.

Parameters

  [in,out] | m | The sparse matrix; must not be `NULL`.
  [in] | row | The row number.
  [in] | col | The column number.
  [in] | data | New data to set.
  [out] | p_old | The previous value, returned intact (not freed).

Returns
  EINA_TRUE on success, EINA_FALSE otherwise (m is `NULL`, or row, column indexes are not valid).

See also
  eina_matrixsparse_cell_data_replace()
  eina_matrixsparse_data_idx_set()

References EINA_SAFETY_ON_FALSE_RETURN_VAL.

## ◆ eina_matrixsparse_data_idx_set()

EINA_API Eina_Bool eina_matrixsparse_data_idx_set | ( | Eina_Matrixsparse * | m,
|  | unsigned long | row,
|  | unsigned long | col,
|  | const void * | data
| ) |  |

Changes cell value at a given row and column position, freeing any previously existing value.

Parameters

  [in,out] | m | The sparse matrix, must not be `NULL`.
  [in] | row | The row number to set the value.
  [in] | col | The column number to set the value.
  [in] | data | New data to set.

In contrast to eina_matrixsparse_data_idx_replace(), this function will call `free_func()` on the existing value, if one exists.

Returns
  EINA_TRUE on success, EINA_FALSE otherwise (m is `NULL`, indexes are not valid).

See also
  eina_matrixsparse_cell_data_replace()

References EINA_SAFETY_ON_FALSE_RETURN_VAL.

## ◆ eina_matrixsparse_row_idx_clear()

EINA_API Eina_Bool eina_matrixsparse_row_idx_clear | ( | Eina_Matrixsparse * | m,
|  | unsigned long | row
| ) |  |

Clears (erases all cells) of a given row number.

Parameters

  [in,out] | m | The sparse matrix to operate on.
  [in] | row | The row number to clear.

Existing cells will be cleared with `free_func()` given to eina_matrixsparse_new().

Returns
  EINA_TRUE on success, EINA_FALSE on failure (such as requesting a row outside the matrix's defined size). It is considered successful if the row had no cells filled.

Warning
  Cells, rows or columns are not reference counted and thus references to freed instances may become invalid.

References EINA_SAFETY_ON_FALSE_RETURN_VAL.

## ◆ eina_matrixsparse_column_idx_clear()

EINA_API Eina_Bool eina_matrixsparse_column_idx_clear | ( | Eina_Matrixsparse * | m,
|  | unsigned long | col
| ) |  |

Clears (erases all cells) of column given its index.

Existing cells will be cleared with `free_func()` given to eina_matrixsparse_new().

Parameters

  [in,out] | m | The sparse matrix to operate on.
  [in] | col | The column number to clear.

Returns
  EINA_TRUE on success, EINA_FALSE on failure (such as requesting a column outside the matrix's defined size). It is considered successful if the column had no cells filled.

Warning
  Cells, rows or columns are not reference counted and thus references to freed instances may become invalid.

References EINA_SAFETY_ON_FALSE_RETURN_VAL.

## ◆ eina_matrixsparse_cell_idx_clear()

EINA_API Eina_Bool eina_matrixsparse_cell_idx_clear | ( | Eina_Matrixsparse * | m,
|  | unsigned long | row,
|  | unsigned long | col
| ) |  |

Clears (erases) cell at a given row, column position.

Existing cell will be cleared with the `free_func()` given to eina_matrixsparse_new().

Parameters

  [in,out] | m | The sparse matrix to operate on.
  [in] | row | The row number.
  [in] | col | The column number.

Returns
  EINA_TRUE on success, EINA_FALSE on failure (such as requesting a row or column outside the matrix's defined size). It is considered successful if no cell existed at the otherwise valid position.

Warning
  Cells, rows or columns are not reference counted and thus references to freed instances may become invalid.

Note
  This call might also free the column and/or row if this was the last remaining cell contained.

References EINA_SAFETY_ON_FALSE_RETURN_VAL.

## ◆ eina_matrixsparse_cell_clear()

EINA_API Eina_Bool eina_matrixsparse_cell_clear | ( | Eina_Matrixsparse_Cell * | cell | ) |

Clears (erases) cell given its reference.

Parameters

  [in,out] | cell | The cell reference; must not be `NULL`.

Returns
  EINA_TRUE on success, EINA_FALSE on failure.

Warning
  Cells, rows or columns are not reference counted and thus references to freed instances may become invalid.

Note
  This call might also free the column and/or row if this was the last remaining cell contained.

## ◆ eina_matrixsparse_iterator_new()

EINA_API Eina_Iterator* eina_matrixsparse_iterator_new | ( | const Eina_Matrixsparse * | m | ) |

Creates a new iterator over only the existing matrix cells.

This is a quick walk over the defined cells; the holes in the Sparse Matrix are skipped over, thus the returned entries will not have consecutive index numbers.

The iterator's data element will be the current cell reference. This cell's position and value can be retrieved with eina_matrixsparse_cell_position_get() and eina_matrixsparse_cell_data_get().

Parameters

  [in] | m | The Sparse Matrix reference; must not be `NULL`.

Returns
  A new iterator.

Warning
  If the matrix structure changes then the iterator becomes invalid! That is, if you add or remove cells this iterator behavior is undefined and your program may crash!

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.

## ◆ eina_matrixsparse_iterator_complete_new()

EINA_API Eina_Iterator* eina_matrixsparse_iterator_complete_new | ( | const Eina_Matrixsparse * | m | ) |

Creates a new iterator over all matrix cells.

In contrast to eina_matrixsparse_iterator_new(), this routine iterates across all row and column positions in the matrix, returning dummy cells with no data where there are empty holes.

Be aware that since this iterates over all potential elements of a Sparse Matrix, not just the elements with actual data, this can result in a very large number of function calls.

The iterator's data element will be the current cell reference. This cell's position and value can be retrieved with eina_matrixsparse_cell_position_get() and eina_matrixsparse_cell_data_get(). If the cell is empty then the reference will be a dummy/placeholder, thus setting value with eina_matrixsparse_cell_data_set() will leave the pointer unreferenced.

Parameters

  [in] | m | The Sparse Matrix reference; must not be `NULL`.

Returns
  A new iterator.

Warning
  If the matrix structure changes then the iterator becomes invalid! That is, if you add or remove cells this iterator behavior is undefined and your program may crash!

References EINA_MAGIC_SET, FUNC_ITERATOR_FREE, FUNC_ITERATOR_GET_CONTAINER, and FUNC_ITERATOR_NEXT.