A
          / \      _             Play Now                         Nemesis on 
          | |     | |  _______   _        _   _______    _______   _    _______
          | |\    | | |   ____| |  \    /  | |   ____|  /   ____| | |  /   ____|
 /-------/-------------------------------------------------------------------,
O= Home <=XX|  About  News  Pics  Adventurers  Wizards  Download  Connect     >
 \-------\-------------------------------------------------------------------'
          | |   \   | |  |____  | |      | | |  |____   ___ \  \  | |  ___ \  \
          | |     \_| |_______| |_|      |_| |_______| |_______/  |_| |_______/
          \ /
           V  

Documentation Area

Document Path: /doc/LPC/arrays

ARRAYS

There is support for arrays. The arrays can be declared by prefixing
the variable name with a "*". So the line 

int *arr;

declares arr as an array of integers. 
You probably already know that variable types in declarations are not 
interpreted by the compiler, but for documentation purposes correct types
are very helpful!

Arrays are stored by reference, so all assignments of whole arrays will
just copy the address. The array will be deallocated when no variable
points to it any longer.

The current number of elements in an array can be determined using the sizeof
function.

When a variable points to an array, items can be accessed with indexing:
'arr[3]' as an example. Indexing starts with 0, the maximum valid index of an
array is sizeof(arr)-1 (assuming the array is not empty). Using an index 
outside these boundaries leads to an "index out of bounds" error.

The name of the array being indexed can be any expression, even a function 
call: 'func()[2]'. 
It can also be another array, if this array has pointers to arrays:

arr = allocate(2);
arr[0] = allocate(3);
arr[1] = allocate(3);

Now 'arr[1][2]' is a valid value.

The 'sizeof()' function (yes, in true C this is not a function) will give the
number of elements in an array.

ARRAY CONSTRUCTOR

Arrays can be constructed with a list inside '({' and '})'. Example:
({ 1, "xx", 2 })
will be construct a new array with size 3, initialized with 1, "xx" and 2
respectively. 
Of course multi dimensional consttructors are also possible:
mixed *arr = ({ 1, ({ "a", "b", "c" )}, 3 });

The empty constructor can be used to make sure a variable is of type array:
mixed *arr = ({ });

Use the allocate function to initialize big arrays to 0,

ARRAY ARITHMETICS

Two arrays can be added, the elements of the two arrays are appended:

sum_array = ({ 11, 12, 13 }) + ({ 14, 15 });

leads to the same result as 

sum_array = ({ 11, 12, 13, 14, 15 });

You can extract a continous part of an array using the syntax 
array[start..end]. So, using sum_array from the above example, sum_array[2..3]
results in the array ({ 13, 14 }). Remember array indexes start with 0!

Note: While using the array[start..end] syntax no "index out of bound" is
reported, but only existing elements are returned.

MORE EXAMPLES

Add a single element to the end of an array: arr += ({ 99 });
Note, that forgetting the ({ and }) will result in an "Bad type to rhs +="
error.

Remove first element of an array: arr = arr[1..sizeof(arr)-1];

Remove n-th element: arr = arr[0..n-2]+arr[n..sizeof(arr)-1];

arr[1..sizeof(arr)] returns the same result as arr[1..sizeof(arr)-1],
since array boundaries are not verified. For the same reason the two examples
above work even for an empty array, each returning an empty array as result.


See also:
LPC/foreach
efun/sizeof
LPC/alists
efun/allocate