[Half-Life AMXX] / include / cellarray.inc Repository:
ViewVC logotype

Annotation of /include/cellarray.inc

Parent Directory Parent Directory | Revision Log 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