dvander@2168: /**
dvander@2168:  * vim: set ts=4 :
dvander@2168:  * =============================================================================
dvander@2168:  * SourceMod (C)2004-2008 AlliedModders LLC.  All rights reserved.
dvander@2168:  * =============================================================================
dvander@2168:  *
dvander@2168:  * This file is part of the SourceMod/SourcePawn SDK.
dvander@2168:  *
dvander@2168:  * This program is free software; you can redistribute it and/or modify it under
dvander@2168:  * the terms of the GNU General Public License, version 3.0, as published by the
dvander@2168:  * Free Software Foundation.
dvander@2168:  * 
dvander@2168:  * This program is distributed in the hope that it will be useful, but WITHOUT
dvander@2168:  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
dvander@2168:  * FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
dvander@2168:  * details.
dvander@2168:  *
dvander@2168:  * You should have received a copy of the GNU General Public License along with
dvander@2168:  * this program.  If not, see <http://www.gnu.org/licenses/>.
dvander@2168:  *
dvander@2168:  * As a special exception, AlliedModders LLC gives you permission to link the
dvander@2168:  * code of this program (as well as its derivative works) to "Half-Life 2," the
dvander@2168:  * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
dvander@2168:  * by the Valve Corporation.  You must obey the GNU General Public License in
dvander@2168:  * all respects for all other code used.  Additionally, AlliedModders LLC grants
dvander@2168:  * this exception to all derivative works.  AlliedModders LLC defines further
dvander@2168:  * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
dvander@2168:  * or <http://www.sourcemod.net/license.php>.
dvander@2168:  *
dvander@2168:  * Version: $Id$
dvander@2168:  */
dvander@2168:  
dvander@2168: #if defined _adt_stack_included
dvander@2168:  #endinput
dvander@2168: #endif
dvander@2168: #define _adt_stack_included
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Creates a stack structure.  A stack is a LIFO (last in, first out) 
dvander@2168:  * vector (array) of items.  It has O(1) insertion and O(1) removal.
dvander@2168:  *
dvander@2168:  * Stacks have two operations: Push (adding an item) and Pop (removes 
dvander@2168:  * items in reverse-push order).
dvander@2168:  * 
dvander@2168:  * The contents of the stack are uniform; i.e. storing a string and then 
dvander@2168:  * retrieving it as an integer is NOT the same as StringToInt()!
dvander@2168:  *
dvander@2168:  * The "blocksize" determines how many cells each slot has; it cannot
dvander@2168:  * be changed after creation.
dvander@2168:  *
dvander@2168:  * @param blocksize		The number of cells each entry in the stack can 
dvander@2168:  *						hold.  For example, 32 cells is equivalent to:
dvander@2168:  *						new Array[X][32]
dvander@2168:  * @return				New stack Handle.
dvander@2168:  */
dvander@2168: native Handle:CreateStack(blocksize=1);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Pushes a value onto the end of the stack, adding a new index.
dvander@2168:  *
dvander@2168:  * This may safely be used even if the stack has a blocksize
dvander@2168:  * greater than 1.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @param value			Value to push.
dvander@2168:  * @noreturn
dvander@2168:  * @error				Invalid Handle or out of memory.
dvander@2168:  */
dvander@2168: native PushStackCell(Handle:stack, any:value);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Pushes a string onto the end of a stack, truncating it if it is 
dvander@2168:  * too big.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @param value			String to push.
dvander@2168:  * @noreturn
dvander@2168:  * @error				Invalid Handle or out of memory.
dvander@2168:  */
dvander@2168: native PushStackString(Handle:stack, const String:value[]);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Pushes an array of cells onto the end of a stack.  The cells
dvander@2168:  * are pushed as a block (i.e. the entire array takes up one stack slot),
dvander@2168:  * rather than pushing each cell individually.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @param values		Block of values to copy.
dvander@2168:  * @param size			If not set, the number of elements copied from the array
dvander@2168:  *						will be equal to the blocksize.  If set higher than the 
dvander@2168:  *						blocksize, the operation will be truncated.
dvander@2168:  * @noreturn
dvander@2168:  * @error				Invalid Handle or out of memory.
dvander@2168:  */
dvander@2168: native PushStackArray(Handle:stack, const any:values[], size=-1);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Pops a cell value from a stack.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @param value			Variable to store the value.
dvander@2168:  * @param block			Optionally specify which block to read from
dvander@2168:  *						(useful if the blocksize > 0).
dvander@2168:  * @param asChar		Optionally read as a byte instead of a cell.
dvander@2168:  * @return				True on success, false if the stack is empty.
dvander@2168:  * @error				Invalid Handle.
dvander@2168:  */
dvander@2168: native bool:PopStackCell(Handle:stack, &any:value, block=0, bool:asChar=false);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Pops a string value from a stack.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @param buffer		Buffer to store string.
dvander@2168:  * @param maxlength		Maximum size of the buffer.
dvander@2168:  * @return				True on success, false if the stack is empty.
dvander@2168:  * @error				Invalid Handle.
dvander@2168:  */
dvander@2168: native bool:PopStackString(Handle:stack, String:buffer[], maxlength, &written=0);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Pops an array of cells from a stack.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @param buffer		Buffer to store the array in.
dvander@2168:  * @param size			If not set, assumes the buffer size is equal to the
dvander@2168:  *						blocksize.  Otherwise, the size passed is used.
dvander@2168:  * @return				True on success, false if the stack is empty.
dvander@2168:  * @error				Invalid Handle.
dvander@2168:  */
dvander@2168: native bool:PopStackArray(Handle:stack, any:buffer[], size=-1);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Checks if a stack is empty.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @return				True if empty, false if not empty.
dvander@2168:  * @error				Invalid Handle.
dvander@2168:  */
dvander@2168: native bool:IsStackEmpty(Handle:stack);
dvander@2168: 
dvander@2168: /**
dvander@2168:  * Pops a value off a stack, ignoring it completely.
dvander@2168:  *
dvander@2168:  * @param stack			Stack Handle.
dvander@2168:  * @return				True if something was popped, false otherwise.
dvander@2168:  * @error				Invalid Handle.
dvander@2168:  */
dvander@2168: stock PopStack(Handle:stack)
dvander@2168: {
dvander@2168: 	new value;
dvander@2168: 	
dvander@2168: 	return PopStackCell(stack, value);
dvander@2168: }