This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
VtArray< ELEM > Class Template Reference

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

#include <array.h>

Inherits Vt_ArrayBase.

Public Types

typedef ELEM ElementType
 Type this array holds.
 
typedef ELEM value_type
 
using iterator = ElementType *
 Iterator type.
 
using const_iterator = ElementType const *
 Const iterator type.
 
typedef std::reverse_iterator< iteratorreverse_iterator
 Reverse iterator type.
 
typedef std::reverse_iterator< const_iteratorconst_reverse_iterator
 Reverse const iterator type.
 
typedef ElementTypereference
 Reference type.
 
typedef ElementType const & const_reference
 Const reference type.
 
typedef ElementTypepointer
 Pointer type.
 
typedef ElementType const * const_pointer
 Const pointer type.
 

Public Member Functions

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

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;
}
ElementType * iterator
Iterator type.
Definition: array.h:222
iterator end()
Returns a non-const iterator to the end of the array.
Definition: array.h:366

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;
}
ElementType const * const_iterator
Const iterator type.
Definition: array.h:224

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

Member Typedef Documentation

◆ ElementType

typedef ELEM ElementType

Type this array holds.

Definition at line 215 of file array.h.

◆ value_type

typedef ELEM value_type

Definition at line 216 of file array.h.

Constructor & Destructor Documentation

◆ VtArray() [1/8]

VtArray ( )
inline

Create an empty array.

Definition at line 243 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);
Represents an arbitrary dimensional rectangular container class.
Definition: array.h:211
std::enable_if<!std::is_integral< ForwardIter >::value >::type assign(ForwardIter first, ForwardIter last)
Assign array contents.
Definition: array.h:726

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() [3/8]

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() [4/8]

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() [5/8]

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() [6/8]

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

Initialize array from the contents of a initializerList.

Definition at line 299 of file array.h.

◆ VtArray() [7/8]

VtArray ( size_t  n)
inlineexplicit

Create an array filled with n value-initialized elements.

Definition at line 305 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 311 of file array.h.

◆ ~VtArray()

~VtArray ( )
inline

Definition at line 344 of file array.h.

Member Function Documentation

◆ _GetShapeData() [1/2]

Vt_ShapeData * _GetShapeData ( )
inline

Definition at line 808 of file array.h.

◆ _GetShapeData() [2/2]

Vt_ShapeData const * _GetShapeData ( ) const
inline

Definition at line 805 of file array.h.

◆ 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 354 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 784 of file array.h.

◆ operator!=()

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

Tests two arrays for inequality.

Definition at line 799 of file array.h.

◆ operator=() [1/3]

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

Replace current array contents with those in initializerList.

Definition at line 339 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 328 of file array.h.

◆ operator=() [3/3]

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

Copy assign from other.

This array shares underlying data with other.

Definition at line 318 of file array.h.

◆ operator==()

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

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

Definition at line 792 of file array.h.

◆ operator[]() [1/2]

ElementType & operator[] ( size_t  index)
inline

Allows usage of [i].

Definition at line 773 of file array.h.

◆ operator[]() [2/2]

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

Allows usage of [i].

Definition at line 778 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 825 of file array.h.

◆ swap

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

Swap array contents.

Definition at line 832 of file array.h.


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