diff options
Diffstat (limited to 'libraries/eina/src/include/eina_matrixsparse.h')
-rw-r--r-- | libraries/eina/src/include/eina_matrixsparse.h | 399 |
1 files changed, 0 insertions, 399 deletions
diff --git a/libraries/eina/src/include/eina_matrixsparse.h b/libraries/eina/src/include/eina_matrixsparse.h deleted file mode 100644 index 97d1ca5..0000000 --- a/libraries/eina/src/include/eina_matrixsparse.h +++ /dev/null | |||
@@ -1,399 +0,0 @@ | |||
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 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 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 | */ | ||
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 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 | */ | ||
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 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 | */ | ||
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 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 1 on success, 0 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 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 | */ | ||
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 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 | */ | ||
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 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 | */ | ||
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 1 on success, 0 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 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 | */ | ||
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 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 | */ | ||
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 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 | */ | ||
323 | EAPI 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 | */ | ||
337 | EAPI 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 | */ | ||
359 | EAPI 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 | */ | ||
385 | EAPI 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_ */ | ||