Sparse Matrix

- Main Page
- Related Pages
- Modules
- Namespaces
- Data Structures
- Files
- Examples

Typedefs | Functions
Sparse Matrix
Eina » Data Types » Containers

These functions provide matrix sparse management. 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_Matrixsparse * | eina_matrixsparse_new (unsigned long rows, unsigned long cols, void(*free_func)(void *user_data, void *cell_data), const void *user_data)
| Create a new Sparse Matrix. More...
void | eina_matrixsparse_free (Eina_Matrixsparse *m)
| Free resources allocated to Sparse Matrix. More...
void | eina_matrixsparse_size_get (const Eina_Matrixsparse *m, unsigned long *rows, unsigned long *cols)
| Get the current size of Sparse Matrix. More...
Eina_Bool | eina_matrixsparse_size_set (Eina_Matrixsparse *m, unsigned long rows, unsigned long cols)
| Resize the Sparse Matrix. More...
Eina_Bool | eina_matrixsparse_cell_idx_get (const Eina_Matrixsparse *m, unsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell)
| Get the cell reference inside Sparse Matrix. More...
void * | eina_matrixsparse_cell_data_get (const Eina_Matrixsparse_Cell *cell)
| Get data associated with given cell reference. More...
void * | eina_matrixsparse_data_idx_get (const Eina_Matrixsparse *m, unsigned long row, unsigned long col)
| Get data associated with given cell given its indexes. More...
Eina_Bool | eina_matrixsparse_cell_position_get (const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col)
| Get position (indexes) of the given cell. More...
Eina_Bool | eina_matrixsparse_cell_data_replace (Eina_Matrixsparse_Cell *cell, const void *data, void **p_old)
| Change cell reference value without freeing the possibly existing old value. More...
Eina_Bool | eina_matrixsparse_cell_data_set (Eina_Matrixsparse_Cell *cell, const void *data)
| Change cell value freeing the possibly existing old value. More...
Eina_Bool | eina_matrixsparse_data_idx_replace (Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old)
| Change cell value without freeing the possibly existing old value, using indexes. More...
Eina_Bool | eina_matrixsparse_data_idx_set (Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data)
| Change cell value freeing the possibly existing old value, using indexes. More...
Eina_Bool | eina_matrixsparse_row_idx_clear (Eina_Matrixsparse *m, unsigned long row)
| Clear (erase all cells) of row given its index. More...
Eina_Bool | eina_matrixsparse_column_idx_clear (Eina_Matrixsparse *m, unsigned long col)
| Clear (erase all cells) of column given its index. More...
Eina_Bool | eina_matrixsparse_cell_idx_clear (Eina_Matrixsparse *m, unsigned long row, unsigned long col)
| Clear (erase) cell given its indexes. More...
Eina_Bool | eina_matrixsparse_cell_clear (Eina_Matrixsparse_Cell *cell)
| Clear (erase) cell given its reference. More...
Eina_Iterator * | eina_matrixsparse_iterator_new (const Eina_Matrixsparse *m)
| Creates a new iterator over existing matrix cells. More...
Eina_Iterator * | eina_matrixsparse_iterator_complete_new (const Eina_Matrixsparse *m)
| Creates a new iterator over all matrix cells. More...

## Detailed Description

These functions provide matrix sparse management.

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

## Function Documentation

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

Create a new Sparse Matrix.

Parameters

  rows | number of rows in matrix. Operations with rows greater than this value will fail.
  cols | number of columns in matrix. Operations with columns greater than this value will fail.
  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.
  user_data | given to free_func as first parameter.

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

References EINA_MAGIC_SET.

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

Free resources allocated to Sparse Matrix.

Parameters

  m | The Sparse Matrix instance to free, must not be `NULL`.

References EINA_MAGIC_NONE, and EINA_MAGIC_SET.

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

Get the current size of Sparse Matrix.

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

Parameters

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

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

Resize the Sparse Matrix.

This will resize the sparse matrix, possibly freeing cells on rows and columns that will cease to exist.

Parameters

  m | the sparse matrix to operate on.
  rows | the new number of rows, must be greater than zero.
  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 after this call any reference might be invalid if instance were freed.

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

Get the cell reference inside Sparse Matrix.

Parameters

  m | the sparse matrix to operate on.
  row | the new number of row to clear.
  col | the new number of column to clear.
  cell | pointer to return cell reference, if any exists.

Returns
  `1` on success, `0` on failure. It is considered success 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()

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

Get data associated with given cell reference.

Parameters

  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()

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

Get data associated with given cell given its indexes.

Parameters

  m | the sparse matrix to operate on.
  row | the new number of row to clear.
  col | the new number of column to clear.

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_Bool eina_matrixsparse_cell_position_get | ( | const Eina_Matrixsparse_Cell * | cell,
|  | unsigned long * | row,
|  | unsigned long * | col
| ) |  |

Get position (indexes) of the given cell.

Parameters

  cell | the cell reference, must not be `NULL`.
  row | where to store cell row number, may be `NULL`.
  col | where to store cell column number, may be `NULL`.

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

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

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

Parameters

  cell | the cell reference, must not be `NULL`.
  data | new data to set.
  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_Bool eina_matrixsparse_cell_data_set | ( | Eina_Matrixsparse_Cell * | cell,
|  | const void * | data
| ) |  |

Change cell value freeing the possibly existing old value.

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

Parameters

  cell | the cell reference, must not be `NULL`.
  data | new data to set.

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

See also
  eina_matrixsparse_cell_data_replace()
  eina_matrixsparse_data_idx_set()

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

Change cell value without freeing the possibly existing old value, using indexes.

Parameters

  m | the sparse matrix, must not be `NULL`.
  row | the row number to set the value.
  col | the column number to set the value.
  data | new data to set.
  p_old | returns the old value intact (not freed).

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

See also
  eina_matrixsparse_cell_data_replace()
  eina_matrixsparse_data_idx_set()

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

Change cell value freeing the possibly existing old value, using indexes.

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

Parameters

  m | the sparse matrix, must not be `NULL`.
  row | the row number to set the value.
  col | the column number to set the value.
  data | new data to set.

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

See also
  eina_matrixsparse_cell_data_replace()

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

Clear (erase all cells) of row given its index.

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

Parameters

  m | the sparse matrix to operate on.
  row | the new number of row to clear.

Returns
  EINA_TRUE on success, EINA_FALSE on failure. It is considered success if row had no cells filled. Failure is asking for clear row outside matrix size.

Warning
  cells, rows or columns are not reference counted and thus after this call any reference might be invalid if instance were freed.

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

Clear (erase all cells) of column given its index.

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

Parameters

  m | the sparse matrix to operate on.
  col | the new number of column to clear.

Returns
  EINA_TRUE on success, EINA_FALSE on failure. It is considered success if column had no cells filled. Failure is asking for clear column outside matrix size.

Warning
  cells, rows or columns are not reference counted and thus after this call any reference might be invalid if instance were freed.

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

Clear (erase) cell given its indexes.

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

Parameters

  m | the sparse matrix to operate on.
  row | the new number of row to clear.
  col | the new number of column to clear.

Returns
  EINA_TRUE on success, EINA_FALSE on failure. It is considered success if did not exist but index is inside matrix size.

Warning
  cells, rows or columns are not reference counted and thus after this call any reference might be invalid if instance were freed.

Note
  This call might delete container column and row if this cell was the last remainder.

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

Clear (erase) cell given its reference.

Parameters

  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 after this call any reference might be invalid if instance were freed.

Note
  This call might delete container column and row if this cell was the last remainder.

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

Creates a new iterator over existing matrix cells.

This is a cheap walk, it will just report existing cells and holes in the sparse matrix will be ignored. That means the reported indexes will not be sequential.

The iterator data will be the cell reference, one may query current position with eina_matrixsparse_cell_position_get() and cell value with eina_matrixsparse_cell_data_get().

Parameters

  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_Iterator* eina_matrixsparse_iterator_complete_new | ( | const Eina_Matrixsparse * | m | ) |

Creates a new iterator over all matrix cells.

Unlike eina_matrixsparse_iterator_new() this one will report all matrix cells, even those that are still empty (holes). These will be reported as dummy cells that contains no data.

Be aware that iterating a big matrix (1000x1000) will call your function that number of times (1000000 times in that case) even if your matrix have no elements at all!

The iterator data will be the cell reference, one may query current position with eina_matrixsparse_cell_position_get() and cell value with eina_matrixsparse_cell_data_get(). If cell is empty then the reference will be a dummy/placeholder, thus setting value with eina_matrixsparse_cell_data_set() will leave pointer unreferenced.

Parameters

  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.