CopperSpice API  1.7.2
QVarLengthArray< T, Prealloc > Class Template Reference

Provides a low level variable length array. More...

Public Typedefs

typedef const T * const_iterator
 
typedef const value_typeconst_pointer
 
typedef const value_typeconst_reference
 
typedef std::reverse_iterator< const_iteratorconst_reverse_iterator
 
typedef qptrdiff difference_type
 
typedef T * iterator
 
typedef value_typepointer
 
typedef value_typereference
 
typedef std::reverse_iterator< iteratorreverse_iterator
 
typedef int size_type
 
typedef T value_type
 

Public Methods

 QVarLengthArray (const QVarLengthArray< T, Prealloc > &other)
 
 QVarLengthArray (int size=0)
 
 ~QVarLengthArray ()
 
void append (const T &value)
 
void append (const T *buffer, int length)
 
const T & at (int index) const
 
T & back ()
 
const T & back () const
 
iterator begin ()
 
const_iterator begin () const
 
int capacity () const
 
const_iterator cbegin () const
 
const_iterator cend () const
 
void clear ()
 
const_iterator constBegin () const
 
const T * constData () const
 
const_iterator constEnd () const
 
bool contains (const T &value) const
 
int count () const
 
const_reverse_iterator crbegin () const
 
const_reverse_iterator crend () const
 
T * data ()
 
const T * data () const
 
bool empty () const
 
iterator end ()
 
const_iterator end () const
 
iterator erase (const_iterator begin, const_iterator end)
 
iterator erase (const_iterator pos)
 
T & first ()
 
const T & first () const
 
T & front ()
 
const T & front () const
 
int indexOf (const T &value, int from=0) const
 
iterator insert (const_iterator before, const T &value)
 
iterator insert (const_iterator before, int count, const T &value)
 
void insert (int index, const T &value)
 
void insert (int index, int count, const T &value)
 
bool isEmpty () const
 
T & last ()
 
const T & last () const
 
int lastIndexOf (const T &value, int from=-1) const
 
int length () const
 
QVarLengthArray< T, Prealloc > & operator+= (const T &value)
 
QVarLengthArray< T, Prealloc > & operator<< (const T &value)
 
QVarLengthArray< T, Prealloc > & operator= (const QVarLengthArray< T, Prealloc > &other)
 
QVarLengthArray< T, Prealloc > & operator= (std::initializer_list< T > list)
 
T & operator[] (int index)
 
const T & operator[] (int index) const
 
void pop_back ()
 
void prepend (const T &value)
 
void push_back (const T &value)
 
reverse_iterator rbegin ()
 
const_reverse_iterator rbegin () const
 
void remove (int index)
 
void remove (int index, int count)
 
void removeLast ()
 
reverse_iterator rend ()
 
const_reverse_iterator rend () const
 
void replace (int index, const T &value)
 
void reserve (int size)
 
void resize (int size)
 
int size () const
 
void squeeze ()
 
value (int index) const
 
value (int index, const T &defaultValue) const
 

Related Functions

These are not member functions

bool operator!= (const QVarLengthArray< T, Prealloc1 > &left, const QVarLengthArray< T, Prealloc2 > &right)
 
bool operator== (const QVarLengthArray< T, Prealloc1 > &left, const QVarLengthArray< T, Prealloc2 > &right)
 

Detailed Description

template<class T, int Prealloc>
class QVarLengthArray< T, Prealloc >

The QVarLengthArray class provides a low level variable length array. C++ does not have a built in variable length array. This class only makes sense in very specific cases.

For example, the following code will not compile:

int myfunc(int n) {
int table[n + 1]; // INCORRECT
return table[n];
}

An alternative is to allocate the array on the heap using new. This approach has a drawback if myfunc() is called frequently. Heap allocation can be expensive and slow.

int myfunc(int n) {
int *table = new int[n + 1];
...
int retval = table[n];
delete[] table;
return retval;
}

The QVarLengthArray class allocates a specified number of elements on the stack. If the array needs to grow beyond the original stack allocation it will automatically use the heap. Stack allocation has the advantage that it is much faster than heap allocation.

In this example QVarLengthArray will preallocate 1024 elements on the stack and use them unless n + 1 is greater than 1024. If you omit the second template argument, QVarLengthArray's default of 256 is used.

int myfunc(int n) {
return array[n];
}

Constraints on type T

The QVarLengthArray value type T should be Default Constructible and Copy Constructible to work with all methods of this class. Data types like QObject are not copy constructible and therefore should never be stored in a container. You can however use a pointer to a QObject or any subclass as the type T.

Comparison with QVector

QVarLengthArray is similar to QVector however it provides a resizable array data structure. The following are the key differences between the two classes,

  • QVarLengthArray's API is a considered low level
  • Provides no iterators and lacks much of the QVector functionality
  • QVarLengthArray does not initialize the memory if the value is a basic type whereas QVector does
See also
QList, QLinkedList, QVector

Member Typedef Documentation

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::const_iterator

Typedef for const T *.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::const_pointer

Typedef for const T *.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::const_reference

Typedef for const T &.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::const_reverse_iterator

Typedef for const T *.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::difference_type

Typedef for ptrdiff_t.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::iterator

Typedef for T *.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::pointer

Typedef for T *.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::reference

Typedef for T &.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::reverse_iterator

Typedef for T *.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::size_type

Typedef for int.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::value_type

Typedef for T.

Constructor & Destructor Documentation

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::QVarLengthArray ( int  size = 0)
inlineexplicit

Constructs an array with an initial size of size elements.

The new elements are default initialized. Refer to default constructed elements for additional information.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::QVarLengthArray ( const QVarLengthArray< T, Prealloc > &  other)
inline

Constructs a copy of other.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::~QVarLengthArray ( )
inline

Destroys the array.

Method Documentation

template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::append ( const T &  value)
inline

Appends item value to the array, extending the array if necessary.

See also
removeLast()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::append ( const T *  buffer,
int  length 
)

Appends length amount of items referenced by buffer to this array.

template<class T , int Prealloc>
const T & QVarLengthArray< T, Prealloc >::at ( int  index) const
inline

Returns a reference to the item at index position index. The given index must be a valid position in the array.

See also
value(), operator[]()
template<class T , int Prealloc>
T & QVarLengthArray< T, Prealloc >::back ( )
inline

Equivalent to calling removeLast().

template<class T , int Prealloc>
const T & QVarLengthArray< T, Prealloc >::back ( ) const
inline

Equivalent to calling removeLast().

template<class T , int Prealloc>
iterator QVarLengthArray< T, Prealloc >::begin ( )
inline

Returns an STL-style iterator pointing to the first item in the array.

See also
constBegin(), end()
template<class T , int Prealloc>
const_iterator QVarLengthArray< T, Prealloc >::begin ( ) const
inline

Returns an STL-style iterator pointing to the first item in the array.

template<class T , int Prealloc>
int QVarLengthArray< T, Prealloc >::capacity ( ) const
inline

Returns the maximum number of elements that can be stored in the array without forcing a reallocation.

The purpose of this method is to provide a means of fine tuning QVarLengthArray's memory usage. This method is rarely used. If you want to know how many items are in the array call size().

See also
reserve()
template<class T , int Prealloc>
const_iterator QVarLengthArray< T, Prealloc >::cbegin ( ) const
inline

Returns a const STL-style iterator pointing to the first item in the array.

See also
begin(), constEnd()
template<class T , int Prealloc>
const_iterator QVarLengthArray< T, Prealloc >::cend ( ) const
inline

Returns a const STL-style iterator pointing to the imaginary item after the last item in the array.

See also
constBegin(), end()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::clear ( )
inline

Removes all the elements from the array. Same as calling resize(0).

template<class T , int Prealloc>
const_iterator QVarLengthArray< T, Prealloc >::constBegin ( ) const
inline

Returns a const STL-style iterator pointing to the first item in the array.

See also
begin(), constEnd()
template<class T , int Prealloc>
const T * QVarLengthArray< T, Prealloc >::constData ( ) const
inline

Returns a const pointer to the data stored in the array. The pointer can be used to access the items in the array. The pointer remains valid as long as the array is not reallocated.

This method is mostly useful to pass an array to a function which accepts a raw C++ array.

See also
data(), operator[]()
template<class T , int Prealloc>
const_iterator QVarLengthArray< T, Prealloc >::constEnd ( ) const
inline

Returns a const STL-style iterator pointing to the imaginary item after the last item in the array.

See also
constBegin(), end()
template<class T , int Prealloc>
bool QVarLengthArray< T, Prealloc >::contains ( const T &  value) const
inline

Returns true if the array contains an occurrence of value, otherwise returns false. This method requires the value type to have an implementation of operator==().

See also
indexOf(), lastIndexOf()
template<class T , int Prealloc>
int QVarLengthArray< T, Prealloc >::count ( ) const
inline

Equivalent to calling size().

See also
isEmpty(), resize()
template<class T , int Prealloc>
const_reverse_iterator QVarLengthArray< T, Prealloc >::crbegin ( ) const
inline

Returns a const STL-style reverse iterator pointing to the first item in the variable length array, in reverse order.

See also
begin(), rbegin(), rend()
template<class T , int Prealloc>
const_reverse_iterator QVarLengthArray< T, Prealloc >::crend ( ) const
inline

Returns a const STL-style reverse iterator pointing to one past the last item in the variable length array, in reverse order.

See also
end(), rend(), rbegin()
template<class T , int Prealloc>
T * QVarLengthArray< T, Prealloc >::data ( )
inline

Returns a pointer to the data stored in the array. The pointer can be used to access and modify the items in the array.

int *data = array.data();
for (int i = 0; i < 10; ++i) {
data[i] = 2 * i;
}

The pointer remains valid as long as the array is not reallocated. This method is mostly useful to pass an array to a method which accepts a raw C++ array.

See also
constData(), operator[]()
template<class T , int Prealloc>
const T * QVarLengthArray< T, Prealloc >::data ( ) const
inline

This is an overloaded method.

template<class T , int Prealloc>
bool QVarLengthArray< T, Prealloc >::empty ( ) const
inline

Returns true if the array has size 0, otherwise returns false.

Equivalent to calling isEmpty().

template<class T , int Prealloc>
iterator QVarLengthArray< T, Prealloc >::end ( )
inline

Returns an STL-style iterator pointing to the imaginary item after the last item in the array.

See also
begin(), constEnd()
template<class T , int Prealloc>
const_iterator QVarLengthArray< T, Prealloc >::end ( ) const
inline

Returns an STL-style iterator pointing to the imaginary item after the last item in the array.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::iterator QVarLengthArray< T, Prealloc >::erase ( const_iterator  begin,
const_iterator  end 
)

Removes all the items from begin up to (but not including) end. Returns an iterator to the same item that end referred to before the call.

template<class T , int Prealloc>
iterator QVarLengthArray< T, Prealloc >::erase ( const_iterator  pos)
inline

Removes the item pointed to by the iterator pos from the vector, and returns an iterator to the next item in the vector (which may be end()).

See also
insert(), remove()
template<class T , int Prealloc>
T & QVarLengthArray< T, Prealloc >::first ( )
inline

Returns a reference to the first item in the array. The array must not be empty. If the array can be empty, check isEmpty() before calling this method.

See also
last(), isEmpty()
template<class T , int Prealloc>
const T & QVarLengthArray< T, Prealloc >::first ( ) const
inline

Returns a reference to the first item in the array. The array must not be empty. If the array can be empty, check isEmpty() before calling this method.

template<class T , int Prealloc>
T & QVarLengthArray< T, Prealloc >::front ( )
inline

Equivalent to calling first().

template<class T , int Prealloc>
const T & QVarLengthArray< T, Prealloc >::front ( ) const
inline

Equivalent to calling first().

template<class T , int Prealloc>
int QVarLengthArray< T, Prealloc >::indexOf ( const T &  value,
int  from = 0 
) const

Returns the index position of the first occurrence of value in the array, searching forward from index position from. Returns -1 if no item matched.

This method requires the type T to support operator==().

See also
lastIndexOf(), contains()
template<class T , int Prealloc>
iterator QVarLengthArray< T, Prealloc >::insert ( const_iterator  before,
const T &  value 
)
inline

Inserts value in front of the item pointed to by the iterator before. Returns an iterator pointing at the inserted item.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc >::iterator QVarLengthArray< T, Prealloc >::insert ( const_iterator  before,
int  count,
const T &  value 
)

Inserts count copies of value in front of the item pointed to by the iterator before. Returns an iterator pointing at the first of the inserted items.

template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::insert ( int  index,
const T &  value 
)
inline

Inserts value at index position index in the array. If index is 0 the value is prepended to the vector. If index is equal to size() the value is appended to the vector.

For large arrays, this operation can be slow (linear time), because it requires moving all the items at indexes i and above by one position further in memory. If you want a container class that provides a fast insert() method use QLinkedList instead.

See also
remove()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::insert ( int  index,
int  count,
const T &  value 
)
inline

Inserts count copies of value at index position index in the array.

template<class T , int Prealloc>
bool QVarLengthArray< T, Prealloc >::isEmpty ( ) const
inline

Returns true if the array has size 0, otherwise returns false.

See also
size(), resize()
template<class T , int Prealloc>
T & QVarLengthArray< T, Prealloc >::last ( )
inline

Returns a reference to the last item in the array. The array must not be empty. If the array can be empty, check isEmpty() before calling this method.

See also
first(), isEmpty()
template<class T , int Prealloc>
const T & QVarLengthArray< T, Prealloc >::last ( ) const
inline

Returns a reference to the last item in the array. The array must not be empty. If the array can be empty, check isEmpty() before calling this method.

See also
first(), isEmpty()
template<class T , int Prealloc>
int QVarLengthArray< T, Prealloc >::lastIndexOf ( const T &  value,
int  from = -1 
) const

Returns the index position of the last occurrence of the value value in the array, searching backward from index position from. If from is -1 (the default), the search starts at the last item. Returns -1 if no item matched.

This method requires the type T to support operator==().

See also
indexOf(), contains()
template<class T , int Prealloc>
int QVarLengthArray< T, Prealloc >::length ( ) const
inline

Equivalent to calling size().

See also
isEmpty(), resize()
template<class T , int Prealloc>
QVarLengthArray< T, Prealloc > & QVarLengthArray< T, Prealloc >::operator+= ( const T &  value)
inline

Appends value to the array and returns a reference to this vector.

See also
append(), operator>>()
template<class T , int Prealloc>
QVarLengthArray< T, Prealloc > & QVarLengthArray< T, Prealloc >::operator<< ( const T &  value)
inline

Appends value to the array and returns a reference to this vector.

See also
append(), operator+=()
template<class T , int Prealloc>
QVarLengthArray< T, Prealloc > & QVarLengthArray< T, Prealloc >::operator= ( const QVarLengthArray< T, Prealloc > &  other)
inline

Assigns other to this array and returns a reference to this array.

template<class T , int Prealloc>
QVarLengthArray< T, Prealloc > & QVarLengthArray< T, Prealloc >::operator= ( std::initializer_list< T >  list)
inline

Assigns the values of list to this array, and returns a reference to this array.

template<class T , int Prealloc>
T & QVarLengthArray< T, Prealloc >::operator[] ( int  index)
inline

Returns a reference to the item at index position index. The given index must be a valid index position in the array.

See also
at(), data()
template<class T , int Prealloc>
const T & QVarLengthArray< T, Prealloc >::operator[] ( int  index) const
inline

Equivalent to calling at[].

template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::pop_back ( )
inline

Equivalent to calling removeLast().

template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::prepend ( const T &  value)
inline

Inserts value at the beginning of the array. This is the same as vector.insert(0, value).

For large arrays, this operation can be slow (linear time), because it requires moving all the items in the array by one position further in memory. If you want a container class that provides a fast prepend() method use QList or QLinkedList instead.

See also
append(), insert()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::push_back ( const T &  value)
inline

Appends value to the array, extending the array if necessary.

template<class T , int Prealloc>
reverse_iterator QVarLengthArray< T, Prealloc >::rbegin ( )
inline

Returns a STL-style reverse iterator pointing to the first item in the variable length array, in reverse order.

See also
begin(), crbegin(), rend()
template<class T , int Prealloc>
const_reverse_iterator QVarLengthArray< T, Prealloc >::rbegin ( ) const
inline

Returns a STL-style reverse iterator pointing to the first item in the variable length array, in reverse order.

See also
begin(), crbegin(), rend()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::remove ( int  index)
inline

Removes the element at index position index.

See also
insert(), replace()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::remove ( int  index,
int  count 
)
inline

Removes count elements from the middle of the array, starting at index position i.

See also
insert(), replace()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::removeLast ( )
inline

Decreases the size of the array by one. The allocated size is not changed.

See also
append()
template<class T , int Prealloc>
reverse_iterator QVarLengthArray< T, Prealloc >::rend ( )
inline

Returns a STL-style reverse iterator pointing to one past the last item in the variable length array, in reverse order.

See also
end(), crend(), rbegin()
template<class T , int Prealloc>
const_reverse_iterator QVarLengthArray< T, Prealloc >::rend ( ) const
inline

Returns a STL-style reverse iterator pointing to one past the last item in the variable length array, in reverse order.

See also
end(), crend(), rbegin()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::replace ( int  index,
const T &  value 
)
inline

Replaces the item at index position index with value. The index must be a valid position in the array.

See also
operator[](), remove()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::reserve ( int  size)

Attempts to allocate memory for at least size elements. If you know in advance how large the array can get, you can call this method and if you call resize() often, you are likely to get better performance. If size is an underestimate, the worst that will happen is that the QVarLengthArray will be a bit slower.

The purpose of this method is to provide a means of fine tuning QVarLengthArray's memory usage. This method is rarely used. If you want to know how many items are in the array, call size().

See also
capacity()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::resize ( int  size)

Sets the size of the array to size. If size is greater than the current size, elements are added to the end. If size is less than the current size, elements are removed from the end.

The new elements are default initialized. Refer to default constructed elements for additional information.

See also
size()
template<class T , int Prealloc>
int QVarLengthArray< T, Prealloc >::size ( ) const
inline

Returns the number of elements in the array.

See also
isEmpty(), resize()
template<class T , int Prealloc>
void QVarLengthArray< T, Prealloc >::squeeze ( )

Releases any memory not required to store the items. If the container can fit its storage on the stack allocation, it will free the heap allocation and copy the elements back to the stack.

The purpose of this method is to provide a means of fine tuning QVarLengthArray's memory usage. This method is rarely used.

See also
reserve(), capacity(), resize()
template<class T , int Prealloc>
T QVarLengthArray< T, Prealloc >::value ( int  index) const

Returns the value at index position index.

If the index i is out of bounds the method returns a default initialized object. Refer to default constructed elements for additional information.

If index is guaranteed to be within bounds use at() instead, which is slightly faster.

See also
at(), operator[]()
template<class T , int Prealloc>
T QVarLengthArray< T, Prealloc >::value ( int  index,
const T &  defaultValue 
) const

If the index index is out of bounds, the method returns defaultValue.

Friends And Related Function Documentation

bool operator!= ( const QVarLengthArray< T, Prealloc1 > &  left,
const QVarLengthArray< T, Prealloc2 > &  right 
)
related

Returns true if the two arrays, specified by left and right, are not equal.

Two arrays are considered equal if they contain the same values in the same order. This method requires the value type to have an implementation of operator==().

See also
operator==()
bool operator== ( const QVarLengthArray< T, Prealloc1 > &  left,
const QVarLengthArray< T, Prealloc2 > &  right 
)
related

Returns true if the two arrays, specified by left and right, are equal.

Two arrays are considered equal if they contain the same values in the same order. This method requires the value type to have an implementation of operator==().

See also
operator!=()