aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/libraries/eina/src/include/eina_matrixsparse.h
diff options
context:
space:
mode:
authorDavid Walter Seikel2012-01-04 18:41:13 +1000
committerDavid Walter Seikel2012-01-04 18:41:13 +1000
commitdd7595a3475407a7fa96a97393bae8c5220e8762 (patch)
treee341e911d7eb911a51684a7412ef7f7c7605d28e /libraries/eina/src/include/eina_matrixsparse.h
parentAdd the skeleton. (diff)
downloadSledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.zip
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.gz
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.bz2
SledjHamr-dd7595a3475407a7fa96a97393bae8c5220e8762.tar.xz
Add the base Enlightenment Foundation Libraries - eina, eet, evas, ecore, embryo, and edje.
Note that embryo wont be used, but I'm not sure yet if you can build edje without it.
Diffstat (limited to 'libraries/eina/src/include/eina_matrixsparse.h')
-rw-r--r--libraries/eina/src/include/eina_matrixsparse.h399
1 files changed, 399 insertions, 0 deletions
diff --git a/libraries/eina/src/include/eina_matrixsparse.h b/libraries/eina/src/include/eina_matrixsparse.h
new file mode 100644
index 0000000..97d1ca5
--- /dev/null
+++ b/libraries/eina/src/include/eina_matrixsparse.h
@@ -0,0 +1,399 @@
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 */
60typedef struct _Eina_Matrixsparse Eina_Matrixsparse;
61
62/**
63 * @typedef Eina_Matrixsparse_Row
64 * Type for a generic sparse matrix row, opaque for users.
65 */
66typedef 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 */
72typedef 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 NULL if allocation failed and eina_error
91 * is set.
92 */
93EAPI 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 */
104EAPI 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 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 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 NULL. If @a m is
118 * invalid, returned value is zero, otherwise it's a positive integer.
119 */
120EAPI 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 1 on success, 0 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 */
139EAPI 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 1 on success, 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 */
159EAPI 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 */
171EAPI 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 NULL if nothing is associated.
181 *
182 * @see eina_matrixsparse_cell_idx_get()
183 * @see eina_matrixsparse_cell_data_get()
184 */
185EAPI 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 1 on success, 0 otherwise (@c cell is @c NULL).
195 */
196EAPI 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 1 on success, 0 otherwise (@a cell is @c NULL).
208 *
209 * @see eina_matrixsparse_cell_data_set()
210 * @see eina_matrixsparse_data_idx_replace()
211 */
212EAPI 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 1 on success, 0 otherwise (@a cell is @c NULL).
224 *
225 * @see eina_matrixsparse_cell_data_replace()
226 * @see eina_matrixsparse_data_idx_set()
227 */
228EAPI 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 1 on success, 0 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 */
245EAPI 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 1 on success, 0 otherwise (@a m is @c NULL, indexes are not valid).
260 *
261 * @see eina_matrixsparse_cell_data_replace()
262 */
263EAPI 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 1 on success, 0 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 */
284EAPI 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 1 on success, 0 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 */
303EAPI 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 1 on success, 0 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. Note that this call might delete container column and
321 * row if this cell was the last remainder.
322 */
323EAPI Eina_Bool eina_matrixsparse_cell_idx_clear(Eina_Matrixsparse *m, unsigned long row, unsigned long col);
324
325/**
326 * Clear (erase) cell given its reference.
327 *
328 * @param cell the cell reference, must @b not be @c NULL.
329 *
330 * @return 1 on success, 0 on failure.
331 *
332 * @warning cells, rows or columns are not reference counted and thus
333 * after this call any reference might be invalid if instance were
334 * freed. Note that this call might delete container column and
335 * row if this cell was the last remainder.
336 */
337EAPI Eina_Bool eina_matrixsparse_cell_clear(Eina_Matrixsparse_Cell *cell);
338
339/* iterators */
340
341/**
342 * Creates a new iterator over existing matrix cells.
343 *
344 * This is a cheap walk, it will just report existing cells and holes
345 * in the sparse matrix will be ignored. That means the reported
346 * indexes will not be sequential.
347 *
348 * The iterator data will be the cell reference, one may query current
349 * position with eina_matrixsparse_cell_position_get() and cell value
350 * with eina_matrixsparse_cell_data_get().
351 *
352 * @param m The Sparse Matrix reference, must @b not be @c NULL.
353 * @return A new iterator.
354 *
355 * @warning if the matrix structure changes then the iterator becomes
356 * invalid! That is, if you add or remove cells this iterator
357 * behavior is undefined and your program may crash!
358 */
359EAPI Eina_Iterator *eina_matrixsparse_iterator_new(const Eina_Matrixsparse *m);
360
361/**
362 * Creates a new iterator over all matrix cells.
363 *
364 * Unlike eina_matrixsparse_iterator_new() this one will report all
365 * matrix cells, even those that are still empty (holes). These will
366 * be reported as dummy cells that contains no data.
367 *
368 * Be aware that iterating a big matrix (1000x1000) will call your
369 * function that number of times (1000000 times in that case) even if
370 * your matrix have no elements at all!
371 *
372 * The iterator data will be the cell reference, one may query current
373 * position with eina_matrixsparse_cell_position_get() and cell value
374 * with eina_matrixsparse_cell_data_get(). If cell is empty then the
375 * reference will be a dummy/placeholder, thus setting value with
376 * eina_matrixsparse_cell_data_set() will leave pointer unreferenced.
377 *
378 * @param m The Sparse Matrix reference, must @b not be @c NULL.
379 * @return A new iterator.
380 *
381 * @warning if the matrix structure changes then the iterator becomes
382 * invalid! That is, if you add or remove cells this iterator
383 * behavior is undefined and your program may crash!
384 */
385EAPI Eina_Iterator *eina_matrixsparse_iterator_complete_new(const Eina_Matrixsparse *m);
386
387/**
388 * @}
389 */
390
391/**
392 * @}
393 */
394
395/**
396 * @}
397 */
398
399#endif /* EINA_MATRIXSPARSE_H_ */