From ae86152282fbfd0a4060e41d7532463f351fa242 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Valentin=20Gr=C3=BCnbacher?= Date: Tue, 17 Feb 2015 15:25:53 +0100 Subject: [PATCH] cellarray/celltrie/cellstack: Documentation fixes and consistency updates --- plugins/include/cellarray.inc | 30 +++-- plugins/include/cellstack.inc | 138 ++++++++++--------- plugins/include/celltrie.inc | 244 ++++++++++++++++++++-------------- 3 files changed, 232 insertions(+), 180 deletions(-) diff --git a/plugins/include/cellarray.inc b/plugins/include/cellarray.inc index 3c52a233..261c4707 100644 --- a/plugins/include/cellarray.inc +++ b/plugins/include/cellarray.inc @@ -63,7 +63,9 @@ stock ByteCountToCells(size) * number of items. The items are not valid to read or set * until they have actually been pushed into the array. * - * @return Handle to the array. + * @return New array handle, which must be freed via ArrayDestroy() + * @error If an invalid cellsize is provided an error will be + * thrown. */ native Array:ArrayCreate(cellsize = 1, reserved = 32); @@ -431,7 +433,7 @@ native DoNotUse:ArrayGetStringHandle(Array:which, item); * * @param which Array to destroy * - * @return 1 if the array was destroyed, 0 if nothing had to be + * @return 1 if the Array was destroyed, 0 if nothing had to be * destroyed (invalid handle) */ native ArrayDestroy(&Array:which); @@ -444,10 +446,10 @@ native ArrayDestroy(&Array:which); * * public MySortFunc(Array:array, item1, item2, const data[], data_size) * - * array - Array handle in its current un-sorted state - * item1, item2 - Current item pair being compared - * data[] - Extra data array passed to the sort func - * data_size - Size of extra data + * array - Array handle in its current un-sorted state + * item1, item2 - Current item pair being compared + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * * @note The comparison function should return: * -1 if item1 should go before item2 @@ -485,20 +487,20 @@ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); * * public MySortFunc(Array:array, elem1, elem2, const data[], data_size) * - * array - Array handle in its current un-sorted state - * elem1, elem2 - Current element pair being compared - * data[] - Extra data array passed to the sort func - * data_size - Size of extra data + * array - Array handle in its current un-sorted state + * elem1, elem2 - Current element pair being compared + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * * @note For Arrays with a cellsize larger than 1 (used for storing arrays and * strings), the function is called in the following manner: * * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size) * - * array - Array handle in its current un-sorted state - * elem1[], elem2[] - Current element pair being compared - * data[] - Extra data array passed to the sort func - * data_size - Size of extra data + * array - Array handle in its current un-sorted state + * elem1[], elem2[] - Current element pair being compared + * data[] - Extra data array passed to the sort func + * data_size - Size of extra data * * * @note The comparison function should return: diff --git a/plugins/include/cellstack.inc b/plugins/include/cellstack.inc index 81043d76..15e8567f 100644 --- a/plugins/include/cellstack.inc +++ b/plugins/include/cellstack.inc @@ -12,131 +12,139 @@ #endif #define _cellstack_included +/** + * Stack tag declaration + * + * @note Plugins are responsible for freeing all Stack handles they acquire. + * Failing to free handles will result in the plugin and AMXX leaking + * memory. + */ 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. + * Creates a stack structure. A stack is a LIFO (last in, first out) vector of + * 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). + * @note Stacks provide only two operations: Push (adding an item to the top) + * and Pop (remove an item from the top, in reverse-push order). + * @note The contents of the stack are uniform; i.e. storing a string and then + * retrieving it as an integer is NOT the same as str_to_num()! + * @note The "blocksize" determines how many cells each stack slot has, it can + * not be changed after creation. * - * 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()! + * @param blocksize The number of cells each entry in the stack can hold * - * 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. + * @return New stack Handle, which must be freed via DestroyStack() + * @error If an invalid blocksize is provided an error will be + * thrown. */ 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. + * @note This may safely be used even if the stack has a blocksize greater than + * 1. * - * @param handle Stack handle. - * @param value Value to push. + * @param handle Stack handle + * @param value Value to push * * @noreturn - * @error Invalid handle or out of memory. + * @error If an invalid handle is provided or the resizing + * operation runs out of memory, an error will be thrown. */ native PushStackCell(Stack:handle, any:value); /** - * Pushes a string onto the end of a stack, truncating it if it is - * too big. + * Pushes a string onto the end of a stack, truncating it if it is too long. * - * @param handle Stack handle. - * @param value String to push. + * @param handle Stack handle + * @param value String to push * * @noreturn - * @error Invalid handle or out of memory. + * @error If an invalid handle is provided or the resizing + * operation runs out of memory, an error will be thrown. */ 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. + * 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, * - * @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. + * @error If an invalid handle is provided or the resizing + * operation runs out of memory, an error will be thrown. */ 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. + * @param handle Stack handle + * @param value Variable to store the value in + * @param block Optionally specify which block to read from (useful if the + * blocksize is > 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. + * @return True on success, false if the stack is empty. + * @error If an invalid handle, invalid block or invalid byte is + * provided, an error will be thrown. */ 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. + * @param handle Stack handle + * @param buffer Buffer to copy string to + * @param maxlength Maximum size of the buffer + * @param written Variable to store number of characters copied to * - * @return True on success, false if the stack is empty. - * @error Invalid handle. + * @return True on success, false if the stack is empty + * @error If an invalid handle is provided an error will be thrown. */ 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. + * @param handle Stack handle + * @param buffer Array to copy value to + * @param size Size of buffer, if not set (-1) assumes the size is equal to + * the stack blocksize * - * @return True on success, false if the stack is empty. - * @error Invalid handle. + * @return True on success, false if the stack is empty + * @error If an invalid handle is provided an error will be thrown. */ native bool:PopStackArray(Stack:handle, any:buffer[], size = -1); /** - * Checks if a stack is empty. + * Returns if a stack is empty. * - * @param handle Stack handle. + * @param handle Stack handle * - * @return True if empty, false if not empty. - * @error Invalid handle. + * @return True if empty, false if not empty + * @error If an invalid handle is provided an error will be thrown. */ native bool:IsStackEmpty(Stack:handle); /** * Pops a value off a stack, ignoring it completely. * - * @param handle Stack handle. + * @param handle Stack handle * - * @return True if something was popped, false otherwise. - * @error Invalid handle. + * @return True if a value was popped, false if stack is empty + * @error If an invalid handle is provided an error will be thrown. */ stock PopStack(Stack:handle) { @@ -145,10 +153,14 @@ stock PopStack(Stack:handle) } /** - * Destroys the stack, and resets the handle to 0 to prevent accidental usage after it is destroyed. + * Destroys a stack and frees its memory. * - * @param which The stack to destroy. + * @note The function automatically sets the variable passed to it to 0 to aid + * in preventing accidental usage after destroy. * - * @noreturn + * @param handle Stack to destroy + * + * @return 1 if the Stack was destroyed, 0 if nothing had to be + * destroyed (invalid handle) */ native DestroyStack(&Stack:handle); diff --git a/plugins/include/celltrie.inc b/plugins/include/celltrie.inc index 9a05a4b2..729be00c 100644 --- a/plugins/include/celltrie.inc +++ b/plugins/include/celltrie.inc @@ -8,180 +8,213 @@ // https://alliedmods.net/amxmodx-license #if defined _celltrie_included - #endinput + #endinput #endif #define _celltrie_included +/** + * Hash map tag declaration + * + * @note The word "Trie" in this API is historical. As of AMX Mod X 1.8.3, + * tries have been internally replaced with hash tables, which have O(1) + * insertion time instead of O(n). + * @note Plugins are responsible for freeing all Trie handles they acquire. + * Failing to free handles will result in the plugin and AMXX leaking + * memory. + */ enum Trie { Invalid_Trie = 0 }; +/** + * Hash map snapshot tag declaration + * + * @note Plugins are responsible for freeing all Snapshot handles they acquire. + * Failing to free handles will result in the plugin and AMXX leaking + * memory. + */ enum Snapshot { Invalid_Snapshot = 0 }; /** - * Creates a hash map. A hash map is a container that can map strings (called - * "keys") to arbitrary values (cells, arrays, or strings). Keys in a hash map - * are unique. That is, there is at most one entry in the map for a given key. + * Creates a hash map. A hash map is a container that maps strings (called keys) + * to arbitrary values (cells, arrays or strings). * - * Insertion, deletion, and lookup in a hash map are all considered to be fast - * operations, amortized to O(1), or constant time. + * @note Keys in a hash map are unique so there is no more than one entry in the + * map for any given key. + * @note Insertion, deletion, and lookup in a hash map are all considered to be + * fast operations, amortized to O(1), or constant time. * - * The word "Trie" in this API is historical. As of AMX Mod X 1.8.3, tries have - * been internally replaced with hash tables, which have O(1) insertion time - * instead of O(n). - * - * @return New Map handle, which must be freed via TrieDestroy(). + * @return New Map handle, which must be freed via TrieDestroy() */ native Trie:TrieCreate(); /** * Clears all entries from a Map. * - * @param handle Map handle. + * @param handle Map handle * - * @error Invalid handle. + * @error If an invalid handle is provided an error will be + * thrown. + * @noreturn */ native TrieClear(Trie:handle); /** - * Sets a value in a hash map, either inserting a new entry or replacing an old one. + * Sets a cell value in a hash map, either inserting a new entry or replacing + * an old one. * - * @param handle Map handle. - * @param key Key string. - * @param value Value to store at this key. - * @param replace If false, operation will fail if the key is already set. + * @param handle Map handle + * @param key Key string + * @param value Value to store + * @param replace If false the operation will fail if the key is already set * - * @return True on success, false on failure. - * @error Invalid handle. + * @return 1 on success, 0 otherwise + * @error If an invalid handle is provided an error will be + * thrown. */ native TrieSetCell(Trie:handle, const key[], any:value, bool:replace = true); /** - * Sets a string value in a Map, either inserting a new entry or replacing an old one. + * Sets a string value in a hash map, either inserting a new entry or replacing + * an old one. * - * @param handle Map handle. - * @param key Key string. - * @param value String to store. - * @param replace If false, operation will fail if the key is already set. + * @param handle Map handle + * @param key Key string + * @param value String to store + * @param replace If false the operation will fail if the key is already set * - * @return True on success, false on failure. - * @error Invalid handle. + * @return 1 on success, 0 otherwise + * @error If an invalid handle is provided an error will be + * thrown. */ native TrieSetString(Trie:handle, const key[], const value[], bool:replace = true); /** - * Sets an array value in a Map, either inserting a new entry or replacing an old one. + * Sets an array value in a hash map, either inserting a new entry or replacing + * an old one. * - * @param handle Map handle. - * @param key Key string. - * @param buffer Array to store. - * @param size Number of items in the array. - * @param replace If false, operation will fail if the key is already set. + * @param handle Map handle + * @param key Key string + * @param buffer Array to store + * @param size Array size + * @param replace If false the operation will fail if the key is already set * - * @return True on success, false on failure. - * @error Invalid handle. - * Invalid array size. + * @return 1 on success, 0 otherwise + * @error If an invalid handle is provided an error will be + * thrown. or invalid array size */ native TrieSetArray(Trie:handle, const key[], const any:buffer[], size, bool:replace = true); /** - * Retrieves a value in a Map. + * Retrieves a cell value from a hash map. * - * @param handle Map handle. - * @param key Key string. - * @param value Variable to store value. - * @return True on success. False if the key is not set, or the key is set - * as an array or string (not a value). - * @error Invalid handle. + * @param handle Map handle + * @param key Key string + * @param value Variable to store value to + * + * @return True on success, false if either the key is not set or the + * value type does not match (value is string or array) + * @error If an invalid handle is provided an error will be + * thrown. */ native bool:TrieGetCell(Trie:handle, const key[], &any:value); /** - * Retrieves a string in a Map. + * Retrieves a string from a hash map. * - * @param handle Map handle. - * @param key Key string. - * @param output Buffer to store value. - * @param outputsize Maximum size of string buffer. - * @param size Optional parameter to store the number of bytes written to the buffer. + * @param handle Map handle + * @param key Key string + * @param output Buffer to copy the value to + * @param outputsize Maximum size of buffer + * @param size Optional variable to store the number of cells written + * to the buffer in * - * @return True on success. False if the key is not set, or the key is set - * as a value or array (not a string). - * @error Invalid handle. - * Invalid buffer size. + * @return True on success, false if either the key is not set or + * the value type does not match (value is cell or array) + * @error If an invalid handle is provided an error will be + * thrown. */ native bool:TrieGetString(Trie:handle, const key[], output[], outputsize, &size = 0); /** - * Retrieves an array in a Map. + * Retrieves a string from a hash map. * - * @param handle Map handle. - * @param key Key string. - * @param output Buffer to store array. - * @param outputsize Maximum size of array buffer. - * @param size Optional parameter to store the number of elements written to the buffer. + * @param handle Map handle + * @param key Key string + * @param output Array to copy the value to + * @param outputsize Maximum size of array + * @param size Optional variable to store the number of cells written + * to the array in * - * @return True on success. False if the key is not set, or the key is set - * as a value or string (not an array). - * @error Invalid handle. - * Invalid array size. + * @return True on success, false if either the key is not set or + * the value type does not match (value is cell or string) + * @error If an invalid handle or array size is provided an error + * will be thrown. */ native bool:TrieGetArray(Trie:handle, const key[], any:output[], outputsize, &size = 0); /** - * Removes a key entry from a Map. + * Removes an entry from a hash map. * - * @param handle Map handle. - * @param key Key string. + * @param handle Map handle + * @param key Key string * - * @return True on success, false if the value was never set. - * @error Invalid handle. + * @return True on success, false if the key was never set + * @error If an invalid handle is provided an error will be + * thrown. */ native bool:TrieDeleteKey(Trie:handle, const key[]); /** - * Checks a key entry existence from a Map. + * Checks a hash map for the existence of an entry. * - * @param handle Map handle. - * @param key Key string. + * @param handle Map handle + * @param key Key string * - * @return True on success, false if the value was never set. - * @error Invalid handle. + * @return True if the key is set, false otherwise + * @error If an invalid handle is provided an error will be + * thrown. */ native bool:TrieKeyExists(Trie:handle, const key[]); /** - * Destroys a Map. + * Destroys a hash map and frees its memory. * - * @param handle Map handle. + * @note The function automatically sets the variable passed to it to 0 to aid + * in preventing accidental usage after destroy. * - * @return True on success, false if the value was never set. - * @error Invalid handle. + * @param handle Map handle + * + * @return 1 on success, 0 if an invalid handle was passed in */ native TrieDestroy(&Trie:handle); /** - * Retrieves the number of elements in a map. + * Returns the number of entries in a hash map. * - * @param handle Map handle. + * @param handle Map handle * - * @return Number of elements in the trie. - * @error Invalid handle. + * @return Number of elements in the hash map + * @error If an invalid handle is provided an error will be + * thrown. */ native TrieGetSize(Trie:handle); /** - * Creates a snapshot of all keys in the map. If the map is changed after this - * call, the changes are not reflected in the snapshot. Keys are not sorted. + * Creates a snapshot of all keys in a hash map. If the map is changed + * afterwards, the changes are not reflected in the snapshot. + * Keys are not sorted. * - * @param handle Map handle. + * @param handle Map handle * - * @return New map snapshot handle, which must be freed via TrieSnapshotDestroy(). - * @error Invalid handle. + * @return New map snapshot handle, which must be freed via + * TrieSnapshotDestroy() + * @error If an invalid handle is provided an error will be + * thrown. */ native Snapshot:TrieSnapshotCreate(Trie:handle); @@ -190,10 +223,11 @@ native Snapshot:TrieSnapshotCreate(Trie:handle); * different from the size of the map, since the map can change after the * snapshot of its keys was taken. * - * @param handle Map snapshot. + * @param handle Map snapshot handle * - * @return Number of keys. - * @error Invalid handle. + * @return Number of keys + * @error If an invalid handle is provided an error will be + * thrown. */ native TrieSnapshotLength(Snapshot:handle); @@ -201,33 +235,37 @@ native TrieSnapshotLength(Snapshot:handle); * Returns the buffer size required to store a given key. That is, it returns * the length of the key plus one. * - * @param handle Map snapshot. - * @param index Key index (starting from 0). + * @param handle Map snapshot handle + * @param index Key index (starting from 0) * - * @return Buffer size required to store the key string. - * @error Invalid handle or index out of range. + * @return Buffer size required to store the key string + * @error If an invalid handle is provided an error will be + * thrown. or index out of range */ native TrieSnapshotKeyBufferSize(Snapshot:handle, index); /** * Retrieves the key string of a given key in a map snapshot. * - * @param handle Map snapshot. - * @param index Key index (starting from 0). - * @param buffer String buffer. - * @param maxlength Maximum buffer length. + * @param handle Map snapshot handle + * @param index Key index (starting from 0) + * @param buffer String buffer + * @param maxlength Maximum buffer length * - * @return Number of bytes written to the buffer. - * @error Invalid handle or index out of range. + * @return Number of bytes written to the buffer + * @error If an invalid handle is provided an error will be + * thrown. or index out of range */ native TrieSnapshotGetKey(Snapshot:handle, index, buffer[], maxlength); /** - * Destroys a Map snapshot + * Destroys a map snapshot and frees its memory. * - * @param handle Map snapshot. + * @note The function automatically sets the variable passed to it to 0 to aid + * in preventing accidental usage after destroy. * - * @return True on success, false if the value was never set. - * @error Invalid handle. + * @param handle Map snapshot handle + * + * @return 1 on success, 0 if an invalid handle was passed in */ native TrieSnapshotDestroy(&Snapshot:handle);