Inherits Vt_ArrayBase.
|
| 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 .
|
|
VtArray & | operator= (VtArray const &other) |
| Copy assign from other .
|
|
VtArray & | operator= (VtArray &&other) |
| Move assign from other .
|
|
VtArray & | operator= (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 .
|
|
ElementType & | operator[] (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 () |
|
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;
a[0] = 123;
a[1] = 234;
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;
sum += *i;
}
ElementType * iterator
Iterator type.
iterator end()
Returns a non-const iterator to the end of the array.
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;
sum += *i;
}
ElementType const * const_iterator
Const iterator type.
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.
Definition at line 227 of file array.h.