SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND


Platform::Containers
Template Class Array

GeneralContainerType
   |
   +-GeneralCollectionType
        |
        +-GeneralSequenceType
             |
             +-Array

Implemented in:
Platform.Containers.Array.h

template <typename Element>
class Array:
public GeneralSequenceType

A dynamically sized array container. Holds a sequence of elements in adjacent positions in memory.

See Also:
Containers

Inner Compounds, Typedefs, and Enumscollapse
typedef ElementType
          Denotes the element type within the container.
typedef EntryType
          Denotes the entry type within the container.

Inner Compounds, Typedefs, and Enums inherited from class GeneralSequenceTypecollapse
ConstEnumerator, ConstIterator, Enumerator, Iterator

Fields inherited from class GeneralContainerTypecollapse
base

Constructor Summarycollapse
Array()
          Creates an empty array.
Array(const Array& container)
          Creates a copy of the specified array.
Array(const Array& container, Int fromIndex, Int toIndex)
          Creates a new array and copies into it the contents of another array within a given range.
template <typename ContainerX>
Array(const ContainerX& container)

          Creates a new array and copies the elements from the specified container using its enumerator.
Array(const ElementType& object, Int count)
          Creates a new array and fills it with copies of the specified object.
Array(const ElementType* source, Int count)
          Creates a new array and copies into it the contents of the given source.
Array(Int capacity)
          Creates an empty array with the specified initial capacity.
~Array()
          Destructor.

Method Summarycollapse
Void addAllAt(Int index, const Array& container)
          DOCTODO.
template <typename ContainerX>
Void
addAllAt(Int index, const ContainerX& container)
          DOCTODO.
Void addAllFirst(const Array& container)
          Inserts the contents of the specified array at the very beginning of this array (head).
Void addAllLast(const Array& container)
          Inserts the contents of the specified array at the very end of this array (tail).
Void addArray(const ElementType* source, Int count)
          Appends the objects pointed to by the specified source to the end of this array.
Void addArrayAt(Int index, const ElementType* source, Int count)
          Inserts the objects pointed to by the specified source at the given index in this array.
Void addAt(Int index, const ElementType& object)
          DOCTODO.
Void addFirst(const ElementType& object)
          Inserts a copy of the specified object at the very beginning of this array (head).
Void addLast(const ElementType& object)
          Inserts a copy of the specified object at the very end of this array (tail).
Void addMultiple(const ElementType& object, Int count)
          Appends copies of the given object to the end of this array.
Void addMultipleAt(Int index, const ElementType& object, Int count)
          Inserts copies of the given object at the specified position into this array.
ElementType& at(Int index)
          DOCTODO.
const ElementType& at(Int index) const
          DOCTODO.
Int binarySearch(const ElementType& object) const
          Attempts to find the specified element in this array using a binary search algorithm.
template <typename Comparator>
Int
binarySearch(const ElementType& object, Comparator compareFn) const
          Attempts to find the specified element in this array using a binary search algorithm.
Int capacity() const
          Returns the current capacity of this array.
template <typename Collection,
typename Predicate>
Collection&
collectEntries(Collection& collection, Predicate function) const
          Returns a collection of pointers to the elements within this array that match the predicate function.
Array& ensureCapacity(Int capacity)
          Resizes the capacity of this array such that it can hold the specified number of elements without reallocation.
ElementType extractAt(Int index)
          DOCTODO.
ElementType extractFirst()
          Removes the first element in this array (head) and returns its copy.
ElementType extractLast()
          Removes the last element in this array (tail) and returns its copy.
ElementType& first()
          Returns a reference to the first element in this array (head).
const ElementType& first() const
          Returns a reference to the first element in this array (head).
Int indexOf(const ElementType& object) const
          Returns the index of the first occurance of the specified object in this array.
Int indexOf(const ElementType& object, Int fromIndex) const
          Returns the index of the first occurance of the specified object in this array starting search at the given index.
Bool isValidIndex(Int index) const
          DOCTODO.
ElementType& last()
          Returns a reference to the last element in this array (tail).
const ElementType& last() const
          Returns a reference to the last element in this array (tail).
Int lastIndexOf(const ElementType& object) const
          Searches this array backwards for the specified object.
Int lastIndexOf(const ElementType& object, Int fromIndex) const
          Searches this array backwards for the specified object.
Array& operator=(const Array& container)
          Copies the contents of the given array into this array.
ElementType& operator[](Int index)
          DOCTODO.
const ElementType& operator[](Int index) const
          DOCTODO.
Void removeAt(Int index)
          DOCTODO.
Void removeFirst()
          Removes the first element in this array (head).
Void removeLast()
          Removes the last element in this array (tail).
Void removeRange(Int fromIndex, Int toIndex)
          DOCTODO.
Array& resize(Int size)
          Resizes this array such that it has exactly enough space to hold the specified number of elements.
ElementType* sequence()
          Returns the pointer to the first element of this array.
const ElementType* sequence() const
          Returns the pointer to the first element of this array.
Array& sort()
          Sorts the elements in this array according to their natural ordering.
template <typename Comparator>
Array&
sort(Comparator compareFn)
          Sorts the elements in this array according to their natural ordering.
template <typename Comparator,
typename Exchanger>
Array&
sort(Comparator compareFn, Exchanger exchangeFn)
          Sorts the elements in this array according to their natural ordering.
Array& trimCapacity()
          Resizes the capacity of this array such that any excess space at the end is removed.

Methods inherited from class GeneralContainerTypecollapse
compareTo, deepSize, empty, equals, exchangeWith, hashCode, isEmpty, size, toString, toXml

Methods inherited from class GeneralCollectionTypecollapse
contains, containsAll, containsAll, remove, removeAll, removeAll, retainAll, retainAll

Methods inherited from class GeneralSequenceTypecollapse
add, addAll, addAll, replaceAll

Friend Summarycollapse
friend Io::ISerializer& operator<<(Io::ISerializer& serializer, const Array& container)
          Serializes the state of an Array object.
friend Io::IDeserializer& operator>>(Io::IDeserializer& deserializer, Array& container)
          Deserializes the state of an Array object.

 

Constructor Detail

Array[inline]

Array()

Creates an empty array.


Array[inline]

Array(const Array& container)

Creates a copy of the specified array.

Parameters:
container - an array to copy elements from

Array[explicit, inline]

Array(const Array& container, Int fromIndex, Int toIndex)

Creates a new array and copies into it the contents of another array within a given range.

Parameters:
container - the source array to copy elements from
fromIndex - the start position within the source array
toIndex - the end position within the source array

Array[explicit, inline]

template <typename ContainerX>
Array(const ContainerX& container)

Creates a new array and copies the elements from the specified container using its enumerator.

Parameters:
container - a container to copy elements from

Array[explicit, inline]

Array(const ElementType& object, Int count)

Creates a new array and fills it with copies of the specified object.

Parameters:
object - an object to fill the array with
count - the number of copies to make

Array[explicit, inline]

Array(const ElementType* source, Int count)

Creates a new array and copies into it the contents of the given source.

Parameters:
source - a pointer to the objects to copy into the array
count - the number of elements to copy

Array[explicit, inline]

Array(Int capacity)

Creates an empty array with the specified initial capacity.

Parameters:
capacity - the initial capacity specified in the number of elements

~Array[inline]

~Array()

Destructor.

 

Method Detail

addAllAt[inline]

Void addAllAt(Int index, const Array& container)

DOCTODO.

Parameters:
index - DOCTODO
container - DOCTODO

addAllAt[inline]

template <typename ContainerX>
Void addAllAt(Int index, const ContainerX& container)

DOCTODO.

Parameters:
index - DOCTODO
container - DOCTODO

addAllFirst[inline]

Void addAllFirst(const Array& container)

Inserts the contents of the specified array at the very beginning of this array (head).

Parameters:
container - an array to prepend to this array

addAllLast[inline]

Void addAllLast(const Array& container)

Inserts the contents of the specified array at the very end of this array (tail).

Parameters:
container - an array to append to this array

addArray[inline]

Void addArray(const ElementType* source, Int count)

Appends the objects pointed to by the specified source to the end of this array.

Parameters:
source - a pointer to the objects to be copied
count - the number of objects to copy

addArrayAt[inline]

Void addArrayAt(Int index, const ElementType* source, Int count)

Inserts the objects pointed to by the specified source at the given index in this array.

Parameters:
index - position in this array at which the elements are inserted
source - a pointer to the objects to be copied
count - DOCthe number of objects to copy

addAt[inline]

Void addAt(Int index, const ElementType& object)

DOCTODO.

Parameters:
index - DOCTODO
object - DOCTODO

addFirst[inline]

Void addFirst(const ElementType& object)

Inserts a copy of the specified object at the very beginning of this array (head).

Parameters:
object - an object to prepend to this array

addLast[inline]

Void addLast(const ElementType& object)

Inserts a copy of the specified object at the very end of this array (tail).

Parameters:
object - an object to append to this array

addMultiple[inline]

Void addMultiple(const ElementType& object, Int count)

Appends copies of the given object to the end of this array.

Parameters:
object - an object to create copies of
count - the number of copies to append

addMultipleAt[inline]

Void addMultipleAt(Int index, const ElementType& object, Int count)

Inserts copies of the given object at the specified position into this array.

Parameters:
index - position at which the copies are inserted
object - an object to create copies of
count - the number of copies to insert

at[inline]

ElementType& at(Int index)

DOCTODO.

Parameters:
index - DOCTODO
Returns:
DOCTODO

at[inline]

const ElementType& at(Int index) const

DOCTODO.

Parameters:
index - DOCTODO
Returns:
DOCTODO

binarySearch[inline]

Int binarySearch(const ElementType& object) const

Attempts to find the specified element in this array using a binary search algorithm.

Parameters:
object - an object to find in this array
Returns:
the index (>= 0) of the element if found, otherwise (-(insertion point) - 1) which is the index where the element would be inserted
Preconditions:
the array must be sorted prior to using this method
See Also:
Arrays::binarySearch, sort

binarySearch[inline]

template <typename Comparator>
Int binarySearch(const ElementType& object, Comparator compareFn) const

Attempts to find the specified element in this array using a binary search algorithm.

Parameters:
object - an object to find in this array
compareFn - comparator function
Returns:
the index (>= 0) of the element if found, otherwise (-(insertion point) - 1) which is the index where the element would be inserted
Preconditions:
the array must be sorted prior to using this method
See Also:
Arrays::binarySearch, sort

capacity[inline]

Int capacity() const

Returns the current capacity of this array.

Returns:
the current capacity of this array

collectEntries[inline]

template <typename Collection, typename Predicate>
Collection& collectEntries(Collection& collection, Predicate function) const

Returns a collection of pointers to the elements within this array that match the predicate function.

Parameters:
collection - a container to hold the resulting collection of pointers
function - a predicate function to select which elements to add to the collection
Returns:
the input collection with the selected pointers appended at the end (if any)

ensureCapacity[inline]

Array& ensureCapacity(Int capacity)

Resizes the capacity of this array such that it can hold the specified number of elements without reallocation.

Parameters:
capacity - the desired minimum number of elements this array should be able to hold without reallocation
Returns:
a reference to this array

extractAt[inline]

ElementType extractAt(Int index)

DOCTODO.

Parameters:
index - DOCTODO
Returns:
DOCTODO

extractFirst[inline]

ElementType extractFirst()

Removes the first element in this array (head) and returns its copy.

Returns:
the copy of the first element in the array
Preconditions:
the array must contain at least one element (i.e. !isEmpty())

extractLast[inline]

ElementType extractLast()

Removes the last element in this array (tail) and returns its copy.

Returns:
the copy of the last element in the array
Preconditions:
the array must contain at least one element (i.e. !isEmpty())

first[inline]

ElementType& first()

Returns a reference to the first element in this array (head).

Returns:
a reference to the first element in this array
Preconditions:
the array must contain at least one element (i.e. !isEmpty())

first[inline]

const ElementType& first() const

Returns a reference to the first element in this array (head).

Returns:
a reference to the first element in this array
Preconditions:
the array must contain at least one element (i.e. !isEmpty())

indexOf[inline]

Int indexOf(const ElementType& object) const

Returns the index of the first occurance of the specified object in this array. If the search is unsuccessful (element not found) this method returns -1.

Parameters:
object - an object to find in this array
Returns:
the index of the first occurance of the specified object in this array, or -1 if not found
See Also:
Lang::equal

indexOf[inline]

Int indexOf(const ElementType& object, Int fromIndex) const

Returns the index of the first occurance of the specified object in this array starting search at the given index. If the search is unsuccessful (the object is not found) this method returns -1.

Parameters:
object - an object to find in this array
fromIndex - the position in this array to start searching from
Returns:
the index of the first occurance of the specified object in this array, or -1 if not found
See Also:
Lang::equal

isValidIndex[inline]

Bool isValidIndex(Int index) const

DOCTODO.

Parameters:
index - DOCTODO
Returns:
DOCTODO

last[inline]

ElementType& last()

Returns a reference to the last element in this array (tail).

Returns:
a reference to the last element in this array
Preconditions:
the array must contain at least one element (i.e. !isEmpty())

last[inline]

const ElementType& last() const

Returns a reference to the last element in this array (tail).

Returns:
a reference to the last element in this array
Preconditions:
the array must contain at least one element (i.e. !isEmpty())

lastIndexOf[inline]

Int lastIndexOf(const ElementType& object) const

Searches this array backwards for the specified object. The search starts at the last element of this array (tail) and continues towards the beginning (head).

Parameters:
object - an object to find in this array
Returns:
the index of the last occurance of the specified object in this array, or -1 if not found
See Also:
Lang::equal

lastIndexOf[inline]

Int lastIndexOf(const ElementType& object, Int fromIndex) const

Searches this array backwards for the specified object. The search starts at the specified index within this array (tail) and continues towards the beginning (head).

Parameters:
object - an object to find in this array
fromIndex - the position in this array to start searching from
Returns:
the index of the last occurance of the specified object in this array, or -1 if not found
See Also:
Lang::equal

operator=[inline]

Array& operator=(const Array& container)

Copies the contents of the given array into this array. The contents of this array are destroyed and the array is resized, if necessary, to hold the elements from the source array. If the copy operation is unsuccessfull (e.g. an exception is thrown during element copy) the operation is rolled back (the contents of this array unmodified) and the exception is re-thrown.

Parameters:
container - an array to copy elements from
Returns:
this array

operator[][inline]

ElementType& operator[](Int index)

DOCTODO.

Parameters:
index - DOCTODO
Returns:
DOCTODO

operator[][inline]

const ElementType& operator[](Int index) const

DOCTODO.

Parameters:
index - DOCTODO
Returns:
DOCTODO

removeAt[inline]

Void removeAt(Int index)

DOCTODO.

Parameters:
index - DOCTODO

removeFirst[inline]

Void removeFirst()

Removes the first element in this array (head).

Preconditions:
the array must contain at least one element (i.e. !isEmpty())

removeLast[inline]

Void removeLast()

Removes the last element in this array (tail).

Preconditions:
the array must contain at least one element (i.e. !isEmpty())

removeRange[inline]

Void removeRange(Int fromIndex, Int toIndex)

DOCTODO.

Parameters:
fromIndex - DOCTODO
toIndex - DOCTODO

resize[inline]

Array& resize(Int size)

Resizes this array such that it has exactly enough space to hold the specified number of elements.

Remarks:
this is an UNSAFE OPERATION: the excess elements are not destroyed and the excess space is not initialized
Parameters:
size - the desired number of elements in this array
Returns:
a reference to this array

sequence[inline]

ElementType* sequence()

Returns the pointer to the first element of this array.

Returns:
the pointer to the first element of this array

sequence[inline]

const ElementType* sequence() const

Returns the pointer to the first element of this array.

Returns:
the pointer to the first element of this array

sort[inline]

Array& sort()

Sorts the elements in this array according to their natural ordering.

See Also:
Arrays::sort
Returns:
a reference to this array

sort[inline]

template <typename Comparator>
Array& sort(Comparator compareFn)

Sorts the elements in this array according to their natural ordering.

Parameters:
compareFn - comparator function
See Also:
Arrays::sort
Returns:
a reference to this array

sort[inline]

template <typename Comparator, typename Exchanger>
Array& sort(Comparator compareFn, Exchanger exchangeFn)

Sorts the elements in this array according to their natural ordering.

Parameters:
compareFn - comparator function
exchangeFn - exchanger function
See Also:
Arrays::sort
Returns:
a reference to this array

trimCapacity[inline]

Array& trimCapacity()

Resizes the capacity of this array such that any excess space at the end is removed.

Returns:
a reference to this array

 

Friend Detail

operator<<[inline]

friend Io::ISerializer& operator<<(Io::ISerializer& serializer, const Array& container)

Serializes the state of an Array object.

Parameters:
container - an array object to serialize
serializer - a serializer to receive state data
Returns:
the reference to the serializer

operator>>[inline]

friend Io::IDeserializer& operator>>(Io::IDeserializer& deserializer, Array& container)

Deserializes the state of an Array object.

Parameters:
container - an array object to deserialize
deserializer - a deserializer to retrieve state data from
Returns:
the reference to the deserializer


SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND