Tizen Native API  3.0
Sparse Matrix

These functions provide matrix sparse management.

For more information, you can look at the tutorial_matrixsparse_page.

Functions

Eina_Matrixsparseeina_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.
void eina_matrixsparse_free (Eina_Matrixsparse *m)
 Frees resources allocated to Sparse Matrix.
void eina_matrixsparse_size_get (const Eina_Matrixsparse *m, unsigned long *rows, unsigned long *cols)
 Gets the current size of Sparse Matrix.
Eina_Bool eina_matrixsparse_size_set (Eina_Matrixsparse *m, unsigned long rows, unsigned long cols)
 Resizes the Sparse Matrix.
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 Sparse Matrix.
void * eina_matrixsparse_cell_data_get (const Eina_Matrixsparse_Cell *cell)
 Gets data associated with given cell reference.
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.
Eina_Bool eina_matrixsparse_cell_position_get (const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col)
 Gets position (indexes) of the given cell.
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.
Eina_Bool eina_matrixsparse_cell_data_set (Eina_Matrixsparse_Cell *cell, const void *data)
 Changes cell value freeing the possibly existing old value.
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 without freeing the possibly existing old value, using indexes.
Eina_Bool eina_matrixsparse_data_idx_set (Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data)
 Changes cell value freeing the possibly existing old value, using indexes.
Eina_Bool eina_matrixsparse_row_idx_clear (Eina_Matrixsparse *m, unsigned long row)
 Clears (erases all cells) of row given its index.
Eina_Bool eina_matrixsparse_column_idx_clear (Eina_Matrixsparse *m, unsigned long col)
 Clears (erases all cells) of column given its index.
Eina_Bool eina_matrixsparse_cell_idx_clear (Eina_Matrixsparse *m, unsigned long row, unsigned long col)
 Clears (erases) cell given its indexes.
Eina_Bool eina_matrixsparse_cell_clear (Eina_Matrixsparse_Cell *cell)
 Clears (erases) cell given its reference.
Eina_Iteratoreina_matrixsparse_iterator_new (const Eina_Matrixsparse *m)
 Creates a new iterator over existing matrix cells.
Eina_Iteratoreina_matrixsparse_iterator_complete_new (const Eina_Matrixsparse *m)
 Creates a new iterator over all matrix cells.

Typedefs

typedef struct _Eina_Matrixsparse Eina_Matrixsparse
typedef struct
_Eina_Matrixsparse_Row 
Eina_Matrixsparse_Row
typedef struct
_Eina_Matrixsparse_Cell 
Eina_Matrixsparse_Cell

Typedef Documentation

Type for a generic sparse matrix.

Type for a generic sparse matrix cell, opaque for users.

Type for a generic sparse matrix row, opaque for users.


Function Documentation

Clears (erases) cell given its reference.

Parameters:
cellThe 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.
Since :
2.3.1

Gets data associated with given cell reference.

Parameters:
cellGiven cell reference, must not be NULL.
Returns:
Data associated with given cell.
See also:
eina_matrixsparse_cell_idx_get()
eina_matrixsparse_data_idx_get()
Since :
2.3.1
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:
cellThe cell reference, must not be NULL.
dataNew data to set.
p_oldReturns 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()
Since :
2.3.1

Changes 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:
cellThe cell reference, must not be NULL.
dataNew 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()
Since :
2.3.1
Eina_Bool eina_matrixsparse_cell_idx_clear ( Eina_Matrixsparse m,
unsigned long  row,
unsigned long  col 
)

Clears (erases) cell given its indexes.

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

Parameters:
mThe sparse matrix to operate on.
rowThe new number of row to clear.
colThe 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.
Since :
2.3.1
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 Sparse Matrix.

Parameters:
mThe sparse matrix to operate on.
rowThe new number of row to clear.
colThe new number of column to clear.
cellPointer 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()
Since :
2.3.1
Eina_Bool eina_matrixsparse_cell_position_get ( const Eina_Matrixsparse_Cell cell,
unsigned long *  row,
unsigned long *  col 
)

Gets position (indexes) of the given cell.

Parameters:
cellThe cell reference, must not be NULL.
rowWhere to store cell row number, may be NULL.
colWhere to store cell column number, may be NULL.
Returns:
EINA_TRUE on success, EINA_FALSE otherwise (cell is NULL).
Since :
2.3.1

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

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

Parameters:
mThe sparse matrix to operate on.
colThe 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.
Since :
2.3.1
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:
mThe sparse matrix to operate on.
rowThe new number of row to clear.
colThe 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()
Since :
2.3.1
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 without freeing the possibly existing old value, using indexes.

Parameters:
mThe sparse matrix, must not be NULL.
rowThe row number to set the value.
colThe column number to set the value.
dataNew data to set.
p_oldreturns 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()
Since :
2.3.1
Eina_Bool eina_matrixsparse_data_idx_set ( Eina_Matrixsparse m,
unsigned long  row,
unsigned long  col,
const void *  data 
)

Changes 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:
mThe sparse matrix, must not be NULL.
rowThe row number to set the value.
colThe column number to set the value.
dataNew 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()
Since :
2.3.1

Frees resources allocated to Sparse Matrix.

Parameters:
mThe Sparse Matrix instance to free, must not be NULL.
Since :
2.3.1

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:
mThe 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!
Since :
2.3.1

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:
mThe 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!
Since :
2.3.1
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:
rowsNumber of rows in matrix. Operations with rows greater than this value will fail.
colsNumber of columns in matrix. Operations with columns greater than this value will fail.
free_funcUsed 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_dataGiven to free_func as first parameter.
Returns:
Newly allocated matrix, or NULL if allocation failed.
Since :
2.3.1

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

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

Parameters:
mThe sparse matrix to operate on.
rowThe 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.
Since :
2.3.1
void eina_matrixsparse_size_get ( const Eina_Matrixsparse m,
unsigned long *  rows,
unsigned long *  cols 
)

Gets 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:
mThe sparse matrix to operate on.
rowsReturns the number of rows, may be NULL. If m is invalid, returned value is zero, otherwise it's a positive integer.
colsReturns the number of columns, may be NULL. If m is invalid, returned value is zero, otherwise it's a positive integer.
Since :
2.3.1
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, possibly freeing cells on rows and columns that will cease to exist.

Parameters:
mThe sparse matrix to operate on.
rowsThe new number of rows, must be greater than zero.
colsThe 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.
Since :
2.3.1