PCL
pcl::ReferenceSortedArray< T, A > Class Template Reference

Dynamic sorted array of pointers to objects providing direct iteration and element access by reference. More...

#include <ReferenceSortedArray.h>

+ Inheritance diagram for pcl::ReferenceSortedArray< T, A >:

Public Types

typedef array_implementation::allocator allocator
 
typedef ReferenceArray< T, A > array_implementation
 
typedef array_implementation::block_allocator block_allocator
 
typedef array_implementation::const_indirect_iterator const_indirect_iterator
 
typedef array_implementation::const_iterator const_iterator
 
typedef array_implementation::const_reverse_iterator const_reverse_iterator
 
typedef array_implementation::indirect_iterator indirect_iterator
 
typedef array_implementation::iterator iterator
 
typedef array_implementation::reverse_iterator reverse_iterator
 

Public Member Functions

 ReferenceSortedArray ()=default
 
 ReferenceSortedArray (size_type n, const T *p)
 
template<class FI >
 ReferenceSortedArray (FI i, FI j)
 
 ReferenceSortedArray (const ReferenceSortedArray &)=default
 
 ReferenceSortedArray (ReferenceSortedArray &&)=default
 
 ~ReferenceSortedArray ()
 
void Add (const ReferenceSortedArray &x)
 
void Add (const array_implementation &x)
 
const_iterator Add (const T *p, size_type n=1)
 
template<class FI >
void Add (FI i, FI j)
 
template<class F >
void Apply (F f) const
 
void Assign (const ReferenceSortedArray &x)
 
void Assign (const array_implementation &x)
 
void Assign (const T *p, size_type n=1)
 
template<class FI >
void Assign (FI i, FI j)
 
const_iterator At (size_type i) const
 
size_type Available () const
 
const_iterator Begin () const
 
const_iterator begin () const
 
size_type Capacity () const
 
void Clear ()
 
template<class C >
void CloneAssign (const C &x)
 
void CloneAssign (ReferenceSortedArray &x)
 
void CloneAssign (SortedArray< T, A > &x)
 
void CloneAssign (IndirectSortedArray< T, A > &x)
 
bool Contains (const T &v) const
 
bool Contains (const T *p) const
 
template<class BP >
bool Contains (const T &v, BP p) const
 
size_type Count (const T &v) const
 
size_type Count (const T *p) const
 
template<class BP >
size_type Count (const T &v, BP p) const
 
template<class UP >
size_type CountIf (UP p) const
 
void Destroy (iterator i, size_type n=1)
 
void Destroy (iterator i, iterator j)
 
void Destroy (const T &v)
 
template<class BP >
void Destroy (const T &v, BP p)
 
void Destroy ()
 
const_iterator End () const
 
const_iterator end () const
 
void EnsureUnique ()
 
void Fill (const T &v)
 
const T & First () const
 
template<class F >
const_iterator FirstThat (F f) const
 
const allocatorGetAllocator () const
 
uint64 Hash (uint64 seed=0) const
 
uint32 Hash32 (uint32 seed=0) const
 
uint64 Hash64 (uint64 seed=0) const
 
void Import (iterator i, iterator j)
 
bool IsAliasOf (const ReferenceSortedArray &x) const
 
bool IsEmpty () const
 
bool IsUnique () const
 
bool IsValid () const
 
const T & Last () const
 
template<class F >
const_iterator LastThat (F f) const
 
size_type Length () const
 
size_type LowerBound () const
 
const_iterator MaxItem () const
 
template<class BP >
const_iterator MaxItem (BP p) const
 
const_iterator MinItem () const
 
template<class BP >
const_iterator MinItem (BP p) const
 
iterator MutableAt (size_type i)
 
iterator MutableBegin ()
 
iterator MutableEnd ()
 
T & MutableFirst ()
 
iterator MutableIterator (const_iterator i)
 
T & MutableLast ()
 
reverse_iterator MutableReverseBegin ()
 
reverse_iterator MutableReverseEnd ()
 
const T & operator* () const
 
ReferenceSortedArrayoperator= (const ReferenceSortedArray &x)
 
ReferenceSortedArrayoperator= (ReferenceSortedArray &&x)
 
ReferenceSortedArrayoperator= (const array_implementation &x)
 
ReferenceSortedArrayoperator= (array_implementation &&x)
 
const T & operator[] (size_type i) const
 
indirect_iterator Release ()
 
void Remove (const_iterator i, size_type n=1)
 
void Remove (const_iterator i, const_iterator j)
 
void Remove (const T &v)
 
template<class BP >
void Remove (const T &v, BP p)
 
void RemovePointer (const T *p)
 
void Reserve (size_type n)
 
const_reverse_iterator ReverseBegin () const
 
const_reverse_iterator ReverseEnd () const
 
const_iterator Search (const T &v) const
 
const_iterator Search (const T *p) const
 
template<class BP >
const_iterator Search (const T &v, BP p) const
 
const_iterator SearchLast (const T &v) const
 
const_iterator SearchLast (const T *p) const
 
template<class BP >
const_iterator SearchLast (const T &v, BP p) const
 
void SetAllocator (const allocator &a)
 
void Shrink (size_type n=1)
 
size_type Size () const
 
void Sort ()
 
void Squeeze ()
 
template<class S >
S & ToCommaSeparated (S &s) const
 
template<class S >
S & ToNewLineSeparated (S &s) const
 
template<class S , typename SP >
S & ToSeparated (S &s, SP separator) const
 
template<class S , typename SP , class AF >
S & ToSeparated (S &s, SP separator, AF append) const
 
template<class S >
S & ToSpaceSeparated (S &s) const
 
template<class S >
S & ToTabSeparated (S &s) const
 
void Transfer (ReferenceSortedArray &x)
 
void Transfer (ReferenceSortedArray &&x)
 
void Transfer (array_implementation &x)
 
void Transfer (array_implementation &&x)
 
void Truncate (const_iterator i)
 
void UniquifyIterator (iterator &i)
 
void UniquifyIterators (iterator &i, iterator &j)
 
size_type UpperBound () const
 

Friends

bool operator< (const ReferenceSortedArray &x1, const ReferenceSortedArray &x2)
 
bool operator< (const ReferenceSortedArray &x1, const array_implementation &x2)
 
bool operator< (const array_implementation &x1, const ReferenceSortedArray &x2)
 
bool operator== (const ReferenceSortedArray &x1, const ReferenceSortedArray &x2)
 
bool operator== (const ReferenceSortedArray &x1, const array_implementation &x2)
 
bool operator== (const array_implementation &x1, const ReferenceSortedArray &x2)
 
void Swap (ReferenceSortedArray &x1, ReferenceSortedArray &x2)
 

Detailed Description

template<typename T, class A = StandardAllocator>
class pcl::ReferenceSortedArray< T, A >

ReferenceSortedArray is a generic, finite sorted sequence of pointers to objects, implemented as a reference-counted, dynamic array of pointers to T instances with automatic sorting of inserted array elements. The type A provides dynamic allocation for contiguous sequences of void* (StandardAllocator is used by default).

Ordering of array elements is implemented by indirection, that is, the pointed-to objects are compared for sorting, not the contained pointers.

Unlike IndirectArray and IndirectSortedArray, ReferenceSortedArray provides direct access to the objects pointed to by its contained pointers, including direct iteration through references instead of pointers. This makes ReferenceSortedArray a perfect replacement for SortedArray in cases where storing copies of objects is impractical or inviable; for example, when the objects to be stored are unique by nature. As a prerequisite for this functionality, ReferenceSortedArray, unlike IndirectSortedArray and IndirectArray, and like ReferenceArray, cannot contain null pointers.

See also
ReferenceArray, IndirectArray, IndirectSortedArray, Array, SortedArray, ReferenceCounter

Definition at line 100 of file ReferenceSortedArray.h.

Member Typedef Documentation

◆ allocator

template<typename T, class A = StandardAllocator>
typedef array_implementation::allocator pcl::ReferenceSortedArray< T, A >::allocator

#

Definition at line 116 of file ReferenceSortedArray.h.

◆ array_implementation

template<typename T, class A = StandardAllocator>
typedef ReferenceArray<T,A> pcl::ReferenceSortedArray< T, A >::array_implementation

#

Definition at line 106 of file ReferenceSortedArray.h.

◆ block_allocator

template<typename T, class A = StandardAllocator>
typedef array_implementation::block_allocator pcl::ReferenceSortedArray< T, A >::block_allocator

#

Definition at line 111 of file ReferenceSortedArray.h.

◆ const_indirect_iterator

template<typename T, class A = StandardAllocator>
typedef array_implementation::const_indirect_iterator pcl::ReferenceSortedArray< T, A >::const_indirect_iterator

#

Definition at line 146 of file ReferenceSortedArray.h.

◆ const_iterator

template<typename T, class A = StandardAllocator>
typedef array_implementation::const_iterator pcl::ReferenceSortedArray< T, A >::const_iterator

#

Definition at line 126 of file ReferenceSortedArray.h.

◆ const_reverse_iterator

template<typename T, class A = StandardAllocator>
typedef array_implementation::const_reverse_iterator pcl::ReferenceSortedArray< T, A >::const_reverse_iterator

#

Definition at line 136 of file ReferenceSortedArray.h.

◆ indirect_iterator

template<typename T, class A = StandardAllocator>
typedef array_implementation::indirect_iterator pcl::ReferenceSortedArray< T, A >::indirect_iterator

#

Definition at line 141 of file ReferenceSortedArray.h.

◆ iterator

template<typename T, class A = StandardAllocator>
typedef array_implementation::iterator pcl::ReferenceSortedArray< T, A >::iterator

#

Definition at line 121 of file ReferenceSortedArray.h.

◆ reverse_iterator

template<typename T, class A = StandardAllocator>
typedef array_implementation::reverse_iterator pcl::ReferenceSortedArray< T, A >::reverse_iterator

#

Definition at line 131 of file ReferenceSortedArray.h.

Constructor & Destructor Documentation

◆ ReferenceSortedArray() [1/5]

template<typename T, class A = StandardAllocator>
pcl::ReferenceSortedArray< T, A >::ReferenceSortedArray ( )
default

Constructs an empty reference sorted array.

◆ ReferenceSortedArray() [2/5]

template<typename T, class A = StandardAllocator>
pcl::ReferenceSortedArray< T, A >::ReferenceSortedArray ( size_type  n,
const T *  p 
)
inline

Constructs a reference sorted array that stores n copies of a non-null pointer p.

If p is nullptr, this function constructs an empty reference array.

Definition at line 161 of file ReferenceSortedArray.h.

◆ ReferenceSortedArray() [3/5]

template<typename T, class A = StandardAllocator>
template<class FI >
pcl::ReferenceSortedArray< T, A >::ReferenceSortedArray ( FI  i,
FI  j 
)
inline

Constructs a reference array as a copy of the sequence of non-null pointers defined by the range [i,j) of forward iterators. The stored sequence of pointers is sorted in ascending order by comparing the pointed objects.

If the range [i,j) contains null pointers, these are ignored and hence not included in the constructed reference array.

Definition at line 178 of file ReferenceSortedArray.h.

◆ ReferenceSortedArray() [4/5]

template<typename T, class A = StandardAllocator>
pcl::ReferenceSortedArray< T, A >::ReferenceSortedArray ( const ReferenceSortedArray< T, A > &  )
default

Copy constructor.

◆ ReferenceSortedArray() [5/5]

template<typename T, class A = StandardAllocator>
pcl::ReferenceSortedArray< T, A >::ReferenceSortedArray ( ReferenceSortedArray< T, A > &&  )
default

Move constructor.

◆ ~ReferenceSortedArray()

template<typename T, class A = StandardAllocator>
pcl::ReferenceSortedArray< T, A >::~ReferenceSortedArray ( )
inline

Destroys a ReferenceSortedArray object.

Deallocates the internal array of pointers to objects, but does not destroy the pointed objects. To destroy them, you have to call Destroy() or Delete() explicitly.

Definition at line 201 of file ReferenceSortedArray.h.

Member Function Documentation

◆ Add() [1/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Add ( const ReferenceSortedArray< T, A > &  x)
inline

#

Definition at line 782 of file ReferenceSortedArray.h.

Referenced by pcl::operator<<().

◆ Add() [2/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Add ( const array_implementation x)
inline

#

Definition at line 794 of file ReferenceSortedArray.h.

◆ Add() [3/4]

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::Add ( const T *  p,
size_type  n = 1 
)
inline

#

Definition at line 801 of file ReferenceSortedArray.h.

◆ Add() [4/4]

template<typename T, class A = StandardAllocator>
template<class FI >
void pcl::ReferenceSortedArray< T, A >::Add ( FI  i,
FI  j 
)
inline

#

Definition at line 811 of file ReferenceSortedArray.h.

◆ Apply()

template<typename T, class A = StandardAllocator>
template<class F >
void pcl::ReferenceSortedArray< T, A >::Apply ( f) const
inline

Calls f( const T& x ) for every unmodifiable object x in this reference array, successively from the first contained object to the last.

Definition at line 1078 of file ReferenceSortedArray.h.

◆ Assign() [1/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Assign ( const ReferenceSortedArray< T, A > &  x)
inline

Assigns a reference sorted array x to this reference sorted array.

Decrements the reference counter of the current array data, and destroys it if it becomes unreferenced.

Increments the reference counter of the source array's data and references it in this array.

Definition at line 573 of file ReferenceSortedArray.h.

◆ Assign() [2/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Assign ( const array_implementation x)
inline

Assigns a reference array x to this reference sorted array.

Causes this reference sorted array to store a sorted copy of the pointers in the source array x. Sorting is performed by comparing the pointed objects, not the pointers.

Definition at line 635 of file ReferenceSortedArray.h.

◆ Assign() [3/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Assign ( const T *  p,
size_type  n = 1 
)
inline

Replaces the contents of this reference sorted array with a sequence of n pointers equal to p.

if p is nullptr, this function yields an empty array.

Definition at line 689 of file ReferenceSortedArray.h.

◆ Assign() [4/4]

template<typename T, class A = StandardAllocator>
template<class FI >
void pcl::ReferenceSortedArray< T, A >::Assign ( FI  i,
FI  j 
)
inline

Replaces the contents of this reference sorted array with a sorted copy of the sequence of pointers defined by the range [i,j) of forward iterators.

If the range [i,j) contains null pointers, these are ignored and hence not included in this reference array. Sorting is performed by comparing the pointed objects, not the pointers.

Note
i and j must not be iterators into this array.

Definition at line 706 of file ReferenceSortedArray.h.

◆ At()

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::At ( size_type  i) const
inline

Returns an immutable reference array iterator located at the specified array index i.

Definition at line 343 of file ReferenceSortedArray.h.

◆ Available()

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::Available ( ) const
inline

Returns the length of the space available in this reference array, or zero if this reference array cannot contain more pointers. The available space is the number of pointers to objects that can be added to this reference array without requiring a reallocation. It is equal to Capacity() - Length() by definition.

Definition at line 272 of file ReferenceSortedArray.h.

◆ Begin()

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::Begin ( ) const
inline

Returns an immutable iterator located at the beginning of this array.

Definition at line 393 of file ReferenceSortedArray.h.

Referenced by pcl::ReferenceSortedArray< FileDataCacheItem >::Add().

◆ begin()

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::begin ( ) const
inline

STL-compatible iteration. Equivalent to Begin() const.

Definition at line 537 of file ReferenceSortedArray.h.

◆ Capacity()

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::Capacity ( ) const
inline

Returns the capacity of this reference array. The capacity is the maximum number of pointers to objects that this reference array can contain without requiring a reallocation.

Definition at line 260 of file ReferenceSortedArray.h.

◆ Clear()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Clear ( )
inline

Removes all pointers contained by this object, yielding an empty reference sorted array.

If this array is empty, then calling this member function has no effect.

If this array uniquely references its internal array data structure, all pointers contained are deallocated; otherwise its reference counter is decremented. Then a new, empty array data structure is created and uniquely referenced.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 947 of file ReferenceSortedArray.h.

◆ CloneAssign() [1/4]

template<typename T, class A = StandardAllocator>
template<class C >
void pcl::ReferenceSortedArray< T, A >::CloneAssign ( const C &  x)
inline

Replaces the contents of this reference sorted array with a sorted list of pointers to newly created copies of the objects stored in the specified container x. This function works for both direct and indirect containers.

Keep in mind that after calling this function (with a reference to a nonempty container) this array will store newly allocated objects. You should call Destroy() to deallocate these objects before destructing this reference array in order to avoid a memory leak.

Definition at line 724 of file ReferenceSortedArray.h.

◆ CloneAssign() [2/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::CloneAssign ( ReferenceSortedArray< T, A > &  x)
inline

#

Definition at line 732 of file ReferenceSortedArray.h.

◆ CloneAssign() [3/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::CloneAssign ( SortedArray< T, A > &  x)
inline

#

Definition at line 739 of file ReferenceSortedArray.h.

◆ CloneAssign() [4/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::CloneAssign ( IndirectSortedArray< T, A > &  x)
inline

#

Definition at line 746 of file ReferenceSortedArray.h.

◆ Contains() [1/3]

template<typename T, class A = StandardAllocator>
bool pcl::ReferenceSortedArray< T, A >::Contains ( const T &  v) const
inline

#

Definition at line 1222 of file ReferenceSortedArray.h.

◆ Contains() [2/3]

template<typename T, class A = StandardAllocator>
bool pcl::ReferenceSortedArray< T, A >::Contains ( const T *  p) const
inline

#

Definition at line 1229 of file ReferenceSortedArray.h.

◆ Contains() [3/3]

template<typename T, class A = StandardAllocator>
template<class BP >
bool pcl::ReferenceSortedArray< T, A >::Contains ( const T &  v,
BP  p 
) const
inline

#

Definition at line 1237 of file ReferenceSortedArray.h.

◆ Count() [1/3]

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::Count ( const T &  v) const
inline

Returns the number of objects equal to v in this reference array.

Definition at line 1108 of file ReferenceSortedArray.h.

◆ Count() [2/3]

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::Count ( const T *  p) const
inline

Returns the number of pointers equal to p stored in this reference array.

If p is nullptr, this function should return zero — or you are in serious trouble!

Definition at line 1121 of file ReferenceSortedArray.h.

◆ Count() [3/3]

template<typename T, class A = StandardAllocator>
template<class BP >
size_type pcl::ReferenceSortedArray< T, A >::Count ( const T &  v,
BP  p 
) const
inline

Returns the number of objects in this reference array such that for each counted object x the binary predicate p( x, v ) returns true.

Definition at line 1131 of file ReferenceSortedArray.h.

◆ CountIf()

template<typename T, class A = StandardAllocator>
template<class UP >
size_type pcl::ReferenceSortedArray< T, A >::CountIf ( UP  p) const
inline

Returns the number of objects in this reference array such that for each counted object x the unary predicate p( x ) returns true.

Definition at line 1141 of file ReferenceSortedArray.h.

◆ Destroy() [1/5]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Destroy ( iterator  i,
size_type  n = 1 
)
inline

Destroys and removes a sequence of n contiguous objects, starting at the specified location i in this reference sorted array.

This function destroys and deallocates the pointed objects, then removes the corresponding pointers in this array. The array length is decreased by the number of destroyed objects.

Warning
See Destroy( iterator, iterator ) for critical information on this member function.

Definition at line 963 of file ReferenceSortedArray.h.

◆ Destroy() [2/5]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Destroy ( iterator  i,
iterator  j 
)
inline

Destroys and removes the objects in a range [i,j) of iterators in this reference sorted array.

This function destroys and deallocates the pointed objects, then removes the corresponding pointers in this array. The array length is decreased by the number of destroyed objects.

Warning
This function is potentially dangerous. If the array contains duplicate pointers in the specified range of iterators, this function will lead to a crash as a result of multiple deletions. To minimize the risk of multiple deletions, this function ignores the normal data sharing mechanism so that all objects sharing the same array data structure will correctly have the destroyed objects removed. However, be aware of potential problems if other reference or indirect containers store pointers to deleted objects in different data structures, which will be invalid after calling this function.

Definition at line 986 of file ReferenceSortedArray.h.

◆ Destroy() [3/5]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Destroy ( const T &  v)
inline

Destroys and removes all objects equal to v in this reference sorted array.

This function destroys and deallocates the pointed objects, then removes the corresponding pointers in this array. The array length is decreased by the number of destroyed objects.

Warning
See Destroy( iterator, iterator ) for critical information on this member function.

Definition at line 1002 of file ReferenceSortedArray.h.

◆ Destroy() [4/5]

template<typename T, class A = StandardAllocator>
template<class BP >
void pcl::ReferenceSortedArray< T, A >::Destroy ( const T &  v,
BP  p 
)
inline

Destroys and removes every object x in this reference sorted array such that the binary predicate p( x, v ) is true.

This function destroys and deallocates the pointed objects, then removes the corresponding pointers in this array. The array length is decreased by the number of destroyed objects.

Warning
See Destroy( iterator, iterator ) for critical information on this member function.

Definition at line 1019 of file ReferenceSortedArray.h.

◆ Destroy() [5/5]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Destroy ( )
inline

Destroys and removes all objects in this reference sorted array, yielding an empty array.

Warning
See Destroy( iterator, iterator ) for critical information on this member function.

Definition at line 1031 of file ReferenceSortedArray.h.

◆ End()

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::End ( ) const
inline

Returns an immutable iterator located at the end of this array.

Definition at line 409 of file ReferenceSortedArray.h.

Referenced by pcl::ReferenceSortedArray< FileDataCacheItem >::Add().

◆ end()

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::end ( ) const
inline

STL-compatible iteration. Equivalent to End() const.

Definition at line 545 of file ReferenceSortedArray.h.

◆ EnsureUnique()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::EnsureUnique ( )
inline

Ensures that this reference array uniquely references its contained object pointers.

If necessary, this member function generates a duplicate of the array of pointers, references it, and then decrements the reference counter of the original pointer array.

Definition at line 233 of file ReferenceSortedArray.h.

◆ Fill()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Fill ( const T &  v)
inline

Sets all objects contained by this array equal to v.

Definition at line 1068 of file ReferenceSortedArray.h.

◆ First()

template<typename T, class A = StandardAllocator>
const T& pcl::ReferenceSortedArray< T, A >::First ( ) const
inline

Returns a reference to the first unmodifiable object in this reference array. This function should never be called for an empty array.

Definition at line 472 of file ReferenceSortedArray.h.

◆ FirstThat()

template<typename T, class A = StandardAllocator>
template<class F >
const_iterator pcl::ReferenceSortedArray< T, A >::FirstThat ( f) const
inline

Returns an immutable iterator pointing to the first object x in this reference sorted array such that f( const T& x ) is true. Returns End() if such pointer does not exist.

Definition at line 1089 of file ReferenceSortedArray.h.

◆ GetAllocator()

template<typename T, class A = StandardAllocator>
const allocator& pcl::ReferenceSortedArray< T, A >::GetAllocator ( ) const
inline

Returns a reference to the allocator object used by this reference array.

Definition at line 326 of file ReferenceSortedArray.h.

◆ Hash()

template<typename T, class A = StandardAllocator>
uint64 pcl::ReferenceSortedArray< T, A >::Hash ( uint64  seed = 0) const
inline

Returns a non-cryptographic hash value computed for this reference array. This function is a synonym for Hash64().

Definition at line 1457 of file ReferenceSortedArray.h.

◆ Hash32()

template<typename T, class A = StandardAllocator>
uint32 pcl::ReferenceSortedArray< T, A >::Hash32 ( uint32  seed = 0) const
inline

Returns a 32-bit non-cryptographic hash value computed for this reference array.

This function calls pcl::Hash32() for the internal array of pointers, not for the pointed objects.

The seed parameter can be used to generate repeatable hash values. It can also be set to a random value in compromised environments.

Definition at line 1448 of file ReferenceSortedArray.h.

◆ Hash64()

template<typename T, class A = StandardAllocator>
uint64 pcl::ReferenceSortedArray< T, A >::Hash64 ( uint64  seed = 0) const
inline

Returns a 64-bit non-cryptographic hash value computed for this reference array.

This function calls pcl::Hash64() for the internal array of pointers, not for the pointed objects.

The seed parameter can be used to generate repeatable hash values. It can also be set to a random value in compromised environments.

Definition at line 1433 of file ReferenceSortedArray.h.

◆ Import()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Import ( iterator  i,
iterator  j 
)
inline

Causes this reference sorted array to store the sequence of pointers defined by the range [i,j) of iterators. The previously referenced data structure is dereferenced and deallocated if it becomes unreferenced. The sequence [i,j) is sorted in ascending order by comparing the pointed objects.

Definition at line 758 of file ReferenceSortedArray.h.

◆ IsAliasOf()

template<typename T, class A = StandardAllocator>
bool pcl::ReferenceSortedArray< T, A >::IsAliasOf ( const ReferenceSortedArray< T, A > &  x) const
inline

Returns true iff this reference array is an alias of the array x.

Two objects are aliases if both share the same data. Two reference containers are aliases if they share a unique set of object pointers.

Definition at line 220 of file ReferenceSortedArray.h.

◆ IsEmpty()

template<typename T, class A = StandardAllocator>
bool pcl::ReferenceSortedArray< T, A >::IsEmpty ( ) const
inline

Returns true iff this reference array is empty.

Definition at line 300 of file ReferenceSortedArray.h.

◆ IsUnique()

template<typename T, class A = StandardAllocator>
bool pcl::ReferenceSortedArray< T, A >::IsUnique ( ) const
inline

Returns true iff this reference array uniquely references its contained array of pointers to objects.

Definition at line 209 of file ReferenceSortedArray.h.

◆ IsValid()

template<typename T, class A = StandardAllocator>
bool pcl::ReferenceSortedArray< T, A >::IsValid ( ) const
inline

Returns true only if this reference array is valid. A reference array is valid if it references an internal structure with an array of pointers, even if it is an empty array.

In general, all ReferenceSortedArray objects are valid with only two exceptions:

  • Objects that have been move-copied or move-assigned to other arrays.
  • Objects that have been invalidated explicitly by calling Transfer().

An invalid array object cannot be used and should be destroyed immediately. Invalid arrays are always destroyed automatically during move construction and move assignment operations.

Definition at line 292 of file ReferenceSortedArray.h.

◆ Last()

template<typename T, class A = StandardAllocator>
const T& pcl::ReferenceSortedArray< T, A >::Last ( ) const
inline

Returns a reference to the last unmodifiable object in this reference array. This function should never be called for an empty array.

Definition at line 490 of file ReferenceSortedArray.h.

◆ LastThat()

template<typename T, class A = StandardAllocator>
template<class F >
const_iterator pcl::ReferenceSortedArray< T, A >::LastThat ( f) const
inline

Returns an immutable iterator pointing to the last object x in this reference sorted array such that f( const T& x ) is true. Returns End() if such pointer does not exist.

Definition at line 1100 of file ReferenceSortedArray.h.

◆ Length()

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::Length ( ) const
inline

Returns the length of this reference array.

Definition at line 250 of file ReferenceSortedArray.h.

◆ LowerBound()

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::LowerBound ( ) const
inline

Returns the minimum legal index in this array (always zero). For empty arrays, this function returns a meaningless value.

Definition at line 309 of file ReferenceSortedArray.h.

◆ MaxItem() [1/2]

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::MaxItem ( ) const
inline

#

Definition at line 1163 of file ReferenceSortedArray.h.

◆ MaxItem() [2/2]

template<typename T, class A = StandardAllocator>
template<class BP >
const_iterator pcl::ReferenceSortedArray< T, A >::MaxItem ( BP  p) const
inline

#

Definition at line 1171 of file ReferenceSortedArray.h.

◆ MinItem() [1/2]

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::MinItem ( ) const
inline

#

Definition at line 1148 of file ReferenceSortedArray.h.

◆ MinItem() [2/2]

template<typename T, class A = StandardAllocator>
template<class BP >
const_iterator pcl::ReferenceSortedArray< T, A >::MinItem ( BP  p) const
inline

#

Definition at line 1156 of file ReferenceSortedArray.h.

◆ MutableAt()

template<typename T, class A = StandardAllocator>
iterator pcl::ReferenceSortedArray< T, A >::MutableAt ( size_type  i)
inline

Returns a mutable reference array iterator located at the specified array index i.

Definition at line 352 of file ReferenceSortedArray.h.

◆ MutableBegin()

template<typename T, class A = StandardAllocator>
iterator pcl::ReferenceSortedArray< T, A >::MutableBegin ( )
inline

Returns a mutable iterator located at the beginning of this array.

Definition at line 401 of file ReferenceSortedArray.h.

◆ MutableEnd()

template<typename T, class A = StandardAllocator>
iterator pcl::ReferenceSortedArray< T, A >::MutableEnd ( )
inline

Returns a mutable iterator located at the end of this array.

Definition at line 417 of file ReferenceSortedArray.h.

◆ MutableFirst()

template<typename T, class A = StandardAllocator>
T& pcl::ReferenceSortedArray< T, A >::MutableFirst ( )
inline

Returns a reference to the first object in this reference array. This function should never be called for an empty array.

Definition at line 481 of file ReferenceSortedArray.h.

◆ MutableIterator()

template<typename T, class A = StandardAllocator>
iterator pcl::ReferenceSortedArray< T, A >::MutableIterator ( const_iterator  i)
inline

Returns a mutable iterator pointing to the same array element as the specified immutable iterator i.

Warning
As a side-effect of calling this function, the specified immutable iterator i may become invalid. This happens when this function is called for a shared array, since in this case getting a mutable iterator involves a deep copy of the array through an implicit call to EnsureUnique().

Definition at line 367 of file ReferenceSortedArray.h.

◆ MutableLast()

template<typename T, class A = StandardAllocator>
T& pcl::ReferenceSortedArray< T, A >::MutableLast ( )
inline

Returns a reference to the last object in this reference array. This function should never be called for an empty array.

Definition at line 499 of file ReferenceSortedArray.h.

◆ MutableReverseBegin()

template<typename T, class A = StandardAllocator>
reverse_iterator pcl::ReferenceSortedArray< T, A >::MutableReverseBegin ( )
inline

Returns a mutable reverse iterator located at the reverse beginning of this reference array.

The reverse beginning corresponds to the last object in the array.

Definition at line 439 of file ReferenceSortedArray.h.

◆ MutableReverseEnd()

template<typename T, class A = StandardAllocator>
reverse_iterator pcl::ReferenceSortedArray< T, A >::MutableReverseEnd ( )
inline

Returns a mutable reverse iterator located at the reverse end of this reference array.

The reverse end corresponds to a (nonexistent) object immediately before the first object in the array.

Definition at line 463 of file ReferenceSortedArray.h.

◆ operator*()

template<typename T, class A = StandardAllocator>
const T& pcl::ReferenceSortedArray< T, A >::operator* ( ) const
inline

Returns a reference to the unmodifiable first object in this reference array.

Definition at line 385 of file ReferenceSortedArray.h.

◆ operator=() [1/4]

template<typename T, class A = StandardAllocator>
ReferenceSortedArray& pcl::ReferenceSortedArray< T, A >::operator= ( const ReferenceSortedArray< T, A > &  x)
inline

Copy assignment operator.

Causes this reference sorted array to reference the same set of objects as another reference sorted array x. Returns a reference to this object.

Definition at line 558 of file ReferenceSortedArray.h.

◆ operator=() [2/4]

template<typename T, class A = StandardAllocator>
ReferenceSortedArray& pcl::ReferenceSortedArray< T, A >::operator= ( ReferenceSortedArray< T, A > &&  x)
inline

Move assignment operator. Returns a reference to this object.

Definition at line 581 of file ReferenceSortedArray.h.

◆ operator=() [3/4]

template<typename T, class A = StandardAllocator>
ReferenceSortedArray& pcl::ReferenceSortedArray< T, A >::operator= ( const array_implementation x)
inline

Assigns a reference array x to this reference sorted array.

Causes this reference sorted array to store a sorted copy of the pointers in the source array x. Sorting is performed by comparing the pointed objects, not the pointers. Returns a reference to this object.

Definition at line 622 of file ReferenceSortedArray.h.

◆ operator=() [4/4]

template<typename T, class A = StandardAllocator>
ReferenceSortedArray& pcl::ReferenceSortedArray< T, A >::operator= ( array_implementation &&  x)
inline

Move assignment of a reference array.

The transferred array is sorted after the assignment. Returns a reference to this object.

Definition at line 647 of file ReferenceSortedArray.h.

◆ operator[]()

template<typename T, class A = StandardAllocator>
const T& pcl::ReferenceSortedArray< T, A >::operator[] ( size_type  i) const
inline

Returns a reference to the immutable object at the specified array index i. No bounds checking is performed.

Definition at line 376 of file ReferenceSortedArray.h.

◆ Release()

template<typename T, class A = StandardAllocator>
indirect_iterator pcl::ReferenceSortedArray< T, A >::Release ( )
inline

Releases the set of pointers contained by this reference sorted array.

This member function returns a pointer to the internal block of pointers stored in this object, after ensuring that it is uniquely referenced. If the array is empty, this function may return the null pointer.

Before returning, this member function empties this array without deallocating its contained data. The caller is then responsible for deallocating the returned block when it is no longer required.

Definition at line 775 of file ReferenceSortedArray.h.

◆ Remove() [1/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Remove ( const_iterator  i,
size_type  n = 1 
)
inline

Removes a sequence of n contiguous pointers starting at the specified location i in this reference array.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 845 of file ReferenceSortedArray.h.

◆ Remove() [2/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Remove ( const_iterator  i,
const_iterator  j 
)
inline

Removes a sequence of contiguous pointers in the range [i,j) of this reference array.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 857 of file ReferenceSortedArray.h.

◆ Remove() [3/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Remove ( const T &  v)
inline

Removes all existing pointers whose pointed objects are equal to the specified value v in this reference array.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 904 of file ReferenceSortedArray.h.

◆ Remove() [4/4]

template<typename T, class A = StandardAllocator>
template<class BP >
void pcl::ReferenceSortedArray< T, A >::Remove ( const T &  v,
BP  p 
)
inline

Removes every pointer x in this reference array such that the binary predicate p( *x, v ) is true.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 917 of file ReferenceSortedArray.h.

◆ RemovePointer()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::RemovePointer ( const T *  p)
inline

Removes all contained pointers equal to p in this reference array.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 928 of file ReferenceSortedArray.h.

◆ Reserve()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Reserve ( size_type  n)
inline

Ensures that this reference array has enough capacity to store n pointers.

After calling this member function with n > 0, this object is guaranteed to uniquely reference its array data.

Definition at line 1043 of file ReferenceSortedArray.h.

◆ ReverseBegin()

template<typename T, class A = StandardAllocator>
const_reverse_iterator pcl::ReferenceSortedArray< T, A >::ReverseBegin ( ) const
inline

Returns an immutable reverse iterator located at the reverse beginning of this reference array.

The reverse beginning corresponds to the last object in the array.

Definition at line 428 of file ReferenceSortedArray.h.

◆ ReverseEnd()

template<typename T, class A = StandardAllocator>
const_reverse_iterator pcl::ReferenceSortedArray< T, A >::ReverseEnd ( ) const
inline

Returns an immutable reverse iterator located at the reverse end of this reference array.

The reverse end corresponds to a (nonexistent) object immediately before the first object in the array.

Definition at line 451 of file ReferenceSortedArray.h.

◆ Search() [1/3]

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::Search ( const T &  v) const
inline

#

Definition at line 1178 of file ReferenceSortedArray.h.

◆ Search() [2/3]

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::Search ( const T *  p) const
inline

#

Definition at line 1185 of file ReferenceSortedArray.h.

◆ Search() [3/3]

template<typename T, class A = StandardAllocator>
template<class BP >
const_iterator pcl::ReferenceSortedArray< T, A >::Search ( const T &  v,
BP  p 
) const
inline

#

Definition at line 1193 of file ReferenceSortedArray.h.

◆ SearchLast() [1/3]

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::SearchLast ( const T &  v) const
inline

#

Definition at line 1200 of file ReferenceSortedArray.h.

◆ SearchLast() [2/3]

template<typename T, class A = StandardAllocator>
const_iterator pcl::ReferenceSortedArray< T, A >::SearchLast ( const T *  p) const
inline

#

Definition at line 1207 of file ReferenceSortedArray.h.

◆ SearchLast() [3/3]

template<typename T, class A = StandardAllocator>
template<class BP >
const_iterator pcl::ReferenceSortedArray< T, A >::SearchLast ( const T &  v,
BP  p 
) const
inline

#

Definition at line 1215 of file ReferenceSortedArray.h.

◆ SetAllocator()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::SetAllocator ( const allocator a)
inline

Sets a new allocator object for this reference array.

Definition at line 334 of file ReferenceSortedArray.h.

◆ Shrink()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Shrink ( size_type  n = 1)
inline

Removes a contiguous trailing sequence of n existing pointers from this reference array. This operation is equivalent to:

Truncate( End() - n )

If the specified count n is greater than or equal to the length of this array, this function calls Clear() to yield an empty array.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 892 of file ReferenceSortedArray.h.

◆ Size()

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::Size ( ) const
inline

Returns the total number of bytes required to store the array of object pointers contained by this reference array.

Definition at line 242 of file ReferenceSortedArray.h.

◆ Sort()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Sort ( )
inline

#

Definition at line 1244 of file ReferenceSortedArray.h.

◆ Squeeze()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Squeeze ( )
inline

Causes this reference array to allocate the exact required memory space to store its contained pointers.

If the array has excess capacity, a new copy of its contained pointers is generated and stored in a newly allocated memory block that fits them exactly, then the previous memory block is deallocated.

If the array is empty, calling this function is equivalent to Clear(). Note that in this case a previously allocated memory block (by a call to Reserve()) may also be deallocated.

Definition at line 1060 of file ReferenceSortedArray.h.

◆ ToCommaSeparated()

template<typename T, class A = StandardAllocator>
template<class S >
S& pcl::ReferenceSortedArray< T, A >::ToCommaSeparated ( S &  s) const
inline

Generates a comma-separated sequence of string tokens. Returns a reference to the target string s.

This function is equivalent to:

ToSeparated( s, ',' );

Definition at line 1376 of file ReferenceSortedArray.h.

◆ ToNewLineSeparated()

template<typename T, class A = StandardAllocator>
template<class S >
S& pcl::ReferenceSortedArray< T, A >::ToNewLineSeparated ( S &  s) const
inline

Generates a newline-separated sequence of string tokens. Returns a reference to the target string s.

This function is equivalent to:

ToSeparated( s, '\n' );

Definition at line 1418 of file ReferenceSortedArray.h.

◆ ToSeparated() [1/2]

template<typename T, class A = StandardAllocator>
template<class S , typename SP >
S& pcl::ReferenceSortedArray< T, A >::ToSeparated ( S &  s,
SP  separator 
) const
inline

Generates a sequence of string tokens separated with the specified separator string. Returns a reference to the target string s.

For each element in this array, this function appends a string representation (known as a token) to the target string s. If the array contains more than one element, successive tokens are separated with the specified separator.

The string type S must have a meaningful Append() member function and type conversion semantics to transform an array element to a string. The standard String and IsoString PCL classes provide the required functionality for most scalar types, although it is probably better to use String::ToSeparated() and IsoString::ToSeparated() instead of calling these functions directly.

Definition at line 1334 of file ReferenceSortedArray.h.

◆ ToSeparated() [2/2]

template<typename T, class A = StandardAllocator>
template<class S , typename SP , class AF >
S& pcl::ReferenceSortedArray< T, A >::ToSeparated ( S &  s,
SP  separator,
AF  append 
) const
inline

Generates a sequence of string tokens separated with the specified separator string by calling an append function. Returns a reference to the target string s.

For each element x in this array, this function appends a string representation (known as a token) to the target string s by calling the append function:

append( s, S( x ) );

If the array contains more than one element, successive tokens are separated by calling:

append( s, S( separator ) );

The string type S must have type conversion semantics to transform an array element to a string. The standard String and IsoString PCL classes provide the required functionality for most scalar types, although it is probably easier to use String::ToSeparated() and IsoString::ToSeparated() instead of calling these functions directly.

Definition at line 1362 of file ReferenceSortedArray.h.

◆ ToSpaceSeparated()

template<typename T, class A = StandardAllocator>
template<class S >
S& pcl::ReferenceSortedArray< T, A >::ToSpaceSeparated ( S &  s) const
inline

Generates a space-separated sequence of string tokens. Returns a reference to the target string s.

This function is equivalent to:

ToSeparated( s, ' ' );

Definition at line 1390 of file ReferenceSortedArray.h.

◆ ToTabSeparated()

template<typename T, class A = StandardAllocator>
template<class S >
S& pcl::ReferenceSortedArray< T, A >::ToTabSeparated ( S &  s) const
inline

Generates a tabulator-separated sequence of string tokens. Returns a reference to the target string s.

This function is equivalent to:

ToSeparated( s, '\t' );

Definition at line 1404 of file ReferenceSortedArray.h.

◆ Transfer() [1/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Transfer ( ReferenceSortedArray< T, A > &  x)
inline

Transfers data from another reference sorted array x to this object.

Decrements the reference counter of the current array data, and destroys it if it becomes unreferenced.

Transfers source array data to this object, leaving empty and invalid the source object x.

Definition at line 596 of file ReferenceSortedArray.h.

◆ Transfer() [2/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Transfer ( ReferenceSortedArray< T, A > &&  x)
inline

Transfers data from another reference sorted array x to this object.

Decrements the reference counter of the current array data, and destroys it if it becomes unreferenced.

Transfers source array data to this object, leaving empty and invalid the source object x.

Definition at line 610 of file ReferenceSortedArray.h.

◆ Transfer() [3/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Transfer ( array_implementation x)
inline

Transfers data from a reference array x to this object.

Decrements the reference counter of the current array data, and destroys it if it becomes unreferenced.

Transfers source array data to this object, leaving empty and invalid the source object x. The transferred array is sorted after the assignment.

Definition at line 662 of file ReferenceSortedArray.h.

◆ Transfer() [4/4]

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Transfer ( array_implementation &&  x)
inline

Transfers data from a reference array x to this object.

Decrements the reference counter of the current array data, and destroys it if it becomes unreferenced.

Transfers source array data to this object, leaving empty and invalid the source object x. The transferred array is sorted after the assignment.

Definition at line 677 of file ReferenceSortedArray.h.

◆ Truncate()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::Truncate ( const_iterator  i)
inline

Removes a trailing sequence of contiguous pointers from the specified iterator of this reference array. This operation is equivalent to:

Remove( i, End() )

If the specified iterator is located at or after the end of this array, this function does nothing. Otherwise the iterator is constrained to stay in the range [Begin(),End()) of existing array elements.

Only pointers are removed by this function; the pointed objects are not affected in any way.

Definition at line 875 of file ReferenceSortedArray.h.

◆ UniquifyIterator()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::UniquifyIterator ( iterator i)
inline

Ensures that the specified iterator represents a pointer stored in a uniquely referenced indirect array. If necessary, this function builds a new, uniquely referenced copy of the underlying indirect array by calling EnsureUnique().

If the iterator i is changed, it is guaranteed to point to the object at the same array index it was pointing to before calling this function.

Definition at line 513 of file ReferenceSortedArray.h.

◆ UniquifyIterators()

template<typename T, class A = StandardAllocator>
void pcl::ReferenceSortedArray< T, A >::UniquifyIterators ( iterator i,
iterator j 
)
inline

Ensures that the specified iterators represents a pointer stored in a uniquely referenced indirect array. If necessary, this function builds a new, uniquely referenced copy of the underlying indirect array by calling EnsureUnique().

If the iterators i and j are changed, they are guaranteed to point to the objects at the same array indices they were pointing to before calling this function.

Definition at line 528 of file ReferenceSortedArray.h.

◆ UpperBound()

template<typename T, class A = StandardAllocator>
size_type pcl::ReferenceSortedArray< T, A >::UpperBound ( ) const
inline

Returns the maximum legal index in this array. It is equal to Length()-1. For empty arrays, this function returns a meaningless value.

Definition at line 318 of file ReferenceSortedArray.h.

Friends And Related Function Documentation

◆ Swap

template<typename T, class A = StandardAllocator>
void Swap ( ReferenceSortedArray< T, A > &  x1,
ReferenceSortedArray< T, A > &  x2 
)
friend

Exchanges two reference sorted arrays x1 and x2.

Definition at line 1252 of file ReferenceSortedArray.h.


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