Introduce DataPacks (bug 5885, r=ds)

plugins/include/amxmodx.inc

@@ -23,6 +23,7 @@
 #include <sorting>
 #include <cellarray>
 #include <celltrie>
+#include <datapack>
 #include <newmenus>
 
 /* Function is called just after server activation.

plugins/include/datapack.inc

@@ -0,0 +1,130 @@
+
+#if defined _datapack_included
+	#endinput
+#endif
+#define _datapack_included	
+
+/**
+ * DataPacks are a way to store and move around various types of data in AMX Mod X Scripting. 
+ * Since some things are not possible in AMX Mod X, such as a function consuming a String, 
+ * DataPacks help us get these Strings and other items where they need to go.
+ */
+
+enum DataPack
+{
+	Invalid_DataPack = 0
+};
+
+/**
+ * Creates a new data pack.
+ *
+ * @return			A Handle to the data pack.
+ */
+native DataPack:CreateDataPack();
+
+/**
+ * Packs a normal cell into a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @param cell		Cell to add.
+ * @noreturn
+ * @error			Invalid handle.
+ */
+native WritePackCell(DataPack:pack, cell);
+
+/**
+ * Packs a float into a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @param val		Float to add.
+ * @noreturn
+ * @error			Invalid handle.
+ */
+native WritePackFloat(DataPack:pack, Float:val);
+
+/**
+ * Packs a string into a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @param str		String to add.
+ * @return			Length of copied string.
+ * @error			Invalid handle.
+ */
+native WritePackString(DataPack:pack, const str[]);
+
+/**
+ * Reads a cell from a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @return			Cell value.
+ * @error			Invalid handle, or bounds error.
+ */
+native ReadPackCell(DataPack:pack);
+
+/**
+ * Reads a float from a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @return			Float value.
+ * @error			Invalid handle, or bounds error.
+ */
+native Float:ReadPackFloat(DataPack:pack);
+
+/**
+ * Reads a string from a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @param buffer	Destination string buffer.
+ * @param maxlen	Maximum length of output string buffer.
+ * @return			Length of output string.
+ * @error			Invalid handle, or bounds error.
+ */
+native ReadPackString(DataPack:pack, buffer[], maxlen);
+
+/**
+ * Resets the position in a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @param clear		If true, clears the contained data.
+ * @noreturn
+ * @error			Invalid handle.
+ */
+native ResetPack(DataPack:pack, bool:clear=false);
+
+/**
+ * Returns the read or write position in a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @return			Numerical position in the data pack.
+ * @error			Invalid handle.
+ */
+native GetPackPosition(DataPack:pack);
+
+/**
+ * Sets the read/write position in a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @param position	New position to set.
+ * @noreturn
+ * @error			Invalid handle, or position is beyond the pack bounds.
+ */
+native SetPackPosition(DataPack:pack, position);
+
+/**
+ * Returns whether or not a specified number of bytes from the data pack
+ *  position to the end can be read.
+ *
+ * @param pack		Handle to the data pack.
+ * @param bytes		Number of bytes to simulate reading.
+ * @return			True if can be read, false otherwise.
+ * @error			Invalid handle.
+ */
+native bool:IsPackReadable(DataPack:pack, bytes);
+
+/**
+ * Disposes of a data pack.
+ *
+ * @param pack		Handle to the data pack.
+ * @return			True if disposed, false otherwise.
+ */
+native DestroyDataPack(&DataPack:pack);

plugins/testsuite/datapack_test.sma

@@ -0,0 +1,82 @@
+#include <amxmodx>
+
+new failcount;
+new passcount;
+
+public plugin_init()
+{
+	register_plugin("Datapack Test", AMXX_VERSION_STR, "AMXX Dev Team");
+	register_srvcmd("datapacktest", "datapacktest");
+}
+
+test(const testname[], bool:pass)
+{
+	if (!pass)
+	{
+		server_print("[FAIL] %s", testname);
+		failcount++;
+	}
+	else
+	{
+		server_print("[PASS] %s", testname);
+		passcount++;
+	}
+}
+
+stock done()
+{
+	server_print("Finished. %d tests, %d failed", failcount + passcount, failcount);
+}
+
+public datapacktest()
+{
+	failcount = 0;
+	passcount = 0;
+	
+	new DataPack:pack = CreateDataPack();
+	new DataPack:oldPack = pack; // Makes sure that the trie handle system recycles old handles
+	
+	new refCell = 23;
+	new Float:refFloat = 42.42;
+	new refString[] = "I'm a little teapot.";
+	
+	// Write
+	WritePackCell(pack, refCell);		// 8 
+	WritePackString(pack, refString);	// 25 (sizeof string + 4)
+	WritePackFloat(pack, refFloat);		// 8
+	 
+	test("Position #1 test", .pass = GetPackPosition(pack) == 41);
+	test("Readable #1 test", .pass = !IsPackReadable(pack, 41));
+	
+	//resets the index to the beginning, necessary for read.
+	ResetPack(pack);
+	
+	test("Position #2 test", .pass = GetPackPosition(pack) == 0 );
+	test("Readable #2 test", .pass = IsPackReadable(pack, 15));
+	
+	// Read
+	new cellValue = ReadPackCell(pack);
+	new buffer[1024];
+	ReadPackString(pack, buffer, 1024);
+	new Float:floatvalue = ReadPackFloat(pack);
+	
+	test("Cell test", .pass = cellValue == refCell);
+	test("String test", .pass = bool:equal(buffer, refString));
+	test("Float test #1", .pass = floatvalue == refFloat);
+	
+	SetPackPosition(pack, 33);
+	test("Set Position test", .pass = GetPackPosition(pack) == 33);
+	
+	WritePackFloat(pack, refFloat + 1);
+	SetPackPosition(pack, 33);
+	test("Float test #2", .pass = ReadPackFloat(pack) == refFloat + 1);
+
+	ResetPack(pack, .clear = true);
+	test("Clear test", .pass = !IsPackReadable(pack, 15));
+	
+	DestroyDataPack(pack);
+	
+	test("Recycle handles", CreateDataPack() == oldPack);
+	
+	done();
+}