Arrays with N Dimensions

[Archive-Poster]

Introduction

While coding in Pawn we like to use arrays.

Code: Select all

new First[10];
new Second[20][10];
new Third[30][20][10];

This works out just fine and dandy until we get past the third dimension.

Pawn limits scripters to only three dimensions and makes it hard to accomplish using more. The method to be discussed makes it easier on scripters.

N Dimensional (NDim for short) Arrays use two cell arrays to accomplish an infinite amount of dimensions.

NDim arrays are used much like cell arrays. (Most of the documentation is the same)

Code: Select all

/**
 * These arrays are intended to be used for a form of global storage without 
 * limiting how many dimensions a person may need.
 * These are not designed to be used as a replacement for normal arrays, as
 * normal arrays are faster and should be used whenever possible.
 */

Creation

Code: Select all

/**
 * Creates an N Dimensional Array
 *
 * @param cellsize		The cellsize for the last dimension.
 * @param ...			Each param is the size for a dimension.
 *
 * @note				The cellsize should only be changed if working with strings or arrays.
 * @note2				NDim Arrays start zeroed.
 *
 * @return				The NDim handle.
 */
NDim:NDimCreate( const cellsize=1, ... )

Deletion

Code: Select all

/**
 * Destroys the NDim Array, and resets the handle to 0 to prevent accidental usage after it is destroyed.
 *
 * @param tracker		The array to destroy.
 */
NDimDestroy( &NDim:tracker )

Getting

Code: Select all

/**
 * Returns a single cell of data from an NDim Array.
 *
 * @param tracker		The array to retrieve the item from.
 * @param ...			Each param is the element for the corresponding dimension.
 *
 * @return				The value of the cell.
 */
any:NDimGetCell( const NDim:tracker, ... )

/**
 * Returns data within an NDim Array.  
 * Make sure the output buffer matches the size the array was created with!
 *
 * @param tracker		The array to retrieve the item from.
 * @param data			The output buffer to write.
 * @param ...			Each param is the element for the corresponding dimension.
 */
NDimGetArray( const NDim:tracker, data[], ... )

/**
 * Returns a string value from an NDim Array.
 *
 * @param tracker		The array to retrieve the item from.
 * @param output		The variable to store the value in.
 * @param size			Character size of the output buffer.
 * @param ...			Each param is the element for the corresponding dimension.
 */
NDimGetString( const NDim:tracker, output[], const size, ... )

Setting

Code: Select all

/**
 * Sets an NDim Array's single cell value.  Use this only on array that were created with a cellsize of 1!
 *
 * @param tracker		The array to set the item from within.
 * @param input			The value to set.
 * @param ...			Each param is the element for the corresponding dimension.
 */
NDimSetCell( const NDim:tracker, const any:input, ... )

/**
 * Sets an item's data with that of a local buffer.  
 * The buffer size must match what the cellsize that the array was created with!
 *
 * @param tracker		The array to set the item from within.
 * @param input			The input buffer to store.
 * @param ...			Each param is the element for the corresponding dimension.
 */
NDimSetArray( const NDim:tracker, const any:input[], ... )

/**
 * Sets a string value for an NDim Array.  
 * The stored string will be truncated if it is longer than the cellsize the array was created with!
 *
 * @param tracker		The array to set the item from within.
 * @param input			The string to set the item as.
 * @param ...			Each param is the element for the corresponding dimension.
 */
stock NDimSetString( const NDim:tracker, const input[], ... )

Filling
(Remember that NDim Arrays start zeroed)

Code: Select all

/**
 * Sets all of an NDim Array's single cell values.  Use this only on array that were created with a cellsize of 1!
 *
 * @param tracker		The array to set the item from within.
 * @param input			The value to set.
 */
NDimFillCell( const NDim:tracker, const any:input )

/**
 * Sets all items' data with that of a local buffer.  
 * The buffer size must match what the cellsize that the array was created with!
 *
 * @param tracker		The array to set the item from within.
 * @param input			The input buffer to store.
 */
NDimFillArray( const NDim:tracker, const any:input[] )

/**
 * Sets all string values for an NDim Array.  
 * The stored string will be truncated if it is longer than the cellsize the array was created with!
 *
 * @param tracker		The array to set the item from within.
 * @param input			The string to set the item as.
 */
NDimFillString( const NDim:tracker, const input[] )

Invalid NDim Array
Obviously you cannot create an NDim Array with negative sizes. If you do for some reason you will be returned:

Code: Select all

Invalid_NDim

Example

Code: Select all

//1st Dimension ranges from 0-32
//2nd Dimension ranges from 0-5
//3rd Dimension ranges from 0-32
//4th Dimension ranges from 0-19
new NDim:my_ndim_array = NDimCreate(_, 33, 6, 33, 20);

//1st Dimension: 0 <= 23 <= 32
//2nd Dimension: 0 <= 3 <= 5
//3rd Dimension: 0 <= 22 <= 32
//4th Dimension: 0 <= 10 <= 19
NDimSetCell( my_ndim_array, 50.0, 23, 3, 22, 10);

//1st Dimension: 0 <= 23 <= 32
//2nd Dimension: 0 <= 3 <= 5
//3rd Dimension: 0 <= 22 <= 32
//4th Dimension: 0 <= 10 <= 19
new Float:my_saved_value = NDimGetCell( my_ndim_array, 23, 3, 22, 10);