Simbody  3.7
SimTK::ArrayViewConst_< T, X > Class Template Reference

This Array_ helper class is the base class for ArrayView_ which is the base class for Array_; here we provide only the minimal read-only "const" functionality required by any Array_ object, and shallow copy semantics. More...

+ Inheritance diagram for SimTK::ArrayViewConst_< T, X >:

Public Types

Typedefs

Types required of STL containers, plus index_type which is an extension, and packed_size_type which is an implementation detail.

typedef T value_type
 The type of object stored in this container. More...
 
typedef X index_type
 The index type (an extension). More...
 
typedef T * pointer
 A writable pointer to a value_type. More...
 
typedef const T * const_pointer
 A const pointer to a value_type. More...
 
typedef T & reference
 A writable value_type reference. More...
 
typedef const T & const_reference
 A const value_type reference. More...
 
typedef T * iterator
 A writable iterator for this container (same as pointer here). More...
 
typedef const T * const_iterator
 A const iterator for this container (same as const_pointer here). More...
 
typedef std::reverse_iterator< iteratorreverse_iterator
 A writable reverse iterator for this container. More...
 
typedef std::reverse_iterator< const_iteratorconst_reverse_iterator
 A const reverse iterator for this container. More...
 
typedef ArrayIndexTraits< X >::size_type size_type
 An integral type suitable for all indices and sizes for this array. More...
 
typedef ArrayIndexTraits< X >::difference_type difference_type
 A signed integral type that can represent the difference between any two legitimate index values for this array. More...
 
typedef ArrayIndexPackType< size_type >::packed_size_type packed_size_type
 The integral type we actually use internally to store size_type values. More...
 

Public Member Functions

Construction, conversion, and destruction

Constructors here are limited to those that don't allocate new data, and can only accept const data to reference.

Copy assignment is suppressed.

 ArrayViewConst_ ()
 Default constructor allocates no heap space and is very fast. More...
 
 ArrayViewConst_ (const ArrayViewConst_ &src)
 Copy constructor is shallow; the constructed const array object will be referencing the original source data. More...
 
 ArrayViewConst_ (const T *first, const T *last1)
 Construct an ArrayViewConst_<T> by referencing (sharing) a given range of const data [first,last1), without copying that data. More...
 
template<class A >
 ArrayViewConst_ (const std::vector< T, A > &src)
 Construct a ArrayViewConst_<T> by referencing (sharing) the data in a const std::vector<T>, without copying the data; this is also an implicit conversion. More...
 
 operator const ArrayView_< T, X > & () const
 This is an implicit conversion to const ArrayView_<T,X>&, which is harmless since the const result won't permit writing on the elements. More...
 
 operator const Array_< T, X > & () const
 This is an implicit conversion to const Array_<T,X>&, which is harmless since the const result can't be used to write on or resize the data. More...
 
void disconnect ()
 Disconnect this array handle from any data to which it refers, restoring it to the condition it would be in if it had just been default-constructed. More...
 
 ~ArrayViewConst_ ()
 The destructor just disconnects the array view handle from its data; see disconnect() for more information. More...
 
Size and capacity

These methods examine the number of elements (size) or the amount of allocated heap space (capacity).

See the derived Array_<T,X> class for methods that can change the size or capacity.

size_type size () const
 Return the current number of elements stored in this array. More...
 
size_type max_size () const
 Return the maximum allowable size for this array. More...
 
bool empty () const
 Return true if there are no elements currently stored in this array. More...
 
size_type capacity () const
 Return the number of elements this array can currently hold without requiring reallocation. More...
 
size_type allocated () const
 Return the amount of heap space owned by this array; this is the same as capacity() for owner arrays but is zero for non-owners. More...
 
bool isOwner () const
 Does this array own the data to which it refers? If not, it can't be resized, and the destructor will not free any heap space nor call any element destructors. More...
 
Read-only element access

These methods provide read-only (const) access to individual elements that are currently present in the array.

The derived ArrayView_<T,X> class adds the non-const versions of these methods.

const T & operator[] (index_type i) const
 Select an element by its index, returning a const reference. More...
 
const T & at (index_type i) const
 Same as operator[] but always range-checked, even in a Release build. More...
 
const T & getElt (index_type i) const
 Same as the const form of operator[]; exists to provide a non-operator method for element access in case that's needed. More...
 
const T & front () const
 Return a const reference to the first element in this array, which must not be empty (we'll check in a Debug build but not Release). More...
 
const T & back () const
 Return a const reference to the last element in this array, which must not be empty (we'll check in a Debug build but not Release). More...
 
ArrayViewConst_ operator() (index_type index, size_type length) const
 Select a contiguous subarray of the elements of this array and create another ArrayViewConst_ that refers only to those element (without copying). More...
 
ArrayViewConst_ getSubArray (index_type index, size_type length) const
 Same as const form of operator()(index,length); exists to provide non-operator access to that functionality in case it is needed. More...
 

Related Functions

(Note that these are not member functions.)

template<class T , class X >
Xml::Element toXmlElement (const ArrayViewConst_< T, X > &thing, const std::string &name="")
 Partial specialization for XML serialization of ArrayViewConst_ objects. More...
 

Iterators (const only)

These methods deal in iterators, which are STL generalized pointers.

For this class, iterators are just ordinary const pointers to T, and you may depend on that. By necessity, reverse iterators can't be just pointers; however, they contain an ordinary iterator (i.e. a pointer) that can be obtained by calling the reverse iterator's base() method.

const T * cbegin () const
 Return a const pointer to the first element of this array if any, otherwise cend(), which may be null (0) in that case but does not have to be. More...
 
const T * cend () const
 Return a const pointer to what would be the element just after the last one in the array; this may be null (0) if there are no elements but doesn't have to be. More...
 
const T * begin () const
 The const version of begin() is the same as cbegin(). More...
 
const T * end () const
 The const version of end() is the same as cend(). More...
 
const_reverse_iterator crbegin () const
 Return a const reverse iterator pointing to the last element in the array or crend() if the array is empty. More...
 
const_reverse_iterator crend () const
 Return the past-the-end reverse iterator that tests equal to a reverse iterator that has been incremented past the front of the array. More...
 
const_reverse_iterator rbegin () const
 The const version of rbegin() is the same as crbegin(). More...
 
const_reverse_iterator rend () const
 The const version of rend() is the same as crend(). More...
 
const T * cdata () const
 Return a const pointer to the first element of the array, or possibly (but not necessarily) null (0) if the array is empty. More...
 
const T * data () const
 The const version of the data() method is identical to cdata(). More...
 

Detailed Description

template<class T, class X>
class SimTK::ArrayViewConst_< T, X >

This Array_ helper class is the base class for ArrayView_ which is the base class for Array_; here we provide only the minimal read-only "const" functionality required by any Array_ object, and shallow copy semantics.

The ability to write is added by the ArrayView_ class, and the additional ability to reallocate, insert, erase, etc. is added by the Array_ class.

This class is particularly useful for recasting existing const data into a const Array_ without copying. For example a const std::vector can be passed to a const Array& argument by an implicit, near-zero cost conversion to an ArrayViewConst_ which can then convert to a const Array&.

An ArrayViewConst_ is given all the data it is going to have at the time it is constructed (except when it is being accessed from the derived Array_ class that has more capability). The contents and size of a ArrayViewConst_ cannot be changed after construction. In particular, the default copy assignment operator is suppressed. The destructor simply disconnects the ArrayViewConst_ handle from the data it was referencing; no element destruction or heap deallocation occurs.

Template Parameters
TThe type of object to be stored in this container.
XThe type to be used for indexing this container, with default unsigned (not size_t). Any integral type may be used, as well as user types that satisfy the requirements discussed with class ArrayIndexTraits.
See also
Array_, ArrayView_, ArrayIndexTraits

Member Typedef Documentation

◆ value_type

template<class T, class X>
typedef T SimTK::ArrayViewConst_< T, X >::value_type

The type of object stored in this container.

◆ index_type

template<class T, class X>
typedef X SimTK::ArrayViewConst_< T, X >::index_type

The index type (an extension).

◆ pointer

template<class T, class X>
typedef T* SimTK::ArrayViewConst_< T, X >::pointer

A writable pointer to a value_type.

◆ const_pointer

template<class T, class X>
typedef const T* SimTK::ArrayViewConst_< T, X >::const_pointer

A const pointer to a value_type.

◆ reference

template<class T, class X>
typedef T& SimTK::ArrayViewConst_< T, X >::reference

A writable value_type reference.

◆ const_reference

template<class T, class X>
typedef const T& SimTK::ArrayViewConst_< T, X >::const_reference

A const value_type reference.

◆ iterator

template<class T, class X>
typedef T* SimTK::ArrayViewConst_< T, X >::iterator

A writable iterator for this container (same as pointer here).

◆ const_iterator

template<class T, class X>
typedef const T* SimTK::ArrayViewConst_< T, X >::const_iterator

A const iterator for this container (same as const_pointer here).

◆ reverse_iterator

template<class T, class X>
typedef std::reverse_iterator<iterator> SimTK::ArrayViewConst_< T, X >::reverse_iterator

A writable reverse iterator for this container.

◆ const_reverse_iterator

template<class T, class X>
typedef std::reverse_iterator<const_iterator> SimTK::ArrayViewConst_< T, X >::const_reverse_iterator

A const reverse iterator for this container.

◆ size_type

template<class T, class X>
typedef ArrayIndexTraits<X>::size_type SimTK::ArrayViewConst_< T, X >::size_type

An integral type suitable for all indices and sizes for this array.

◆ difference_type

template<class T, class X>
typedef ArrayIndexTraits<X>::difference_type SimTK::ArrayViewConst_< T, X >::difference_type

A signed integral type that can represent the difference between any two legitimate index values for this array.

◆ packed_size_type

template<class T, class X>
typedef ArrayIndexPackType<size_type>::packed_size_type SimTK::ArrayViewConst_< T, X >::packed_size_type

The integral type we actually use internally to store size_type values.

Constructor & Destructor Documentation

◆ ArrayViewConst_() [1/4]

template<class T, class X>
SimTK::ArrayViewConst_< T, X >::ArrayViewConst_ ( )
inline

Default constructor allocates no heap space and is very fast.

◆ ArrayViewConst_() [2/4]

template<class T, class X>
SimTK::ArrayViewConst_< T, X >::ArrayViewConst_ ( const ArrayViewConst_< T, X > &  src)
inline

Copy constructor is shallow; the constructed const array object will be referencing the original source data.

However, if the source is zero length, this will result in a default-constructed array view handle with a null data pointer, even if the source had some unused data allocated.

Parameters
[in]srcThe object whose data will be referenced.
Complexity:
Constant time; extremely fast.

◆ ArrayViewConst_() [3/4]

template<class T, class X>
SimTK::ArrayViewConst_< T, X >::ArrayViewConst_ ( const T *  first,
const T *  last1 
)
inline

Construct an ArrayViewConst_<T> by referencing (sharing) a given range of const data [first,last1), without copying that data.

This will work as long as the size of the source data does not exceed the array's max_size. The resulting object is not resizeable but can be used to read elements of the original data. This will becomes invalid if the original data is destructed or resized, but there is no way for the ArrayViewConst_ class to detect that.

Parameters
[in]first
A pointer to the first data element to be referenced.
[in]last1
A pointer to the position one element past the last one in the range to be referenced.
Remarks
  • If the source data is empty, the resulting ArrayViewConst_ will also be empty and will look as though it had been default-constructed.
  • You can break the connection between the array handle and the data it was constructed from by calling disconnect().
Precondition
first <= last1, last1-first <= max_size()
Complexity:
Dirt cheap. There will be no construction, destruction, or heap allocation performed.
See also
disconnect()

◆ ArrayViewConst_() [4/4]

template<class T, class X>
template<class A >
SimTK::ArrayViewConst_< T, X >::ArrayViewConst_ ( const std::vector< T, A > &  src)
inline

Construct a ArrayViewConst_<T> by referencing (sharing) the data in a const std::vector<T>, without copying the data; this is also an implicit conversion.

This will work as long as the size of the vector does not exceed the array's max_size. The resulting array object is not resizeable but can be used to read elements of the original std::vector. The array becomes invalid if the original std::vector is destructed or resized, but there is no way for the array class to detect that.

Parameters
[in]srcThe std::vector<T> whose data will be referenced by the constructed ArrayViewConst_ handle.
Remarks
  • If the source std::vector is empty, the resulting array will also be empty and will look as though it had been default-constructed. It will therefore not have any connection to the source vector.
  • This is quite dangerous to use since the connection between the array and the vector is tenuous and subject to the vector remaining untouched during the lifetime of the array handle. There is no reference counting; destructing the vector leaves the array referring to garbage. Be careful!
  • You can break the connection between the array view and the vector it was constructed from by calling disconnect().
Precondition
src.size() <= max_size()
Complexity:
Dirt cheap. There will be no construction, destruction, or heap allocation performed.
See also
disconnect()

◆ ~ArrayViewConst_()

template<class T, class X>
SimTK::ArrayViewConst_< T, X >::~ArrayViewConst_ ( )
inline

The destructor just disconnects the array view handle from its data; see disconnect() for more information.

See also
disconnect()

Member Function Documentation

◆ operator const ArrayView_< T, X > &()

template<class T, class X>
SimTK::ArrayViewConst_< T, X >::operator const ArrayView_< T, X > & ( ) const
inline

This is an implicit conversion to const ArrayView_<T,X>&, which is harmless since the const result won't permit writing on the elements.

◆ operator const Array_< T, X > &()

template<class T, class X>
SimTK::ArrayViewConst_< T, X >::operator const Array_< T, X > & ( ) const
inline

This is an implicit conversion to const Array_<T,X>&, which is harmless since the const result can't be used to write on or resize the data.

◆ disconnect()

template<class T, class X>
void SimTK::ArrayViewConst_< T, X >::disconnect ( )
inline

Disconnect this array handle from any data to which it refers, restoring it to the condition it would be in if it had just been default-constructed.

The data pointer will simply be set to null; we'll assume the owner will clean things up later. In either case the size() and capacity() will be zero after this call and data() will return null (0).

◆ size()

template<class T, class X>
size_type SimTK::ArrayViewConst_< T, X >::size ( ) const
inline

Return the current number of elements stored in this array.

◆ max_size()

template<class T, class X>
size_type SimTK::ArrayViewConst_< T, X >::max_size ( ) const
inline

Return the maximum allowable size for this array.

◆ empty()

template<class T, class X>
bool SimTK::ArrayViewConst_< T, X >::empty ( ) const
inline

Return true if there are no elements currently stored in this array.

This is equivalent to the tests begin()==end() or size()==0.

◆ capacity()

template<class T, class X>
size_type SimTK::ArrayViewConst_< T, X >::capacity ( ) const
inline

Return the number of elements this array can currently hold without requiring reallocation.

The value returned by capacity() is always greater than or equal to size(), even if the data is not owned by this array in which case we have capacity()==size() and the array is not reallocatable.

◆ allocated()

template<class T, class X>
size_type SimTK::ArrayViewConst_< T, X >::allocated ( ) const
inline

Return the amount of heap space owned by this array; this is the same as capacity() for owner arrays but is zero for non-owners.

Note
There is no equivalent of this method for std::vector.

◆ isOwner()

template<class T, class X>
bool SimTK::ArrayViewConst_< T, X >::isOwner ( ) const
inline

Does this array own the data to which it refers? If not, it can't be resized, and the destructor will not free any heap space nor call any element destructors.

If the array does not refer to any data it is considered to be an owner since it is resizeable.

Note
There is no equivalent of this method for std::vector.

◆ operator[]()

template<class T, class X>
const T& SimTK::ArrayViewConst_< T, X >::operator[] ( index_type  i) const
inline

Select an element by its index, returning a const reference.

Note that only a value of the array's templatized index type is allowed (default is unsigned). This will be range-checked in a Debug build but not in Release.

Precondition
0 <= i < size()
Complexity:
Constant time.

◆ at()

template<class T, class X>
const T& SimTK::ArrayViewConst_< T, X >::at ( index_type  i) const
inline

Same as operator[] but always range-checked, even in a Release build.

Precondition
0 <= i < size()
Complexity:
Constant time.

◆ getElt()

template<class T, class X>
const T& SimTK::ArrayViewConst_< T, X >::getElt ( index_type  i) const
inline

Same as the const form of operator[]; exists to provide a non-operator method for element access in case that's needed.

◆ front()

template<class T, class X>
const T& SimTK::ArrayViewConst_< T, X >::front ( ) const
inline

Return a const reference to the first element in this array, which must not be empty (we'll check in a Debug build but not Release).

Precondition
The array is not empty.
Complexity:
Constant time.

◆ back()

template<class T, class X>
const T& SimTK::ArrayViewConst_< T, X >::back ( ) const
inline

Return a const reference to the last element in this array, which must not be empty (we'll check in a Debug build but not Release).

Precondition
The array is not empty.
Complexity:
Constant time.

◆ operator()()

template<class T, class X>
ArrayViewConst_ SimTK::ArrayViewConst_< T, X >::operator() ( index_type  index,
size_type  length 
) const
inline

Select a contiguous subarray of the elements of this array and create another ArrayViewConst_ that refers only to those element (without copying).

Parameters
[in]indexThe index of the first element to be included in the subarray; this can be one past the end of the array if length is zero.
[in]lengthThe length of the subarray to be produced.
Returns
A new ArrayViewConst_<T,X> object referencing the original data.
Note
If length==0 the returned array will be in a default-constructed, all-zero and null state with no connection to the original data.
Precondition
index >= 0, length >= 0
index + length <= size()
We'll validate preconditions in Debug builds but not Release.
Complexity:
Dirt cheap; no element construction or destruction or heap allocation is required.

◆ getSubArray()

template<class T, class X>
ArrayViewConst_ SimTK::ArrayViewConst_< T, X >::getSubArray ( index_type  index,
size_type  length 
) const
inline

Same as const form of operator()(index,length); exists to provide non-operator access to that functionality in case it is needed.

◆ cbegin()

template<class T, class X>
const T* SimTK::ArrayViewConst_< T, X >::cbegin ( ) const
inline

Return a const pointer to the first element of this array if any, otherwise cend(), which may be null (0) in that case but does not have to be.

This method is from the C++11 standard; there is also an overloaded begin() from the original standard that returns a const pointer.

◆ cend()

template<class T, class X>
const T* SimTK::ArrayViewConst_< T, X >::cend ( ) const
inline

Return a const pointer to what would be the element just after the last one in the array; this may be null (0) if there are no elements but doesn't have to be.

This method is from the C++11 standard; there is also an overloaded end() from the original standard that returns a const pointer.

◆ begin()

template<class T, class X>
const T* SimTK::ArrayViewConst_< T, X >::begin ( ) const
inline

The const version of begin() is the same as cbegin().

◆ end()

template<class T, class X>
const T* SimTK::ArrayViewConst_< T, X >::end ( ) const
inline

The const version of end() is the same as cend().

◆ crbegin()

template<class T, class X>
const_reverse_iterator SimTK::ArrayViewConst_< T, X >::crbegin ( ) const
inline

Return a const reverse iterator pointing to the last element in the array or crend() if the array is empty.

◆ crend()

template<class T, class X>
const_reverse_iterator SimTK::ArrayViewConst_< T, X >::crend ( ) const
inline

Return the past-the-end reverse iterator that tests equal to a reverse iterator that has been incremented past the front of the array.

You cannot dereference this iterator.

◆ rbegin()

template<class T, class X>
const_reverse_iterator SimTK::ArrayViewConst_< T, X >::rbegin ( ) const
inline

The const version of rbegin() is the same as crbegin().

◆ rend()

template<class T, class X>
const_reverse_iterator SimTK::ArrayViewConst_< T, X >::rend ( ) const
inline

The const version of rend() is the same as crend().

◆ cdata()

template<class T, class X>
const T* SimTK::ArrayViewConst_< T, X >::cdata ( ) const
inline

Return a const pointer to the first element of the array, or possibly (but not necessarily) null (0) if the array is empty.

Note
cdata() is not in the C++11 standard although it would seem obvious in view of the cbegin() and cend() methods that had to be added. The C++11 overloaded const data() method is also available.

◆ data()

template<class T, class X>
const T* SimTK::ArrayViewConst_< T, X >::data ( ) const
inline

The const version of the data() method is identical to cdata().

Friends And Related Function Documentation

◆ toXmlElement()

template<class T , class X >
Xml::Element toXmlElement ( const ArrayViewConst_< T, X > &  thing,
const std::string &  name = "" 
)
related

Partial specialization for XML serialization of ArrayViewConst_ objects.

The output is identical for this class, or its derived classes ArrayView_ and Array_, although there are other signatures for those to ensure this method gets used. The result is a single element with tag word <Array> with the given name (if any) and a version number as attributes. Then each entry is a subelement, as produced by type T's toXmlElement() method.

Note that ArrayViewConst_ can't be a target for deserializaton since it is immutable.


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