1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/plugins/include/adt_array.inc Tue Jul 24 01:18:28 2007 +0000
1.3 @@ -0,0 +1,233 @@
1.4 +/**
1.5 + * vim: set ts=4 :
1.6 + * ===============================================================
1.7 + * SourceMod (C)2004-2007 AlliedModders LLC. All rights reserved.
1.8 + * ===============================================================
1.9 + *
1.10 + * This file is part of the SourceMod/SourcePawn SDK. This file may only be used
1.11 + * or modified under the Terms and Conditions of its License Agreement, which is found
1.12 + * in LICENSE.txt. The Terms and Conditions for making SourceMod extensions/plugins
1.13 + * may change at any time. To view the latest information, see:
1.14 + * http://www.sourcemod.net/license.php
1.15 + *
1.16 + * Version: $Id$
1.17 + */
1.18 +
1.19 +#if defined _adt_array_included
1.20 + #endinput
1.21 +#endif
1.22 +#define _adt_array_included
1.23 +
1.24 +/**
1.25 + * Given a maximum string size (including the null terminator),
1.26 + * returns the number of cells required to fit that string.
1.27 + *
1.28 + * @param size Number of bytes.
1.29 + * @return Minimum number of cells required to fit the byte count.
1.30 + */
1.31 +stock ByteCountToCells(size)
1.32 +{
1.33 + if (!size)
1.34 + {
1.35 + return 1;
1.36 + }
1.37 +
1.38 + return (size + 3) / 4;
1.39 +}
1.40 +
1.41 +/**
1.42 + * Creates a dynamic global cell array. While slower than a normal array,
1.43 + * it can be used globally AND dynamically, which is otherwise impossible.
1.44 + *
1.45 + * The contents of the array are uniform; i.e. storing a string at index X
1.46 + * and then retrieving it as an integer is NOT the same as StringToInt()!
1.47 + * The "blocksize" determines how many cells each array slot has; it cannot
1.48 + * be changed after creation.
1.49 + *
1.50 + * @param blocksize The number of cells each member of the array can
1.51 + * hold. For example, 32 cells is equivalent to:
1.52 + * new Array[X][32]
1.53 + * @param startsize Initial size of the array. Note that data will
1.54 + * NOT be auto-intialized.
1.55 + * @return New Handle to the array object.
1.56 + */
1.57 +native Handle:CreateArray(blocksize=1, startsize=0);
1.58 +
1.59 +/**
1.60 + * Clears an array of all entries. This is the same as ResizeArray(0).
1.61 + *
1.62 + * @param array Array Handle.
1.63 + * @noreturn
1.64 + * @error Invalid Handle.
1.65 + */
1.66 +native ClearArray(Handle:array);
1.67 +
1.68 +/**
1.69 + * Resizes an array. If the size is smaller than the current size,
1.70 + * the array is truncated.
1.71 + *
1.72 + * @param array Array Handle.
1.73 + * @param newsize New size.
1.74 + * @noreturn
1.75 + * @error Invalid Handle or out of memory.
1.76 + */
1.77 +native bool:ResizeArray(Handle:array, newsize);
1.78 +
1.79 +/**
1.80 + * Returns the array size.
1.81 + *
1.82 + * @param array Array Handle.
1.83 + * @return Number of elements in the array.
1.84 + * @error Invalid Handle.
1.85 + */
1.86 +native GetArraySize(Handle:array);
1.87 +
1.88 +/**
1.89 + * Pushes a value onto the end of an array, adding a new index.
1.90 + *
1.91 + * This may safely be used even if the array has a blocksize
1.92 + * greater than 1.
1.93 + *
1.94 + * @param array Array Handle.
1.95 + * @param value Value to push.
1.96 + * @return Index of the new entry.
1.97 + * @error Invalid Handle or out of memory.
1.98 + */
1.99 +native PushArrayCell(Handle:array, any:value);
1.100 +
1.101 +/**
1.102 + * Pushes a string onto the end of an array, truncating it
1.103 + * if it is too big.
1.104 + *
1.105 + * @param array Array Handle.
1.106 + * @param value String to push.
1.107 + * @return Index of the new entry.
1.108 + * @error Invalid Handle or out of memory.
1.109 + */
1.110 +native PushArrayString(Handle:array, const String:value[]);
1.111 +
1.112 +/**
1.113 + * Pushes an array of cells onto the end of an array. The cells
1.114 + * are pushed as a block (i.e. the entire array sits at the index),
1.115 + * rather than pushing each cell individually.
1.116 + *
1.117 + * @param array Array Handle.
1.118 + * @param values Block of values to copy.
1.119 + * @param size If not set, the number of elements copied from the array
1.120 + * will be equal to the blocksize. If set higher than the
1.121 + * blocksize, the operation will be truncated.
1.122 + * @return Index of the new entry.
1.123 + * @error Invalid Handle or out of memory.
1.124 + */
1.125 +native PushArrayArray(Handle:array, const values[], size=-1);
1.126 +
1.127 +/**
1.128 + * Retrieves a cell value from an array.
1.129 + *
1.130 + * @param array Array Handle.
1.131 + * @param index Index in the array.
1.132 + * @param block Optionally specify which block to read from
1.133 + * (useful if the blocksize > 0).
1.134 + * @param asChar Optionally read as a byte instead of a cell.
1.135 + * @return Value read.
1.136 + * @error Invalid Handle, invalid index, or invalid block.
1.137 + */
1.138 +native any:GetArrayCell(Handle:array, index, block=0, bool:asChar=false);
1.139 +
1.140 +/**
1.141 + * Retrieves a string value from an array.
1.142 + *
1.143 + * @param array Array Handle.
1.144 + * @param index Index in the array.
1.145 + * @param buffer Buffer to copy to.
1.146 + * @param maxlength Maximum size of the buffer.
1.147 + * @return Number of characters copied.
1.148 + * @error Invalid Handle or invalid index.
1.149 + */
1.150 +native GetArrayString(Handle:array, index, String:buffer[], maxlength);
1.151 +
1.152 +/**
1.153 + * Retrieves an array of cells from an array.
1.154 + *
1.155 + * @param array Array Handle.
1.156 + * @param index Index in the array.
1.157 + * @param buffer Buffer to store the array in.
1.158 + * @param size If not set, assumes the buffer size is equal to the
1.159 + * blocksize. Otherwise, the size passed is used.
1.160 + * @return Number of cells copied.
1.161 + * @error Invalid Handle or invalid index.
1.162 + */
1.163 +native GetArrayArray(Handle:array, index, buffer[], size=-1);
1.164 +
1.165 +/**
1.166 + * Sets a cell value in an array.
1.167 + *
1.168 + * @param array Array Handle.
1.169 + * @param index Index in the array.
1.170 + * @param value Cell value to set.
1.171 + * @param block Optionally specify which block to write to
1.172 + * (useful if the blocksize > 0).
1.173 + * @param asChar Optionally set as a byte instead of a cell.
1.174 + * @noreturn
1.175 + * @error Invalid Handle, invalid index, or invalid block.
1.176 + */
1.177 +native any:SetArrayCell(Handle:array, index, any:value, block=0, bool:asChar=false);
1.178 +
1.179 +/**
1.180 + * Sets a string value in an array.
1.181 + *
1.182 + * @param array Array Handle.
1.183 + * @param index Index in the array.
1.184 + * @param value String value to set.
1.185 + * @return Number of characters copied.
1.186 + * @error Invalid Handle or invalid index.
1.187 + */
1.188 +native SetArrayString(Handle:array, index, const String:buffer[]);
1.189 +
1.190 +/**
1.191 + * Sets an array of cells in an array.
1.192 + *
1.193 + * @param array Array Handle.
1.194 + * @param index Index in the array.
1.195 + * @param buffer Array to copy.
1.196 + * @param size If not set, assumes the buffer size is equal to the
1.197 + * blocksize. Otherwise, the size passed is used.
1.198 + * @return Number of cells copied.
1.199 + * @error Invalid Handle or invalid index.
1.200 + */
1.201 +native SetArrayArray(Handle:array, index, const values[], size=-1);
1.202 +
1.203 +/**
1.204 + * Shifts an array up. All array contents after and including the given
1.205 + * index are shifted up by one, and the given index is then "free."
1.206 + * After shifting, the contents of the given index is undefined.
1.207 + *
1.208 + * @param array Array Handle.
1.209 + * @param index Index in the array to shift up from.
1.210 + * @noreturn
1.211 + * @error Invalid Handle or invalid index.
1.212 + */
1.213 +native ShiftArrayUp(Handle:array, index);
1.214 +
1.215 +/**
1.216 + * Removes an array index, shifting the entire array down from that position
1.217 + * on. For example, if item 8 of 10 is removed, the last 3 items will then be
1.218 + * (6,7,8) instead of (7,8,9), and all indexes before 8 will remain unchanged.
1.219 + *
1.220 + * @param array Array Handle.
1.221 + * @param index Index in the array to remove at.
1.222 + * @noreturn
1.223 + * @error Invalid Handle or invalid index.
1.224 + */
1.225 +native RemoveFromArray(Handle:array, index);
1.226 +
1.227 +/**
1.228 + * Swaps two items in the array.
1.229 + *
1.230 + * @param array Array Handle.
1.231 + * @param index1 First index.
1.232 + * @param index2 Second index.
1.233 + * @noreturn
1.234 + * @error Invalid Handle or invalid index.
1.235 + */
1.236 +native SwapArrayItems(Handle:array, index1, index2);
