3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _adt_array_included
36 #define _adt_array_included
39 * Given a maximum string size (including the null terminator),
40 * returns the number of cells required to fit that string.
42 * @param size Number of bytes.
43 * @return Minimum number of cells required to fit the byte count.
45 stock ByteCountToCells(size)
52 return (size + 3) / 4;
56 * Creates a dynamic global cell array. While slower than a normal array,
57 * it can be used globally AND dynamically, which is otherwise impossible.
59 * The contents of the array are uniform; i.e. storing a string at index X
60 * and then retrieving it as an integer is NOT the same as StringToInt()!
61 * The "blocksize" determines how many cells each array slot has; it cannot
62 * be changed after creation.
64 * @param blocksize The number of cells each member of the array can
65 * hold. For example, 32 cells is equivalent to:
67 * @param startsize Initial size of the array. Note that data will
68 * NOT be auto-intialized.
69 * @return New Handle to the array object.
71 native Handle:CreateArray(blocksize=1, startsize=0);
74 * Clears an array of all entries. This is the same as ResizeArray(0).
76 * @param array Array Handle.
78 * @error Invalid Handle.
80 native ClearArray(Handle:array);
83 * Clones an array, returning a new handle with the same size and data. This should NOT
84 * be confused with CloneHandle. This is a completely new handle with the same data but
85 * no relation to the original. You MUST close it.
87 * @param array Array handle to be cloned
88 * @return New handle to the cloned array object
89 * @error Invalid Handle
91 native Handle:CloneArray(Handle:array);
94 * Resizes an array. If the size is smaller than the current size,
95 * the array is truncated.
97 * @param array Array Handle.
98 * @param newsize New size.
100 * @error Invalid Handle or out of memory.
102 native bool:ResizeArray(Handle:array, newsize);
105 * Returns the array size.
107 * @param array Array Handle.
108 * @return Number of elements in the array.
109 * @error Invalid Handle.
111 native GetArraySize(Handle:array);
114 * Pushes a value onto the end of an array, adding a new index.
116 * This may safely be used even if the array has a blocksize
119 * @param array Array Handle.
120 * @param value Value to push.
121 * @return Index of the new entry.
122 * @error Invalid Handle or out of memory.
124 native PushArrayCell(Handle:array, any:value);
127 * Pushes a string onto the end of an array, truncating it
130 * @param array Array Handle.
131 * @param value String to push.
132 * @return Index of the new entry.
133 * @error Invalid Handle or out of memory.
135 native PushArrayString(Handle:array, const String:value[]);
138 * Pushes an array of cells onto the end of an array. The cells
139 * are pushed as a block (i.e. the entire array sits at the index),
140 * rather than pushing each cell individually.
142 * @param array Array Handle.
143 * @param values Block of values to copy.
144 * @param size If not set, the number of elements copied from the array
145 * will be equal to the blocksize. If set higher than the
146 * blocksize, the operation will be truncated.
147 * @return Index of the new entry.
148 * @error Invalid Handle or out of memory.
150 native PushArrayArray(Handle:array, const values[], size=-1);
153 * Retrieves a cell value from an array.
155 * @param array Array Handle.
156 * @param index Index in the array.
157 * @param block Optionally specify which block to read from
158 * (useful if the blocksize > 0).
159 * @param asChar Optionally read as a byte instead of a cell.
160 * @return Value read.
161 * @error Invalid Handle, invalid index, or invalid block.
163 native any:GetArrayCell(Handle:array, index, block=0, bool:asChar=false);
166 * Retrieves a string value from an array.
168 * @param array Array Handle.
169 * @param index Index in the array.
170 * @param buffer Buffer to copy to.
171 * @param maxlength Maximum size of the buffer.
172 * @return Number of characters copied.
173 * @error Invalid Handle or invalid index.
175 native GetArrayString(Handle:array, index, String:buffer[], maxlength);
178 * Retrieves an array of cells from an array.
180 * @param array Array Handle.
181 * @param index Index in the array.
182 * @param buffer Buffer to store the array in.
183 * @param size If not set, assumes the buffer size is equal to the
184 * blocksize. Otherwise, the size passed is used.
185 * @return Number of cells copied.
186 * @error Invalid Handle or invalid index.
188 native GetArrayArray(Handle:array, index, buffer[], size=-1);
191 * Sets a cell value in an array.
193 * @param array Array Handle.
194 * @param index Index in the array.
195 * @param value Cell value to set.
196 * @param block Optionally specify which block to write to
197 * (useful if the blocksize > 0).
198 * @param asChar Optionally set as a byte instead of a cell.
200 * @error Invalid Handle, invalid index, or invalid block.
202 native any:SetArrayCell(Handle:array, index, any:value, block=0, bool:asChar=false);
205 * Sets a string value in an array.
207 * @param array Array Handle.
208 * @param index Index in the array.
209 * @param value String value to set.
210 * @return Number of characters copied.
211 * @error Invalid Handle or invalid index.
213 native SetArrayString(Handle:array, index, const String:buffer[]);
216 * Sets an array of cells in an array.
218 * @param array Array Handle.
219 * @param index Index in the array.
220 * @param buffer Array to copy.
221 * @param size If not set, assumes the buffer size is equal to the
222 * blocksize. Otherwise, the size passed is used.
223 * @return Number of cells copied.
224 * @error Invalid Handle or invalid index.
226 native SetArrayArray(Handle:array, index, const values[], size=-1);
229 * Shifts an array up. All array contents after and including the given
230 * index are shifted up by one, and the given index is then "free."
231 * After shifting, the contents of the given index is undefined.
233 * @param array Array Handle.
234 * @param index Index in the array to shift up from.
236 * @error Invalid Handle or invalid index.
238 native ShiftArrayUp(Handle:array, index);
241 * Removes an array index, shifting the entire array down from that position
242 * on. For example, if item 8 of 10 is removed, the last 3 items will then be
243 * (6,7,8) instead of (7,8,9), and all indexes before 8 will remain unchanged.
245 * @param array Array Handle.
246 * @param index Index in the array to remove at.
248 * @error Invalid Handle or invalid index.
250 native RemoveFromArray(Handle:array, index);
253 * Swaps two items in the array.
255 * @param array Array Handle.
256 * @param index1 First index.
257 * @param index2 Second index.
259 * @error Invalid Handle or invalid index.
261 native SwapArrayItems(Handle:array, index1, index2);
264 * Returns the index for the first occurance of the provided string. If the string
265 * cannot be located, -1 will be returned.
267 * @param array Array Handle.
268 * @param item String to search for
269 * @return Array index, or -1 on failure
270 * @error Invalid Handle
272 native FindStringInArray(Handle:array, const String:item[]);
275 * Returns the index for the first occurance of the provided value. If the value
276 * cannot be located, -1 will be returned.
278 * @param array Array Handle.
279 * @param item Value to search for
280 * @return Array index, or -1 on failure
281 * @error Invalid Handle
283 native FindValueInArray(Handle:array, any:item);
