Introduce API to create Stack structures

plugins/include/amxmodx.inc

@@ -22,6 +22,7 @@
 #include <vector>
 #include <sorting>
 #include <cellarray>
+#include <cellstack>
 #include <celltrie>
 #include <datapack>
 #include <newmenus>

plugins/include/cellstack.inc

@@ -0,0 +1,146 @@
+
+#if defined _cellstack_included
+	#endinput
+#endif
+#define _cellstack_included
+
+enum Stack
+{
+	Invalid_Stack = 0
+};
+
+/**
+ * Creates a stack structure.  A stack is a LIFO (last in, first out)
+ * vector (array) of items.  It has O(1) insertion and O(1) removal.
+ *
+ * Stacks have two operations: Push (adding an item) and Pop (removes
+ * items in reverse-push order).
+ *
+ * The contents of the stack are uniform; i.e. storing a string and then
+ * retrieving it as an integer is NOT the same as StringToInt()!
+ *
+ * The "blocksize" determines how many cells each slot has; it cannot
+ * be changed after creation.
+ *
+ * @param blocksize     The number of cells each entry in the stack can
+ *                      hold.  For example, 32 cells is equivalent to:
+ *                      new Array[X][32]
+ *
+ * @return              New stack Handle.
+ * @error               Invalid block size.
+ */
+native Stack:CreateStack(blocksize = 1);
+
+/**
+ * Pushes a value onto the end of the stack, adding a new index.
+ *
+ * This may safely be used even if the stack has a blocksize
+ * greater than 1.
+ *
+ * @param handle        Stack handle.
+ * @param value         Value to push.
+ *
+ * @noreturn
+ * @error               Invalid handle or out of memory.
+ */
+native PushStackCell(Stack:handle, any:value);
+
+/**
+ * Pushes a string onto the end of a stack, truncating it if it is
+ * too big.
+ *
+ * @param handle        Stack handle.
+ * @param value         String to push.
+ *
+ * @noreturn
+ * @error               Invalid handle or out of memory.
+ */
+native PushStackString(Stack:handle, const value[]);
+
+/**
+ * Pushes an array of cells onto the end of a stack.  The cells
+ * are pushed as a block (i.e. the entire array takes up one stack slot),
+ * rather than pushing each cell individually.
+ *
+ * @param handle        Stack handle.
+ * @param values        Block of values to copy.
+ * @param size          If not set, the number of elements copied from the array
+ *                      will be equal to the blocksize.  If set higher than the
+ *                      blocksize, the operation will be truncated.
+ * @noreturn
+ * @error               Invalid handle or out of memory.
+ */
+native PushStackArray(Stack:handle, const any:values[], size= -1);
+
+/**
+ * Pops a cell value from a stack.
+ *
+ * @param handle        Stack handle.
+ * @param value         Variable to store the value.
+ * @param block         Optionally specify which block to read from
+ *                      (useful if the blocksize > 0).
+ * @param asChar        Optionally read as a byte instead of a cell.
+ *
+ * @return              True on success, false if the stack is empty.
+ * @error               Invalid handle, Invalid block or Invalid byte.
+ */
+native bool:PopStackCell(Stack:handle, &any:value, block = 0, bool:asChar = false);
+
+/**
+ * Pops a string value from a stack.
+ *
+ * @param handle        Stack handle.
+ * @param buffer        Buffer to store string.
+ * @param maxlength     Maximum size of the buffer.
+ * @param written       Number of characters copied.
+ *
+ * @return              True on success, false if the stack is empty.
+ * @error               Invalid handle.
+ */
+native bool:PopStackString(Stack:handle, buffer[], maxlength, &written = 0);
+
+/**
+ * Pops an array of cells from a stack.
+ *
+ * @param handle        Stack handle.
+ * @param buffer        Buffer to store the array in.
+ * @param size          If not set, assumes the buffer size is equal to the
+ *                      blocksize.  Otherwise, the size passed is used.
+ *
+ * @return              True on success, false if the stack is empty.
+ * @error               Invalid handle.
+ */
+native bool:PopStackArray(Stack:handle, any:buffer[], size = -1);
+
+/**
+ * Checks if a stack is empty.
+ *
+ * @param handle        Stack handle.
+ *
+ * @return              True if empty, false if not empty.
+ * @error               Invalid handle.
+ */
+native bool:IsStackEmpty(Stack:handle);
+
+/**
+ * Pops a value off a stack, ignoring it completely.
+ *
+ * @param handle        Stack handle.
+ *
+ * @return              True if something was popped, false otherwise.
+ * @error               Invalid handle.
+ */
+stock PopStack(Stack:handle)
+{
+	new value;
+	return PopStackCell(handle, value);
+}
+
+/**
+ * Destroys the stack, and resets the handle to 0 to prevent accidental usage after it is destroyed.
+ *
+ * @param which         The stack to destroy.
+ *
+ * @noreturn
+ */
+native DestroyStack(&Stack:handle);

plugins/testsuite/stacktest.sma

@@ -0,0 +1,73 @@
+#include <amxmodx>
+
+new FailCount;
+new PassCount;
+
+public plugin_init()
+{
+	register_plugin("Stack Tests", AMXX_VERSION_STR, "AMXX Dev Team");
+	register_srvcmd("test_stack", "ServerCommand_TestStack");
+}
+
+assertEqual(const testname[], bool:pass)
+{
+	if (!pass)
+	{
+		server_print("[FAIL] %s", testname);
+		FailCount++;
+	}
+	else
+	{
+		server_print("[PASS] %s", testname);
+		PassCount++;
+	}
+}
+
+done()
+{
+	server_print("Finished. %d tests, %d failed", FailCount + PassCount, FailCount);
+}
+
+public ServerCommand_TestStack()
+{
+	new Stack:stack;
+	new test[20];
+	new buffer[42];
+
+	test[0] = 5;
+	test[1] = 7;
+
+	stack = CreateStack(30);
+	{
+		PushStackCell(stack, 50);
+		PushStackArray(stack, test, 2);
+		PushStackArray(stack, test, 2);
+		PushStackString(stack, "space craaab");
+		PushStackCell(stack, 12);
+	}
+
+	assertEqual("Size test #1", IsStackEmpty(stack) == false);
+
+	PopStack(stack);
+	PopStackString(stack, buffer, charsmax(buffer));
+	assertEqual("String test", bool:equal(buffer, "space craaab"));
+
+	test[0] = 0;
+	test[1] = 0;
+	assertEqual("Array test #1", test[0] == 0 && test[1] == 0);
+
+	PopStackArray(stack, test, 2);
+	assertEqual("Array test #1", test[0] == 5 && test[1] == 7);
+
+	PopStackCell(stack, test[0], 1);
+	assertEqual("Value test #1", test[0] == 7);
+
+	PopStackCell(stack, test[0]);
+	assertEqual("Value test #2", test[0] == 50);
+
+	assertEqual("Size test #2", IsStackEmpty(stack) == true);
+
+	DestroyStack(stack);
+
+	done();
+}