ArrayObject

consoledoc.h

Data structure for storing indexed sequences of key/value pairs.

More...

Public Attributes

bool

Makes the keys and values case-sensitive.

caseString

Helper field which allows you to add new key['keyname'] = value pairs.

Public Functions

void
add(string key, string value)

Adds a new element to the end of an array (same as push_back()).

bool

Appends the target array to the array object.

int

Get the number of elements in the array.

int
countKey(string key)

Get the number of times a particular key is found in the array.

int
countValue(string value)

Get the number of times a particular value is found in the array.

bool
crop(ArrayObject target)

Removes elements with matching keys from array.

bool

Alters array into an exact duplicate of the target array.

void
echo()

Echos the array contents to the console.

void

Emptys all elements from an array.

void
erase(int index)

Removes an element at a specific position from the array.

int

Gets the current pointer index.

int
getIndexFromKey(string key)

Search the array from the current position for the key.

int
getIndexFromValue(string value)

Search the array from the current position for the element.

string
getKey(int index)

Get the key of the array element at the submitted index.

string
getValue(int index)

Get the value of the array element at the submitted index.

void
insert(string key, string value, int index)

Adds a new element to a specified position in the array.

int

Moves array pointer to start of array.

int

Moves array pointer to end of array.

int

Moves array pointer to next position.

int

Moves array pointer to prev position.

void

Removes the last element from the array.

void

Removes the first element from the array.

void
push_back(string key, string value)

Adds a new element to the end of an array.

void
push_front(string key, string value)

Adds a new element to the front of an array.

void
setCurrent(int index)

Sets the current pointer index.

void
setKey(string key, int index)

Set the key at the given index.

void
setValue(string value, int index)

Set the value at the given index.

void
sort(bool ascending)

Alpha sorts the array by value.

void

Alpha sorts the array by value in ascending order.

void

Alpha sorts the array by value in descending order.

void
sortf(string functionName)

Sorts the array by value in ascending order using the given callback function.

void
sortfd(string functionName)

Sorts the array by value in descending order using the given callback function.

void
sortfk(string functionName)

Sorts the array by key in ascending order using the given callback function.

void
sortfkd(string functionName)

Sorts the array by key in descending order using the given callback function.

void
sortk(bool ascending)

Alpha sorts the array by key.

void

Alpha sorts the array by key in ascending order.

void

Alpha sorts the array by key in descending order.

void
sortn(bool ascending)

Numerically sorts the array by value.

void

Numerically sorts the array by value in ascending order.

void

Numerically sorts the array by value in descending order.

void
sortnk(bool ascending)

Numerically sorts the array by key.

void

Numerical sorts the array by key in ascending order.

void

Numerical sorts the array by key in descending order.

void

Removes any elements that have duplicated keys (leaving the first instance)

void

Removes any elements that have duplicated values (leaving the first instance)

Detailed Description

Data structure for storing indexed sequences of key/value pairs.

This is a powerful array class providing PHP style arrays in TorqueScript.

The following features are supported:

  • array pointers: this allows you to move forwards or backwards through the array as if it was a list, including jumping to the start or end.

  • sorting: the array can be sorted in either alphabetic or numeric mode, on the key or the value, and in ascending or descending order

  • add/remove elements: elements can be pushed/popped from the start or end of the array, or can be inserted/erased from anywhere in the middle

  • removal of duplicates: remove duplicate keys or duplicate values

  • searching: search the array and return the index of a particular key or value

  • counting: count the number of instaces of a particular value or key in the array, as well as the total number of elements

  • advanced features: array append, array crop and array duplicate

Array element keys and values can be strings or numbers

Public Attributes

bool caseSensitive 

Makes the keys and values case-sensitive.

By default, comparison of key and value strings will be case-insensitive.

caseString key 

Helper field which allows you to add new key['keyname'] = value pairs.

Public Functions

add(string key, string value)

Adds a new element to the end of an array (same as push_back()).

Parameters:

key

Key for the new element

value

Value for the new element

append(ArrayObject target)

Appends the target array to the array object.

Parameters:

target

ArrayObject to append to the end of this array

count()

Get the number of elements in the array.

countKey(string key)

Get the number of times a particular key is found in the array.

Parameters:

key

Key value to count

countValue(string value)

Get the number of times a particular value is found in the array.

Parameters:

value

Array element value to count

crop(ArrayObject target)

Removes elements with matching keys from array.

Parameters:

target

ArrayObject containing keys to remove from this array

duplicate(ArrayObject target)

Alters array into an exact duplicate of the target array.

Parameters:

target

ArrayObject to duplicate

echo()

Echos the array contents to the console.

empty()

Emptys all elements from an array.

erase(int index)

Removes an element at a specific position from the array.

Parameters:

index

0-based index of the element to remove

getCurrent()

Gets the current pointer index.

getIndexFromKey(string key)

Search the array from the current position for the key.

Parameters:

value

Array key to search for

return:

Index of the first element found, or -1 if none

getIndexFromValue(string value)

Search the array from the current position for the element.

Parameters:

value

Array value to search for

return:

Index of the first element found, or -1 if none

getKey(int index)

Get the key of the array element at the submitted index.

Parameters:

index

0-based index of the array element to get

return:

The key associated with the array element at the specified index, or "" if the index is out of range

getValue(int index)

Get the value of the array element at the submitted index.

Parameters:

index

0-based index of the array element to get

return:

The value of the array element at the specified index, or "" if the index is out of range

insert(string key, string value, int index)

Adds a new element to a specified position in the array.

  • index = 0 will insert an element at the start of the array (same as push_front())

  • index = array.count() will insert an element at the end of the array (same as push_back())

Parameters:

key

Key for the new element

value

Value for the new element

index

0-based index at which to insert the new element

moveFirst()

Moves array pointer to start of array.

return:

Returns the new array pointer

moveLast()

Moves array pointer to end of array.

return:

Returns the new array pointer

moveNext()

Moves array pointer to next position.

return:

Returns the new array pointer, or -1 if already at the end

movePrev()

Moves array pointer to prev position.

return:

Returns the new array pointer, or -1 if already at the start

pop_back()

Removes the last element from the array.

pop_front()

Removes the first element from the array.

push_back(string key, string value)

Adds a new element to the end of an array.

Parameters:

key

Key for the new element

value

Value for the new element

push_front(string key, string value)

Adds a new element to the front of an array.

setCurrent(int index)

Sets the current pointer index.

Parameters:

index

New 0-based pointer index

setKey(string key, int index)

Set the key at the given index.

Parameters:

key

New key value

index

0-based index of the array element to update

setValue(string value, int index)

Set the value at the given index.

Parameters:

value

New array element value

index

0-based index of the array element to update

sort(bool ascending)

Alpha sorts the array by value.

Parameters:

ascending

[optional] True for ascending sort, false for descending sort

sorta()

Alpha sorts the array by value in ascending order.

sortd()

Alpha sorts the array by value in descending order.

sortf(string functionName)

Sorts the array by value in ascending order using the given callback function.

Parameters:

functionName

Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.

function mySortCallback(%a, %b)
{
   return strcmp( %a.name, %b.name );
}

%array.sortf( "mySortCallback" );

sortfd(string functionName)

Sorts the array by value in descending order using the given callback function.

Parameters:

functionName

Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.

see:

sortfk(string functionName)

Sorts the array by key in ascending order using the given callback function.

Parameters:

functionName

Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.

see:

sortfkd(string functionName)

Sorts the array by key in descending order using the given callback function.

Parameters:

functionName

Name of a function that takes two arguments A and B and returns -1 if A is less, 1 if B is less, and 0 if both are equal.

see:

sortk(bool ascending)

Alpha sorts the array by key.

Parameters:

ascending

[optional] True for ascending sort, false for descending sort

sortka()

Alpha sorts the array by key in ascending order.

sortkd()

Alpha sorts the array by key in descending order.

sortn(bool ascending)

Numerically sorts the array by value.

Parameters:

ascending

[optional] True for ascending sort, false for descending sort

sortna()

Numerically sorts the array by value in ascending order.

sortnd()

Numerically sorts the array by value in descending order.

sortnk(bool ascending)

Numerically sorts the array by key.

Parameters:

ascending

[optional] True for ascending sort, false for descending sort

sortnka()

Numerical sorts the array by key in ascending order.

sortnkd()

Numerical sorts the array by key in descending order.

uniqueKey()

Removes any elements that have duplicated keys (leaving the first instance)

uniqueValue()

Removes any elements that have duplicated values (leaving the first instance)