Flummi/amxmodx
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

cellarray: Touch up documentation to make the parser happy and make it consistent

Browse Source
This commit is contained in:
Valentin Grünbacher 2014-08-05 16:05:19 +02:00
parent d60c94cbb1
commit 566596f7b4
1 changed files with 272 additions and 213 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

459
plugins/include/cellarray.inc
View File

@ -5,23 +5,28 @@
#define _cellarray_included #define _cellarray_included
/** /**
* These arrays are intended to be used for a form of global storage without * Cellarray tag declaration
* requiring a #define that needs to be increased each time a person needs more *
* storage. * @note These dynamic arrays are intended to be used for a form of global
* These are not designed to be used as a replacement for normal arrays, as * storage without requiring a #define that needs to be increased each
* normal arrays are faster and should be used whenever possible. * 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 enum Array
{ {
Invalid_Array = 0 Invalid_Array = 0
}; };
/** /**
* Given a maximum string size (including the null terminator), * Returns the number of cells required to fit a string of the specified size
* returns the number of cells required to fit that string. * (including the null terminator).
* *
* @param size Number of bytes. * @param size Number of bytes.
*
* @return Minimum number of cells required to fit the byte count. * @return Minimum number of cells required to fit the byte count.
*/ */
stock ByteCountToCells(size) stock ByteCountToCells(size)
@ -36,12 +41,14 @@ stock ByteCountToCells(size)
/** /**
* Creates a handle to a dynamically sized array. * Creates a handle to a dynamically sized array.
* It is very important that the cellsize you provide matches up with the buffer sizes
* that you pass with subsequent Array{Get,Set,Push} calls.
* *
* @param cellsize How many cells each entry in the array is. * @note It is very important that the provided cellsize matches up with the
* @param reserved How many blank entries are created immediately when the array is created. * buffer sizes that you pass with subsequent Array[Get|Set|Push] calls.
* These entries are not valid to read from until called with ArraySet. *
* @param cellsize Size of each array entry in cells
* @param reserver Amount of blank entries that are inserted immediately
* upon creation of the array. These are not readable until
* initialized with an ArraySet* function.
* *
* @return Handle to the array. * @return Handle to the array.
*/ */
@ -49,349 +56,398 @@ native Array:ArrayCreate(cellsize = 1, reserved = 0);
/** /**
* Clones an array, returning a new handle with the same size and data. * Clones an array, returning a new handle with the same size and data.
* You must close it.
* *
* @param which Array handle to be cloned. * @param which Array handle
* *
* @return New handle to the cloned array object on success, 0 on failure. * @return Handle to the cloned array on success, 0 otherwise
* @error Invalid handle. * @error If an invalid handle is provided an error will be thrown
*/ */
native Array:ArrayClone(Array:which); native Array:ArrayClone(Array:which);
/** /**
* Clears all entries from the array. * Clears all entries from the array.
* *
* @param which The array to clear. * @param which Array handle
* *
* @noreturn * @noreturn
* @error Invalid handle. * @error Invalid handle
*/ */
native ArrayClear(Array:which); native ArrayClear(Array:which);
/** /**
* Returns the number of elements in the array. * Returns the number of elements in the array.
* *
* @param which The array to check. * @param which Array handle
* *
* @return How many elements are in the array. * @return Number of elements in the array
* @error Invalid handle. * @error If an invalid handle is provided an error will be thrown
*/ */
native ArraySize(Array:which); native ArraySize(Array:which);
/** /**
* Resizes an array. If the size is smaller than the current size, * Resizes an array.
* the array is truncated.
* *
* @param which Array handle. * @note If the size is smaller than the current array size the array is
* @param newsize New size. * truncated and data lost.
*
* @param which Array handle
* @param newsize New size
* *
* @noreturn * @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 bool:ArrayResize(Array:which, newsize); native bool:ArrayResize(Array:which, newsize);
/** /**
* Returns data within an array. * Retrieves an array of data from a cellarray.
* Make sure the output buffer matches the size the array was created with!
* *
* @param which The array to retrieve the item from. * @note If the size parameter is specified as -1 the output buffer has to match
* @param item The item to retrieve (zero-based). * the size the array was created with.
* @param output The output buffer to write. *
* @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 * @param size If not set, assumes the buffer size is equal to the
* cellsize. Otherwise, the size passed is used. * cellsize. Otherwise, the specified size is used.
* *
* @return Number of cells copied. * @return Number of cells copied
* @error Invalid handle or invalid index. * @error If an invalid handle or index is provided an error will
* be thrown.
*/ */
native ArrayGetArray(Array:which, item, any:output[], size = -1); native ArrayGetArray(Array:which, item, any:output[], size = -1);
/** /**
* Returns a single cell of data from an array. * Returns a single cell of data from an array
* *
* @param which The array to retrieve the item from. * @param which Array handle
* @param item The item to retrieve (zero-based). * @param item Item index in the array
* @param block Optionally specify which block to read from * @param block If the array has a cellsize >1 this optionally specifies
* (useful if the blocksize > 0). * which block to read from
* @param asChar Optionally read as a byte instead of a cell. * @param asChar If true reads the value as a byte instead of a cell
* *
* @return Value read. * @return Integer value
* @error Invalid handle, invalid index, or invalid block. * @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); native any:ArrayGetCell(Array:which, item, block = 0, bool:asChar = false);
/** /**
* Returns a string value from an array. * Returieves string data from an array.
* *
* @param which The array to retrieve the item from. * @param which Array handle
* @param item The item to retrieve (zero-based). * @param item Item index in the array
* @param output The variable to store the value in. * @param output Buffer to copy value to
* @param size Character size of the output buffer. * @param size Maximum size of the buffer
* *
* @return Number of characters copied. * @return Number of characters copied
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayGetString(Array:which, item, output[], size); native ArrayGetString(Array:which, item, output[], size);
/** /**
* Sets an item's data with that of a local buffer. * Fills an item's data with the contents of an array.
* The buffer size must match what the cellsize that the array was created with!
* The item must already exist, use ArrayPushArray to create a new item within the array.
* *
* @param which The array to set the item from within. * @note If the size parameter is specified as -1 the input buffer has to match
* @param item The item to set (zero-based). * the size the array was created with.
* @param input The input buffer to store. * @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 * @param size If not set, assumes the buffer size is equal to the
* blocksize. Otherwise, the size passed is used. * cellsize. Otherwise, the specified size is used.
* *
* @return Number of cells copied. * @return Number of cells copied
* @error Invalid handle or invalid index. * @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); native ArraySetArray(Array:which, item, const any:input[], size =-1);
/** /**
* Sets an array's single cell value. Use this only on array that were created with a cellsize of 1! * Sets an item's data to a single cell value.
* The item must already exist, use ArrayPushCell to create a new item within the array.
* *
* @param which The array to set the item from within. * @note The item index must already be valid. Use ArrayPushArray to create
* @param item The item to set (zero-based). * a new array item in the cellarray.
* @param input The value to set. *
* @param block Optionally specify which block to write to * @param which Array handle
* (useful if the blocksize > 0). * @param item Item index in the array
* @param asChar Optionally set as a byte instead of a cell. * @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 * @noreturn
* @error Invalid handle, invalid index, or invalid block. * @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); native ArraySetCell(Array:which, item, any:input, block = 0, bool:asChar = false);
/** /**
* Sets a string value from an array. * Sets an item's data to a string value.
* The stored string will be truncated if it is longer than the cellsize the array was created with!
* The item must already exist, use ArrayPushString to create a new item within the array.
* *
* @param which The array to set the item from within. * @note The input will be truncated if it is longer than the cellsize the array
* @param item The item to set (zero-based). * was created with.
* @param input The string to set the item as. * @note The item index must already be valid. Use ArrayPushString to create
* a new array item in the cellarray.
* *
* @return Number of characters copied. * @param which Array handle
* @error Invalid handle or invalid index. * @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[]); native ArraySetString(Array:which, item, const input[]);
/** /**
* Creates a new item at the end of the array and sets its data with that of a local buffer. * Creates a new item at the end of the cellarray and copies the provided array
* The buffer size must match what the cellsize that the array was created with! * into it.
* *
* @param which The array to add the item to. * @note The input will be truncated if it is bigger than the cellsize the array
* @param input The input buffer to store. * was created with.
* @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.
* *
* @return Index of the new entry. * @param which Array handle
* @error Invalid handle or out of memory. * @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); native ArrayPushArray(Array:which, const any:input[], size = -1);
/** /**
* Creates a new item and sets the array's single cell value. * Creates a new item ath the end of the array and sets the item's single cell
* Use this only on array that were created with a cellsize of 1! * value.
* *
* @param which The array to add the item to. * @param which Array handle
* @param input The value to set. * @param input Value to set
* *
* @return Index of the new entry. * @return Index of the new entry
* @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 ArrayPushCell(Array:which, any:input); native ArrayPushCell(Array:which, any:input);
/** /**
* Creates a new element in the array and sets its value to the input buffer. * Creates a new item at the end of the array and copies the provided string
* The stored string will be truncated if it is longer than the cellsize the array was created with! * into it.
* *
* @param which The array to add the item to. * @note The input will be truncated if it is longer than the cellsize the array
* @param input The string to set the item as. * was created with.
* *
* @return Index of the new entry. * @param which Array handle
* @error Invalid handle or out of memory. * @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[]); native ArrayPushString(Array:which, const input[]);
/** /**
* Inserts an item after the selected item. All items beyond it get shifted up 1 space. * Creates a new item behind the specified item and copies the provided array
* The buffer size must match what the cellsize that the array was created with! * into it. All items beyond it get shifted up by one.
* *
* @param which The array to add the item to. * @param which Array handle
* @param item The item to insert after. * @param item Item index in the array
* @param input The input buffer to store. * @param input Array to copy to the cellarray
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayInsertArrayAfter(Array:which, item, const any:input[]); native ArrayInsertArrayAfter(Array:which, item, const any:input[]);
/** /**
* Inserts an item after the selected item. All items beyond it get shifted up 1 space. * Creates a new item behind the specified item and sets the item's single cell
* Use this only on an array that was created with a cellsize of 1! * value. All items beyond it get shifted up by one.
* *
* @param which The array to add the item to. * @param which Array handle
* @param item The item to insert after. * @param item Item index in the array
* @param input The value to set. * @param input The value to set.
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayInsertCellAfter(Array:which, item, any:input); native ArrayInsertCellAfter(Array:which, item, any:input);
/** /**
* Inserts an item after the selected item. All items beyond it get shifted up 1 space. * Creates a new item behind the specified item and copies the provided string
* The stored string will be truncated if it is longer than the cellsize the array was created with! * into it. All items beyond it get shifted up by one.
* *
* @param which The array to add the item to. * @note The input will be truncated if it is longer than the cellsize the array
* @param item The item to insert after. * was created with.
* @param input The value to set. *
* @param which Array handle
* @param item Item index in the array
* @param input String to copy to the array
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayInsertStringAfter(Array:which, item, const input[]); native ArrayInsertStringAfter(Array:which, item, const input[]);
/** /**
* Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. * Creates a new item in front of the specified item and copies the provided
* The buffer size must match what the cellsize that the array was created with! * array into it. All items beyond it get shifted up by one.
* *
* @param which The array to add the item to. * @param which Array handle
* @param item The item to insert before. * @param item Item index in the array
* @param input The input buffer to store. * @param input Array to copy to the cellarray
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayInsertArrayBefore(Array:which, item, const any:input[]); native ArrayInsertArrayBefore(Array:which, item, const any:input[]);
/** /**
* Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. * Creates a new item in front of the specified item and sets the item's single
* Use this only on an array that was created with a cellsize of 1! * cell value. All items beyond it get shifted up by one.
* *
* @param which The array to add the item to. * @param which Array handle
* @param item The item to insert after. * @param item Item index in the array
* @param input The value to set. * @param input Value to set
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayInsertCellBefore(Array:which, item, const any:input); native ArrayInsertCellBefore(Array:which, item, const any:input);
/** /**
* Inserts an item before the selected item. All items beyond it, and the selected item get shifted up 1 space. * Creates a new item in front of the specified item and copies the provided
* The stored string will be truncated if it is longer than the cellsize the array was created with! * string into it. All items beyond it get shifted up by one.
* *
* @param which The array to add the item to. * @note The input will be truncated if it is longer than the cellsize the array
* @param item The item to insert before. * was created with.
* @param input The value to set. *
* @param which Array handle
* @param item Item index in the array
* @param input String to copy to the array
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayInsertStringBefore(Array:which, item, const input[]); native ArrayInsertStringBefore(Array:which, item, const input[]);
/** /**
* Swaps the position of two items. * Swaps the position of two items.
* *
* @param which The array that contains the items. * @param which Array handle
* @param item1 The first item to swap. * @param item1,item2 Item pair to swap
* @param item2 The second item to swap.
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArraySwap(Array:which, item1, item2); native ArraySwap(Array:which, item1, item2);
/** /**
* Deletes an item from the array. All items beyond it get shifted down 1 space. * Deletes an item from the array. All items beyond it get shifted down by one.
* *
* @param which The array that contains the item to delete. * @param which The array that contains the item to delete.
* @param item The item to delete. * @param item The item to delete.
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native ArrayDeleteItem(Array:which, item); native ArrayDeleteItem(Array:which, item);
/** /**
* Returns the index for the first occurance of the provided string. If the string * Searches through the array and returns the index of the first occurance of
* cannot be located, -1 will be returned. * the specified string.
* *
* @param which Array handle. * @param which Array handle
* @param item String to search for. * @param item String to search for
* *
* @return Array index, or -1 on failure. * @return Array index on success, -1 if the string can't be found
* @error Invalid handle. * @error Invalid handle.
*/ */
native ArrayFindString(Array:which, const item[]); native ArrayFindString(Array:which, const item[]);
/** /**
* Returns the index for the first occurance of the provided value. If the value * Searches through the array and returns the index of the first occurance of
* cannot be located, -1 will be returned. * the specified value.
* *
* @param which Array handle. * @param which Array handle.
* @param item Value to search for. * @param item Value to search for
* *
* @return Array index, or -1 on failure. * @return Array index on success, -1 if the value can't be found
* @error Invalid handle. * @error Invalid handle.
*/ */
native ArrayFindValue(Array:which, any:item); native ArrayFindValue(Array:which, any:item);
/** /**
* Creates a handle that is passable to a format compliant routine for printing as a string (with the %a format option). * Creates a special handle that can be passed to a string format routine for
* It is suggested to pass the function directly as a parameter to the format routine. * printing as a string (with the %a format option).
* The array contents must be a null-terminated string!
* *
* An example usage: client_print(id, print_chat, "%a", ArrayGetStringHandle(MessageArray, i)); * @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 The array the string is stored in. * @param which Array handle
* @param item Which item to print the string value of. * @param item Item to retrieve handle of
* *
* @return Handle to the item directly. Do not use or save stale handles. * @return Handle to the item
* @error Invalid handle or invalid index. * @error If an invalid handle or an invalid index is provided an
* error will be thrown
*/ */
native DoNotUse:ArrayGetStringHandle(Array:which, item); native DoNotUse:ArrayGetStringHandle(Array:which, item);
/** /**
* Destroys the array, and resets the handle to 0 to prevent accidental usage after it is destroyed. * 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 The array to destroy. * @param which The array to destroy.
* *
* @noreturn * @return 1 if the array was destroyed, 0 if nothing had to be
* @error Invalid handle. * destroyed (invalid handle)
*/ */
native ArrayDestroy(&Array:which); native ArrayDestroy(&Array:which);
/** /**
* Similar to sorting.inc's CustomSort. * Similar to sorting.inc's CustomSort, the sorting algorithm then uses your
* The sorting algorithm then uses your comparison function to sort the data. * custom comparison function to sort the data.
* The function is called in the following manner: *
* @note The function is called in the following manner:
* *
* public MySortFunc(Array:array, item1, item2, const data[], data_size) * public MySortFunc(Array:array, item1, item2, const data[], data_size)
* *
* array - Array handle in its current un-sorted state. * array - Array handle in its current un-sorted state
* item1, item2 - Current item pair being compared * item1, item2 - Current item pair being compared
* data[] - Extra data array you passed to the sort func. * data[] - Extra data array passed to the sort func
* data_size - Size of extra data you passed to the sort func. * data_size - Size of extra data
* *
* Your function should return: * @note The comparison function should return:
* -1 if item1 should go before item2 * -1 if item1 should go before item2
* 0 if item1 and item2 are equal * 0 if item1 and item2 are equal
* 1 if item1 should go after item2 * 1 if item1 should go after item2
* *
* Note that the parameters after item2 are all optional and you do not need to specify them. * @note All parameters after item2 are optional and you do not need to specify
* Note that unlike the sorting.inc versions, the array passed to the callback is not in mid-sorted state. * and use them.
* @note Unlike the sorting.inc version, the array passed to the callback is not
* in mid-sorted state.
* *
* @param array Array handle. * @param array Array handle
* @param comparefunc A callback function used for comparison. * @param comparefunc Callback function used for comparison
* @param data Extra data array you passed to the sort func. * @param data Extra data that is passed through to the callback
* @param data_size Size of extra data you passed to the sort func. * @param data_size Size of extra data
* *
* @noreturn * @noreturn
* @error Invalid handle or invalid callback. * @error Invalid handle or invalid callback.
@ -399,47 +455,50 @@ native ArrayDestroy(&Array:which);
native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0); native ArraySort(Array:array, const comparefunc[], data[]="", data_size=0);
/** /**
* A faster version of ArraySort. * A faster version of ArraySort, the sorting algorithm then uses your custom
* The sorting algorithm then uses your comparison function to sort the data. * comparison function to sort the data.
* *
* The advantage of this native is that the Array elements being compared are * @note The advantage of this function is that the data of the elements being
* directly passed into your function, instead of the item indexes that are passed by ArraySort. * compared is directly passed to your function, instead of the item
* This removes the need for calling ArrayGet[Cell|String|Array] every time before being * indexes that are passed by ArraySort. This removes the need for calling
* able to compare the elements. * ArrayGet[Cell|String|Array] every time before being able to compare the
* elements.
* *
* For Arrays with a cellsize of 1 (used for storing integers and floats), * @note For Arrays with a cellsize of 1 (used for storing integers and floats),
* the function is called in the following manner: * the function is called in the following manner:
* *
* public MySortFunc(Array:array, elem1, elem2, const data[], data_size) * public MySortFunc(Array:array, elem1, elem2, const data[], data_size)
* *
* array - Array handle in its current un-sorted state. * array - Array handle in its current un-sorted state
* elem1, elem2 - Current element pair being compared * elem1, elem2 - Current element pair being compared
* data[] - Extra data array you passed to the sort func. * data[] - Extra data array passed to the sort func
* data_size - Size of extra data you passed to the sort func. * data_size - Size of extra data
* *
* For Arrays with a cellsize larger than 1 (used for storing arrays and strings), * @note For Arrays with a cellsize larger than 1 (used for storing arrays and
* the function is called in the following manner: * strings), the function is called in the following manner:
* *
* public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size) * public MySortFunc(Array:array, elem1[], elem2[], const data[], data_size)
* *
* array - Array handle in its current un-sorted state. * array - Array handle in its current un-sorted state.
* elem1[], elem2[] - Current element pair being compared * elem1[], elem2[] - Current element pair being compared
* data[] - Extra data array you passed to the sort func. * data[] - Extra data array passed to the sort func
* data_size - Size of extra data you passed to the sort func. * data_size - Size of extra data
* *
* *
* In both cases your function should return: * @note The comparison function should return:
* -1 if elem1 should go before elem2 * -1 if elem1 should go before elem2
* 0 if elem1 and elem2 are equal * 0 if elem1 and elem2 are equal
* 1 if elem1 should go after elem2 * 1 if elem1 should go after elem2
* *
* Note that the parameters after elem2 are all optional and you do not need to specify them. * @note All parameters after item2 are optional and you do not need to specify
* Note that unlike the sorting.inc versions, the array passed to the callback is not in mid-sorted state. * and use them.
* @note Unlike the sorting.inc version, the array passed to the callback is not
* in mid-sorted state.
* *
* @param array Array handle. * @param array Array handle
* @param comparefunc A callback function used for comparison. * @param comparefunc Callback function used for comparison
* @param data Extra data array you passed to the sort func. * @param data Extra data that is passed through to the callback
* @param data_size Size of extra data you passed to the sort func. * @param data_size Size of extra data
* *
* @noreturn * @noreturn
* @error Invalid handle, invalid callback or out of memory. * @error Invalid handle, invalid callback or out of memory.