Parent Directory | Revision Log
Revision 44 - (view) (download)
1 : | ian | 17 | #if defined _cellarray_included |
2 : | #endinput | ||
3 : | #endif | ||
4 : | |||
5 : | #define _cellarray_included | ||
6 : | |||
7 : | ian | 44 | enum Array |
8 : | { | ||
9 : | Invalid_Array = 0 | ||
10 : | }; | ||
11 : | ian | 17 | /** |
12 : | * These arrays are intended to be used for a form of global storage without | ||
13 : | * requiring a #define that needs to be increased each time a person needs more | ||
14 : | * storage. | ||
15 : | * These are not designed to be used as a replacement for normal arrays, as | ||
16 : | * normal arrays are faster and should be used whenever possible. | ||
17 : | */ | ||
18 : | |||
19 : | /** | ||
20 : | * Creates a handle to a dynamically sized array. | ||
21 : | * It is very important that the cellsize you provide matches up with the buffer sizes | ||
22 : | * that you pass with subsequent Array{Get,Set,Push} calls. | ||
23 : | * | ||
24 : | * @param cellsize How many cells each entry in the array is. | ||
25 : | * @param reserved How many blank entries are created immediately when the array is created. These entries are not valid to read from until called with ArraySet. | ||
26 : | * @return Handle to the array. | ||
27 : | */ | ||
28 : | native Array:ArrayCreate(cellsize=1, reserved=32); | ||
29 : | |||
30 : | /** | ||
31 : | * Clears all entries from the array. | ||
32 : | * | ||
33 : | * @param which The array to clear. | ||
34 : | * @return 1 on success, 0 on failure. | ||
35 : | */ | ||
36 : | native ArrayClear(Array:which); | ||
37 : | |||
38 : | /** | ||
39 : | * Returns the number of elements in the array. | ||
40 : | * | ||
41 : | * @param which The array to check. | ||
42 : | * @return How many elements are in the array. | ||
43 : | */ | ||
44 : | native ArraySize(Array:which); | ||
45 : | |||
46 : | /** | ||
47 : | * Returns data within an array. | ||
48 : | * Make sure the output buffer matches the size the array was created with! | ||
49 : | * | ||
50 : | * @param which The array to retrieve the item from. | ||
51 : | * @param item The item to retrieve (zero-based). | ||
52 : | * @param output The output buffer to write. | ||
53 : | */ | ||
54 : | native ArrayGetArray(Array:which, item, any:output[]); | ||
55 : | |||
56 : | /** | ||
57 : | * Returns a single cell of data from an array. | ||
58 : | * Use this only with arrays that were created with a cellsize of 1! | ||
59 : | * | ||
60 : | * @param which The array to retrieve the item from. | ||
61 : | * @param item The item to retrieve (zero-based). | ||
62 : | * @return The value of the cell. | ||
63 : | */ | ||
64 : | native any:ArrayGetCell(Array:which, item); | ||
65 : | |||
66 : | /** | ||
67 : | * Returns a string value from an array. | ||
68 : | * | ||
69 : | * @param which The array to retrieve the item from. | ||
70 : | * @param item The item to retrieve (zero-based). | ||
71 : | * @param output The variable to store the value in. | ||
72 : | * @param size Character size of the output buffer. | ||
73 : | */ | ||
74 : | native ArrayGetString(Array:which, item, output[], size); | ||
75 : | |||
76 : | /** | ||
77 : | * Sets an item's data with that of a local buffer. | ||
78 : | * The buffer size must match what the cellsize that the array was created with! | ||
79 : | * The item must already exist, use ArrayPushArray to create a new item within the array. | ||
80 : | * | ||
81 : | * @param which The array to set the item from within. | ||
82 : | * @param item The item to set (zero-based). | ||
83 : | * @param input The input buffer to store. | ||
84 : | */ | ||
85 : | native ArraySetArray(Array:which, item, const any:input[]); | ||
86 : | |||
87 : | /** | ||
88 : | * Sets an array's single cell value. Use this only on array that were created with a cellsize of 1! | ||
89 : | * The item must already exist, use ArrayPushCell to create a new item within the array. | ||
90 : | * | ||
91 : | * @param which The array to set the item from within. | ||
92 : | * @param item The item to set (zero-based). | ||
93 : | * @param input The value to set. | ||
94 : | */ | ||
95 : | native ArraySetCell(Array:which, item, any:input); | ||
96 : | |||
97 : | /** | ||
98 : | * Sets a string value from an array. | ||
99 : | * The stored string will be truncated if it is longer than the cellsize the array was created with! | ||
100 : | * The item must already exist, use ArrayPushString to create a new item within the array. | ||
101 : | * | ||
102 : | * @param which The array to set the item from within. | ||
103 : | * @param item The item to set (zero-based). | ||
104 : | * @param input The string to set the item as. | ||
105 : | */ | ||
106 : | native ArraySetString(Array:which, item, const input[]); | ||
107 : | |||
108 : | /** | ||
109 : | * Creates a new item at the end of the array and sets its data with that of a local buffer. | ||
110 : | * The buffer size must match what the cellsize that the array was created with! | ||
111 : | * | ||
112 : | * @param which The array to add the item to. | ||
113 : | * @param input The input buffer to store. | ||
114 : | */ | ||
115 : | native ArrayPushArray(Array:which, const any:input[]); | ||
116 : | |||
117 : | /** | ||
118 : | * Creates a new item and sets the array's single cell value. | ||
119 : | * Use this only on array that were created with a cellsize of 1! | ||
120 : | * | ||
121 : | * @param which The array to add the item to. | ||
122 : | * @param input The value to set. | ||
123 : | */ | ||
124 : | native ArrayPushCell(Array:which, any:input); | ||
125 : | |||
126 : | /** | ||
127 : | * Creates a new element in the array and sets its value to the input buffer. | ||
128 : | * The stored string will be truncated if it is longer than the cellsize the array was created with! | ||
129 : | * | ||
130 : | * @param which The array to add the item to. | ||
131 : | * @param input The string to set the item as. | ||
132 : | */ | ||
133 : | native ArrayPushString(Array:which, const input[]); | ||
134 : | |||
135 : | /** | ||
136 : | * Inserts an item after the selected item. All items beyond it get shifted up 1 space. | ||
137 : | * The buffer size must match what the cellsize that the array was created with! | ||
138 : | * | ||
139 : | * @param which The array to add the item to. | ||
140 : | * @param item The item to insert after. | ||
141 : | * @param input The input buffer to store. | ||
142 : | */ | ||
143 : | native ArrayInsertArrayAfter(Array:which, item, const any:input[]); | ||
144 : | |||
145 : | /** | ||
146 : | * Inserts an item after the selected item. All items beyond it get shifted up 1 space. | ||
147 : | * Use this only on an array that was created with a cellsize of 1! | ||
148 : | * | ||
149 : | * @param which The array to add the item to. | ||
150 : | * @param item The item to insert after. | ||
151 : | * @param input The value to set. | ||
152 : | */ | ||
153 : | native ArrayInsertCellAfter(Array:which, item, any:input); | ||
154 : | |||
155 : | /** | ||
156 : | * Inserts an item after the selected item. All items beyond it get shifted up 1 space. | ||
157 : | * The stored string will be truncated if it is longer than the cellsize the array was created with! | ||
158 : | * | ||
159 : | * @param which The array to add the item to. | ||
160 : | * @param item The item to insert after. | ||
161 : | * @param input The value to set. | ||
162 : | */ | ||
163 : | native ArrayInsertStringAfter(Array:which, item, const input[]); | ||
164 : | |||
165 : | /** | ||
166 : | * Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. | ||
167 : | * The buffer size must match what the cellsize that the array was created with! | ||
168 : | * | ||
169 : | * @param which The array to add the item to. | ||
170 : | * @param item The item to insert before. | ||
171 : | * @param input The input buffer to store. | ||
172 : | */ | ||
173 : | native ArrayInsertArrayBefore(Array:which, item, const any:input[]); | ||
174 : | |||
175 : | /** | ||
176 : | * Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. | ||
177 : | * Use this only on an array that was created with a cellsize of 1! | ||
178 : | * | ||
179 : | * @param which The array to add the item to. | ||
180 : | * @param item The item to insert after. | ||
181 : | * @param input The value to set. | ||
182 : | */ | ||
183 : | native ArrayInsertCellBefore(Array:which, item, const any:input); | ||
184 : | |||
185 : | /** | ||
186 : | * Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. | ||
187 : | * The stored string will be truncated if it is longer than the cellsize the array was created with! | ||
188 : | * | ||
189 : | * @param which The array to add the item to. | ||
190 : | * @param item The item to insert before. | ||
191 : | * @param input The value to set. | ||
192 : | */ | ||
193 : | native ArrayInsertStringBefore(Array:which, item, const input[]); | ||
194 : | |||
195 : | /** | ||
196 : | * Swaps the position of two items. | ||
197 : | * | ||
198 : | * @param which The array that contains the items. | ||
199 : | * @param item1 The first item to swap. | ||
200 : | * @param item2 The second item to swap. | ||
201 : | */ | ||
202 : | native ArraySwap(Array:which, item1, item2); | ||
203 : | |||
204 : | /** | ||
205 : | * Deletes an item from the array. All items beyond it get shifted down 1 space. | ||
206 : | * | ||
207 : | * @param which The array that contains the item to delete. | ||
208 : | * @param item The item to delete. | ||
209 : | */ | ||
210 : | native ArrayDeleteItem(Array:which, item); | ||
211 : | |||
212 : | /** | ||
213 : | * Creates a handle that is passable to a format compliant routine for printing as a string (with the %a format option). | ||
214 : | * It is suggested to pass the function directly as a parameter to the format routine. | ||
215 : | * The array contents must be a null-terminated string! | ||
216 : | * | ||
217 : | * An example usage: client_print(id, print_chat, "%a", ArrayGetStringHandle(MessageArray, i)); | ||
218 : | * | ||
219 : | * @param which The array the string is stored in. | ||
220 : | * @param item Which item to print the string value of. | ||
221 : | * @return Handle to the item directly. Do not use or save stale handles. | ||
222 : | */ | ||
223 : | native DoNotUse:ArrayGetStringHandle(Array:which, item); | ||
224 : | |||
225 : | /** | ||
226 : | * Destroys the array, and resets the handle to 0 to prevent accidental usage after it is destroyed. | ||
227 : | * | ||
228 : | * @param which The array to destroy. | ||
229 : | */ | ||
230 : | native ArrayDestroy(&Array:which); | ||
231 : | |||
232 : | |||
233 : | |||
234 : | /** | ||
235 : | * Similar to sorting.inc's CustomSort. | ||
236 : | * The sorting algorithm then uses your comparison function to sort the data. | ||
237 : | * The function is called in the following manner: | ||
238 : | * | ||
239 : | * public MySortFunc(Array:array, item1, item2, const data[], data_size) | ||
240 : | * | ||
241 : | * array - Array handle in its current un-sorted state. | ||
242 : | * item1, item2 - Current item pair being compared | ||
243 : | * data[] - Extra data array you passed to the sort func. | ||
244 : | * data_size - Size of extra data you passed to the sort func. | ||
245 : | * | ||
246 : | * Your function should return: | ||
247 : | * -1 if item1 should go before item2 | ||
248 : | * 0 if item1 and item2 are equal | ||
249 : | * 1 if item1 should go after item2 | ||
250 : | * Note that the parameters after item2 are all optional and you do not need to specify them. | ||
251 : | * | ||
252 : | * Note that unlike the sorting.inc versions, the array passed to the callback is not in mid-sorted state. | ||
253 : | */ | ||
254 : | native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); |
Contact | ViewVC Help |
Powered by ViewVC 1.0.4 |