1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/plugins/include/adt_array.inc Sun Jul 06 04:49:55 2008 +0000
1.3 @@ -0,0 +1,283 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * =============================================================================
1.7 + * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
1.8 + * =============================================================================
1.9 + *
1.10 + * This file is part of the SourceMod/SourcePawn SDK.
1.11 + *
1.12 + * This program is free software; you can redistribute it and/or modify it under
1.13 + * the terms of the GNU General Public License, version 3.0, as published by the
1.14 + * Free Software Foundation.
1.15 + *
1.16 + * This program is distributed in the hope that it will be useful, but WITHOUT
1.17 + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
1.18 + * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
1.19 + * details.
1.20 + *
1.21 + * You should have received a copy of the GNU General Public License along with
1.22 + * this program. If not, see <http://www.gnu.org/licenses/>.
1.23 + *
1.24 + * As a special exception, AlliedModders LLC gives you permission to link the
1.25 + * code of this program (as well as its derivative works) to "Half-Life 2," the
1.26 + * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
1.27 + * by the Valve Corporation. You must obey the GNU General Public License in
1.28 + * all respects for all other code used. Additionally, AlliedModders LLC grants
1.29 + * this exception to all derivative works. AlliedModders LLC defines further
1.30 + * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
1.31 + * or <http://www.sourcemod.net/license.php>.
1.32 + *
1.33 + * Version: $Id$
1.34 + */
1.35 +
1.36 +#if defined _adt_array_included
1.37 + #endinput
1.38 +#endif
1.39 +#define _adt_array_included
1.40 +
1.41 +/**
1.42 + * Given a maximum string size (including the null terminator),
1.43 + * returns the number of cells required to fit that string.
1.44 + *
1.45 + * @param size Number of bytes.
1.46 + * @return Minimum number of cells required to fit the byte count.
1.47 + */
1.48 +stock ByteCountToCells(size)
1.49 +{
1.50 + if (!size)
1.51 + {
1.52 + return 1;
1.53 + }
1.54 +
1.55 + return (size + 3) / 4;
1.56 +}
1.57 +
1.58 +/**
1.59 + * Creates a dynamic global cell array. While slower than a normal array,
1.60 + * it can be used globally AND dynamically, which is otherwise impossible.
1.61 + *
1.62 + * The contents of the array are uniform; i.e. storing a string at index X
1.63 + * and then retrieving it as an integer is NOT the same as StringToInt()!
1.64 + * The "blocksize" determines how many cells each array slot has; it cannot
1.65 + * be changed after creation.
1.66 + *
1.67 + * @param blocksize The number of cells each member of the array can
1.68 + * hold. For example, 32 cells is equivalent to:
1.69 + * new Array[X][32]
1.70 + * @param startsize Initial size of the array. Note that data will
1.71 + * NOT be auto-intialized.
1.72 + * @return New Handle to the array object.
1.73 + */
1.74 +native Handle:CreateArray(blocksize=1, startsize=0);
1.75 +
1.76 +/**
1.77 + * Clears an array of all entries. This is the same as ResizeArray(0).
1.78 + *
1.79 + * @param array Array Handle.
1.80 + * @noreturn
1.81 + * @error Invalid Handle.
1.82 + */
1.83 +native ClearArray(Handle:array);
1.84 +
1.85 +/**
1.86 + * Clones an array, returning a new handle with the same size and data. This should NOT
1.87 + * be confused with CloneHandle. This is a completely new handle with the same data but
1.88 + * no relation to the original. You MUST close it.
1.89 + *
1.90 + * @param array Array handle to be cloned
1.91 + * @return New handle to the cloned array object
1.92 + * @error Invalid Handle
1.93 + */
1.94 + native Handle:CloneArray(Handle:array);
1.95 +
1.96 +/**
1.97 + * Resizes an array. If the size is smaller than the current size,
1.98 + * the array is truncated.
1.99 + *
1.100 + * @param array Array Handle.
1.101 + * @param newsize New size.
1.102 + * @noreturn
1.103 + * @error Invalid Handle or out of memory.
1.104 + */
1.105 +native bool:ResizeArray(Handle:array, newsize);
1.106 +
1.107 +/**
1.108 + * Returns the array size.
1.109 + *
1.110 + * @param array Array Handle.
1.111 + * @return Number of elements in the array.
1.112 + * @error Invalid Handle.
1.113 + */
1.114 +native GetArraySize(Handle:array);
1.115 +
1.116 +/**
1.117 + * Pushes a value onto the end of an array, adding a new index.
1.118 + *
1.119 + * This may safely be used even if the array has a blocksize
1.120 + * greater than 1.
1.121 + *
1.122 + * @param array Array Handle.
1.123 + * @param value Value to push.
1.124 + * @return Index of the new entry.
1.125 + * @error Invalid Handle or out of memory.
1.126 + */
1.127 +native PushArrayCell(Handle:array, any:value);
1.128 +
1.129 +/**
1.130 + * Pushes a string onto the end of an array, truncating it
1.131 + * if it is too big.
1.132 + *
1.133 + * @param array Array Handle.
1.134 + * @param value String to push.
1.135 + * @return Index of the new entry.
1.136 + * @error Invalid Handle or out of memory.
1.137 + */
1.138 +native PushArrayString(Handle:array, const String:value[]);
1.139 +
1.140 +/**
1.141 + * Pushes an array of cells onto the end of an array. The cells
1.142 + * are pushed as a block (i.e. the entire array sits at the index),
1.143 + * rather than pushing each cell individually.
1.144 + *
1.145 + * @param array Array Handle.
1.146 + * @param values Block of values to copy.
1.147 + * @param size If not set, the number of elements copied from the array
1.148 + * will be equal to the blocksize. If set higher than the
1.149 + * blocksize, the operation will be truncated.
1.150 + * @return Index of the new entry.
1.151 + * @error Invalid Handle or out of memory.
1.152 + */
1.153 +native PushArrayArray(Handle:array, const any:values[], size=-1);
1.154 +
1.155 +/**
1.156 + * Retrieves a cell value from an array.
1.157 + *
1.158 + * @param array Array Handle.
1.159 + * @param index Index in the array.
1.160 + * @param block Optionally specify which block to read from
1.161 + * (useful if the blocksize > 0).
1.162 + * @param asChar Optionally read as a byte instead of a cell.
1.163 + * @return Value read.
1.164 + * @error Invalid Handle, invalid index, or invalid block.
1.165 + */
1.166 +native any:GetArrayCell(Handle:array, index, block=0, bool:asChar=false);
1.167 +
1.168 +/**
1.169 + * Retrieves a string value from an array.
1.170 + *
1.171 + * @param array Array Handle.
1.172 + * @param index Index in the array.
1.173 + * @param buffer Buffer to copy to.
1.174 + * @param maxlength Maximum size of the buffer.
1.175 + * @return Number of characters copied.
1.176 + * @error Invalid Handle or invalid index.
1.177 + */
1.178 +native GetArrayString(Handle:array, index, String:buffer[], maxlength);
1.179 +
1.180 +/**
1.181 + * Retrieves an array of cells from an array.
1.182 + *
1.183 + * @param array Array Handle.
1.184 + * @param index Index in the array.
1.185 + * @param buffer Buffer to store the array in.
1.186 + * @param size If not set, assumes the buffer size is equal to the
1.187 + * blocksize. Otherwise, the size passed is used.
1.188 + * @return Number of cells copied.
1.189 + * @error Invalid Handle or invalid index.
1.190 + */
1.191 +native GetArrayArray(Handle:array, index, any:buffer[], size=-1);
1.192 +
1.193 +/**
1.194 + * Sets a cell value in an array.
1.195 + *
1.196 + * @param array Array Handle.
1.197 + * @param index Index in the array.
1.198 + * @param value Cell value to set.
1.199 + * @param block Optionally specify which block to write to
1.200 + * (useful if the blocksize > 0).
1.201 + * @param asChar Optionally set as a byte instead of a cell.
1.202 + * @noreturn
1.203 + * @error Invalid Handle, invalid index, or invalid block.
1.204 + */
1.205 +native any:SetArrayCell(Handle:array, index, any:value, block=0, bool:asChar=false);
1.206 +
1.207 +/**
1.208 + * Sets a string value in an array.
1.209 + *
1.210 + * @param array Array Handle.
1.211 + * @param index Index in the array.
1.212 + * @param value String value to set.
1.213 + * @return Number of characters copied.
1.214 + * @error Invalid Handle or invalid index.
1.215 + */
1.216 +native SetArrayString(Handle:array, index, const String:buffer[]);
1.217 +
1.218 +/**
1.219 + * Sets an array of cells in an array.
1.220 + *
1.221 + * @param array Array Handle.
1.222 + * @param index Index in the array.
1.223 + * @param buffer Array to copy.
1.224 + * @param size If not set, assumes the buffer size is equal to the
1.225 + * blocksize. Otherwise, the size passed is used.
1.226 + * @return Number of cells copied.
1.227 + * @error Invalid Handle or invalid index.
1.228 + */
1.229 +native SetArrayArray(Handle:array, index, const any:values[], size=-1);
1.230 +
1.231 +/**
1.232 + * Shifts an array up. All array contents after and including the given
1.233 + * index are shifted up by one, and the given index is then "free."
1.234 + * After shifting, the contents of the given index is undefined.
1.235 + *
1.236 + * @param array Array Handle.
1.237 + * @param index Index in the array to shift up from.
1.238 + * @noreturn
1.239 + * @error Invalid Handle or invalid index.
1.240 + */
1.241 +native ShiftArrayUp(Handle:array, index);
1.242 +
1.243 +/**
1.244 + * Removes an array index, shifting the entire array down from that position
1.245 + * on. For example, if item 8 of 10 is removed, the last 3 items will then be
1.246 + * (6,7,8) instead of (7,8,9), and all indexes before 8 will remain unchanged.
1.247 + *
1.248 + * @param array Array Handle.
1.249 + * @param index Index in the array to remove at.
1.250 + * @noreturn
1.251 + * @error Invalid Handle or invalid index.
1.252 + */
1.253 +native RemoveFromArray(Handle:array, index);
1.254 +
1.255 +/**
1.256 + * Swaps two items in the array.
1.257 + *
1.258 + * @param array Array Handle.
1.259 + * @param index1 First index.
1.260 + * @param index2 Second index.
1.261 + * @noreturn
1.262 + * @error Invalid Handle or invalid index.
1.263 + */
1.264 +native SwapArrayItems(Handle:array, index1, index2);
1.265 +
1.266 +/**
1.267 + * Returns the index for the first occurance of the provided string. If the string
1.268 + * cannot be located, -1 will be returned.
1.269 + *
1.270 + * @param array Array Handle.
1.271 + * @param item String to search for
1.272 + * @return Array index, or -1 on failure
1.273 + * @error Invalid Handle
1.274 + */
1.275 +native FindStringInArray(Handle:array, const String:item[]);
1.276 +
1.277 +/**
1.278 + * Returns the index for the first occurance of the provided value. If the value
1.279 + * cannot be located, -1 will be returned.
1.280 + *
1.281 + * @param array Array Handle.
1.282 + * @param item Value to search for
1.283 + * @return Array index, or -1 on failure
1.284 + * @error Invalid Handle
1.285 + */
1.286 +native FindValueInArray(Handle:array, any:item);
