3 * =============================================================================
4 * SourceMod (C)2004-2007 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 * Resizes an array. If the size is smaller than the current size,
84 * the array is truncated.
86 * @param array Array Handle.
87 * @param newsize New size.
89 * @error Invalid Handle or out of memory.
91 native bool:ResizeArray(Handle:array, newsize);
94 * Returns the array size.
96 * @param array Array Handle.
97 * @return Number of elements in the array.
98 * @error Invalid Handle.
100 native GetArraySize(Handle:array);
103 * Pushes a value onto the end of an array, adding a new index.
105 * This may safely be used even if the array has a blocksize
108 * @param array Array Handle.
109 * @param value Value to push.
110 * @return Index of the new entry.
111 * @error Invalid Handle or out of memory.
113 native PushArrayCell(Handle:array, any:value);
116 * Pushes a string onto the end of an array, truncating it
119 * @param array Array Handle.
120 * @param value String to push.
121 * @return Index of the new entry.
122 * @error Invalid Handle or out of memory.
124 native PushArrayString(Handle:array, const String:value[]);
127 * Pushes an array of cells onto the end of an array. The cells
128 * are pushed as a block (i.e. the entire array sits at the index),
129 * rather than pushing each cell individually.
131 * @param array Array Handle.
132 * @param values Block of values to copy.
133 * @param size If not set, the number of elements copied from the array
134 * will be equal to the blocksize. If set higher than the
135 * blocksize, the operation will be truncated.
136 * @return Index of the new entry.
137 * @error Invalid Handle or out of memory.
139 native PushArrayArray(Handle:array, const values[], size=-1);
142 * Retrieves a cell value from an array.
144 * @param array Array Handle.
145 * @param index Index in the array.
146 * @param block Optionally specify which block to read from
147 * (useful if the blocksize > 0).
148 * @param asChar Optionally read as a byte instead of a cell.
149 * @return Value read.
150 * @error Invalid Handle, invalid index, or invalid block.
152 native any:GetArrayCell(Handle:array, index, block=0, bool:asChar=false);
155 * Retrieves a string value from an array.
157 * @param array Array Handle.
158 * @param index Index in the array.
159 * @param buffer Buffer to copy to.
160 * @param maxlength Maximum size of the buffer.
161 * @return Number of characters copied.
162 * @error Invalid Handle or invalid index.
164 native GetArrayString(Handle:array, index, String:buffer[], maxlength);
167 * Retrieves an array of cells from an array.
169 * @param array Array Handle.
170 * @param index Index in the array.
171 * @param buffer Buffer to store the array in.
172 * @param size If not set, assumes the buffer size is equal to the
173 * blocksize. Otherwise, the size passed is used.
174 * @return Number of cells copied.
175 * @error Invalid Handle or invalid index.
177 native GetArrayArray(Handle:array, index, buffer[], size=-1);
180 * Sets a cell value in an array.
182 * @param array Array Handle.
183 * @param index Index in the array.
184 * @param value Cell value to set.
185 * @param block Optionally specify which block to write to
186 * (useful if the blocksize > 0).
187 * @param asChar Optionally set as a byte instead of a cell.
189 * @error Invalid Handle, invalid index, or invalid block.
191 native any:SetArrayCell(Handle:array, index, any:value, block=0, bool:asChar=false);
194 * Sets a string value in an array.
196 * @param array Array Handle.
197 * @param index Index in the array.
198 * @param value String value to set.
199 * @return Number of characters copied.
200 * @error Invalid Handle or invalid index.
202 native SetArrayString(Handle:array, index, const String:buffer[]);
205 * Sets an array of cells in an array.
207 * @param array Array Handle.
208 * @param index Index in the array.
209 * @param buffer Array to copy.
210 * @param size If not set, assumes the buffer size is equal to the
211 * blocksize. Otherwise, the size passed is used.
212 * @return Number of cells copied.
213 * @error Invalid Handle or invalid index.
215 native SetArrayArray(Handle:array, index, const values[], size=-1);
218 * Shifts an array up. All array contents after and including the given
219 * index are shifted up by one, and the given index is then "free."
220 * After shifting, the contents of the given index is undefined.
222 * @param array Array Handle.
223 * @param index Index in the array to shift up from.
225 * @error Invalid Handle or invalid index.
227 native ShiftArrayUp(Handle:array, index);
230 * Removes an array index, shifting the entire array down from that position
231 * on. For example, if item 8 of 10 is removed, the last 3 items will then be
232 * (6,7,8) instead of (7,8,9), and all indexes before 8 will remain unchanged.
234 * @param array Array Handle.
235 * @param index Index in the array to remove at.
237 * @error Invalid Handle or invalid index.
239 native RemoveFromArray(Handle:array, index);
242 * Swaps two items in the array.
244 * @param array Array Handle.
245 * @param index1 First index.
246 * @param index2 Second index.
248 * @error Invalid Handle or invalid index.
250 native SwapArrayItems(Handle:array, index1, index2);
