 |
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... | |
| 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... | |
| VtArray & | operator= (VtArray const &other) |
Copy assign from other. More... | |
| VtArray & | operator= (VtArray &&other) |
Move assign from other. More... | |
| VtArray & | operator= (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... | |
| ElementType & | operator[] (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... | |
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>:
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:
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:
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:
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.
| typedef ELEM ElementType |
|
inline |
Create an array from a pair of iterators.
Equivalent to:
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())
|
inline |
|
inline |
|
inlineexplicit |
|
inlineexplicit |
|
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.
|
inline |
Tests if two arrays are identical, i.e.
that they share the same underlying copy-on-write data. See also operator==().
|
inline |
|
inline |
|
inline |
Tests two arrays for equality. See also IsIdentical().
|
inline |
|
inline |
|
friend |
1.8.5 
