forked from enlightenment/efl
eina: Cleanup documentation for Sparse Matrix.
Summary: Revises some descriptions, polishes wording, makes punctuation and formatting more consistent, and straightens out some convoluted grammar here and there. There are a few places where the parameter documentation was incorrectly cut-and-pasted from other routines, so this is fixed. Also, in eina_matrixsparse_iterator_new() the docs say the elements are not returned sequentially, but from the context and code I think it meant to say they're not _consecutive_. Subscribers: cedric Differential Revision: https://phab.enlightenment.org/D5924 Reviewed-by: Cedric BAIL <cedric@osg.samsung.com>
This commit is contained in:
Bryce Harrington
Cedric BAIL
parent
34216aa9eb
commit
025b54ce52
|
|
@ -30,7 +30,13 @@
|
|||
/**
|
||||
* @addtogroup Eina_Matrixsparse_Group Sparse Matrix
|
||||
*
|
||||
* @brief These functions provide matrix sparse management.
|
||||
* @brief 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 @ref tutorial_matrixsparse_page.
|
||||
*/
|
||||
|
|
@ -96,25 +102,25 @@ EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
|
|||
const void *user_data);
|
||||
|
||||
/**
|
||||
* @brief Frees resources allocated for Sparse Matrix.
|
||||
* @brief Frees resources allocated for a Sparse Matrix.
|
||||
*
|
||||
* @param[in] m The Sparse Matrix instance to free, must @b not be @c NULL.
|
||||
* @param[in] m The Sparse Matrix instance to free; must @b not be @c NULL.
|
||||
*/
|
||||
EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m);
|
||||
|
||||
/* size manipulation */
|
||||
|
||||
/**
|
||||
* @brief Gets the current size of Sparse Matrix.
|
||||
* @brief Gets the current size of a Sparse Matrix.
|
||||
*
|
||||
* The given parameters are guaranteed to be set if they're not @c NULL,
|
||||
* even if this function fails (ie: @a m is not a valid matrix instance).
|
||||
* even if this function fails (i.e.: @a m is not a valid matrix instance).
|
||||
*
|
||||
* @param[in] m The sparse matrix to operate on.
|
||||
* @param[out] rows Returns the number of rows, may be @c NULL. If @a m
|
||||
* @param[out] rows Returns the number of rows; may be @c NULL. If @a m
|
||||
* is invalid, returned value is zero, otherwise it's a positive
|
||||
* integer.
|
||||
* @param[out] cols Returns the number of columns, may be @c NULL. If @a m is
|
||||
* @param[out] cols Returns the number of columns; may be @c NULL. If @a m is
|
||||
* invalid, returned value is zero, otherwise it's a positive integer.
|
||||
*/
|
||||
EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
|
||||
|
|
@ -124,28 +130,27 @@ EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
|
|||
/**
|
||||
* @brief Resizes the Sparse Matrix.
|
||||
*
|
||||
* This will resize the sparse matrix, possibly freeing cells on rows
|
||||
* and columns that will cease to exist.
|
||||
* This will resize the sparse matrix, potentially freeing cells on rows
|
||||
* and columns that will no longer exist.
|
||||
*
|
||||
* @param[out] m The sparse matrix to operate on.
|
||||
* @param[in] rows The new number of rows, must be greater than zero.
|
||||
* @param[in] cols The new number of columns, must be greater than zero.
|
||||
* @param[in,out] m The sparse matrix to operate on.
|
||||
* @param[in] rows The new number of rows; must be greater than zero.
|
||||
* @param[in] cols The new number of columns; must be greater than zero.
|
||||
* @return #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.
|
||||
* references to freed instances may become invalid.
|
||||
*/
|
||||
EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
|
||||
unsigned long rows,
|
||||
unsigned long cols);
|
||||
|
||||
/* data getting */
|
||||
/* Data getting */
|
||||
|
||||
/**
|
||||
* @brief Gets the cell reference inside Sparse Matrix.
|
||||
* @brief Gets the cell reference inside the Sparse Matrix.
|
||||
*
|
||||
* @param[in] m The sparse matrix to operate on.
|
||||
* @param[in] m The sparse matrix.
|
||||
* @param[in] row The new number of row to clear.
|
||||
* @param[in] col The new number of column to clear.
|
||||
* @param[out] cell Pointer to return cell reference, if any exists.
|
||||
|
|
@ -174,8 +179,8 @@ EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cel
|
|||
* @brief Gets data associated with given cell given its indexes.
|
||||
*
|
||||
* @param[in] m The sparse matrix to operate on.
|
||||
* @param[in] row The new number of row to clear.
|
||||
* @param[in] col The new number of column to clear.
|
||||
* @param[in] row The row number.
|
||||
* @param[in] col The column number.
|
||||
*
|
||||
* @return Data associated with given cell or @c NULL if nothing is associated.
|
||||
*
|
||||
|
|
@ -185,22 +190,23 @@ EAPI void *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cel
|
|||
EAPI void *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col);
|
||||
|
||||
/**
|
||||
* @brief Gets position (indexes) of the given cell.
|
||||
* @brief Gets the row and column position of the given cell.
|
||||
*
|
||||
* @param[in] cell The cell reference, must @b not be @c NULL.
|
||||
* @param[out] row Where to store cell row number, may be @c NULL.
|
||||
* @param[out] col Where to store cell column number, may be @c NULL.
|
||||
* @param[in] cell The cell reference; must @b not be @c NULL.
|
||||
* @param[out] row The returned row number; may be @c NULL.
|
||||
* @param[out] col The returned column number; may be @c NULL.
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL).
|
||||
*/
|
||||
EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col);
|
||||
|
||||
/* data setting */
|
||||
|
||||
/* Data setting */
|
||||
|
||||
/**
|
||||
* @brief Changes cell reference value without freeing the possibly existing old value.
|
||||
*
|
||||
* @param[in,out] cell The cell reference, must @b not be @c NULL.
|
||||
* @param[in,out] cell The cell reference; must @b not be @c NULL.
|
||||
* @param[in] data New data to set.
|
||||
* @param[out] p_old Returns the old value intact (not freed).
|
||||
*
|
||||
|
|
@ -212,13 +218,13 @@ EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell
|
|||
EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell, const void *data, void **p_old);
|
||||
|
||||
/**
|
||||
* @brief Changes cell value freeing the possibly existing old value.
|
||||
* @brief Changes cell value, freeing any previously existing value.
|
||||
*
|
||||
* @param[in,out] cell The cell reference; must @b not be @c NULL.
|
||||
* @param[in] data New data to set.
|
||||
*
|
||||
* In contrast to eina_matrixsparse_cell_data_replace(), this function will
|
||||
* call @c free_func() on existing value.
|
||||
*
|
||||
* @param[in,out] cell The cell reference, must @b not be @c NULL.
|
||||
* @param[in] data New data to set.
|
||||
* call @c free_func() on the existing value, if one exists.
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
|
||||
*
|
||||
|
|
@ -228,16 +234,17 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell,
|
|||
EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, const void *data);
|
||||
|
||||
/**
|
||||
* @brief Changes cell value without freeing the possibly existing old value, using
|
||||
* indexes.
|
||||
* @brief Changes cell value at a given row and column position, without
|
||||
* freeing previously existing values.
|
||||
*
|
||||
* @param[in,out] m The sparse matrix, must @b not be @c NULL.
|
||||
* @param[in] row The row number to set the value.
|
||||
* @param[in] col The column number to set the value.
|
||||
* @param[in,out] m The sparse matrix; must @b not be @c NULL.
|
||||
* @param[in] row The row number.
|
||||
* @param[in] col The column number.
|
||||
* @param[in] data New data to set.
|
||||
* @param[out] p_old returns the old value intact (not freed).
|
||||
* @param[out] p_old The previous value, returned intact (not freed).
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL,
|
||||
* or row, column indexes are not valid).
|
||||
*
|
||||
* @see eina_matrixsparse_cell_data_replace()
|
||||
* @see eina_matrixsparse_data_idx_set()
|
||||
|
|
@ -245,17 +252,17 @@ EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, con
|
|||
EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old);
|
||||
|
||||
/**
|
||||
* @brief Changes cell value freeing the possibly existing old value, using
|
||||
* indexes.
|
||||
*
|
||||
* In contrast to eina_matrixsparse_data_idx_replace(), this function will
|
||||
* call @c free_func() on existing value.
|
||||
* @brief Changes cell value at a given row and column position, freeing
|
||||
* any previously existing value.
|
||||
*
|
||||
* @param[in,out] m The sparse matrix, must @b not be @c NULL.
|
||||
* @param[in] row The row number to set the value.
|
||||
* @param[in] col The column number to set the value.
|
||||
* @param[in] data New data to set.
|
||||
*
|
||||
* In contrast to eina_matrixsparse_data_idx_replace(), this function will
|
||||
* call @c free_func() on the existing value, if one exists.
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
|
||||
*
|
||||
* @see eina_matrixsparse_cell_data_replace()
|
||||
|
|
@ -265,21 +272,20 @@ EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigned lon
|
|||
/* data deleting */
|
||||
|
||||
/**
|
||||
* @brief Clears (erases all cells) of row given its index.
|
||||
* @brief Clears (erases all cells) of a given row number.
|
||||
*
|
||||
* @param[in,out] m The sparse matrix to operate on.
|
||||
* @param[in] row The row number to clear.
|
||||
*
|
||||
* Existing cells will be cleared with @c free_func() given to
|
||||
* eina_matrixsparse_new().
|
||||
*
|
||||
* @param[in,out] m The sparse matrix to operate on.
|
||||
* @param[in] row The new number of row to clear.
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered successful if row
|
||||
* had no cells filled. Failure is asking for clear row outside
|
||||
* matrix size.
|
||||
* @return #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
|
||||
* after this call any reference might be invalid if instance were
|
||||
* freed.
|
||||
* references to freed instances may become invalid.
|
||||
*/
|
||||
EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned long row);
|
||||
|
||||
|
|
@ -290,70 +296,70 @@ EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned lo
|
|||
* eina_matrixsparse_new().
|
||||
*
|
||||
* @param[in,out] m The sparse matrix to operate on.
|
||||
* @param[in] col The new number of column to clear.
|
||||
* @param[in] col The column number to clear.
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered successful if column
|
||||
* had no cells filled. Failure is asking for clear column outside
|
||||
* matrix size.
|
||||
* @return #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
|
||||
* after this call any reference might be invalid if instance were
|
||||
* freed.
|
||||
* references to freed instances may become invalid.
|
||||
*/
|
||||
EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col);
|
||||
|
||||
/**
|
||||
* @brief Clears (erases) cell given its indexes.
|
||||
* @brief Clears (erases) cell at a given row, column position.
|
||||
*
|
||||
* Existing cell will be cleared with @c free_func() given to
|
||||
* Existing cell will be cleared with the @c free_func() given to
|
||||
* eina_matrixsparse_new().
|
||||
*
|
||||
* @param[in,out] m The sparse matrix to operate on.
|
||||
* @param[in] row The new number of row to clear.
|
||||
* @param[in] col The new number of column to clear.
|
||||
* @param[in] row The row number.
|
||||
* @param[in] col The column number.
|
||||
*
|
||||
* @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered successful if did not
|
||||
* exist but index is inside matrix size.
|
||||
* @return #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
|
||||
* after this call any reference might be invalid if instance were
|
||||
* freed.
|
||||
* references to freed instances may become invalid.
|
||||
*
|
||||
* @note This call might delete container column and row if this cell was the
|
||||
* last remainder.
|
||||
* @note This call might also free the column and/or row if this was the
|
||||
* last remaining cell contained.
|
||||
*/
|
||||
EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col);
|
||||
|
||||
/**
|
||||
* @brief Clears (erases) cell given its reference.
|
||||
*
|
||||
* @param[in,out] cell The cell reference, must @b not be @c NULL.
|
||||
* @param[in,out] cell The cell reference; must @b not be @c NULL.
|
||||
*
|
||||
* @return #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.
|
||||
* references to freed instances may become invalid.
|
||||
*
|
||||
* @note This call might delete container column and row if this cell was the
|
||||
* last remainder.
|
||||
* @note This call might also free the column and/or row if this was the
|
||||
* last remaining cell contained.
|
||||
*/
|
||||
EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
|
||||
|
||||
/* iterators */
|
||||
/* Iterators */
|
||||
|
||||
/**
|
||||
* @brief Creates a new iterator over existing matrix cells.
|
||||
* @brief Creates a new iterator over only the 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.
|
||||
* 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 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().
|
||||
* 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().
|
||||
*
|
||||
* @param[in] m The Sparse Matrix reference, must @b not be @c NULL.
|
||||
* @param[in] m The Sparse Matrix reference; must @b not be @c NULL.
|
||||
* @return A new iterator.
|
||||
*
|
||||
* @warning If the matrix structure changes then the iterator becomes
|
||||
|
|
@ -365,21 +371,23 @@ EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
|
|||
/**
|
||||
* @brief 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.
|
||||
* 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 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!
|
||||
* 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 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
|
||||
* 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 pointer unreferenced.
|
||||
* eina_matrixsparse_cell_data_set() will leave the pointer
|
||||
* unreferenced.
|
||||
*
|
||||
* @param[in] m The Sparse Matrix reference, must @b not be @c NULL.
|
||||
* @param[in] m The Sparse Matrix reference; must @b not be @c NULL.
|
||||
* @return A new iterator.
|
||||
*
|
||||
* @warning If the matrix structure changes then the iterator becomes
|
||||
|
|
|
|||
Loading…
Reference in New Issue