dvander@1156: /**
dvander@1156:  * vim: set ts=4 :
dvander@1156:  * ===============================================================
dvander@1156:  * SourceMod (C)2004-2007 AlliedModders LLC.  All rights reserved.
dvander@1156:  * ===============================================================
dvander@1156:  *
dvander@1156:  *  This file is part of the SourceMod/SourcePawn SDK.  This file may only be used 
dvander@1156:  * or modified under the Terms and Conditions of its License Agreement, which is found 
dvander@1156:  * in LICENSE.txt.  The Terms and Conditions for making SourceMod extensions/plugins 
dvander@1156:  * may change at any time.  To view the latest information, see:
dvander@1156:  *   http://www.sourcemod.net/license.php
dvander@1156:  *
dvander@1156:  * Version: $Id$
dvander@1156:  */
dvander@1156:  
dvander@1156: #if defined _adt_array_included
dvander@1156:  #endinput
dvander@1156: #endif
dvander@1156: #define _adt_array_included
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Given a maximum string size (including the null terminator), 
dvander@1156:  * returns the number of cells required to fit that string.
dvander@1156:  *
dvander@1156:  * @param size			Number of bytes.
dvander@1156:  * @return				Minimum number of cells required to fit the byte count.
dvander@1156:  */
dvander@1156: stock ByteCountToCells(size)
dvander@1156: {
dvander@1156: 	if (!size)
dvander@1156: 	{
dvander@1156: 		return 1;
dvander@1156: 	}
dvander@1156: 	
dvander@1156: 	return (size + 3) / 4;
dvander@1156: }
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Creates a dynamic global cell array.  While slower than a normal array,
dvander@1156:  * it can be used globally AND dynamically, which is otherwise impossible.
dvander@1156:  * 
dvander@1156:  * The contents of the array are uniform; i.e. storing a string at index X 
dvander@1156:  * and then retrieving it as an integer is NOT the same as StringToInt()!
dvander@1156:  * The "blocksize" determines how many cells each array slot has; it cannot
dvander@1156:  * be changed after creation.
dvander@1156:  *
dvander@1156:  * @param blocksize		The number of cells each member of the array can 
dvander@1156:  *						hold.  For example, 32 cells is equivalent to:
dvander@1156:  *						new Array[X][32]
dvander@1156:  * @param startsize		Initial size of the array.  Note that data will 
dvander@1156:  *						NOT be auto-intialized.
dvander@1156:  * @return				New Handle to the array object.
dvander@1156:  */
dvander@1156: native Handle:CreateArray(blocksize=1, startsize=0);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Clears an array of all entries.  This is the same as ResizeArray(0).
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @noreturn
dvander@1156:  * @error				Invalid Handle.
dvander@1156:  */
dvander@1156: native ClearArray(Handle:array);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Resizes an array.  If the size is smaller than the current size,
dvander@1156:  * the array is truncated.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param newsize		New size.
dvander@1156:  * @noreturn
dvander@1156:  * @error				Invalid Handle or out of memory.
dvander@1156:  */
dvander@1156: native bool:ResizeArray(Handle:array, newsize);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Returns the array size.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @return				Number of elements in the array.
dvander@1156:  * @error				Invalid Handle.
dvander@1156:  */
dvander@1156: native GetArraySize(Handle:array);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Pushes a value onto the end of an array, adding a new index.
dvander@1156:  *
dvander@1156:  * This may safely be used even if the array has a blocksize
dvander@1156:  * greater than 1.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param value			Value to push.
dvander@1156:  * @return				Index of the new entry.
dvander@1156:  * @error				Invalid Handle or out of memory.
dvander@1156:  */
dvander@1156: native PushArrayCell(Handle:array, any:value);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Pushes a string onto the end of an array, truncating it
dvander@1156:  * if it is too big.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param value			String to push.
dvander@1156:  * @return				Index of the new entry.
dvander@1156:  * @error				Invalid Handle or out of memory.
dvander@1156:  */
dvander@1156: native PushArrayString(Handle:array, const String:value[]);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Pushes an array of cells onto the end of an array.  The cells
dvander@1156:  * are pushed as a block (i.e. the entire array sits at the index),
dvander@1156:  * rather than pushing each cell individually.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param values		Block of values to copy.
dvander@1156:  * @param size			If not set, the number of elements copied from the array
dvander@1156:  *						will be equal to the blocksize.  If set higher than the 
dvander@1156:  *						blocksize, the operation will be truncated.
dvander@1156:  * @return				Index of the new entry.
dvander@1156:  * @error				Invalid Handle or out of memory.
dvander@1156:  */
dvander@1156: native PushArrayArray(Handle:array, const values[], size=-1);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Retrieves a cell value from an array.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array.
dvander@1156:  * @param block			Optionally specify which block to read from
dvander@1156:  *						(useful if the blocksize > 0).
dvander@1156:  * @param asChar		Optionally read as a byte instead of a cell.
dvander@1156:  * @return				Value read.
dvander@1156:  * @error				Invalid Handle, invalid index, or invalid block.
dvander@1156:  */
dvander@1156: native any:GetArrayCell(Handle:array, index, block=0, bool:asChar=false);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Retrieves a string value from an array.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array.
dvander@1156:  * @param buffer		Buffer to copy to.
dvander@1156:  * @param maxlength		Maximum size of the buffer.
dvander@1156:  * @return				Number of characters copied.
dvander@1156:  * @error				Invalid Handle or invalid index.
dvander@1156:  */
dvander@1156: native GetArrayString(Handle:array, index, String:buffer[], maxlength);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Retrieves an array of cells from an array.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array.
dvander@1156:  * @param buffer		Buffer to store the array in.
dvander@1156:  * @param size			If not set, assumes the buffer size is equal to the
dvander@1156:  *						blocksize.  Otherwise, the size passed is used.
dvander@1156:  * @return				Number of cells copied.
dvander@1156:  * @error				Invalid Handle or invalid index.
dvander@1156:  */
dvander@1156: native GetArrayArray(Handle:array, index, buffer[], size=-1);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Sets a cell value in an array.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array.
dvander@1156:  * @param value			Cell value to set.
dvander@1156:  * @param block			Optionally specify which block to write to
dvander@1156:  *						(useful if the blocksize > 0).
dvander@1156:  * @param asChar		Optionally set as a byte instead of a cell.
dvander@1156:  * @noreturn
dvander@1156:  * @error				Invalid Handle, invalid index, or invalid block.
dvander@1156:  */
dvander@1156: native any:SetArrayCell(Handle:array, index, any:value, block=0, bool:asChar=false);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Sets a string value in an array.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array.
dvander@1156:  * @param value			String value to set.
dvander@1156:  * @return				Number of characters copied.
dvander@1156:  * @error				Invalid Handle or invalid index.
dvander@1156:  */
dvander@1156: native SetArrayString(Handle:array, index, const String:buffer[]);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Sets an array of cells in an array.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array.
dvander@1156:  * @param buffer		Array to copy.
dvander@1156:  * @param size			If not set, assumes the buffer size is equal to the
dvander@1156:  *						blocksize.  Otherwise, the size passed is used.
dvander@1156:  * @return				Number of cells copied.
dvander@1156:  * @error				Invalid Handle or invalid index.
dvander@1156:  */
dvander@1156: native SetArrayArray(Handle:array, index, const values[], size=-1);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Shifts an array up.  All array contents after and including the given 
dvander@1156:  * index are shifted up by one, and the given index is then "free."  
dvander@1156:  * After shifting, the contents of the given index is undefined.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array to shift up from.
dvander@1156:  * @noreturn
dvander@1156:  * @error				Invalid Handle or invalid index.
dvander@1156:  */
dvander@1156: native ShiftArrayUp(Handle:array, index);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Removes an array index, shifting the entire array down from that position 
dvander@1156:  * on.  For example, if item 8 of 10 is removed, the last 3 items will then be
dvander@1156:  * (6,7,8) instead of (7,8,9), and all indexes before 8 will remain unchanged.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index			Index in the array to remove at.
dvander@1156:  * @noreturn
dvander@1156:  * @error				Invalid Handle or invalid index.
dvander@1156:  */
dvander@1156: native RemoveFromArray(Handle:array, index);
dvander@1156: 
dvander@1156: /**
dvander@1156:  * Swaps two items in the array.
dvander@1156:  *
dvander@1156:  * @param array			Array Handle.
dvander@1156:  * @param index1		First index.
dvander@1156:  * @param index2		Second index.
dvander@1156:  * @noreturn
dvander@1156:  * @error				Invalid Handle or invalid index.
dvander@1156:  */
dvander@1156: native SwapArrayItems(Handle:array, index1, index2);