3 * ===============================================================
4 * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
5 * ===============================================================
7 * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
8 * or modified under the Terms and Conditions of its License Agreement, which is found
9 * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
10 * may change at any time. To view the latest information, see:
11 * http://www.sourcemod.net/license.php
16 #if defined _adt_array_included
19 #define _adt_array_included
22 * Given a maximum string size (including the null terminator),
23 * returns the number of cells required to fit that string.
25 * @param size Number of bytes.
26 * @return Minimum number of cells required to fit the byte count.
28 stock ByteCountToCells(size)
35 return (size + 3) / 4;
39 * Creates a dynamic global cell array. While slower than a normal array,
40 * it can be used globally AND dynamically, which is otherwise impossible.
42 * The contents of the array are uniform; i.e. storing a string at index X
43 * and then retrieving it as an integer is NOT the same as StringToInt()!
44 * The "blocksize" determines how many cells each array slot has; it cannot
45 * be changed after creation.
47 * @param blocksize The number of cells each member of the array can
48 * hold. For example, 32 cells is equivalent to:
50 * @param startsize Initial size of the array. Note that data will
51 * NOT be auto-intialized.
52 * @return New Handle to the array object.
54 native Handle:CreateArray(blocksize=1, startsize=0);
57 * Clears an array of all entries. This is the same as ResizeArray(0).
59 * @param array Array Handle.
61 * @error Invalid Handle.
63 native ClearArray(Handle:array);
66 * Resizes an array. If the size is smaller than the current size,
67 * the array is truncated.
69 * @param array Array Handle.
70 * @param newsize New size.
72 * @error Invalid Handle or out of memory.
74 native bool:ResizeArray(Handle:array, newsize);
77 * Returns the array size.
79 * @param array Array Handle.
80 * @return Number of elements in the array.
81 * @error Invalid Handle.
83 native GetArraySize(Handle:array);
86 * Pushes a value onto the end of an array, adding a new index.
88 * This may safely be used even if the array has a blocksize
91 * @param array Array Handle.
92 * @param value Value to push.
93 * @return Index of the new entry.
94 * @error Invalid Handle or out of memory.
96 native PushArrayCell(Handle:array, any:value);
99 * Pushes a string onto the end of an array, truncating it
102 * @param array Array Handle.
103 * @param value String to push.
104 * @return Index of the new entry.
105 * @error Invalid Handle or out of memory.
107 native PushArrayString(Handle:array, const String:value[]);
110 * Pushes an array of cells onto the end of an array. The cells
111 * are pushed as a block (i.e. the entire array sits at the index),
112 * rather than pushing each cell individually.
114 * @param array Array Handle.
115 * @param values Block of values to copy.
116 * @param size If not set, the number of elements copied from the array
117 * will be equal to the blocksize. If set higher than the
118 * blocksize, the operation will be truncated.
119 * @return Index of the new entry.
120 * @error Invalid Handle or out of memory.
122 native PushArrayArray(Handle:array, const values[], size=-1);
125 * Retrieves a cell value from an array.
127 * @param array Array Handle.
128 * @param index Index in the array.
129 * @param block Optionally specify which block to read from
130 * (useful if the blocksize > 0).
131 * @param asChar Optionally read as a byte instead of a cell.
132 * @return Value read.
133 * @error Invalid Handle, invalid index, or invalid block.
135 native any:GetArrayCell(Handle:array, index, block=0, bool:asChar=false);
138 * Retrieves a string value from an array.
140 * @param array Array Handle.
141 * @param index Index in the array.
142 * @param buffer Buffer to copy to.
143 * @param maxlength Maximum size of the buffer.
144 * @return Number of characters copied.
145 * @error Invalid Handle or invalid index.
147 native GetArrayString(Handle:array, index, String:buffer[], maxlength);
150 * Retrieves an array of cells from an array.
152 * @param array Array Handle.
153 * @param index Index in the array.
154 * @param buffer Buffer to store the array in.
155 * @param size If not set, assumes the buffer size is equal to the
156 * blocksize. Otherwise, the size passed is used.
157 * @return Number of cells copied.
158 * @error Invalid Handle or invalid index.
160 native GetArrayArray(Handle:array, index, buffer[], size=-1);
163 * Sets a cell value in an array.
165 * @param array Array Handle.
166 * @param index Index in the array.
167 * @param value Cell value to set.
168 * @param block Optionally specify which block to write to
169 * (useful if the blocksize > 0).
170 * @param asChar Optionally set as a byte instead of a cell.
172 * @error Invalid Handle, invalid index, or invalid block.
174 native any:SetArrayCell(Handle:array, index, any:value, block=0, bool:asChar=false);
177 * Sets a string value in an array.
179 * @param array Array Handle.
180 * @param index Index in the array.
181 * @param value String value to set.
182 * @return Number of characters copied.
183 * @error Invalid Handle or invalid index.
185 native SetArrayString(Handle:array, index, const String:buffer[]);
188 * Sets an array of cells in an array.
190 * @param array Array Handle.
191 * @param index Index in the array.
192 * @param buffer Array to copy.
193 * @param size If not set, assumes the buffer size is equal to the
194 * blocksize. Otherwise, the size passed is used.
195 * @return Number of cells copied.
196 * @error Invalid Handle or invalid index.
198 native SetArrayArray(Handle:array, index, const values[], size=-1);
201 * Shifts an array up. All array contents after and including the given
202 * index are shifted up by one, and the given index is then "free."
203 * After shifting, the contents of the given index is undefined.
205 * @param array Array Handle.
206 * @param index Index in the array to shift up from.
208 * @error Invalid Handle or invalid index.
210 native ShiftArrayUp(Handle:array, index);
213 * Removes an array index, shifting the entire array down from that position
214 * on. For example, if item 8 of 10 is removed, the last 3 items will then be
215 * (6,7,8) instead of (7,8,9), and all indexes before 8 will remain unchanged.
217 * @param array Array Handle.
218 * @param index Index in the array to remove at.
220 * @error Invalid Handle or invalid index.
222 native RemoveFromArray(Handle:array, index);
225 * Swaps two items in the array.
227 * @param array Array Handle.
228 * @param index1 First index.
229 * @param index2 Second index.
231 * @error Invalid Handle or invalid index.
233 native SwapArrayItems(Handle:array, index1, index2);
