3 * =============================================================================
4 * SourceMod (C)2004-2008 AlliedModders LLC. All rights reserved.
5 * =============================================================================
7 * This file is part of the SourceMod/SourcePawn SDK.
9 * This program is free software; you can redistribute it and/or modify it under
10 * the terms of the GNU General Public License, version 3.0, as published by the
11 * Free Software Foundation.
13 * This program is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
15 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
18 * You should have received a copy of the GNU General Public License along with
19 * this program. If not, see <http://www.gnu.org/licenses/>.
21 * As a special exception, AlliedModders LLC gives you permission to link the
22 * code of this program (as well as its derivative works) to "Half-Life 2," the
23 * "Source Engine," the "SourcePawn JIT," and any Game MODs that run on software
24 * by the Valve Corporation. You must obey the GNU General Public License in
25 * all respects for all other code used. Additionally, AlliedModders LLC grants
26 * this exception to all derivative works. AlliedModders LLC defines further
27 * exceptions, found in LICENSE.txt (as of this writing, version JULY-31-2007),
28 * or <http://www.sourcemod.net/license.php>.
33 #if defined _adt_stack_included
36 #define _adt_stack_included
39 * Creates a stack structure. A stack is a LIFO (last in, first out)
40 * vector (array) of items. It has O(1) insertion and O(1) removal.
42 * Stacks have two operations: Push (adding an item) and Pop (removes
43 * items in reverse-push order).
45 * The contents of the stack are uniform; i.e. storing a string and then
46 * retrieving it as an integer is NOT the same as StringToInt()!
48 * The "blocksize" determines how many cells each slot has; it cannot
49 * be changed after creation.
51 * @param blocksize The number of cells each entry in the stack can
52 * hold. For example, 32 cells is equivalent to:
54 * @return New stack Handle.
56 native Handle:CreateStack(blocksize=1);
59 * Pushes a value onto the end of the stack, adding a new index.
61 * This may safely be used even if the stack has a blocksize
64 * @param stack Stack Handle.
65 * @param value Value to push.
67 * @error Invalid Handle or out of memory.
69 native PushStackCell(Handle:stack, any:value);
72 * Pushes a string onto the end of a stack, truncating it if it is
75 * @param stack Stack Handle.
76 * @param value String to push.
78 * @error Invalid Handle or out of memory.
80 native PushStackString(Handle:stack, const String:value[]);
83 * Pushes an array of cells onto the end of a stack. The cells
84 * are pushed as a block (i.e. the entire array takes up one stack slot),
85 * rather than pushing each cell individually.
87 * @param stack Stack Handle.
88 * @param values Block of values to copy.
89 * @param size If not set, the number of elements copied from the array
90 * will be equal to the blocksize. If set higher than the
91 * blocksize, the operation will be truncated.
93 * @error Invalid Handle or out of memory.
95 native PushStackArray(Handle:stack, const any:values[], size=-1);
98 * Pops a cell value from a stack.
100 * @param stack Stack Handle.
101 * @param value Variable to store the value.
102 * @param block Optionally specify which block to read from
103 * (useful if the blocksize > 0).
104 * @param asChar Optionally read as a byte instead of a cell.
105 * @return True on success, false if the stack is empty.
106 * @error Invalid Handle.
108 native bool:PopStackCell(Handle:stack, &any:value, block=0, bool:asChar=false);
111 * Pops a string value from a stack.
113 * @param stack Stack Handle.
114 * @param buffer Buffer to store string.
115 * @param maxlength Maximum size of the buffer.
116 * @return True on success, false if the stack is empty.
117 * @error Invalid Handle.
119 native bool:PopStackString(Handle:stack, String:buffer[], maxlength, &written=0);
122 * Pops an array of cells from a stack.
124 * @param stack Stack Handle.
125 * @param buffer Buffer to store the array in.
126 * @param size If not set, assumes the buffer size is equal to the
127 * blocksize. Otherwise, the size passed is used.
128 * @return True on success, false if the stack is empty.
129 * @error Invalid Handle.
131 native bool:PopStackArray(Handle:stack, any:buffer[], size=-1);
134 * Checks if a stack is empty.
136 * @param stack Stack Handle.
137 * @return True if empty, false if not empty.
138 * @error Invalid Handle.
140 native bool:IsStackEmpty(Handle:stack);
143 * Pops a value off a stack, ignoring it completely.
145 * @param stack Stack Handle.
146 * @return True if something was popped, false otherwise.
147 * @error Invalid Handle.
149 stock PopStack(Handle:stack)
153 return PopStackCell(stack, value);
