1 /********************************************************************\
2  * gtable.h -- glib -- basic datatype for 2D array of values        *
3  *                                                                  *
4  * This program is free software; you can redistribute it and/or    *
5  * modify it under the terms of the GNU General Public License as   *
6  * published by the Free Software Foundation; either version 2 of   *
7  * the License, or (at your option) any later version.              *
8  *                                                                  *
9  * This program 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    *
12  * GNU General Public License for more details.                     *
13  *                                                                  *
14  * You should have received a copy of the GNU General Public License*
15  * along with this program; if not, contact:                        *
16  *                                                                  *
17  * Free Software Foundation           Voice:  +1-617-542-5942       *
18  * 51 Franklin Street, Fifth Floor    Fax:    +1-617-542-2652       *
19  * Boston, MA  02110-1301,  USA       gnu@gnu.org                   *
20  *                                                                  *
21 \********************************************************************/
22 
23 #ifndef G_TABLE_H
24 #define G_TABLE_H
25 
26 #include <glib.h>
27 
28 /** @addtogroup Table Table
29  * @{
30  * @file gtable.h
31  * This is the API for GTables, a datatype for 2-dimensional tables
32  * with automatic resizing and memory management.
33  *
34  */
35 
36 typedef struct GTable GTable;
37 
38 typedef void (*g_table_entry_constructor) (gpointer entry, gpointer user_data);
39 typedef void (*g_table_entry_destroyer)   (gpointer entry, gpointer user_data);
40 
41 
42 /** Create a new table with the given entry constructor and destroyer.
43  * Both functions must be given. They are used to initialize the table
44  * entries and free unneeded memory when resizing and destroying. */
45 GTable * g_table_new (guint entry_size,
46                       g_table_entry_constructor constructor,
47                       g_table_entry_destroyer destroyer,
48                       gpointer user_data);
49 
50 /** Free the table and all associated table elements. */
51 void     g_table_destroy (GTable *gtable);
52 
53 /** Return the element at the given row and column. If the coordinates
54  * are out-of-bounds, return NULL */
55 gpointer g_table_index (GTable *gtable, int row, int col);
56 
57 /** Resize the table, allocating and deallocating extra table
58  * members if needed. The relationship between table members
59  * before and after resizing is undefined, except in the case
60  * where the number of rows changes, but not the number of
61  * columns. In that case, higher-numbered rows are discarded
62  * first. */
63 void     g_table_resize (GTable *gtable, int rows, int cols);
64 
65 /** Return the number of table rows. */
66 int      g_table_rows (GTable *gtable);
67 
68 /** Return the number of table columns. */
69 int      g_table_cols (GTable *gtable);
70 
71 /** @} */
72 #endif
73