All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
VtArray< ELEM > Class Template Reference

Represents an arbitrary dimensional rectangular container class. More...

Inherits Vt_ArrayBase.

Public Types

typedef ELEM ElementType
 Type this array holds. More...
 
typedef ELEM value_type
 
typedef PointerIterator
< ElementType
iterator
 Iterator type. More...
 
typedef PointerIterator< const
ElementType
const_iterator
 Const iterator type. More...
 
typedef
boost::reverse_iterator
< iterator
reverse_iterator
 Reverse iterator type. More...
 
typedef
boost::reverse_iterator
< const_iterator
const_reverse_iterator
 Reverse const iterator type. More...
 
typedef PointerIterator
< ElementType >::reference 
reference
 Reference type. More...
 
typedef PointerIterator< const
ElementType >::reference 
const_reference
 Const reference type. More...
 
typedef PointerIterator
< ElementType >::pointer 
pointer
 Pointer type. More...
 
typedef PointerIterator< const
ElementType >::pointer 
const_pointer
 Const pointer type. More...
 

Public Member Functions

 VtArray ()
 Create an empty array. More...
 
template<typename LegacyInputIterator >
 VtArray (LegacyInputIterator first, LegacyInputIterator last, typename std::enable_if< !std::is_integral< LegacyInputIterator >::value, void >::type *=nullptr)
 Create an array from a pair of iterators. More...
 
 VtArray (Vt_ArrayForeignDataSource *foreignSrc, ElementType *data, size_t size, bool addRef=true)
 Create an array with foreign source. More...
 
 VtArray (VtArray const &other)
 Copy other. The new array shares underlying data with other. More...
 
 VtArray (VtArray &&other)
 Move from other. More...
 
 VtArray (std::initializer_list< ELEM > initializerList)
 Initialize array from the contents of a initializerList. More...
 
VtArrayoperator= (VtArray const &other)
 Copy assign from other. More...
 
VtArrayoperator= (VtArray &&other)
 Move assign from other. More...
 
VtArrayoperator= (std::initializer_list< ELEM > initializerList)
 Replace current array contents with those in initializerList. More...
 
 VtArray (size_t n, value_type const &value=value_type())
 Create an array filled with n copies of value. More...
 
iterator begin ()
 Return a non-const iterator to the start of the array. More...
 
iterator end ()
 Returns a non-const iterator to the end of the array. More...
 
const_iterator begin () const
 Return a const iterator to the start of the array. More...
 
const_iterator end () const
 Return a const iterator to the end of the array. More...
 
const_iterator cbegin () const
 Return a const iterator to the start of the array. More...
 
const_iterator cend () const
 Return a const iterator to the end of the array. More...
 
reverse_iterator rbegin ()
 Return a non-const reverse iterator to the end of the array. More...
 
reverse_iterator rend ()
 Return a reverse iterator to the start of the array. More...
 
const_reverse_iterator rbegin () const
 Return a const reverse iterator to the end of the array. More...
 
const_reverse_iterator rend () const
 Return a const reverse iterator to the start of the array. More...
 
const_reverse_iterator crbegin () const
 Return a const reverse iterator to the end of the array. More...
 
const_reverse_iterator crend () const
 Return a const reverse iterator to the start of the array. More...
 
pointer data ()
 Return a non-const pointer to this array's data. More...
 
const_pointer data () const
 Return a const pointer to this array's data. More...
 
const_pointer cdata () const
 Return a const pointer to the data held by this array. More...
 
void push_back (ElementType const &elem)
 Append an element to array. More...
 
void pop_back ()
 Remove the last element of an array. More...
 
size_t size () const
 Return the total number of elements in this array. More...
 
size_t capacity () const
 Return the number of items this container can grow to hold without triggering a (re)allocation. More...
 
bool empty () const
 Return true if this array contains no elements, false otherwise. More...
 
void reserve (size_t num)
 Ensure enough memory is allocated to hold num elements. More...
 
reference front ()
 Return a non-const reference to the first element in this array. More...
 
const_reference front () const
 Return a const reference to the first element in this array. More...
 
reference back ()
 Return a reference to the last element in this array. More...
 
const_reference back () const
 Return a const reference to the last element in this array. More...
 
void resize (size_t newSize)
 Resize this array. More...
 
void clear ()
 Equivalent to resize(0). More...
 
template<class ForwardIter >
void assign (ForwardIter first, ForwardIter last)
 Assign array contents. More...
 
void assign (size_t n, const value_type &fill)
 Assign array contents. More...
 
void assign (std::initializer_list< ELEM > initializerList)
 Assign array contents via intializer list Equivalent to: More...
 
void swap (VtArray &other)
 Swap the contents of this array with other. More...
 
ElementTypeoperator[] (size_t index)
 Allows usage of [i]. More...
 
ElementType const & operator[] (size_t index) const
 Allows usage of [i]. More...
 
bool IsIdentical (VtArray const &other) const
 Tests if two arrays are identical, i.e. More...
 
bool operator== (VtArray const &other) const
 Tests two arrays for equality. See also IsIdentical(). More...
 
bool operator!= (VtArray const &other) const
 Tests two arrays for inequality. More...
 
Vt_ShapeData const * _GetShapeData () const
 
Vt_ShapeData * _GetShapeData ()
 

Friends

std::ostream & operator<< (std::ostream &out, const VtArray &self)
 Outputs a comma-separated list of the values in the array. More...
 
void swap (VtArray &lhs, VtArray &rhs)
 Swap array contents. More...
 

Detailed Description

template<typename ELEM>
class VtArray< ELEM >

Represents an arbitrary dimensional rectangular container class.

Originally, VtArray was built to mimic the arrays in menv2x's MDL language, but since VtArray has typed elements, the multidimensionality has found little use. For example, if you have only scalar elements, then to represent a list of vectors you need an two dimensional array. To represent a list of matrices you need a three dimensional array. However with VtArray<GfVec3d> and VtArray<GfMatrix4d>, the VtArray is one dimensional, the extra dimensions are encoded in the element types themselves.

For this reason, VtArray has been moving toward being more like std::vector, and it now has much of std::vector's API, but there are still important differences.

First, VtArray shares data between instances using a copy-on-write scheme. This means that making copies of VtArray instances is cheap: it only copies the pointer to the data. But on the other hand, invoking any non-const member function will incur a copy of the underlying data if it is not uniquely owned. For example, assume 'a' and 'b' are VtArray<int>:

* a = b; // No copy; a and b now share ownership of underlying data.
* a[0] = 123; // A copy is incurred, to detach a's data from b.
* // a and b no longer share data.
* a[1] = 234; // No copy: a's data is uniquely owned by a.
*

Note that since all non-const member functions will potentially cause a copy, it's possible to accidentally incur a copy even when unintended, or when no actual data mutation occurs. For example:

* int sum = 0;
* for (VtArray<int>::iterator i = a.begin(), end = a.end(); i != end; ++i) {
* sum += *i;
* }
*

Invoking a.begin() here will incur a copy if a's data is shared. This is required since it's possible to mutate the data through the returned iterator, even though the subsequent code doesn't do any mutation. This can be avoided by explicitly const-iterating like the following:

* int sum = 0;
* for (VtArray<int>::const_iterator i = a.cbegin(), end = a.cend(); i != end; ++i) {
* sum += *i;
* }
*

Definition at line 193 of file array.h.

Member Typedef Documentation

typedef ELEM ElementType

Type this array holds.

Definition at line 197 of file array.h.

Constructor & Destructor Documentation

VtArray ( )
inline

Create an empty array.

Definition at line 243 of file array.h.

VtArray ( LegacyInputIterator  first,
LegacyInputIterator  last,
typename std::enable_if< !std::is_integral< LegacyInputIterator >::value, void >::type *  = nullptr 
)
inline

Create an array from a pair of iterators.

Equivalent to:

* v.assign(first, last);
*

Note we use enable_if with a dummy parameter here to avoid clashing with our other constructor with the following signature:

VtArray(size_t n, value_type const &value = value_type())

Definition at line 258 of file array.h.

VtArray ( Vt_ArrayForeignDataSource *  foreignSrc,
ElementType data,
size_t  size,
bool  addRef = true 
)
inline

Create an array with foreign source.

Definition at line 267 of file array.h.

VtArray ( VtArray< ELEM > const &  other)
inline

Copy other. The new array shares underlying data with other.

Definition at line 278 of file array.h.

VtArray ( VtArray< ELEM > &&  other)
inline

Move from other.

The new array takes ownership of other's underlying data.

Definition at line 293 of file array.h.

VtArray ( std::initializer_list< ELEM >  initializerList)
inline

Initialize array from the contents of a initializerList.

Definition at line 299 of file array.h.

VtArray ( size_t  n,
value_type const &  value = value_type() 
)
inlineexplicit

Create an array filled with n copies of value.

Definition at line 333 of file array.h.

Member Function Documentation

bool IsIdentical ( VtArray< ELEM > const &  other) const
inline

Tests if two arrays are identical, i.e.

that they share the same underlying copy-on-write data. See also operator==().

Definition at line 605 of file array.h.

bool operator!= ( VtArray< ELEM > const &  other) const
inline

Tests two arrays for inequality.

Definition at line 620 of file array.h.

VtArray& operator= ( VtArray< ELEM > const &  other)
inline

Copy assign from other.

This array shares underlying data with other.

Definition at line 306 of file array.h.

VtArray& operator= ( VtArray< ELEM > &&  other)
inline

Move assign from other.

This array takes ownership of other's underlying data.

Definition at line 316 of file array.h.

VtArray& operator= ( std::initializer_list< ELEM >  initializerList)
inline

Replace current array contents with those in initializerList.

Definition at line 327 of file array.h.

bool operator== ( VtArray< ELEM > const &  other) const
inline

Tests two arrays for equality. See also IsIdentical().

Definition at line 613 of file array.h.

ElementType& operator[] ( size_t  index)
inline

Allows usage of [i].

Definition at line 594 of file array.h.

ElementType const& operator[] ( size_t  index) const
inline

Allows usage of [i].

Definition at line 599 of file array.h.

Friends And Related Function Documentation

std::ostream& operator<< ( std::ostream &  out,
const VtArray< ELEM > &  self 
)
friend

Outputs a comma-separated list of the values in the array.

Definition at line 660 of file array.h.

void swap ( VtArray< ELEM > &  lhs,
VtArray< ELEM > &  rhs 
)
friend

Swap array contents.

Definition at line 667 of file array.h.


The documentation for this class was generated from the following file: