1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
|
#ifndef __GAME_MATRIX__
#define __GAME_MATRIX__
#include <string.h>
#include <stdlib.h>
#include <stdbool.h>
#include <stdio.h>
#include "defs.h"
#include "DynamicArray.h"
/**
* @file
* @defgroup SMatrix SMatrix
* @addtogroup SMatrix
* @{
* A SMatrix is a 2d, rectangular array.
*/
/**
* An SMatrix is an opaque data structure representing a simple rectangular
* matrix.
*
* An SMatrix Stores pointers to data, and not the data itself.
* So when using functions like s_matrix_realloc, it only copies the pointers
* over from the old SMatrix to the new.
*/
typedef struct SMatrix SMatrix;
/**
* convenience structure to store type into and name of a tuple.
* Example:
@code{.c}
typedef enum {
MY_TUPLE_ENUM_NAME,
MY_TUPLE_ENUM_AGE,
MY_TUPLE_ENUM_HEIGHT,
MY_TUPLE_ENUM_END_OF_TUPLE
} MyRowInfoEnum;
const SMatrixRowInformation my_row_info[] = {
{"Name", S_TYPE_STRING},
{"Age", S_TYPE_UINT},
{"Height", S_TYPE_UINT}
{NULL, NULL}
};
@endcode
* The information can then be used like this:
@code{.c}
for (int i = 0, i <= s_matrix_get_last_tuple_n (my_matrix), i++) {
spointer tmp_tuple = s_matrix_get_tuple (my_matrix, i);
for (int j = 0, j <= MY_TUPLE_ENUM_END_OF_TUPLE, j++) {
s_print ("%s: %s", my_row_info[j], tmp_tuple[j]);
}
s_print ("\n");
free (tmp_tuple);
}
@endcode
*
*/
typedef struct SMatrixRowInformation {
char * name; /**< Name of the row. */
SType type; /**< Type of the row. */
} SMatrixRowInformation;
SMatrix *
s_matrix_new (size_t width, size_t height);
void
s_matrix_free (SMatrix * self, bool free_data);
/**
* Reallocate a SMatrix from one tuple width to an other.
*
* @warning The new tuple size must be larger then the last, or it will be
* turnicated, but not freed.
*
* @note You need to free the old SMatrix yourself
* <em>(but not the data stored)</em>, this is to avoid memory leaks.
*/
SMatrix *
s_matrix_realloc (SMatrix * self, size_t width);
/**
* Get element y in tuple x.
*
* Equivalent to matrix[x][y] would be in static 2d arrays.
*/
spointer
s_matrix_get (SMatrix * self, size_t x, size_t y);
/**
* Returns the number representing the last tuple.
* IE: it the last tuple has the x position of 10, this will return 10.
*
* @param self The SMatrix to get the x coordinate of the last tuple.
*
* @return The x coordinate of the last tuple.
*
* @note The value way be wrong.
*/
size_t
s_matrix_get_last_tuple_n (SMatrix self);
/**
* @brief Set data at a point [x,y] in the array.
*
* @param self The SMatrix to operate on.
* @param x The x coordinates of where to put the data.
* (What tuple to put it in).
* @param y The y coordinates to put the data in.
* (What position in the tuple to put it in).
* @param data The data to be placed in the SMatrix.
*/
void
s_matrix_set (SMatrix * self, size_t x, size_t y, spointer data);
/**
* Gets tuple x in SMatrix self.
*
* @param self the matrix to perform the operation on.
* @param x the tuple to get.
*
* @return a pointer to an array congaing painters to the data in the tuple.
*
* @see s_matrix_get_tuple_as_dynamic_array()
*/
spointer *
s_matrix_get_tuple (SMatrix * self, size_t x);
/**
* Append a tuple to a SMatrix.
*
* @param self The SMatrix to perform the operation on.
* @param tuple The <em>allocated</em> data tuple to be copied into the SMatrix.
*
* @note This function will consume (free) allocated data for the tuple.
*
* @note The function assumes that the tuple has the same width as specified
* during construction or reallocation. Any dangling pointers will
* <em>not</em> be freed.
*/
void
s_matrix_append (SMatrix * self, spointer tuple);
/**
* Get tuple x as a SDynamicArray.
*
* @param self the SMatrix to perform the operation on.
* @param x the tuple to get.
*
* @return An SDynamicArray containing pointers to the data in the tuple.
*
* @see s_matrix_get_tuple
*/
SDynamicArray *
s_matrix_get_tuple_as_dynamic_array (SMatrix * self, size_t x);
/**
* This iterates over each tuple. giving the tuple as the item in the
* callback function.
*/
void
s_matrix_foreach (SMatrix * self, ForEachFunc callback, spointer data);
/** @} */
#endif /*__GAME_MATRIX__ */
|