This group discusses the functions to provide matrix sparse management.

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)
	Creates a new Sparse Matrix.
void	eina_matrixsparse_free (Eina_Matrixsparse *m)
	Frees resources allocated to the Sparse Matrix.
void	eina_matrixsparse_size_get (const Eina_Matrixsparse m, unsigned long rows, unsigned long *cols)
	Gets the current size of the 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 the Sparse Matrix.
void *	eina_matrixsparse_cell_data_get (const Eina_Matrixsparse_Cell *cell)
	Gets the data associated to the given cell reference.
void *	eina_matrixsparse_data_idx_get (const Eina_Matrixsparse *m, unsigned long row, unsigned long col)
	Gets the data associated to the given cell given that its indexes are provided.
Eina_Bool	eina_matrixsparse_cell_position_get (const Eina_Matrixsparse_Cell cell, unsigned long row, unsigned long *col)
	Gets the position (indexes) of the given cell.
Eina_Bool	eina_matrixsparse_cell_data_replace (Eina_Matrixsparse_Cell cell, const void data, void **p_old)
	Changes the cell reference value without freeing a possible existing old value.
Eina_Bool	eina_matrixsparse_cell_data_set (Eina_Matrixsparse_Cell cell, const void data)
	Changes the cell value by freeing a possible 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 the cell value without freeing a possible 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 the cell value by freeing a possible existing old value, using indexes.
Eina_Bool	eina_matrixsparse_row_idx_clear (Eina_Matrixsparse *m, unsigned long row)
	Clears (erases) all the cells of the row given that its index is provided.
Eina_Bool	eina_matrixsparse_column_idx_clear (Eina_Matrixsparse *m, unsigned long col)
	Clears (erases) all the cells of the column given that its index is provided.
Eina_Bool	eina_matrixsparse_cell_idx_clear (Eina_Matrixsparse *m, unsigned long row, unsigned long col)
	Clears (erases) a cell given that its indexes are provided.
Eina_Bool	eina_matrixsparse_cell_clear (Eina_Matrixsparse_Cell *cell)
	Clears (erases) a cell given that its referenceis provided.
Eina_Iterator *	eina_matrixsparse_iterator_new (const Eina_Matrixsparse *m)
	Creates a new iterator over existing matrix cells.
Eina_Iterator *	eina_matrixsparse_iterator_complete_new (const Eina_Matrixsparse *m)
	Creates a new iterator over all the matrix cells.
Typedefs
typedef struct _Eina_Matrixsparse	Eina_Matrixsparse
	The structure type for a generic sparse matrix.
typedef struct _Eina_Matrixsparse_Row	Eina_Matrixsparse_Row
	The structure type for a generic sparse matrix row, opaque for users.
typedef struct _Eina_Matrixsparse_Cell	Eina_Matrixsparse_Cell
	The structure type for a generic sparse matrix cell, opaque for users.

Function Documentation

Eina_Bool eina_matrixsparse_cell_clear ( Eina_Matrixsparse_Cell * cell )

Clears (erases) a cell given that its referenceis provided.

Since :: 2.3.1

Remarks:: The cells, rows, or columns are not reference counted and thus after this call any reference might be invalid if an instance is freed.; This call might delete a container column and row if this cell is the last remainder.

Parameters:

[in] cell The cell reference, must not be NULL

Returns:: EINA_TRUE on success, otherwise EINA_FALSE on failure

void* eina_matrixsparse_cell_data_get ( const Eina_Matrixsparse_Cell * cell )

Gets the data associated to the given cell reference.

Since :: 2.3.1

Parameters:

[in] cell The given cell reference, must not be NULL

Returns:: The data associated to the given cell

See also:: eina_matrixsparse_cell_idx_get(); eina_matrixsparse_data_idx_get()

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

Changes the cell reference value without freeing a possible existing old value.

Since :: 2.3.1

Parameters:

[in]	cell	The cell reference, must not be `NULL`
[in]	data	The new data to set
[out]	p_old	The old value that is intact (not freed)

Returns:: EINA_TRUE on success, otherwise EINA_FALSE (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
	)

Changes the cell value by freeing a possible existing old value.

Since :: 2.3.1

Remarks:: In contrast to eina_matrixsparse_cell_data_replace(), this function calls free_func() on the existing value.

Parameters:

[in]	cell	The cell reference, must not be `NULL`
[in]	data	The new data to set

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

See also:: eina_matrixsparse_cell_data_replace(); eina_matrixsparse_data_idx_set()

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

Clears (erases) a cell given that its indexes are provided.

Since :: 2.3.1

Remarks:: Existing cells are cleared with free_func() given to eina_matrixsparse_new().; The cells, rows, or columns are not reference counted and thus after this call any reference might be invalid if an instance is freed.; This call might delete a container column and row if this cell is the last remainder.

Parameters:

[in]	m	The sparse matrix to operate on
[in]	row	The new row number to clear
[in]	col	The new column number to clear

Returns:: EINA_TRUE on success, otherwise EINA_FALSE on failure
It is considered successful if it does not exist but its index is inside the matrix size.

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.

Since :: 2.3.1

Parameters:

[in]	m	The sparse matrix to operate on
[in]	row	The new row number to clear
[in]	col	The new column number to clear
[out]	cell	A pointer to return the cell reference, if it exists

Returns:: 1 on success, otherwise 0 on failure
It is considered successful if it does not exist but its index is inside the matrix size, in this case *cell == NULL

See also:: eina_matrixsparse_cell_data_get(); eina_matrixsparse_data_idx_get()

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

Gets the position (indexes) of the given cell.

Since :: 2.3.1

Parameters:

[in]	cell	The cell reference, must not be `NULL`
[out]	row	The location to store the cell row number, may be `NULL`
[out]	col	The location to store the column number, may be `NULL`

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

Eina_Bool eina_matrixsparse_column_idx_clear	(	Eina_Matrixsparse *	m,
		unsigned long	col
	)

Clears (erases) all the cells of the column given that its index is provided.

Since :: 2.3.1

Remarks:: Existing cells are cleared with free_func() given to eina_matrixsparse_new().; The cells, rows, or columns are not reference counted and thus after this call any reference might be invalid if an instance is freed.

Parameters:

[in]	m	The sparse matrix to operate on
[in]	col	The new column number to clear

Returns:: EINA_TRUE on success, otherwise EINA_FALSE on failure
It is considered successful if the column has no filled cells
Failure is asking for a clear column outside the matrix size.

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

Gets the data associated to the given cell given that its indexes are provided.

Since :: 2.3.1

Parameters:

[in]	m	The sparse matrix to operate on
[in]	row	The new row number to clear
[in]	col	The new column number to clear

Returns:: The data associated to the given cell, otherwise NULL if nothing is associated

See also:: eina_matrixsparse_cell_idx_get(); eina_matrixsparse_cell_data_get()

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

Changes the cell value without freeing a possible existing old value, using indexes.

Since :: 2.3.1

Parameters:

[in]	m	The sparse matrix, must not be `NULL`
[in]	row	The row number to set the value of
[in]	col	The column number to set the value of
[in]	data	The new data to set
[out]	p_old	The old value that is intact (not freed)

Returns:: EINA_TRUE on success, otherwise EINA_FALSE (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
	)

Changes the cell value by freeing a possible existing old value, using indexes.

Since :: 2.3.1

Remarks:: In contrast to eina_matrixsparse_data_idx_replace(), this function calls free_func() on the existing value.

Parameters:

[in]	m	The sparse matrix, must not be `NULL`
[in]	row	The row number to set the value of
[in]	col	The column number to set the value of
[in]	data	The new data to set

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

See also:: eina_matrixsparse_cell_data_replace()

void eina_matrixsparse_free ( Eina_Matrixsparse * m )

Frees resources allocated to the Sparse Matrix.

Since :: 2.3.1

Parameters:

[in] m The Sparse Matrix instance to free, must not be NULL

Eina_Iterator* eina_matrixsparse_iterator_complete_new ( const Eina_Matrixsparse * m )

Creates a new iterator over all the matrix cells.

Since :: 2.3.1

Remarks:: Unlike eina_matrixsparse_iterator_new(), this one reports all the matrix cells, even those that are still empty (holes). These are reported as dummy cells that contain no data.; Be aware that iterating a big matrix (1000x1000) calls your function that number of times (1000000 times in that case) even if your matrix have no elements at all.; The iterator data is the cell reference, one may query the current position with eina_matrixsparse_cell_position_get() and cell value with eina_matrixsparse_cell_data_get(). If the cell is empty then the reference is a dummy/placeholder, thus setting a value with eina_matrixsparse_cell_data_set() leaves the pointer unreferenced.; If the matrix structure changes then the iterator becomes invalid. That is, if you add or remove cells this iterator's behavior is undefined and your program may crash.

Parameters:

[in] m The Sparse Matrix reference, must not be NULL

Returns:: A new iterator

Eina_Iterator* eina_matrixsparse_iterator_new ( const Eina_Matrixsparse * m )

Creates a new iterator over existing matrix cells.

Since :: 2.3.1

Remarks:: This is a cheap walk, it just reports existing cells and holes in the sparse matrix are ignored. That means the reported indexes are not sequential.; The iterator data is the cell reference, one may query the current position with eina_matrixsparse_cell_position_get() and cell value with eina_matrixsparse_cell_data_get().; If the matrix structure changes then the iterator becomes invalid. That is, if you add or remove cells this iterator's behavior is undefined and your program may crash.

Parameters:

[in] m The Sparse Matrix reference, must not be NULL

Returns:: A new iterator

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.

Since :: 2.3.1

Parameters:

[in]	rows	The number of rows in the matrix Operations with rows greater than this value fail.
[in]	cols	The number of columns in the matrix Operations with columns greater than this value fail.
[in]	free_func	The function 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 other possible functions.
[in]	user_data	The data given to free_func as the first parameter

Returns:: The newly allocated matrix, otherwise NULL if allocation fails and eina_error is set

Eina_Bool eina_matrixsparse_row_idx_clear	(	Eina_Matrixsparse *	m,
		unsigned long	row
	)

Clears (erases) all the cells of the row given that its index is provided.

Since :: 2.3.1

Remarks:: Existing cells are cleared with free_func() given to eina_matrixsparse_new().; The cells, rows, or columns are not reference counted and thus after this call any reference might be invalid if an instance is freed.

Parameters:

[in]	m	The sparse matrix to operate on
[in]	row	The new row number to clear

Returns:: EINA_TRUE on success, otherwise EINA_FALSE on failure
It is considered successful if the row has no filled cells
Failure is asking for a clear row outside the matrix size.

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

Gets the current size of the Sparse Matrix.

Since :: 2.3.1

Remarks:: 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:

[in]	m	The sparse matrix to operate on
[out]	rows	The number of rows, may be `NULL` If m is invalid the returned value is zero, otherwise it's a positive integer.
[out]	cols	The number of columns, may be `NULL` If m is invalid the 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
	)

Resizes the Sparse Matrix.

This resizes the sparse matrix, possibly freeing cells of rows and columns that cease to exist.

Since :: 2.3.1

Remarks:: The cells, rows, or columns are not reference counted and thus after this call any reference might be invalid if the instance is freed.

Parameters:

[in]	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, otherwise EINA_FALSE on failure

Functions

Typedefs

Function Documentation