From 950f3f97c1d4c72e5d5961d399df4a59f43f2303 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 24 Feb 2015 22:16:36 +0100 Subject: [PATCH] datapack: Tabs->spaces, consistency, nuke IsPackReadable --- plugins/include/datapack.inc | 138 +++++++++++++++++++---------------- 1 file changed, 76 insertions(+), 62 deletions(-) diff --git a/plugins/include/datapack.inc b/plugins/include/datapack.inc index 80d12648..27950db5 100644 --- a/plugins/include/datapack.inc +++ b/plugins/include/datapack.inc @@ -8,131 +8,145 @@ // https://alliedmods.net/amxmodx-license #if defined _datapack_included - #endinput + #endinput #endif -#define _datapack_included +#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. + * Datapack tag declaration + * + * @note Datapacks provide a way to store and move around arbitrary amounts (and + * types) of data in AMX Mox X. Data is packed into a single cell value - + * the DataPack handle. This handle can be passed around more easily, can + * be returned by functions and can simulate advanced concepts like string + * consummation. + * @note Plugins are responsible for freeing all datapack handles they acquire. + * Failing to free handles will result in the plugin and AMXX leaking + * memory. */ enum DataPack { - Invalid_DataPack = 0 + Invalid_DataPack = 0 }; /** - * Creates a new data pack. + * Creates a new datapack. * - * @return A Handle to the data pack. + * @return New datapack handle, which must be freed via DestroyDataPack(). */ native DataPack:CreateDataPack(); /** - * Packs a normal cell into a data pack. + * Packs a cell value into a datapack. + * + * @param pack Datapack handle + * @param cell Cell value to pack * - * @param pack Handle to the data pack. - * @param cell Cell to add. * @noreturn - * @error Invalid handle. + * @error If an invalid handle is provided, an error will be thrown. */ native WritePackCell(DataPack:pack, any:cell); /** - * Packs a float into a data pack. + * Packs a float value into a datapack. + * + * @param pack Datapack handle + * @param val Float value to pack * - * @param pack Handle to the data pack. - * @param val Float to add. * @noreturn - * @error Invalid handle. + * @error If an invalid handle is provided, an error will be thrown. */ native WritePackFloat(DataPack:pack, Float:val); /** - * Packs a string into a data pack. + * Packs a string into a datapack. * - * @param pack Handle to the data pack. - * @param str String to add. - * @return Length of copied string. - * @error Invalid handle. + * @param pack Datapack handle + * @param str String to pack + * + * @return Length of copied string + * @error If an invalid handle is provided, an error will be thrown. */ native WritePackString(DataPack:pack, const str[]); /** - * Reads a cell from a data pack. + * Reads a cell from a Datapack. * - * @param pack Handle to the data pack. - * @return Cell value. - * @error Invalid handle, or bounds error. + * @param pack Datapack handle + * + * @return Cell value + * @error If an invalid handle is provided, or not enough data is left + * in the datapack, an error will be thrown. */ native any:ReadPackCell(DataPack:pack); /** - * Reads a float from a data pack. + * Reads a float from a datapack. * - * @param pack Handle to the data pack. - * @return Float value. - * @error Invalid handle, or bounds error. + * @param pack Datapack handle + * + * @return Float value + * @error If an invalid handle is provided, or not enough data is left + * in the datapack, an error will be thrown. */ -native Float:ReadPackFloat(DataPack:pack); +native Float:ReadPackFloat(datapack:pack); /** - * Reads a string from a data pack. + * Reads a string from a Datapack. * - * @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. + * @param pack Datapack handle + * @param buffer Buffer to copy string to + * @param maxlen Maximum size of buffer + * + * @return Number of cells written to buffer + * @error If an invalid handle is provided, or not enough data is left + * in the datapack, an error will be thrown. */ native ReadPackString(DataPack:pack, buffer[], maxlen); /** - * Resets the position in a data pack. + * Resets the datapack read/write position to the start. + * + * @param pack Datapack handle + * @param clear If true, clears the contained data * - * @param pack Handle to the data pack. - * @param clear If true, clears the contained data. * @noreturn - * @error Invalid handle. + * @error If an invalid handle is provided, an error will be thrown. */ -native ResetPack(DataPack:pack, bool:clear=false); +native ResetPack(DataPack:pack, bool:clear = false); /** - * Returns the read or write position in a data pack. + * Returns the datapack read/write position. * - * @param pack Handle to the data pack. - * @return Numerical position in the data pack. - * @error Invalid handle. + * @param pack Datapack handle + * + * @return Position in the datapack + * @error If an invalid handle is provided, an error will be thrown. */ native GetPackPosition(DataPack:pack); /** - * Sets the read/write position in a data pack. + * Sets the datapack read/write position. + * + * @note This should only ever be used with (known to be valid) positions + * returned by GetPackPosition(). It is not possible for plugins to safely + * compute datapack positions. + * + * @param pack Datapack handle + * @param position New position to set * - * @param pack Handle to the data pack. - * @param position New position to set. * @noreturn - * @error Invalid handle, or position is beyond the pack bounds. + * @error If an invalid handle is provided, or the new position is + * out of datapack bounds, an error will be thrown. */ 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. + * Destroys the datapack and frees its memory. * - * @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 Datapack handle * - * @param pack Handle to the data pack. - * @return True if disposed, false otherwise. + * @return True if disposed, false otherwise */ native DestroyDataPack(&DataPack:pack);