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< ElementTypeiterator
 Iterator type. More...
 
typedef PointerIterator< const ElementTypeconst_iterator
 Const iterator type. More...
 
typedef boost::reverse_iterator< iteratorreverse_iterator
 Reverse iterator type. More...
 
typedef boost::reverse_iterator< const_iteratorconst_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...
 
 VtArray (size_t n)
 Create an array filled with n value-initialized elements. More...
 
 VtArray (size_t n, value_type const &value)
 Create an array filled with n copies of value. 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 const & AsConst () const noexcept
 Return *this as a const reference. 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...
 
template<typename... Args>
void emplace_back (Args &&... args)
 Initializes a new element at the end of the array. More...
 
void push_back (ElementType const &element)
 Appends an element at the end of the array. More...
 
void push_back (ElementType &&element)
 Appends an element at the end of the 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...
 
const_reference cfront () 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...
 
const_reference cback () const
 Return a const reference to the last element in this array. More...
 
void resize (size_t newSize)
 Resize this array. More...
 
template<class FillElemsFn >
void resize (size_t newSize, FillElemsFn &&fillElems)
 Resize this array. More...
 
void clear ()
 Equivalent to resize(0). More...
 
iterator erase (const_iterator pos)
 Removes a single element at pos from the array. More...
 
iterator erase (const_iterator first, const_iterator last)
 Remove a range of elements [first, last) from the array. More...
 
template<class ForwardIter >
std::enable_if<!std::is_integral< ForwardIter >::value >::type 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 a 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 and 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 incurs 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;
}

This can be quite subtle. In C++, calling a member function that has const and non-const overloads on a non-const object must invoke the non-const version, even if the const version would suffice. So something as simple this:

float x = array[123];

Invokes the non-const operator[] if array is non-const. That means this kind of benign looking code can cause a copy-on-write detachment of the entire array, and thus is not safe to invoke concurrently with any other member function. If we were building this class today we would make different choices about this API, but changing this now is a gargantuan task, so it remains.

So, it is best practice to ensure you use const VtArray, or const VtArray &, or VtArray::AsConst(), as well as the c-prefixed member functions like cbegin()/cend(), cfront()/cback() to avoid these pitfalls when your intent is not to mutate the array.

Regarding thread safety, for the same reasons spelled out above, all mutating member functions must be invoked exclusively to all other member functions, even if they are invoked in a way that does not mutate (as in the operator[] example above). This is the same general rule that the STL abides by.

Also, and again for the same reasons, all mutating member functions can invalidate iterators, even if the member functions are invoked in a way that does not mutate (as in the operator[] example above).

The TfEnvSetting 'VT_LOG_STACK_ON_ARRAY_DETACH_COPY' can be set to help determine where unintended copy-on-write detaches come from. When set, VtArray will log a stack trace for every copy-on-write detach that occurs.

Definition at line 229 of file array.h.

Member Typedef Documentation

◆ ElementType

typedef ELEM ElementType

Type this array holds.

Definition at line 233 of file array.h.

Constructor & Destructor Documentation

◆ VtArray() [1/8]

VtArray ( )
inline

Create an empty array.

Definition at line 279 of file array.h.

◆ VtArray() [2/8]

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 294 of file array.h.

◆ VtArray() [3/8]

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

Create an array with foreign source.

Definition at line 303 of file array.h.

◆ VtArray() [4/8]

VtArray ( VtArray< ELEM > const &  other)
inline

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

Definition at line 314 of file array.h.

◆ VtArray() [5/8]

VtArray ( VtArray< ELEM > &&  other)
inline

Move from other.

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

Definition at line 329 of file array.h.

◆ VtArray() [6/8]

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

Initialize array from the contents of a initializerList.

Definition at line 335 of file array.h.

◆ VtArray() [7/8]

VtArray ( size_t  n)
inlineexplicit

Create an array filled with n value-initialized elements.

Definition at line 341 of file array.h.

◆ VtArray() [8/8]

VtArray ( size_t  n,
value_type const &  value 
)
inlineexplicit

Create an array filled with n copies of value.

Definition at line 347 of file array.h.

Member Function Documentation

◆ AsConst()

VtArray const& AsConst ( ) const
inlinenoexcept

Return *this as a const reference.

This ensures that all operations on the result do not mutate and thus are safe to invoke concurrently with other non-mutating operations, and will never cause a copy-on-write detach.

Note that the return is a const reference to this object, so it is only valid within the lifetime of this array object. Take special care invoking AsConst() on VtArray temporaries/rvalues.

Definition at line 390 of file array.h.

◆ IsIdentical()

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 791 of file array.h.

◆ operator !=()

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

Tests two arrays for inequality.

Definition at line 806 of file array.h.

◆ operator=() [1/3]

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

Copy assign from other.

This array shares underlying data with other.

Definition at line 354 of file array.h.

◆ operator=() [2/3]

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

Move assign from other.

This array takes ownership of other's underlying data.

Definition at line 364 of file array.h.

◆ operator=() [3/3]

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

Replace current array contents with those in initializerList.

Definition at line 375 of file array.h.

◆ operator==()

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

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

Definition at line 799 of file array.h.

◆ operator[]() [1/2]

ElementType& operator[] ( size_t  index)
inline

Allows usage of [i].

Definition at line 780 of file array.h.

◆ operator[]() [2/2]

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

Allows usage of [i].

Definition at line 785 of file array.h.

Friends And Related Function Documentation

◆ operator<<

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 846 of file array.h.

◆ swap

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

Swap array contents.

Definition at line 853 of file array.h.


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