Overview
Examples
Screenshots
Comparisons
Applications
Download
Documentation
Tutorials
Bazaar
Status & Roadmap
FAQ
Authors & License
Forums
Funding Ultimate++
Search on this site













SourceForge.net Logo

Array

 

template <class T>

class Array : public MoveableAndDeepCopyOption< Array<T> > 

T

Type or base class of elements stored in the Array. There is no common requirement for T.

The most universal form of basic random access container. Its features are derived from fact that typically it is  implemented using indirect container of pointers to T like Vector<T*>. Nevertheless it supports common concepts as ownership of contained elements, reference (not pointer) access to elements and so on.

It provides almost all operations of Vector with the same semantics and almost any Vector can be directly replaced by Array. On the other hand, it provides some special operations impossible for Vector and most important, it never invalidates references (that means C++ references and pointers) to elements (it often invalidates iterators, though).

Array can be also used to store polymorphic elements - stored elements could be derived from T. To store such elements, you pass a pointer to an element previously created on the heap. Still, Array takes over ownership of such element (it e.g. deletes it when appropriate). You can also use this method to create an Array of elements that do not have either pick, deep copy constructor nor default constructor.

There are also operations that allow detaching an element from an Array, removing it but not destroying. Pointer to such element is returned from this operation and the Array gives up ownership.

Disadvantage of Array over Vector is performance - most operations are significantly slower than with Vectors (by factor up to 8, it depends on the speed of malloc/free). Still, some operations might be even faster, e.g. Insert and Remove operations usually move much less memory.

As for memory, for small size of elements, Array memory consumption is significantly higher than Vector consumption. As the size of the elements grow, Array starts to be better than Vector.

Iterators to Array satisfy all C++ standard library requirements for random access iterator plus they allow assignment (and copy constructor) and testing for 0 (that is NULL) pointer.

Like any other NTL container, Array is a moveable type with pick and optional deep copy transfer semantics.

 

 

Constructor Detail

 

Array()

Default constructor. Constructs an empty Array.

 


 

Array(pick_ Array& v)

Pick constructor. Transfers the source Array in low constant time, but destroys it by picking.

v

Source Array.

 


 

Array(const Array& v, int)

Optional deep copy constructor.

Requires T to have deep copy constructor or optional deep copy constructor if the Array stores only objects of type T.

Requires polymorphic deep copy if the Array stores also objects of type derived from T.

v

Source Array.

 


 

~Array()

Destructor. Invokes the destructor of every element in the Array.

 


 

Array(std::initializer_list<Tinit)

C++11 initialization.

 

Public Member List

 

T& Add()

Adds a new default constructed element to the Array.

Requires T to have default constructor.

Invalidates iterators to the Array.

Return value

Reference to newly added default constructed element.

 


 

T& Add(const T& x)

Adds a new element with specified value to the Array.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

x

The value that is copied to newly created element.

Return value

Reference to new element in Array.

 


 

T& Add(T&& x)

Adds new element to the Array and picks value of parameter to it.

 


 

T& Add(T *newt)

Adds a new element to the Array. Element is specified by pointer to an object created using operator new. Array takes over ownership of this object. This variant allows the use of an Array as a polymorphic container, because the type of the added element can be either T or a type derived from T. No constructor is applied.

newt

Object to be added.

Return value

Reference to the new element  (that is *newt).

 


 

template <class TT> TT& Create()

Creates and adds a new element to the Array.

Requires T to have default constructor.

TT

Type of the new element.

Return value

Reference to the newly created element.

 


 

const T& operator[](int iconst

Returns a reference to the element at the specified position.

i

Position of the element.

Return value

Constant reference to the element.

 


 

T& operator[](int i)

Returns a reference to the element at the specified position.

i

Position of element.

Return value

Reference to the element.

 


 

int GetCount() const

Returns the number of elements in the Array.

Return value

Actual number of elements.

 


 

bool IsEmpty() const

Tests whether Array is empty. Same as GetCount() == 0.

Return value

true if Array is empty, false otherwise.

 


 

void Trim(int n)

Reduces the number of elements in the Array to the specified number. Required number must be less than or equal to the actual number of elements in the Array.

n

Required number of elements.

 


 

void SetCount(int n)

Changes the count of elements in the Array to the specified value. If the required number of elements is greater than actual number, the newly added elements are default constructed. If the Array's capacity has to be increased, the new capacity will exactly match the required number of elements (unlike SetCountR).

Requires T to have default constructor.

Invalidates iterators to the Array.

n

Required number of elements.

 


 

void SetCount(int n, const T& init)

Changes the count of elements in the Array to the specified value. If the required number of elements is greater than the actual number, the newly added elements are initialized to the specified value using copy constructor. If the Array's capacity has to be increased, the new capacity will exactly match the required number of elements (unlike SetCountR).

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

n

Required number of elements.

init

Initialization value of the newly added elements.

 


 

void SetCountR(int n)

Changes the count of elements in the Array to the specified value. If the required number of elements is greater than the actual number, the newly added elements are default constructed. If the Array's capacity has to be increased, the new capacity will be greater than the required number of elements (unlike SetCount) to allow adding other elements without further increasing capacity.

Requires T to have default constructor.

Invalidates iterators to the Array.

n

Required number of elements.

 


 

void SetCountR(int n, const T& init)

Changes the count of elements in the Array to the specified value. If the required number of elements is greater than the actual number, the newly added elements are initialized to the specified value using copy constructor. If the Array's capacity has to be increased, he new capacity will be greater than the required number of elements (unlike SetCount) to allow adding other elements without further increasing capacity.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

n

Required number of elements.

init

Initialization value of the newly added elements.

 


 

void Clear()

Removes all elements from the Array. Capacity is also cleared to zero.

Invalidates iterators to the Array.

 


 

T& At(int i)

If the specified position is lower than the number of elements in the Array (i < GetCount()), returns a reference to the element at the specified position. Otherwise increases the number of elements in the Array to i + 1. Newly added elements are default constructed. If the Array's capacity has to be increased, the new capacity will be greater than the required number of elements to allow adding other elements without further increasing capacity.

Requires T to have default constructor.

Invalidates iterators to the Array.

i

Position of the required element.

Return value

Reference to the required element.

 


 

T& At(int i, const T& x)

If specified position is lower than number of elements in the Array (i < GetCount()), returns a reference to the element at the specified position. Otherwise increases the number of elements in the Array to i + 1. Newly added elements are copy constructed from x. If the Array's capacity has to be increased, the new capacity will be greater than the required number of elements to allow adding other elements without further increasing capacity.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

i

Position of the required element.

x

Initialization value of newly added elements.

Return value

Reference to the required element.

 


 

void Shrink()

Minimizes memory consumption of the Array by decreasing the capacity to the number of elements.

 


 

void Reserve(int xtra)

Reserves capacity. If required capacity is greater than the current capacity, capacity is increased to the required value.

xtra

Required capacity.

 


 

int GetAlloc() const

Returns current capacity of the Array.

Return value

Capacity of the Array.

 


 

void Set(int i, const T& x, int count)

Sets the requested number of elements starting at the position i to the specified value. If the required number of elements exceeds existing elements of the Array then elements are added to the Array.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

i

Starting position.

x

Value.

count

Number of elements.

 


 

T& Set(int i, const T& x)

Sets the element at i to x and returns a reference to this element.

 


 

void Remove(int i, int count = 1)

Removes requested number of elements.

Invalidates iterators to the Array.

i

Position.

count

Number of elements to remove.

 


 

void Remove(const int *sorted_list, int n)

Removes number of elements from the Array. Time of operation almost does not depend on number of elements.

Invalidates iterators to the Array.

sorted_list

Pointer to the Array of positions to remove. It must be sorted from lowest to greatest value.

n

Number of elements to remove.

 


 

void Remove(const Vector<int>& sorted_list)

Removes number of elements from the Array. Same as Remove(sorted_list, sorted_list.GetCount()).

Invalidates iterators to the Array.

sorted_list

Sorted Vector of positions to remove.

 


 

void InsertN(int i, int count = 1)

Inserts a specified number of default constructed elements at the specified position.

Requires T to have default constructor.

Invalidates iterators to the Array.

i

Position.

count

Number of elements to insert.

 


 

T& Insert(int i)

Inserts one default constructed element at the specified position.

Requires T to have default constructor.

Invalidates iterators to the Array.

i

Position.

 


 

void Insert(int i, const T& x, int count)

Inserts a specified number of elements, setting them to a specified value.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

i

Position.

x

Value of the inserted elements.

count

Number of elements to insert.

 


 

T& Insert(int i, const T& x)

Inserts an element at i setting it to x and returns a reference to it.

 


 

T& InsertPick(int i, T&& x)

Inserts an element at i picking the content of x and returns a reference to it.

 


 

void Insert(int i, const Array& x)

Inserts all elements from another Array.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

i

Position.

x

Source Array.

 


 

void Insert(int i, const Array& x, int offset, int count)

Inserts a range of elements from another Array.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

i

Insertion position.

x

Source Array.

offset

Position of first element in source Array to be inserted.

count

Number of elements to insert.

 


 

void Insert(int i, std::initializer_list<Tinit)

Inserts C++11 style initializer list.

 


 

void Append(std::initializer_list<Tinit)

Appends C++11 style initializer list.

 


 

void Append(const Array& x)

Appends all elements of source Array.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

x

Source Array.

 


 

void Append(const Array& x, int o, int c)

Appends a range of elements from source Array.

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

x

Source Array.

o

Position of the first element in source Array to be inserted.

c

Number of elements to insert.

 


 

void InsertPick(int i, Array&& x)

Inserts the source Array at the specified position using pick transfer semantics. It is faster than deep copy insert, does not use deep copy constructor for T, but destroys the source Array by picking.

 


 

void AppendPick(Array&& x)

Appends source Array using pick transfer semantics. It is faster than deep copy insert, does not use deep copy constructor for T, but destroys the source Array by picking.

 


 

void Swap(int i1, int i2)

Swaps elements without using copy constructor.

Invalidates iterators to the Array.

i1

Position of the first element.

i2

Position of the second element.

 


 

void Move(int i1, int i2)

Removes element at position i1 and inserts it at i2, without using copy constructor of T.

Invalidates iterators to the Array.

i1

Position of the element to move.

i2

Target position.

 


 

T *Detach(int i)

Removes the element at position i, giving up ownership. Client is responsible for deletion of the element.

Invalidates iterators to the Array.

i

Position of the element to remove.

Return value

Pointer to the element allocated on the heap.

 


 

T *Swap(int i, T *newt)

Sets element at i to newt.and returns a pointer to original element. Client is responsible for deletion of the original element.

 


 

T& Set(int i, T *newt)

Replaces element at the specified position by an element previously created on the heap. Array takes over ownership of the element.

i

Position.

newt

New element allocated on the heap.

Return value

Reference to new element.

 


 

void Insert(int i, T *newt)

Inserts an element previously created on the heap at the specified position. Array takes over ownership of element.

Invalidates iterators to the Array.

i

Insertion position.

newt

New element allocated on the heap.

 


 

void Drop(int n = 1)

Drops specified number of last elements in the Array (same as Trim(GetCount() - n)).

n

Number of elements.

 


 

T& Top()

Returns reference to the last element in the Array.

Return value

Reference of last element in the Array.

 


 

const T& Top() const

Returns constant reference to the last element in the Array.

Return value

Reference of last element in the Array.

 


 

T *PopDetach()

Drops the last element in the Array, giving up ownership (same as Detach(GetCount() - 1)). Client is responsible for deletion of element.

Invalidates iterators to the Array.

Return value

Pointer to element allocated on the heap.

 


 

void Swap(Array& b)

Swaps content of Array with another array in constant time operation.

b

Target array.

 


 

Array& operator<<(const T& x)

Operator replacement of void Add(const T&x). By returning a reference to the Array it allows adding more elements in a single expression, thus e.g. allowing to construct a temporary Array as part of an expression like Foo((Array<int>() << 1 << 2 << 4)).

Requires T to have deep copy constructor.

Invalidates iterators to the Array.

x

The value that is copied to newly created element.

Return value

Reference to the Array (*this).

 


 

Array& operator<<(T *newt)

Operator replacement of void Add(T *x). By returning a reference to the Array it allows adding more elements in a single expression, thus e.g. allowing to construct a temporary Array as part of an expression like Foo((Array<Bar>() << new Bar << new DerivedFromBar)).

Invalidates iterators to the Array.

newt

Object to be added.

Return value

Reference to the Array (*this).

 


 

Array& operator|(pick_ T& x)

Operator replacement of void AddPick(pick_ T&x). By returning a reference to the Array it allows adding more elements in a single expression, thus e.g. allowing to construct a temporary Array as part of an expression.

Requires T to have pick constructor.

Invalidates iterators to the Array.

x

Source instance of T that is to be picked.

Return value

Reference to Array (*this).

 


 

bool IsPicked() const

Returns true if the Array is in picked state.

Return value

true if the Array is in picked state, false otherwise.

 


 

void Serialize(Stream& s)

Serializes the content of the Array to/from the Stream. Works only if NTL is used as part of UPP. Does not work with polymorphic Arrays (those storing objects derived from T).

Requires T to have serialization operator defined.

s

Target/source stream.

 


 

void operator=(pick_ Array& v)

Pick operator. Transfers the source Array in low constant time, but destroys it by picking.

v

Source Array.

 


 

typedef T ValueType

Typedef of T for use in templated algorithms.

 


 

class Iterator : public ConstIterator

Iterator type.

 


 

class ConstIterator

Constant iterator type.

 


 

Iterator Begin()

Returns a non-constant iterator to the first element in the Array.

Return value

Iterator.

 


 

Iterator End()

Returns a non-constant iterator to the position just beyond the last element in Array.

Return value

Iterator.

 


 

Iterator GetIter(int pos)

Returns a non-constant iterator to the element at the specified position. Same as Begin() + pos. The benefit of this method is that pos is range checked in debug mode.

pos

Required position.

Return value

Iterator.

 


 

ConstIterator Begin() const

Returns a constant iterator to the first element in Array.

Return value

Iterator.

 


 

ConstIterator End() const

Returns a constant iterator to the position just beyond the last element in Array.

Return value

Iterator.

 


 

ConstIterator GetIter(int posconst

Returns a constant iterator to the element at the specified position. Same as Begin() + pos. The benefit of this method is that pos is range checked in debug mode..

pos

Required position.

Return value

Iterator.

 


 

friend void Swap(Arraya, Arrayb)

Specialization of the generic Swap for Array. Swaps the arrays in simple constant time operation.

a

First Array to swap.

b

Second Array to swap.


 

friend void IterSwap(Iterator a, Iterator b)

Specialization of the generic IterSwap for Array. Swaps the elements in an Array without any requirements for T.

a

Iterator to first element.

b

Iterator to second element.

 

 

Do you want to contribute?