namespace Array

namespace Array

Provides a set of functions to manipulate arrays.

namespace contents

function

combine(array,array) - Combines two arrays into a single array

function

del(array,void) - Deletes an item from an array

function

each(array) - This function takes a closure and applies it to each element within the array

function

eachWithIndex(array) - This function takes a closure and applies it to each element within the array providing the index as the second parameter.

function

find(array,string) - Locates an item in an array by value and returns its index number

function

getIndex(array,string) - Finds the index number of an array item from its key string

function

getName(array,number) - Finds the key string of an array item

function

intersect(array,array) - Calculates the intersection of two arrays

function

join(array,string) - Converts an array to a string with a specified string between the items

function

keyExists(array,string) - Discovers whether there is an item with a particular key in an array

function

keys(array) - Returns an array of strings representing the keys in the array

function

last(array) - Fetch the last value within the array.

function

map(array) - This function takes a closure and applies it to each named element within the array

function

pop(array) - Pops a variable from the end of an array

function

print(array) - Dumps an array to stdout

function

push(array,void) - Pushes a variable onto the end of an array

function

resize(array,number) - Resize the array that is being used.

function

shift(array) - Shifts a variable from the start of an array

function

size(array) - Returns the number of items that are in an array

function

sort(array,number) - Sorts an array

function

sort(array) - Sorts an array in an ascending direction

function

subtract(array,array) - Subtracts array b from array a

function

union(array,array) - Calculates the union of two arrays

function

unshift(array,void) - Shifts a variable onto the start of an array

function

valueExists(array,void) - Discovers whether there is an item with a particular value in an array

Functions

function combine

Click to go up to the list

Combines two arrays into a single array

function combine( array keys, array values )

Combines the specified arrays into a single array, where the strings in the keys array are used as keys to the values from the values array. In the case of duplicate keys, the last one in the array is used. If the arrays are not the same size, the combination stops when the end of the shortest array is reached. Any keys which are not strings are ignored.

Parameter #1: array keys - The key strings

Parameter #2: array values - The variables associated with the keys

An array containing the specified keys and values

array a = [ "Four", "Five", "Six" ];
array b = [ 4, 5, 6 ];
array c = Array.combine(a, b); » c = [ 'Four' => 4, 'Five' => 5, 'Six' => 6 ]

function del

Click to go up to the list

Deletes an item from an array

function del( array a, void var )

This function deletes an item from the specified array, if it exists. The var parameter can be either the index number or the key string of the item to delete.

Parameter #1: array a - The array to delete an item from

Parameter #2: void var - The index or key of the item to delete

array a = [ 1, 2, "Three" => 3 ];
Array.del(a, 0); » a = [ 2, "Three" => 3 ]
Array.del(a, "Three"); » a = [ 2 ]

function each

Click to go up to the list

This function takes a closure and applies it to each element within the array

function each( array a )

The function will go through each element within the array and call the supplied closure. If you wish to terminate the iteration you need to return false, otherwise the function will continue to run.

Parameter #1: array a - The array

true if there is no recipient or the iteration was successful, false otherwise

Array.each( someArray ) using ( value ) {
Console.println( "Value: " + value );
}

function eachWithIndex

Click to go up to the list

This function takes a closure and applies it to each element within the array providing the index as the second parameter.

function eachWithIndex( array a )

The function will go through each element within the array and call the supplied closure. If you wish to terminate the iteration you need to return false, otherwise the function will continue to run.

Parameter #1: array a - The array

true if there is no recipient or the iteration was successful, false otherwise

Array.eachWithIndex( someArray ) using ( value, index ) {
Console.println( "Value: " + value + " at index $index" );
}

function find

Click to go up to the list

Locates an item in an array by value and returns its index number

function find(array a, string var)

Parameter #1: array a - The array to search through

Parameter #2: string var - The value of the item to search for

The index of the array item, or -1 if no match was found.

array a = [ "Four", "Five", "Six" ];
number location = Array.find(a, "Four");

function getIndex

Click to go up to the list

Finds the index number of an array item from its key string

function getIndex( array a, string var )

Parameter #1: array a - The array

Parameter #2: string var - The key string

The index of the array item, or -1 on failure

array a = [ 1, 2, "Three" => 3 ];
number three = Array.index(a, "Three");

function getName

Click to go up to the list

Finds the key string of an array item

function getname( array a, number index )

Parameter #1: array a - The array

Parameter #2: number index - The index of the array item

The key string of the item, or an empty string on failure

array a = [ 1, 2, "Three" => 3 ];
string name = Array.getName(a, 2);

function intersect

Click to go up to the list

Calculates the intersection of two arrays

function intersect( array a, array b )

This function calculates the intersection of the two input arrays. The output array contains only keys which are in both of the input arrays. The values associated with the items in the output array are taken from array a. If there aren't any intersecting keys, the returned array will be empty.

Parameter #1: array a - The first array, which the values are taken from

Parameter #2: array b - The second array

An array containing only keys which are in both input arrays

array a = [ "Four" => 4, "Five" => 5, "Six" => 6 ];
array b = [ 4, "Five" => 5, 6 ];
array c = Array.intersect(a, b); » c = [ 'Five' => 5 ]

function join

Click to go up to the list

Converts an array to a string with a specified string between the items

function join( array a, string value )

Parameter #1: array a - The array to convert into a string

Parameter #2: string value - A delimiting string to place between each pair of array items

A string representation of the array

array a = [ 1, 2, 3 ];
string data = Array.join(a, ":"); » data = "1:2:3"

function keyExists

Click to go up to the list

Discovers whether there is an item with a particular key in an array

function keyExists( array a, string key )

Parameter #1: array a - The array

Parameter #2: string key - The key string to look for

true if it exists, false if it does not

array a = [ 1, 2, "Three" => 3 ];
if( Array.keyExists(a, "Three") )
Array.del(a, "Three");

function keys

Click to go up to the list

Returns an array of strings representing the keys in the array

function keys( array a )

This function returns an array of the key strings which are present in the specified array. Note that the returned array is in hash order (which is basically random), not in the same order as the array that was passed in.

Parameter #1: array a - The array

An array containing the key strings

array a = [ "Name" => "Chris", "Age" => "Too Old" ];
array keys = Array.keys(a);

function last

Click to go up to the list

Fetch the last value within the array.

function last( array a )

Parameter #1: array a - The array to fetch the value from

The last value within the array

array a = [ 5, 6, 4 ];
void v = Array.last(a); » v = 6

function map

Click to go up to the list

This function takes a closure and applies it to each named element within the array

function map( array a )

The function will go through each element within the array that is linked to a name, and call the supplied closure with the name and the value. If you wish to terminate the iteration you need to return false, otherwise the function will continue to run.

Parameter #1: array a - The array

true if there is no recipient or the iteration was successful, false otherwise

Array.map( someArray ) using ( key, value ) {
Console.println( "Key '$key' has value '$value'" );
}

function pop

Click to go up to the list

Pops a variable from the end of an array

function pop( array a )

Parameter #1: array a - The array to pop a variable from

The variable which was popped from the end of the array

array a = [ 1, 2, 3, 4 ];
number size = Array.pop(a); » a = [ 1, 2, 3 ]

function print

Click to go up to the list

Dumps an array to stdout

function print( array vars )

This is a debugging function used to dump an array directly to stdout, bypassing the Console system, and as such should not normally be used.

Parameter #1: array vars - The array to dump

function push

Click to go up to the list

Pushes a variable onto the end of an array

function push( array a, void var )

Parameter #1: array a - The array to push the variable onto

Parameter #2: void var - The variable to push onto the end of the array

array a = [ 1, 2, 3 ];
Array.push(a,4); » a = [ 1, 2, 3, 4 ]

function resize

Click to go up to the list

Resize the array that is being used.

function resize( array a )

Sometimes you need more space within an array and this can give it to you. The best time to use this function is to make an array large very quickly.

Parameter #1: array a - The array to resize

Parameter #2: number size - The new size

array a = [ 5, 6, 4 ];
Array.resize(a,1000000); » a = very big

function shift

Click to go up to the list

Shifts a variable from the start of an array

function shift( array a )

Parameter #1: array a - The array to shift a variable from

The variable which was shifted from the start of the array

array a = [ 1, 2, 3 ];
number size = Array.shift(a); » a = [ 2, 3 ]

function size

Click to go up to the list

Returns the number of items that are in an array

function size( array a )

Parameter #1: array a - The array

The number of items that are in the array

array a = [ 1, 2, 3 ];
number size = Array.size(a);

function sort

Click to go up to the list

function sort( array a, number direction )

This function sorts an array into the specified order. It uses the standard C qsort() function, so it is not guaranteed to be a "stable" sort (ie. items with equal value may get arbitrarily mixed up). All of the items in the array must be of the same type. Currently only numbers, strings, arrays, and objects can be sorted. Arrays are sorted by their size (smallest to largest). Objects to be sorted must all be of the same class, and the class must have a static member function called compare() which accepts two objects as parameters and returns a negative number if the first object is "smaller" than the second one, a positive number if the first object is "larger" than the second one, and 0 if they are equal. On error, an empty array is returned. If the direction parameter is omitted, an ascending sort is performed.

It is possible to avoid the restriction on types by passing sort a closure. The closure must take two parameters and return -1 if the first is less than the second, 0 if they are the same, and 1 otherwise.

Parameter #1: array a - The array to sort

Parameter #2: number direction - Array.SORT_ASCENDING or Array.SORT_DESCENDING

The sorted array

array a = [ 5, 6, 4 ];
array b = Array.sort(a, Array.SORT_ASCENDING); » b = [ 4, 5, 6 ]
array c = Array.sort(a, Array.SORT_DESCENDING); » c = [ 6, 5, 4 ]

You can also sort using a closure:

array a = [ 5, 6, 4 ];
array b = Array.sort(a, Array.SORT_ASCENDING) using ( a, b ) {
    if( a < b ) return -1;
    if( a == b ) return 0;
    if( a > b ) return 1;
};

function sort

Click to go up to the list

Sorts an array in an ascending direction

function sort( array a )

This function sorts an array into the specified order. It uses the standard C qsort() function, so it is not guaranteed to be a "stable" sort (ie. items with equal value may get arbitrarily mixed up). All of the items in the array must be of the same type. Currently only numbers, strings, arrays, and objects can be sorted. Arrays are sorted by their size (smallest to largest). Objects to be sorted must all be of the same class, and the class must have a static member function called compare() which accepts two objects as parameters and returns a negative number if the first object is "smaller" than the second one, a positive number if the first object is "larger" than the second one, and 0 if they are equal. On error, an empty array is returned. If the direction parameter is omitted, an ascending sort is performed.

It is possible to avoid the restriction on types by passing sort a closure. The closure must take two parameters and return -1 if the first is less than the second, 0 if they are the same, and 1 otherwise.

Parameter #1: array a - The array to sort

The sorted array

array a = [ 5, 6, 4 ];
array b = Array.sort(a); » b = [ 4, 5, 6 ]

You can also sort using a closure:

array a = [ 5, 6, 4 ];
array b = Array.sort(a) using ( a, b ) {
    if( a < b ) return -1;
    if( a == b ) return 0;
    if( a > b ) return 1;
};

function subtract

Click to go up to the list

Subtracts array b from array a

function subtract( array a, array b )

This function removes any items from array a which have the same key as an item in array b. Items which don't have keys are dropped.

Parameter #1: array a - The minuend

Parameter #2: array b - The subtrahend

An array containing all the keys which are in a but not b

array a = [ "Four" => 4, "Five" => 5, "Six" => 6 ];
array b = [ 4, "Five" => 5, 6 ];
array c = Array.subtract(a, b); » c = [ 'Four' => 4, 'Six' => 6 ]

function union

Click to go up to the list

Calculates the union of two arrays

function union( array a, array b )

This function unifies the two input arrays, producing a single output array containing one item for each of the keys that is in the input arrays. Where a key is present in both input arrays, the value is taken from array a. Items which don't have keys are dropped.

Parameter #1: array a - The first array, which the values are taken from

Parameter #2: array b - The second array

An array containing one of each key that is in the two sets

array a = [ "Four" => 4, "Five" => 5, "Six" => 6 ];
array b = [ 4, "Seven" => 7, 6 ];
array c = Array.union(a, b); » c = [ 'Seven' => 7, 'Four' => 4, 'Five' => 5, 'Six' => 6 ]

function unshift

Click to go up to the list

Shifts a variable onto the start of an array

function unshift( array a, void var )

Parameter #1: array a - The array to shift a variable onto

Parameter #2: void var - The variable to shift onto the start of the array

array a = [ 1, 2, 3 ];
Array.unshift(a, 4); » a = [ 4, 1, 2, 3 ]

function valueExists

Click to go up to the list

Discovers whether there is an item with a particular value in an array

function valueExists( array a, void value )

Parameter #1: array a - The array

Parameter #2: void value - The value to look for

True if it exists, false if it does not

array a = [ 1, 2, "Three" => 3 ];
if( Array.valueExists(a, 4) )
Array.push(a, 4);

Automatically generated at 12:07PM, Wednesday 25 May 2005 by feritedoc.