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