src/include/eina_matrixsparse.h

   1 /* EINA - EFL data type library
   2  * Copyright (C) 2009 Gustavo Sverzut Barbieri
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Lesser General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2.1 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Lesser General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Lesser General Public
  15  * License along with this library;
  16  * if not, see <http://www.gnu.org/licenses/>.
  17  */
  18
  19 #ifndef EINA_MATRIXSPARSE_H_
  20 #define EINA_MATRIXSPARSE_H_
  21
  22 #include <stdlib.h>
  23
  24 #include "eina_config.h"
  25
  26 #include "eina_types.h"
  27 #include "eina_iterator.h"
  28 #include "eina_accessor.h"
  29
  30 /**
  31  * @addtogroup Eina_Matrixsparse_Group Sparse Matrix
  32  *
  33  * @brief These functions provide matrix sparse management.
  34  *
  35  * For more information, you can look at the @ref tutorial_matrixsparse_page.
  36  */
  37
  38 /**
  39  * @addtogroup Eina_Data_Types_Group Data Types
  40  *
  41  * @{
  42  */
  43
  44 /**
  45  * @addtogroup Eina_Containers_Group Containers
  46  *
  47  * @{
  48  */
  49
  50 /**
  51  * @defgroup Eina_Matrixsparse_Group Sparse Matrix
  52  *
  53  * @{
  54  */
  55
  56 /**
  57  * @typedef Eina_Matrixsparse
  58  * Type for a generic sparse matrix.
  59  */
  60 typedef struct _Eina_Matrixsparse Eina_Matrixsparse;
  61
  62 /**
  63  * @typedef Eina_Matrixsparse_Row
  64  * Type for a generic sparse matrix row, opaque for users.
  65  */
  66 typedef struct _Eina_Matrixsparse_Row Eina_Matrixsparse_Row;
  67
  68 /**
  69  * @typedef Eina_Matrixsparse_Cell
  70  * Type for a generic sparse matrix cell, opaque for users.
  71  */
  72 typedef struct _Eina_Matrixsparse_Cell      Eina_Matrixsparse_Cell;
  73
  74 /* constructors and destructors */
  75
  76 /**
  77  * @brief Create a new Sparse Matrix.
  78  *
  79  * @param rows number of rows in matrix. Operations with rows greater than this
  80  *        value will fail.
  81  * @param cols number of columns in matrix. Operations with columns greater
  82  *        than this value will fail.
  83  * @param free_func used to delete cell data contents, used by
  84  *        eina_matrixsparse_free(), eina_matrixsparse_size_set(),
  85  *        eina_matrixsparse_row_idx_clear(),
  86  *        eina_matrixsparse_column_idx_clear(),
  87  *        eina_matrixsparse_cell_idx_clear() and possible others.
  88  * @param user_data given to @a free_func as first parameter.
  89  *
  90  * @return Newly allocated matrix or @c NULL if allocation failed and eina_error
  91  *         is set.
  92  */
  93 EAPI Eina_Matrixsparse *eina_matrixsparse_new(unsigned long rows,
  94                                               unsigned long cols,
  95                                               void (*free_func)(void *user_data,
  96                                                                 void *cell_data),
  97                                               const void *user_data);
  98
  99 /**
 100  * @brief Free resources allocated to Sparse Matrix.
 101  *
 102  * @param m The Sparse Matrix instance to free, must @b not be @c NULL.
 103  */
 104 EAPI void eina_matrixsparse_free(Eina_Matrixsparse *m);
 105
 106 /* size manipulation */
 107
 108 /**
 109  * @brief Get the current size of Sparse Matrix.
 110  *
 111  * The given parameters are guaranteed to be set if they're not @c NULL,
 112  * even if this function fails (ie: @a m is not a valid matrix instance).
 113  *
 114  * @param m the sparse matrix to operate on.
 115  * @param rows returns the number of rows, may be @c NULL. If @a m is invalid,
 116  *        returned value is zero, otherwise it's a positive integer.
 117  * @param cols returns the number of columns, may be @c NULL. If @a m is
 118  *        invalid, returned value is zero, otherwise it's a positive integer.
 119  */
 120 EAPI void eina_matrixsparse_size_get(const Eina_Matrixsparse *m,
 121                                      unsigned long           *rows,
 122                                      unsigned long           *cols);
 123
 124 /**
 125  * @brief Resize the Sparse Matrix.
 126  *
 127  * This will resize the sparse matrix, possibly freeing cells on rows
 128  * and columns that will cease to exist.
 129  *
 130  * @param m the sparse matrix to operate on.
 131  * @param rows the new number of rows, must be greater than zero.
 132  * @param cols the new number of columns, must be greater than zero.
 133  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
 134  *
 135  * @warning cells, rows or columns are not reference counted and thus
 136  *     after this call any reference might be invalid if instance were
 137  *     freed.
 138  */
 139 EAPI Eina_Bool eina_matrixsparse_size_set(Eina_Matrixsparse *m,
 140                                           unsigned long      rows,
 141                                           unsigned long      cols);
 142
 143 /* data getting */
 144
 145 /**
 146  * Get the cell reference inside Sparse Matrix.
 147  *
 148  * @param m the sparse matrix to operate on.
 149  * @param row the new number of row to clear.
 150  * @param col the new number of column to clear.
 151  * @param cell pointer to return cell reference, if any exists.
 152  *
 153  * @return @c 1 on success, @c 0 on failure. It is considered success if did not
 154  *     exist but index is inside matrix size, in this case @c *cell == NULL
 155  *
 156  * @see eina_matrixsparse_cell_data_get()
 157  * @see eina_matrixsparse_data_idx_get()
 158  */
 159 EAPI Eina_Bool eina_matrixsparse_cell_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col, Eina_Matrixsparse_Cell **cell);
 160
 161 /**
 162  * Get data associated with given cell reference.
 163  *
 164  * @param cell given cell reference, must @b not be @c NULL.
 165  *
 166  * @return data associated with given cell.
 167  *
 168  * @see eina_matrixsparse_cell_idx_get()
 169  * @see eina_matrixsparse_data_idx_get()
 170  */
 171 EAPI void     *eina_matrixsparse_cell_data_get(const Eina_Matrixsparse_Cell *cell);
 172
 173 /**
 174  * Get data associated with given cell given its indexes.
 175  *
 176  * @param m the sparse matrix to operate on.
 177  * @param row the new number of row to clear.
 178  * @param col the new number of column to clear.
 179  *
 180  * @return Data associated with given cell or @c NULL if nothing is associated.
 181  *
 182  * @see eina_matrixsparse_cell_idx_get()
 183  * @see eina_matrixsparse_cell_data_get()
 184  */
 185 EAPI void     *eina_matrixsparse_data_idx_get(const Eina_Matrixsparse *m, unsigned long row, unsigned long col);
 186
 187 /**
 188  * Get position (indexes) of the given cell.
 189  *
 190  * @param cell the cell reference, must @b not be @c NULL.
 191  * @param row where to store cell row number, may be @c NULL.
 192  * @param col where to store cell column number, may be @c NULL.
 193  *
 194  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@c cell is @c NULL).
 195  */
 196 EAPI Eina_Bool eina_matrixsparse_cell_position_get(const Eina_Matrixsparse_Cell *cell, unsigned long *row, unsigned long *col);
 197
 198 /* data setting */
 199
 200 /**
 201  * Change cell reference value without freeing the possibly existing old value.
 202  *
 203  * @param cell the cell reference, must @b not be @c NULL.
 204  * @param data new data to set.
 205  * @param p_old returns the old value intact (not freed).
 206  *
 207  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
 208  *
 209  * @see eina_matrixsparse_cell_data_set()
 210  * @see eina_matrixsparse_data_idx_replace()
 211  */
 212 EAPI Eina_Bool eina_matrixsparse_cell_data_replace(Eina_Matrixsparse_Cell *cell, const void *data, void **p_old);
 213
 214 /**
 215  * Change cell value freeing the possibly existing old value.
 216  *
 217  * In contrast to eina_matrixsparse_cell_data_replace(), this function will
 218  * call @c free_func() on existing value.
 219  *
 220  * @param cell the cell reference, must @b not be @c NULL.
 221  * @param data new data to set.
 222  *
 223  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a cell is @c NULL).
 224  *
 225  * @see eina_matrixsparse_cell_data_replace()
 226  * @see eina_matrixsparse_data_idx_set()
 227  */
 228 EAPI Eina_Bool eina_matrixsparse_cell_data_set(Eina_Matrixsparse_Cell *cell, const void *data);
 229
 230 /**
 231  * Change cell value without freeing the possibly existing old value, using
 232  * indexes.
 233  *
 234  * @param m the sparse matrix, must @b not be @c NULL.
 235  * @param row the row number to set the value.
 236  * @param col the column number to set the value.
 237  * @param data new data to set.
 238  * @param p_old returns the old value intact (not freed).
 239  *
 240  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
 241  *
 242  * @see eina_matrixsparse_cell_data_replace()
 243  * @see eina_matrixsparse_data_idx_set()
 244  */
 245 EAPI Eina_Bool eina_matrixsparse_data_idx_replace(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data, void **p_old);
 246
 247 /**
 248  * Change cell value freeing the possibly existing old value, using
 249  * indexes.
 250  *
 251  * In contrast to eina_matrixsparse_data_idx_replace(), this function will
 252  * call @c free_func() on existing value.
 253  *
 254  * @param m the sparse matrix, must @b not be @c NULL.
 255  * @param row the row number to set the value.
 256  * @param col the column number to set the value.
 257  * @param data new data to set.
 258  *
 259  * @return #EINA_TRUE on success, #EINA_FALSE otherwise (@a m is @c NULL, indexes are not valid).
 260  *
 261  * @see eina_matrixsparse_cell_data_replace()
 262  */
 263 EAPI Eina_Bool eina_matrixsparse_data_idx_set(Eina_Matrixsparse *m, unsigned long row, unsigned long col, const void *data);
 264
 265 /* data deleting */
 266
 267 /**
 268  * Clear (erase all cells) of row given its index.
 269  *
 270  * Existing cells will be cleared with @c free_func() given to
 271  * eina_matrixsparse_new().
 272  *
 273  * @param m the sparse matrix to operate on.
 274  * @param row the new number of row to clear.
 275  *
 276  * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if row
 277  *     had no cells filled. Failure is asking for clear row outside
 278  *     matrix size.
 279  *
 280  * @warning cells, rows or columns are not reference counted and thus
 281  *     after this call any reference might be invalid if instance were
 282  *     freed.
 283  */
 284 EAPI Eina_Bool eina_matrixsparse_row_idx_clear(Eina_Matrixsparse *m, unsigned long row);
 285
 286 /**
 287  * Clear (erase all cells) of column given its index.
 288  *
 289  * Existing cells will be cleared with @c free_func() given to
 290  * eina_matrixsparse_new().
 291  *
 292  * @param m the sparse matrix to operate on.
 293  * @param col the new number of column to clear.
 294  *
 295  * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if column
 296  *     had no cells filled. Failure is asking for clear column outside
 297  *     matrix size.
 298  *
 299  * @warning cells, rows or columns are not reference counted and thus
 300  *     after this call any reference might be invalid if instance were
 301  *     freed.
 302  */
 303 EAPI Eina_Bool eina_matrixsparse_column_idx_clear(Eina_Matrixsparse *m, unsigned long col);
 304
 305 /**
 306  * Clear (erase) cell given its indexes.
 307  *
 308  * Existing cell will be cleared with @c free_func() given to
 309  * eina_matrixsparse_new().
 310  *
 311  * @param m the sparse matrix to operate on.
 312  * @param row the new number of row to clear.
 313  * @param col the new number of column to clear.
 314  *
 315  * @return #EINA_TRUE on success, #EINA_FALSE on failure. It is considered success if did not
 316  *     exist but index is inside matrix size.
 317  *
 318  * @warning cells, rows or columns are not reference counted and thus
 319  *     after this call any reference might be invalid if instance were
 320  *     freed.
 321  *
 322  * @note This call might delete container column and row if this cell was the
 323  * last remainder.
 324  */
 325 EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col);
 326
 327 /**
 328  * Clear (erase) cell given its reference.
 329  *
 330  * @param cell the cell reference, must @b not be @c NULL.
 331  *
 332  * @return #EINA_TRUE on success, #EINA_FALSE on failure.
 333  *
 334  * @warning cells, rows or columns are not reference counted and thus
 335  *     after this call any reference might be invalid if instance were
 336  *     freed.
 337  *
 338  * @note This call might delete container column and row if this cell was the
 339  * last remainder.
 340  */
 341 EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
 342
 343 /* iterators */
 344
 345 /**
 346  * Creates a new iterator over existing matrix cells.
 347  *
 348  * This is a cheap walk, it will just report existing cells and holes
 349  * in the sparse matrix will be ignored. That means the reported
 350  * indexes will not be sequential.
 351  *
 352  * The iterator data will be the cell reference, one may query current
 353  * position with eina_matrixsparse_cell_position_get() and cell value
 354  * with eina_matrixsparse_cell_data_get().
 355  *
 356  * @param m The Sparse Matrix reference, must @b not be @c NULL.
 357  * @return A new iterator.
 358  *
 359  * @warning if the matrix structure changes then the iterator becomes
 360  *    invalid! That is, if you add or remove cells this iterator
 361  *    behavior is undefined and your program may crash!
 362  */
 363 EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
 364
 365 /**
 366  * Creates a new iterator over all matrix cells.
 367  *
 368  * Unlike eina_matrixsparse_iterator_new() this one will report all
 369  * matrix cells, even those that are still empty (holes). These will
 370  * be reported as dummy cells that contains no data.
 371  *
 372  * Be aware that iterating a big matrix (1000x1000) will call your
 373  * function that number of times (1000000 times in that case) even if
 374  * your matrix have no elements at all!
 375  *
 376  * The iterator data will be the cell reference, one may query current
 377  * position with eina_matrixsparse_cell_position_get() and cell value
 378  * with eina_matrixsparse_cell_data_get(). If cell is empty then the
 379  * reference will be a dummy/placeholder, thus setting value with
 380  * eina_matrixsparse_cell_data_set() will leave pointer unreferenced.
 381  *
 382  * @param m The Sparse Matrix reference, must @b not be @c NULL.
 383  * @return A new iterator.
 384  *
 385  * @warning if the matrix structure changes then the iterator becomes
 386  *    invalid! That is, if you add or remove cells this iterator
 387  *    behavior is undefined and your program may crash!
 388  */
 389 EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matrixsparse *m);
 390
 391 /**
 392  * @}
 393  */
 394
 395 /**
 396  * @}
 397  */
 398
 399 /**
 400  * @}
 401  */
 402
 403 #endif /* EINA_MATRIXSPARSE_H_ */