Murl Engine Lua Addon API  Version 1.0 beta
Murl.Array.WChar

A generic array template class for moveable objects eg. structs or fundamental data types like UInt32, Real, etc.

The array class works for moveable objects only, use ObjectArray class for storing non-moveable objects.
This class is based on the NTL Vector container, see http://www.ultimatepp.org


Table members

Functions


Murl.Array.WChar.new()

Construct an empty array.

Murl.Array.WChar new()

Returns
Murl.Array.WChar

Murl.Array.WChar.new(item)

Construct an array containing a single item.

Murl.Array.WChar new(Integer item)

Parameters
itemThe item.
Returns
Murl.Array.WChar

Murl.Array.WChar.new(item1, item2)

Construct an array containing two items.

Murl.Array.WChar new(Integer item1, Integer item2)

Parameters
item1The first item.
item2The second item.
Returns
Murl.Array.WChar

Murl.Array.WChar.new(item1, item2, item3)

Construct an array containing three items.

Murl.Array.WChar new(Integer item1, Integer item2, Integer item3)

Parameters
item1The first item.
item2The second item.
item3The third item.
Returns
Murl.Array.WChar

Murl.Array.WChar.new(other)

Construct an array from an already existing one, performing a deep copy.

Murl.Array.WChar new(Murl.Array.WChar other)

Parameters
otherThe array to copy.
Returns
Murl.Array.WChar


Methods


Clear()

Clear the array and remove the underlying storage.

Clear()


Empty()

Empty the array, but keep the underlying storage.

Empty()


Shrink()

Shrink the array so that the underlying storage is only as large as necessary.

Shrink()


Trim(n)

Reduce the array to a given number of items.

Boolean Trim(Integer n)

Parameters
nThe new number of items in the array, must be smaller than the current item count.
Returns
Boolean true if successful.

Drop(n)

Reduce the array by removing a given number of items from the end.

Boolean Drop(Integer n)

Parameters
nThe number of items to remove from the end.
Returns
Boolean true if successful.

Reserve(n)

Reserve storage space. If the given size is less than the actual size, nothing is done.

Reserve(Integer n)

Parameters
nThe number of items the underlying storage should hold.

SetCount(n)

Set the actual number of items in the array. If the given number is smaller than the current size, the array is trimmed, and existing items beyond the new size are destroyed. If the given number is higher, new items are initialized via the value type's default constructor. If the given number is also higher than the underlying storage's capacity, the storage is enlarged to hold exactly the requested number of items.

Boolean SetCount(Integer n)

Parameters
nThe new number of items in the array.
Returns
Boolean true if successful.

SetCount(n, item)

Set the actual number of items in the array. If the given number is smaller than the current size, the array is trimmed, and existing items beyond the new size are destroyed. If the given number is higher, new items are initialized via the given value's copy constructor. If the given number is also higher than the underlying storage's capacity, the storage is enlarged to hold exactly the requested number of items.

Boolean SetCount(Integer n, Integer item)

Parameters
nThe new number of items in the array.
itemThe value to initialize any newly added items with.
Returns
Boolean true if successful.

SetCountAndReserve(n)

Set the actual number of items in the array and reserve extra storage space. If the given number is smaller than the current size, the array is trimmed, and existing items beyond the new size are destroyed. If the given number is higher, new items are initialized via the value type's default constructor. If the given number is also higher than the underlying storage's capacity, the storage is enlarged and some extra capacity is added.

Boolean SetCountAndReserve(Integer n)

Parameters
nThe new number of items in the array.
Returns
Boolean true if successful.

SetCountAndReserve(n, item)

Set the actual number of items in the array and reserve extra storage space. If the given number is smaller than the current size, the array is trimmed, and existing items beyond the new size are destroyed. If the given number is higher, new items are initialized via the given value's copy constructor. If the given number is also higher than the underlying storage's capacity, the storage is enlarged and some extra capacity is added.

Boolean SetCountAndReserve(Integer n, Integer item)

Parameters
nThe new number of items in the array.
itemThe value to initialize any newly added items with.
Returns
Boolean true if successful.

Set(index, item)

Initialize an item with a given item. If the given index is greater than the actual array size, the array is enlarged as needed.

Integer Set(Integer index, Integer item)

Parameters
indexThe index of the item to set.
itemThe source item to copy.
Returns
Integer A reference to the set item.

Set(index, item, count)

Initialize a range of items with a given item. If the given index plus the count is greater than the actual array size, the array is enlarged as needed.

Boolean Set(Integer index, Integer item, Integer count)

Parameters
indexThe index of the first item to set.
itemThe source item to copy.
countThe number of items to set.
Returns
Boolean true if successful.

Fill(item)

Fill all items with a given item.

Fill(Integer item)

Parameters
itemThe source item to copy.

Swap(index1, index2)

Swap two array items.

Swap(Integer index1, Integer index2)

Parameters
index1The index of the first item.
index2The index of the second item.

Swap(other)

Exchange the content of the array with a given second one.

Murl.Array.WChar Swap(Murl.Array.WChar other)

Parameters
otherThe second array.
Returns
Murl.Array.WChar other The second array.

Add()

Add a new item at the end of the array. The new item entry is initialized using the value type's default constructor.

Integer Add()

Returns
Integer A reference to the newly created item.

Add(item)

Add a given item at the end of the array. The new item entry is initialized using the given item's copy constructor.

Integer Add(Integer item)

Parameters
itemThe given item to be inserted at the end of the array.
Returns
Integer A reference to the newly created item.

Add(other)

Add a given array of items at the end of the array. The new item entries are initialized using the original items' copy constructors.

Boolean Add(Murl.Array.WChar other)

Parameters
otherThe given item array to be inserted.
Returns
Boolean true if successful.

Add(other, offset, count)

Add a subset of given array of items at the end of the array. The new item entries are initialized using the original items' copy constructors.

Boolean Add(Murl.Array.WChar other, Integer offset, Integer count)

Parameters
otherThe given source item array.
offsetThe index into the source array specifying the first item to copy.
countThe number of source array items to copy.
Returns
Boolean true if successful.

AddN(count)

Add a given number of new items at the end of the array. The new item entries are initialized using the value type's default constructor.

AddN(Integer count)

Parameters
countThe number of new items to be inserted at the end of the array.

Insert(index)

Insert a new item at a given position. The new item entry is initialized using the value type's default constructor.

Integer Insert(Integer index)

Parameters
indexthe zero-based index where the new item should be inserted.
Returns
Integer A reference to the newly created item.

Insert(index, item)

Insert a given item at a given position. The new item is initialized using the given item's copy constructor.

Integer Insert(Integer index, Integer item)

Parameters
indexthe zero-based index where the new item should be inserted.
itemThe given item to be inserted.
Returns
Integer A reference to the newly created item.

Insert(index, item, count)

Insert a number of copies of a given item at a given position. The new item entries are initialized using the given item's copy constructor.

Boolean Insert(Integer index, Integer item, Integer count)

Parameters
indexthe zero-based index where the new items should be inserted.
itemThe given item to be inserted.
countThe number of copies of the given item to insert.
Returns
Boolean true if successful.

Insert(index, other)

Insert a given array of items at a given position. The new item entries are initialized using the original items' copy constructors.

Boolean Insert(Integer index, Murl.Array.WChar other)

Parameters
indexthe zero-based index where the new items should be inserted.
otherThe given item array to be inserted.
Returns
Boolean true if successful.

Insert(index, other, offset, count)

Insert a subset of given array of items at a given position. The new item entries are initialized using the original items' copy constructors.

Boolean Insert(Integer index, Murl.Array.WChar other, Integer offset, Integer count)

Parameters
indexthe zero-based index where the new items should be inserted.
otherThe given source item array.
offsetThe index into the source array specifying the first item to copy.
countThe number of source array items to copy.
Returns
Boolean true if successful.

InsertN(index, count)

Insert a given number of new items at a given position. The new item entries are initialized using the value type's default constructor.

Boolean InsertN(Integer index, Integer count)

Parameters
indexthe zero-based index where the new items should be inserted.
countThe number of new items to be inserted.
Returns
Boolean true if successful.

RemoveGet(index)

Remove (and destroy) an item at a given position and get a copy of the item.

Integer RemoveGet(Integer index)

Parameters
indexThe zero-based index from where to remove the item.
Returns
Integer A copy of the removed item.

Remove(index, count)

Remove (and destroy) a number of items at a given position.

Boolean Remove(Integer index, Integer count)

Parameters
indexThe zero-based index from where to remove the items.
countThe number of items to remove.
Returns
Boolean true if successful.

Remove(sortedIndices)

Remove (and destroy) a number of items at given positions.

Remove(Murl.Array.SInt32 sortedIndices)

Parameters
sortedIndicesA sorted array of indices where to remove the items.

Find(item)

Find the first occurrence of a given item in the array.

Integer Find(Integer item)

Parameters
itemThe item to find.
Returns
Integer The index of the item, or -1 if the item was not found.

Find(item, firstIndex)

Find the first occurrence of a given item in the array.

Integer Find(Integer item, Integer firstIndex)

Parameters
itemThe item to find.
firstIndexThe index where to start searching.
Returns
Integer The index of the item, or -1 if the item was not found.

FindLast(item)

Find the last occurrence of a given item in the array.

Integer FindLast(Integer item)

Parameters
itemThe item to find.
Returns
Integer The index of the item, or -1 if the item was not found.

FindLast(item, lastIndex)

Find the last occurrence of a given item in the array.

Integer FindLast(Integer item, Integer lastIndex)

Parameters
itemThe item to find.
lastIndexThe index where to start searching.
Returns
Integer The index of the item, or -1 if the item was not found.

Front()

Retrieve the first item from the array. Synonymous to Bottom().

Integer Front()

Returns
Integer A const reference to the first item.

Back()

Retrieve the last item from the array. Synonymous to Top().

Integer Back()

Returns
Integer A const reference to the last item.

Bottom()

Retrieve the first item from the array.

Integer Bottom()

Returns
Integer A const reference to the first item.

Top()

Retrieve the last item from the array.

Integer Top()

Returns
Integer A const reference to the last item.

Pop()

Remove the last item from the array.

Integer Pop()

Returns
Integer A copy of the removed item.

At(index)

Retrieve the item at a given position from the array. If the given index is greater than the actual array size, the array is enlarged as needed, using the value type's default constructor for initializing.

Integer At(Integer index)

Parameters
indexThe zero-based index of the item to retrieve.
Returns
Integer A reference to the specified item.

At(index, item)

Retrieve the item at a given position from the array. If the given index is greater than the actual array size, the array is enlarged as needed, using the given reference item's copy constructor for initializing.

Integer At(Integer index, Integer item)

Parameters
indexThe zero-based index of the item to retrieve.
itemThe reference item used for initialization.
Returns
Integer A reference to the specified item.

GetCount()

Get the number of items in the array.

Integer GetCount()

Returns
Integer The number of items.

GetCountUInt32()

Get the number of items in the array.

Integer GetCountUInt32()

Returns
Integer The number of items.

IsEmpty()

Check if the array is empty.

Boolean IsEmpty()

Returns
Boolean true if the array is empty, false otherwise.

GetAlloc()

Get the number of actually allocated items.

Integer GetAlloc()

Returns
Integer The number of allocated items.

IsEqual(other)

Compare the array to another one.

Boolean IsEqual(Murl.Array.WChar other)

Parameters
otherThe array to compare.
Returns
Boolean true if both arrays have identical contents.

IsIndexValid(index)

Check if a given index is a valid index.

Boolean IsIndexValid(Integer index)

Parameters
indexThe index to check.
Returns
Boolean true if index >= 0 and index < GetCount().

Get(index)

Get the item at a given position from the array.

Integer Get(Integer index)

Parameters
indexThe zero-based index of the item to retrieve.
Returns
Integer A reference to the specified item.

GetByteSize()

Get the number of bytes of the underlying raw array.

Integer GetByteSize()

Returns
Integer The number of bytes of the underlying raw array.

ReAllocMove(numAlloc)

ReAllocMove(Integer numAlloc)



Metamethods


The length operator

The length operator is denoted by the unary prefix operator #.

Returns
GetCount()

The equal to operator.

The "equal to" comparison operator, calls IsEqual().

Returns
Boolean = Murl.Array.WChar == Murl.Array.WChar

The array subscript operator.

Retrieve the item at a given position from the array.

Parameters
indexThe zero-based index of the item to retrieve.
Returns
Integer = Murl.Array.WChar [Integer index]
Assign
Murl.Array.WChar [Integer index] = Integer