Class CArray API

A class for more sophisticated array handling than the VBScript built-in arrays allow for. Of course there's System.Collections.ArrayList, but I was aiming for something that a) would not require .NET and b) could easily be used as a queue or stack as well as a "regular" array.

Version:

1.0, 2011-01-02

Author:

Ansgar Wiechers <ansgar.wiechers@planetcobalt.net>

See also:

http://msdn.microsoft.com/en-us/library/system.collections.arraylist.aspx

Property Summary

First

Get or set the first element of the CArray.


Item(index)
default

Get or set the element at the given index of the CArray.


Items

Initialize the CArray with data or get all elements from the CArray.


Last

Get or set the last element of the CArray.

Method Summary

Add(element)

Add the given element at the end of the CArray.


AllIndexOf(element)

Return a CArray with all indexes on which the given element occurs in the CArray.


Append(arr)

Append each element of the given array or CArray to the end of this CArray.


Clear()

Remove all elements from the CArray.


Count()

Return the number of elements in this CArray.


Exists(element)

Indicate whether the given element does or doesn't exist in this CArray.


Flatten()

Transform a multi-dimensional CArray into a one-dimensional CArray by expanding nested arrays.


GetSlice(first, last)

Return a slice (sub-array) from this CArray.


IndexOf(element)

Return the index of the first occurrance of the given element in the CArray.


InsertBefore(index, element)

Insert the given element into the CArray before the given index.


InsertFirst(element)

Insert the given element as the first element.


InsertLast(element)

Insert the given element as the last element.


LastIndexOf(element)

Return the index of the last occurrance of the given element in the CArray.


Pop()

Remove the last element from the CArray and return it to the caller.


Push(element)

Insert the given element as the last element.


Remove(index)

Remove the element at the given index from the CArray and return it to the caller.


RemoveFirst()

Remove the first element from the CArray and return it to the caller.


RemoveLast()

Remove the first element from the CArray and return it to the caller.


RemoveSlice(first, last)

Remove a slice (sub-array) from this CArray and return it to the caller.


Reverse()

Revert the order of the elements in the CArray.


Sort()

Sort the CArray in ascending order.


ToArray()

Return the elements of the CArray as a plain VBScript array.


UpperBound()

Return the index of this CArray's upper boundary.

Property Detail

First

First
read-write

Get or set the first element of the CArray. If no first element exists (i.e. the CArray does not contain any elements), an error is raised. Getting the first element does not remove the element from the CArray.

Raises:

Index out of bounds. (9)

See also:

InsertFirst(element)

RemoveFirst()


Item

Item(index)
read-write, default

Get or set the element at the given index of the CArray. If the index is outside the CArray's boundaries, an error is raised. Getting an element does not remove the element from the CArray.

Raises:

Index out of bounds. (9)

See also:

InsertBefore(index,element)

Remove(index)


Items

Items
read-write

Initialize the CArray with data or get all elements from the CArray. When (Re-)initializing the CArray with (new) data, any data already present in the CArray is discarded. Data that is neither an array nor a CArray is treated as an array with size 1.


Last

Last
read-write

Get or set the last element of the CArray. If no last element exists (i.e. the CArray does not contain any elements), an error is raised. Getting the last element does not remove the element from the CArray.

Raises:

Index out of bounds. (9)

See also:

Push(element)

Pop()

InsertLast(element)

RemoveLast()

Method Detail

Add

Public Add(element)

Add the given element at the end of the CArray. Array and CArray elements are added as nested items. To concatenate an array or CArray with this CArray, use Append() instead.

Parameters:

element - The element to add.

See also:

Append(arr)


AllIndexOf

Public AllIndexOf(element)

Return a CArray with all indexes on which the given element occurs in the CArray. The function does not recurse into nested arrays.

Parameters:

element - The element for which to check.

Returns:

CArray with all indexes for the given element.


Append

Public Append(arr)

Append each element of the given array or CArray to the end of this CArray. Arguments that are not an array or CArray are simply added to the CArray (you could as well use Add() in this case).

Parameters:

arr - The array or CArray to append.

See also:

Add(element)


Clear

Public Clear()

Remove all elements from the CArray.


Count

Public Count()

Return the number of elements in this CArray.

Returns:

The number of elements in the CArray.


Exists

Public Exists(element)

Indicate whether the given element does or doesn't exist in this CArray. The function does not recurse into nested arrays.

Parameters:

element - The element to check for.

Returns:

True if the element is found in the CArray, otherwise False.


Flatten

Public Flatten()

Transform a multi-dimensional CArray into a one-dimensional CArray by expanding nested arrays.


GetSlice

Public GetSlice(first, last)

Return a slice (sub-array) from this CArray. The interval defined by the indexes is left-closed right-open (i.e. the element referred to by the last index is not included with the slice).

If both index values are outside the CArray's boundaries, or if the last index is greater than or equal to the first index, an empty CArray is returned. Negative indexes are allowed and refer to elements counted from the upper boundary of the array, starting with -1. Parameters can be Null and are then interpreted as the CArray's lower or upper boundary respectively.

Parameters:

first - Index of the beginning of the slice (included).

last - Index of the end of the slice (excluded).

Returns:

A slice from the CArray. The slice is also a CArray.


IndexOf

Public IndexOf(element)

Return the index of the first occurrance of the given element in the CArray. If no occurrance is found, the return value is Null. The function does not recurse into nested arrays.

Parameters:

element - The element to check for.

Returns:

The index of the first occurrance of element or Null.


InsertBefore

Public InsertBefore(index, element)

Insert the given element into the CArray before the given index.

Parameters:

index - Index before which the element should be inserted.

element - Element to insert into the CArray.

Raises:

Index out of bounds. (9)


InsertFirst

Public InsertFirst(element)

Insert the given element as the first element. This is basically an alias for InsertBefore(0, element) to have coherent method names for using CArray as a queue.

Parameters:

element - Element to insert into the CArray.

See also:

InsertLast(element)

RemoveFirst()

RemoveLast()

InsertBefore(index,element)


InsertLast

Public InsertLast(element)

Insert the given element as the last element. This is basically an alias for Add() to have coherent method names for using CArray as a queue.

Parameters:

element - Element to add to the CArray.

See also:

InsertFirst(element)

RemoveFirst()

RemoveLast()

Add(element)


LastIndexOf

Public LastIndexOf(element)

Return the index of the last occurrance of the given element in the CArray. If no occurrance is found, the return value is Null. The function does not recurse into nested arrays.

Parameters:

element - The element to check for.

Returns:

The index of the last occurrance of element or Null.


Pop

Public Pop()

Remove the last element from the CArray and return it to the caller. If the CArray does not contain any elements, an error is raised. This is basically an alias for Remove(CArray.UpperBound) to have coherent method names for using CArray as a stack.

Returns:

The element that was last in the CArray.

Raises:

Index out of bounds. (9)

See also:

Push(element)

Remove(index)


Push

Public Push(element)

Insert the given element as the last element. This is basically an alias for Add() to have coherent method names for using CArray as a stack.

Parameters:

element - Element to add to the CArray.

See also:

Pop()

Add(element)


Remove

Public Remove(index)

Remove the element at the given index from the CArray and return it to the caller. If the given index is outside the boundaries of the CArray, an error is raised.

Parameters:

index - The index of the element to remove.

Returns:

The element that was removed from the CArray.

Raises:

Index out of bounds. (9)


RemoveFirst

Public RemoveFirst()

Remove the first element from the CArray and return it to the caller. If the CArray does not contain any elements, an error is raised. This is basically an alias for Remove(0) to have coherent method names for using CArray as a queue.

Returns:

The element that was first in the CArray.

Raises:

Index out of bounds. (9)

See also:

InsertFirst(element)

InsertLast(element)

RemoveLast()

Remove(index)


RemoveLast

Public RemoveLast()

Remove the first element from the CArray and return it to the caller. If the CArray does not contain any elements, an error is raised. This is basically an alias for Remove(CArray.UpperBound) to have coherent method names for using CArray as a queue.

Returns:

The element that was last in the CArray.

Raises:

Index out of bounds. (9)

See also:

InsertFirst(element)

InsertLast(element)

RemoveFirst()

Remove(index)


RemoveSlice

Public RemoveSlice(first, last)

Remove a slice (sub-array) from this CArray and return it to the caller. The interval defined by the indexes is left-closed right-open (i.e. the element referred to by the last index is not included with the slice).

If both index values are outside the CArray's boundaries, or if the last index is greater than or equal to the first index, nothing is removed and an empty CArray is returned. Negative indexes are allowed and refer to elements counted from the upper boundary of the array, starting with -1. Parameters can be Null and are then interpreted as the CArray's lower or upper boundary respectively.

Parameters:

first - Index of the beginning of the slice (included).

last - Index of the end of the slice (excluded).

Returns:

The slice removed from the CArray. This slice is also a CArray.


Reverse

Public Reverse()

Revert the order of the elements in the CArray.


Sort

Public Sort()

Sort the CArray in ascending order. If the CArray contains any complex data types (like nested arrays or objects) an error will be raised. Arrays will raise error 10 (type mismatch), while objects will raise error 438 (property or method not supported).

Raises:

Type mismatch. (10)

Object doesn't support this property or method. (438)

See also:

http://msdn.microsoft.com/en-us/library/xe43cc8d.aspx


ToArray

Public ToArray()

Return the elements of the CArray as a plain VBScript array.

Returns:

Array with the elements of the CArray.


UpperBound

Public UpperBound()

Return the index of this CArray's upper boundary.

Returns:

The index of the CArray's upper boundary.

Created with VBSdoc.