File content in cellarray.inc // vim: set ts=4 sw=4 tw=99 noet: // // AMX Mod X, based on AMX Mod by Aleksander Naszko ("OLO"). // Copyright (C) The AMX Mod X Development Team. // // This software is licensed under the GNU General Public License, version 3 or higher. // Additional exceptions apply. For full license details, see LICENSE.txt or visit: // https://alliedmods.net/amxmodx-license #if defined _cellarray_included #endinput #endif #define _cellarray_included /** * Cellarray tag declaration * * @note These dynamic arrays are intended to be used for a form of global * storage without requiring a #define that needs to be increased each * time the plugin author requires more storage. These are not designed * to be a full replacement for normal arrays, as those are faster and * should be used whenever possible. * @note Plugins are responsible for freeing all Array handles they acquire, * including those from ArrayClone. Failing to free handles will result * in the plugin and AMXX leaking memory. */ enum Array { Invalid_Array = 0 }; /** * Returns the number of cells required to fit a string of the specified size * (including the null terminator). * * @param size Number of bytes. * * @return Minimum number of cells required to fit the byte count. */ stock ByteCountToCells(size) { if (!size) { return 1; } return (size + 3) / 4; } /** * Creates a handle to a dynamically sized array. * * @note It is very important that the provided cellsize matches up with the * buffer sizes that are passed with subsequent Array[Get|Set|Push] calls. * @note Initially the "reserved" parameter was intended to create blank entries * that would immediately be usable with Array[Get|Set] functions. This * functionality was never working as intended, and can now be achieved * using ArrayResize(). * * @param cellsize Size of each array entry in cells * @param reserved Pre-allocates space in the array for the specified * number of items. The items are not valid to read or set * until they have actually been pushed into 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); /** * Clones an array, returning a new handle with the same size and data. * * @param which Array handle * * @return Handle to the cloned array on success, 0 otherwise * @error If an invalid handle is provided an error will be * thrown. */ native Array:ArrayClone(Array:which); /** * Clears all entries from the array. * * @param which Array handle * * @noreturn * @error Invalid handle */ native ArrayClear(Array:which); /** * Returns the number of elements in the array. * * @param which Array handle * * @return Number of elements in the array * @error If an invalid handle is provided an error will be * thrown. */ native ArraySize(Array:which); /** * Resizes an array. * * @note If the size is smaller than the current array size the array is * truncated and data lost. * * @param which Array handle * @param newsize New size * * @noreturn * @error If an invalid handle is provided or the resizing * operation runs out of memory, an error will be thrown. */ native bool:ArrayResize(Array:which, newsize); /** * Retrieves an array of data from a cellarray. * * @note If the size parameter is specified as -1 the output buffer has to match * the size the array was created with. * * @param which Array handle * @param item Item index in the array * @param output Buffer to copy value to * @param size If not set, assumes the buffer size is equal to the * cellsize. Otherwise, the specified size is used. * * @return Number of cells copied * @error If an invalid handle or index is provided an error will * be thrown. */ native ArrayGetArray(Array:which, item, any:output[], size = -1); /** * Returns a single cell of data from an array * * @param which Array handle * @param item Item index in the array * @param block If the array has a cellsize >1 this optionally specifies * which block to read from * @param asChar If true reads the value as a byte instead of a cell * * @return Integer value * @error If an invalid handle, index or block is provided an * error will be thrown. */ native any:ArrayGetCell(Array:which, item, block = 0, bool:asChar = false); /** * Returieves string data from an array. * * @param which Array handle * @param item Item index in the array * @param output Buffer to copy value to * @param size Maximum size of the buffer * * @return Number of characters copied * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayGetString(Array:which, item, output[], size); /** * Fills an item's data with the contents of an array. * * @note If the size parameter is specified as -1 the input buffer has to match * the size the array was created with. * @note The item index must already be valid. Use ArrayPushArray to create * a new array item in the cellarray. * * @param which Array handle * @param item Item index in the array * @param input Array to copy to the cellarray * @param size If not set, assumes the buffer size is equal to the * cellsize. Otherwise, the specified size is used. * * @return Number of cells copied * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArraySetArray(Array:which, item, const any:input[], size =-1); /** * Sets an item's data to a single cell value. * * @note The item index must already be valid. Use ArrayPushArray to create * a new array item in the cellarray. * * @param which Array handle * @param item Item index in the array * @param input Value to set * @param block If the array has a cellsize >1 this optionally specifies * which block to write to * @param asChar If true writes the value as a byte instead of a cell * * @noreturn * @error If an invalid handle, index or block is provided an * error will be thrown. */ native ArraySetCell(Array:which, item, any:input, block = 0, bool:asChar = false); /** * Sets an item's data to a string value. * * @note The input will be truncated if it is longer than the cellsize the array * was created with. * @note The item index must already be valid. Use ArrayPushString to create * a new array item in the cellarray. * * @param which Array handle * @param item Item index in the array * @param input String to copy to the array * * @return Number of characters copied * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArraySetString(Array:which, item, const input[]); /** * Creates a new item at the end of the cellarray and copies the provided array * into it. * * @note The input will be truncated if it is bigger than the cellsize the array * was created with. * * @param which Array handle * @param input Array to copy to the cellarray * @param size If not set, assumes the buffer size is equal to the * cellsize. Otherwise, the specified size is used. * * @return Index of the new entry * @error If an invalid handle is provided or the resizing * operation runs out of memory, an error will be thrown. */ native ArrayPushArray(Array:which, const any:input[], size = -1); /** * Creates a new item at the end of the array and sets the item's single cell * value. * * @param which Array handle * @param input Value to set * * @return Index of the new entry * @error If an invalid handle is provided or the resizing * operation runs out of memory, an error will be thrown. */ native ArrayPushCell(Array:which, any:input); /** * Creates a new item at the end of the array and copies the provided string * into it. * * @note The input will be truncated if it is longer than the cellsize the array * was created with. * * @param which Array handle * @param input String to copy to the array * * @return Index of the new entry * @error If an invalid handle is provided or the resizing * operation runs out of memory, an error will be thrown. */ native ArrayPushString(Array:which, const input[]); /** * Creates a new item behind the specified item and copies the provided array * into it. All items beyond it get shifted up by one. * * @param which Array handle * @param item Item index in the array * @param input Array to copy to the cellarray * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayInsertArrayAfter(Array:which, item, const any:input[]); /** * Creates a new item behind the specified item and sets the item's single cell * value. All items beyond it get shifted up by one. * * @param which Array handle * @param item Item index in the array * @param input Value to set * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayInsertCellAfter(Array:which, item, any:input); /** * Creates a new item behind the specified item and copies the provided string * into it. All items beyond it get shifted up by one. * * @note The input will be truncated if it is longer than the cellsize the array * was created with. * * @param which Array handle * @param item Item index in the array * @param input String to copy to the array * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayInsertStringAfter(Array:which, item, const input[]); /** * Creates a new item in front of the specified item and copies the provided * array into it. All items beyond it get shifted up by one. * * @param which Array handle * @param item Item index in the array * @param input Array to copy to the cellarray * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayInsertArrayBefore(Array:which, item, const any:input[]); /** * Creates a new item in front of the specified item and sets the item's single * cell value. All items beyond it get shifted up by one. * * @param which Array handle * @param item Item index in the array * @param input Value to set * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayInsertCellBefore(Array:which, item, const any:input); /** * Creates a new item in front of the specified item and copies the provided * string into it. All items beyond it get shifted up by one. * * @note The input will be truncated if it is longer than the cellsize the array * was created with. * * @param which Array handle * @param item Item index in the array * @param input String to copy to the array * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayInsertStringBefore(Array:which, item, const input[]); /** * Swaps the position of two items. * * @param which Array handle * @param item1,item2 Item pair to swap * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArraySwap(Array:which, item1, item2); /** * Deletes an item from the array. All items beyond it get shifted down by one. * * @param which Array handle * @param item Item to delete * * @noreturn * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native ArrayDeleteItem(Array:which, item); /** * Searches through the array and returns the index of the first occurence of * the specified string. * * @param which Array handle * @param item String to search for * * @return Array index on success, -1 if the string can't be found * @error Invalid handle. */ native ArrayFindString(Array:which, const item[]); /** * Searches through the array and returns the index of the first occurence of * the specified value. * * @param which Array handle * @param item Value to search for * * @return Array index on success, -1 if the value can't be found * @error If an invalid handle is provided an error will be * thrown. */ native ArrayFindValue(Array:which, any:item); /** * Creates a special handle that can be passed to a string format routine for * printing as a string (with the %a format option). * * @note It is recommended to pass the function as a parameter to the format * routine directly. The array item must contain a null-terminated string! * @note Do not save or otherwise use the handles returned by this function. * @note Example usage: * console_print(id, "%a", ArrayGetStringHandle(MessageArray, i)); * * @param which Array handle * @param item Item to retrieve handle of * * @return Handle to the item * @error If an invalid handle or an invalid index is provided an * error will be thrown. */ native DoNotUse:ArrayGetStringHandle(Array:which, item); /** * Destroys the array and frees its memory. * * @note The function automatically sets the variable passed to it to 0 to aid * in preventing accidental usage after destroy. * * @param which Array to destroy * * @return 1 if the Array was destroyed, 0 if nothing had to be * destroyed (invalid handle) */ native ArrayDestroy(&Array:which); /** * Similar to sorting.inc's CustomSort, the sorting algorithm then uses the * custom comparison function to sort the data. * * @note The function is called in the following manner: * * 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 * * @note The comparison function should return: * -1 if item1 should go before item2 * 0 if item1 and item2 are equal * 1 if item1 should go after item2 * * @note All parameters after item2 are optional and do not need to be specified * and used. * @note Unlike the sorting.inc version, the array passed to the callback is not * in mid-sorted state. * * @param array Array handle * @param comparefunc Callback function used for comparison * @param data Extra data that is passed through to the callback * @param data_size Size of extra data * * @noreturn * @error If an invalid handle or an invalid callback is provided * an error will be thrown. */ native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); /** * A faster version of ArraySort, the sorting algorithm then uses the custom * comparison function to sort the data. * * @note The advantage of this function is that the data of the elements being * compared is directly passed to the function, instead of the item * indexes that are passed by ArraySort. This removes the need for calling * ArrayGet[Cell|String|Array] every time before being able to compare the * elements. * * @note For Arrays with a cellsize of 1 (used for storing integers and floats), * 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 * * @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 * * * @note The comparison function should return: * -1 if elem1 should go before elem2 * 0 if elem1 and elem2 are equal * 1 if elem1 should go after elem2 * * @note All parameters after item2 are optional and do not need to be specified * and used. * @note Unlike the sorting.inc version, the array passed to the callback is not * in mid-sorted state. * * @param array Array handle * @param comparefunc Callback function used for comparison * @param data Extra data that is passed through to the callback * @param data_size Size of extra data * * @noreturn * @error If an invalid handle or an invalid callback is provided * an error will be thrown. */ native ArraySortEx(Array:array, const comparefunc[], data[]="", data_size=0);