![]() |
Implementation of a vector for (polymorphic) pointers. More...
#include <PtrVector.h>
Classes | |
class | CastIterator |
Dynamic cast iterator for polymorphic pointer vectors.The CastIterator class is part of the PtrVector class and represent a forward iterator over all elements of type C contained in a range of elements of type T, where C is a type derived from T. More... | |
class | ConstCastIterator |
Dynamic cast iterator for polymorphic pointer vectors.The ConstCastIterator class is part of the PtrVector class and represent a forward iterator over all elements of type C contained in a range of elements of type T, where C is a type derived from T. The ConstCastIterator is the counterpart of CastIterator for constant vectors. More... | |
Public Types | |
typedef T * | ValueType |
Type of the underlying values. | |
typedef T * | PointerType |
Pointer to a non-const object. | |
typedef const T * | ConstPointerType |
Pointer to a const object. | |
typedef T *& | ReferenceType |
Reference to a non-const object. | |
typedef T *const & | ConstReferenceType |
Reference to a const object. | |
typedef size_t | SizeType |
Size type of the pointer vector. | |
typedef PtrIterator< T > | Iterator |
Iterator over non-const objects. | |
typedef PtrIterator< const T > | ConstIterator |
Iterator over const objects. | |
typedef D | DeletionPolicy |
Type of the deletion policy. | |
typedef G | GrowthPolicy |
Type of the growth policy. | |
typedef ValueType | value_type |
Type of the underlying values. | |
typedef PointerType | pointer |
Pointer to a non-const object. | |
typedef ConstPointerType | const_pointer |
Pointer to a const object. | |
typedef ReferenceType | reference |
Reference to a non-const object. | |
typedef ConstReferenceType | const_reference |
Reference to a const object. | |
typedef SizeType | size_type |
Size type of the pointer vector. | |
Public Member Functions | |
template<typename T2 , typename D2 , typename G2 > | |
PtrVector< T, D, G > & | operator= (const PtrVector< T2, D2, G2 > &pv) |
Assignment operator for different PtrVector instances. More... | |
template<typename C > | |
PtrVector< T, D, G >::BLAZE_TEMPLATE CastIterator< C > | erase (CastIterator< C > pos) |
Removing an element from the pointer vector. More... | |
template<typename C > | |
PtrVector< T, D, G >::BLAZE_TEMPLATE CastIterator< C > | release (CastIterator< C > pos) |
Releasing an element from the pointer vector. More... | |
Constructors | |
PtrVector (SizeType initCapacity=0) | |
Standard constructor for PtrVector. More... | |
PtrVector (const PtrVector &pv) | |
Copy constructor for PtrVector. More... | |
template<typename T2 , typename D2 , typename G2 > | |
PtrVector (const PtrVector< T2, D2, G2 > &pv) | |
Conversion constructor from different PtrVector instances. More... | |
Destructor | |
~PtrVector () | |
Destructor for PtrVector. More... | |
Assignment operators | |
PtrVector & | operator= (const PtrVector &pv) |
Copy assignment operator for PtrVector. More... | |
template<typename T2 , typename D2 , typename G2 > | |
PtrVector & | operator= (const PtrVector< T2, D2, G2 > &pv) |
Get functions | |
SizeType | maxSize () const |
Returns the maximum possible size of a pointer vector. More... | |
SizeType | size () const |
Returns the current size of the pointer vector. More... | |
template<typename C > | |
SizeType | size () const |
SizeType | capacity () const |
Returns the capacity of the pointer vector. More... | |
bool | isEmpty () const |
Returns true if the pointer vector has no elements. More... | |
Access functions | |
ReferenceType | operator[] (SizeType index) |
Subscript operator for the direct access to the pointer vector elements. More... | |
ConstReferenceType | operator[] (SizeType index) const |
Subscript operator for the direct access to the pointer vector elements. More... | |
ReferenceType | front () |
Returns a reference to the first element of the pointer vector. More... | |
ConstReferenceType | front () const |
Returns a reference to the first element of the pointer vector. More... | |
ReferenceType | back () |
Returns a reference to the last element of the pointer vector. More... | |
ConstReferenceType | back () const |
Returns a reference to the last element of the pointer vector. More... | |
Iterator functions | |
Iterator | begin () |
Returns an iterator to the beginning of the pointer vector. More... | |
ConstIterator | begin () const |
Returns an iterator to the beginning of the pointer vector. More... | |
template<typename C > | |
CastIterator< C > | begin () |
template<typename C > | |
ConstCastIterator< C > | begin () const |
Iterator | end () |
Returns an iterator just past the last element of the pointer vector. More... | |
ConstIterator | end () const |
Returns an iterator just past the last element of the pointer vector. More... | |
template<typename C > | |
CastIterator< C > | end () |
template<typename C > | |
ConstCastIterator< C > | end () const |
Element functions | |
void | pushBack (PointerType p) |
Adding an element to the end of the pointer vector. More... | |
void | popBack () |
Removing an element from the end of the pointer vector. More... | |
void | releaseBack () |
Releasing the element at the end of the pointer vector. More... | |
template<typename IteratorType > | |
void | assign (IteratorType first, IteratorType last) |
Assigning a range of elements to the pointer vector. More... | |
Iterator | insert (Iterator pos, PointerType p) |
Inserting an element into the pointer vector. More... | |
template<typename IteratorType > | |
void | insert (Iterator pos, IteratorType first, IteratorType last) |
Inserting a range of elements into the pointer vector. More... | |
Iterator | erase (Iterator pos) |
Removing an element from the pointer vector. More... | |
template<typename C > | |
CastIterator< C > | erase (CastIterator< C > pos) |
Iterator | release (Iterator pos) |
Releasing an element from the pointer vector. More... | |
template<typename C > | |
CastIterator< C > | release (CastIterator< C > pos) |
void | clear () |
Removing all elements from the pointer vector. More... | |
Utility functions | |
void | reserve (SizeType newCapacity) |
Setting the minimum capacity of the pointer vector. More... | |
void | swap (PtrVector &pv) noexcept |
Swapping the contents of two pointer vectors. More... | |
Private Member Functions | |
Helper functions | |
size_t | calcCapacity (size_t minCapacity) const |
Calculating the new capacity of the vector based on its growth policy. More... | |
void | deleteElement (PointerType ptr) const |
Deleting an element of the pointer vector according to the deletion policy. More... | |
Insertion helper functions | |
void | insert (T **const pos, PointerType p) |
Inserting an element into the pointer vector. More... | |
template<typename IteratorType > | |
void | insert (T **pos, IteratorType first, IteratorType last, SizeType n) |
Inserting a range of elements into the pointer vector. More... | |
Private Attributes | |
Member variables | |
SizeType | size_ |
The current size of the pointer vector. | |
SizeType | capacity_ |
The capacity of the pointer vector. | |
PointerType * | begin_ |
Pointer to the first element of the pointer vector. | |
PointerType * | end_ |
Pointer to the last element of the pointer vector. | |
Friends | |
CastIterator/ConstCastIterator comparison operators | |
template<typename L , typename R > | |
bool | operator== (const CastIterator< L > &lhs, const CastIterator< R > &rhs) |
Equality comparison between two CastIterator objects. More... | |
template<typename L , typename R > | |
bool | operator== (const CastIterator< L > &lhs, const ConstCastIterator< R > &rhs) |
Equality comparison between a CastIterator and a ConstCastIterator. More... | |
template<typename L , typename R > | |
bool | operator== (const ConstCastIterator< L > &lhs, const CastIterator< R > &rhs) |
Equality comparison between a ConstCastIterator and a CastIterator. More... | |
template<typename L , typename R > | |
bool | operator== (const ConstCastIterator< L > &lhs, const ConstCastIterator< R > &rhs) |
Equality comparison between two ConstCastIterator objects. More... | |
template<typename L , typename R > | |
bool | operator!= (const CastIterator< L > &lhs, const CastIterator< R > &rhs) |
Inequality comparison between two CastIterator objects. More... | |
template<typename L , typename R > | |
bool | operator!= (const CastIterator< L > &lhs, const ConstCastIterator< R > &rhs) |
Inequality comparison between a CastIterator and a ConstCastIterator. More... | |
template<typename L , typename R > | |
bool | operator!= (const ConstCastIterator< L > &lhs, const CastIterator< R > &rhs) |
Inequality comparison between a ConstCastIterator and a CastIterator. More... | |
template<typename L , typename R > | |
bool | operator!= (const ConstCastIterator< L > &lhs, const ConstCastIterator< R > &rhs) |
Inequality comparison between two ConstCastIterator objects. More... | |
Implementation of a vector for (polymorphic) pointers.
The std::vector is one of the standard libraries most useful tools. It is the standard solution for a dynamically allocated, automatically growing, and memory managed array. It provides fast random access to its elements, since a vector guarantees that the elements lie adjacent in memory and manages the dynamically allocated memory according to the RAII idiom.
Yet there are some situations, where users of std::vector experience several drawbacks, especially when std::vector is used in combination with pointers. For instance, a const_iterator over a range of pointers will not allow the stored pointers to change, but the objects behind the pointers remain changeable. The following example illustrates that it is possible to change the values of double values through an iterator-to-const:
The basic reason for this behavior is that std::vector is unaware of the fact that it stores pointers instead of objects and therefore the pointer are considered constant, not the objects behind the pointer.
Another drawback of std::vector is the fact that during destruction of a vector object the dynamically allocated bodies are not deleted. Again, std::vector is unaware of the special property of pointers and therefore does not apply any kind of deletion policy. It basically calls the default destructor for pointers, which in turn does nothing and especially does not destroy the attached objects.
A different approach is taken by the Boost ptr_vector. A ptr_vector is perfectly aware of the fact that is stores pointers to dynamically objects (and in consequence may only be used with pointers to dynamically allocated objects) and takes full responsibilty for these resources. However, in order to accomplish this task, ptr_vector completely abstracts from the fact that it stores pointers and provides a view as if it would contain objects instead of pointers. Unfortunately, this strict memory management might cause problems, for instance in case the vector to pointers is used both internally (including proper resource management) and outside by the user (without any resource management).
In case both std::vector and boost::ptr_vector are not suitable data structures, the Blaze library provides a special vector container for pointers, which is a cross of the functionalities of the std::vector and ptr_vector. The Blaze PtrVector is not a RAII class in the classic sense (as for instance the Boost ptr_vector) since it does not strictly encapsule the resource management. As in the case of std::vector, it still is the responsibility of a user of PtrVector to manage the resources accordingly. However, PtrVector can be used internally to store pointers to dynamically allocated objects and resources within RAII classes, and outside by a user as storage for handles to resources that are managed elsewhere. In contrast to the boost::ptr_vector, the PtrVector provides full access to the contained pointers, but its iterators work similar to the ptr_vector iterator and only provide access to the objects behind the pointers, creating the illusion that objects are stored instead of pointers:
Notice the differences in the usage of the iterator in contrast to the std::vector and boost::ptr_vector. In contrast to them the functions of PtrVector follow the naming convention of the Blaze library (i.e. pushBack instead of push_back). In addition, the underlying iterator adds an additional dereference to all access operators, which eases the access to the underlying objects:
A noteworthy difference between the STL vector and the pointer vector is the used template argument: instead of the pointer type, the Blaze pointer vector is only provided with the type of the underlying objects:
Additionally, the Blaze pointer vector offers some limited possibilities to configure the memory management and the growth of the internal storage, and implements special features for polymorphic pointers, as for instance a convenient way to iterate over a subset of polymorphic objects contained in the pointer vector.
For polymorphic pointers, the PtrVector class additionally offers two special iterators to iterate over all objects of a specific type: the CastIterator and ConstCastIterator.
In the example, the cast iterators are used to iterate over all objects of type B within the pointer vector, where B must be a type derived from A. The attempt to use these iterators for types that are not derived from A results in a compile time error. Note that the usage of the cast iterators is computaionally more expensive than the use of the standard iterators. Therefore these iterators should not be used unless a down-cast is really necessary, e.g. in order to access a type specific function.
If a pointer vector is used within an other container and is used to store polymorphic pointers, you might face the problem of not being able to create type definitions for the cast iterators. Whereas it is possible to create typedefs for the standard iterators, it is unfortunately not possible (yet) to create type definitions for template classes. In order to create a new return type within the container, the following approach could be taken:
Instead of a typedef within the Container class, a new class CastIterator is derived from the PtrVector::CastIterator class. This approach acts similar as the typedef as a user can now use the Container as follows:
This provides the same abstraction from the internal implementation as the desired typedef. The same approach could be taken for a ConstCastIterator definition.
The growth and deletion behavior of the PtrVector class can be adapted to any specific task. The second template argument of the PtrVector specifies the growth rate. The following growth rates can be selected:
The third template argument of the PtrVector specifies the deletion behavior for the case that the pointer vector is destroyed. Note that the deletion behavior has only limited effect on the memory management of the contained resources. For instance, copying a PtrVector always results in a shallow copy, i.e., the contained resources are not copied/cloned. Therefore the deletion policy should be considered a convenience functionality in the context of a resource managing class. The following policies can be selected:
|
inlineexplicit |
Standard constructor for PtrVector.
initCapacity | The initial capacity of the pointer vector. |
The default initial capacity of the pointer vector is specified by the selected growth policy.
|
inline |
Copy constructor for PtrVector.
pv | The pointer vector to be copied. |
|
inline |
Conversion constructor from different PtrVector instances.
pv | The pointer vector to be copied. |
|
inline |
Destructor for PtrVector.
In the destructor, the selected deletion policy is applied to all elements of the pointer vector.
|
inline |
Assigning a range of elements to the pointer vector.
first | Iterator to the first element of the element range. |
last | Iterator to the element one past the last element of the element range. |
std::length_error | Maximum pointer vector length exceeded. |
This functions assigns the elements in the range to the pointer vector. All elements previously contained in the pointer vector are removed. The assign function runs in linear time.
|
inline |
Returns a reference to the last element of the pointer vector.
|
inline |
Returns a reference to the last element of the pointer vector.
|
inline |
Returns an iterator to the beginning of the pointer vector.
Returns an iterator to the first element of type C within the pointer vector.
This function returns an iterator to the first element of type C within in the pointer vector, where C is a type derived from the type T of objects contained in the pointer vector. In case there is no element of type C contained in the vector, an iterator just past the last element of the pointer vector is returned. In combination with the according end function (see example), this iterator allows to iterate over all objects of type C in the range of the pointer vector. The attempt to use this function for types that are not derived from T results in a compile time error.
|
inline |
Returns an iterator to the beginning of the pointer vector.
Returns an iterator to the first element of type C within the pointer vector.
This function returns an iterator to the first element of type C within in the pointer vector, where C is a type derived from the type T of objects contained in the pointer vector. In case there is no element of type C contained in the vector, an iterator just past the last element of the pointer vector is returned. In combination with the according end function (see example), this iterator allows to iterate over all objects of type C in the range of the pointer vector. The attempt to use this function for types that are not derived from T results in a compile time error.
|
inlineprivate |
Calculating the new capacity of the vector based on its growth policy.
minCapacity | The minimum necessary capacity. |
|
inline |
Returns the capacity of the pointer vector.
|
inline |
Removing all elements from the pointer vector.
|
inlineprivate |
Deleting an element of the pointer vector according to the deletion policy.
ptr | The element to be deleted. |
|
inline |
Returns an iterator just past the last element of the pointer vector.
This function returns an iterator just past the last element of the pointer vector. In combination with the according begin function (see example), this iterator allows to iterate over all objects of type C in the range of the pointer vector. The attempt to use this function for types that are not derived from T results in a compile time error.
|
inline |
Returns an iterator just past the last element of the pointer vector.
This function returns an iterator just past the last element of the pointer vector. In combination with the according begin function (see example), this iterator allows to iterate over all objects of type C in the range of the pointer vector. The attempt to use this function for types that are not derived from T results in a compile time error.
|
inline |
Removing an element from the pointer vector.
pos | The position of the element to be removed. |
This function erases an element from the pointer vector, i.e. the element is deleted according to the deletion policy of the pointer vector and removed from the vector. Note that in case the deletion policy is NoDelete, this function is identical to the release() function.
|
inline |
Removing an element from the pointer vector.
pos | The position of the element to be removed. |
This function erases an element from the pointer vector, i.e. the element is deleted according to the deletion policy of the pointer vector and removed from the vector. Note that in case the deletion policy is NoDelete, this function is identical to the release() function.
|
inline |
Returns a reference to the first element of the pointer vector.
|
inline |
Returns a reference to the first element of the pointer vector.
|
inline |
Inserting an element into the pointer vector.
pos | The position before which the element is inserted. |
p | The pointer to be inserted into the pointer vector. |
std::length_error | Maximum pointer vector length exceeded. |
The insert function runs in linear time. Note however that inserting elements into a pointer vector can be a relatively time-intensive operation.
|
inline |
Inserting a range of elements into the pointer vector.
pos | The position before which the elements are inserted. |
first | Iterator to the first element of the element range. |
last | Iterator to the element one past the last element of the element range. |
std::length_error | Maximum pointer vector length exceeded. |
This functions inserts the elements in the range into the pointer vector. The insert function runs in linear time. Note however that inserting elements into a pointer vector can be a relatively time-intensive operation.
|
private |
Inserting an element into the pointer vector.
pos | The position before which the element is inserted. |
p | The pointer to be inserted into the pointer vector. |
std::length_error | Maximum pointer vector length exceeded. |
|
private |
Inserting a range of elements into the pointer vector.
pos | The position before which the elements are inserted. |
first | Iterator to the first element of the element range. |
last | Iterator to the element one past the last element of the element range. |
n | The number of elements to be inserted. |
std::length_error | Maximum pointer vector length exceeded. |
|
inline |
Returns true if the pointer vector has no elements.
|
inline |
Returns the maximum possible size of a pointer vector.
PtrVector< T, D, G > & blaze::PtrVector< T, D, G >::operator= | ( | const PtrVector< T, D, G > & | pv | ) |
Copy assignment operator for PtrVector.
pv | The pointer vector to be copied. |
PtrVector<T,D,G>& blaze::PtrVector< T, D, G >::operator= | ( | const PtrVector< T2, D2, G2 > & | pv | ) |
Assignment operator for different PtrVector instances.
pv | The pointer vector to be copied. |
|
inline |
Subscript operator for the direct access to the pointer vector elements.
index | Access index. The index has to be in the range ![]() |
|
inline |
Subscript operator for the direct access to the pointer vector elements.
index | Access index. The index has to be in the range ![]() |
|
inline |
Removing an element from the end of the pointer vector.
This function removes the element at the end of the pointer vector, i.e. the element is deleted according to the deletion policy and removed from the vector. Note that in case the deletion policy is NoDelete, this function is identical to the releaseBack() function.
|
inline |
Adding an element to the end of the pointer vector.
p | The pointer to be added to the end of the pointer vector. |
std::length_error | Maximum pointer vector length exceeded. |
The pushBack function runs in constant time.
|
inline |
Releasing an element from the pointer vector.
pos | The position of the element to be released. |
This function releases an element from the pointer vector, i.e. the element is removed without applying the deletion policy. Therefore the responsibility to delete the element is passed to the function caller.
|
inline |
Releasing an element from the pointer vector.
pos | The position of the element to be released. |
This function releases an element from the pointer vector, i.e. the element is removed without applying the deletion policy. Therefore the responsibility to delete the element is passed to the function caller.
|
inline |
Releasing the element at the end of the pointer vector.
This function releases the element at the end of the pointer vector, i.e. the element is removed without applying the deletion policy. Therefore the responsibility to delete the element is passed to the function caller. Note that in case the deletion policy is NoDelete, this function is identical to the popBack() function.
void blaze::PtrVector< T, D, G >::reserve | ( | SizeType | newCapacity | ) |
Setting the minimum capacity of the pointer vector.
newCapacity | The new minimum capacity of the pointer vector. |
|
inline |
Returns the current size of the pointer vector.
Returns the total number of objects of type C contained in the pointer vector.
This function calculates the total number of objects of type C within the pointer vector, where C is a type derived from the type T of objects contained in the pointer vector. The attempt to use this function for types that are not derived from T results in a compile time error.
|
inlinenoexcept |
Swapping the contents of two pointer vectors.
pv | The pointer vector to be swapped. |
no-throw | guarantee. |
|
friend |
Inequality comparison between two CastIterator objects.
lhs | The left hand side cast iterator. |
rhs | The right hand side cast iterator. |
|
friend |
Inequality comparison between a CastIterator and a ConstCastIterator.
lhs | The left hand side cast iterator. |
rhs | The right hand side constant cast iterator. |
|
friend |
Inequality comparison between a ConstCastIterator and a CastIterator.
lhs | The left hand side constant cast iterator. |
rhs | The right hand side cast iterator. |
|
friend |
Inequality comparison between two ConstCastIterator objects.
lhs | The left hand side constant cast iterator. |
rhs | The right hand side constant cast iterator. |
|
friend |
Equality comparison between two CastIterator objects.
lhs | The left hand side cast iterator. |
rhs | The right hand side cast iterator. |
|
friend |
Equality comparison between a CastIterator and a ConstCastIterator.
lhs | The left hand side cast iterator. |
rhs | The right hand side constant cast iterator. |
|
friend |
Equality comparison between a ConstCastIterator and a CastIterator.
lhs | The left hand side constant cast iterator. |
rhs | The right hand side cast iterator. |
|
friend |
Equality comparison between two ConstCastIterator objects.
lhs | The left hand side constant cast iterator. |
rhs | The right hand side constant cast iterator. |