amxmodx/plugins/include/cellarray.inc

526 lines
18 KiB
SourcePawn
Raw Normal View History

2016-01-17 00:15:52 +00:00
// 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 ath 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);