Class Index Cross Index Namespace Index

template Class FrameCPP::Version_3_4_5::Container< class T >

Generic Container.
Contained in: FrameCPP::Version_3_4_5
Derived from: FrameCPP::Version_3_4_5::ContainerBase
Derived by: none

#include "../../../../../lib/framecpp/src/Version3_4_5/container.hh"


public function member index:

Container(); Default constructor.
Container(const Container< T >& c); Container copy constructor.
virtual ~Container(); Destructor.
iterator append(const T& data); Append an element to the end of the container.
iterator append(const T* data); Append an element to the end of the container.
iterator append(T* data, bool allocate = true, bool owns = true); Append an element to the end of the container.
T* back(); Returns the last item in the container.
const T* back() const; Returns the last item in the container.
iterator begin(); Returns an iterator at the beginning of the container.
const_iterator begin() const; Returns an iterator at the beginning of the container.
iterator end(); Returns an iterator at the end of the container.
const_iterator end() const; Returns an iterator at the end of the container.
void erase(unsigned int index); Erase an element.
void erase(iterator start, iterator finish); Erases a range of elements.
T* front(); Returns the first item in the container.
const T* front() const; Returns the first item in the container.
inline unsigned int getSize() const;
iterator insert(iterator iter, const T& data); Insert an element into the container.
iterator insert(iterator iter, const T* data); Insert an element into the container.
iterator insert(iterator iter, T* data, bool allocate = true, bool owns = true); Insert an element into the container.
iterator insert(size_t index, const T& data); Insert an element into the container.
iterator insert(size_t index, const T* data); Insert an element into the container.
iterator insert(size_t index, T* data, bool allocate = true, bool owns = true); Insert an element into the container.
bool isOwned(const_iterator iter) const; Returns the ownership of an element.
bool isOwned(size_t index) const; Returns the ownership of an element.
bool operator !=(const Container< T >& c) const;
const Container< T >& operator +=(const Container< T >& c); += Assignment operator.
const Container< T >& operator =(const Container< T >& c); Assignment operator.
bool operator ==(const Container< T >& c) const; Equality operator.
virtual T* operator [](unsigned int index);
virtual const T* operator [](unsigned int index) const;
void setOwnership(iterator iter, bool owns); Set Ownership
void setOwnership(size_t index, bool owns); Set Ownership.
unsigned int size() const; Returns the size of the container.
 

Description:

This implements a generic container object. It is a template class, and is used to store any type of frame object. Its principal feature is that it keeps track of ownership.

One of the principle problems when creating or using a container class is how to store the elements. If the user adds an element to the class, should it be copied, or should a reference to the added element be stored instead? If a reference (or pointer) is stored, the user must be careful about deallocating objects. If an element is destructed while a reference to it exists in a container, then a segmentation fault may occur. On the other hand, if an object is added to the container and the user doesn't destruct it, then there is a memory leak. If the programmer decides to implement a container which only copies elements, other trade-offs are made. If the container is storing large objects, then copying may take a significant amount of time and incur a large memory overhead. Furthermore, nesting containers may become awkward as the order in which containers are added becomes important or other overhead is required to obtain a reference to the copied element in the container.

One way to solve these problems is to implement a reference counting system. However, this can quickly become complicated. The method I have chosen is an ownership system.

There are two things which need to be known when adding an element to a container:

  1. Do I copy the object or use a reference?
  2. Who is responsible for deleting the object (i.e., who owns it)?

If the container copies the object upon insertion and subsequently owns it, then we have the first case above. If the container just inserts a reference and doesn't own it then we have the second case. Sometimes a mixture of the two is desired, for example if the user is creating objects (perhaps by reading them in from a stream) and inserting them into a container, they may not want to keep track of all of the pointers to delete them later (he wants the container to do that). But he also doesn't want to do another wasteful copy of the data. In this case, he would want a reference stored and the container to own the elements.

The system I have chosen solves the ownership issue by storing a flag along with each element which records the ownership state of that element. If the container owns the object, then it will get destructed whenever it is removed from the container (perhaps upon the destruction of the container itself). However, if the object is not owned then it will not be destroyed. To summarize, we have the following two states:

The ownership state of an element can be determined via the isOwned accessor. There are two versions, one taking an index and the other taking a constant iterator. It is possible to manipulate the ownership of an element via the setOwnership mutator.

When objects are inserted into the container, it is possible to specify whether they should be copied into the container or if only a reference should be stored.

By default, objects are copied into the container and the container will ownd the objects.

Implementation Notes:



Function Member Descriptions:


FrameCPP::Version_3_4_5::Container::Container - Default constructor.


Container();
This just creates an empty container.




FrameCPP::Version_3_4_5::Container::Container - Container copy constructor.


Container(const Container< T >& c);
This is the copy constructor for this class. It iterates through source container, copying its objects into this container. The manner in which it copies the elements depends upon their ownership in the source container. If the source container owns the element, then a copy of that element is made and inserted into the new container. The new container now owns that element. If the source container does not own the element, then the pointer to the element is inserted into the new container. A copy is not made, therefore the new container does NOT own the element. In Summary, we have:
   source                                     dest
   ownership      copy method                 ownership
   ---------      -----------                 ---------
   owned     ---> allocate copy          ---> owned
   unowned   ---> assign current pointer ---> unowned
 

Parameters:
ParameterDescription
const Container< T >& cThe container to copy from

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.



FrameCPP::Version_3_4_5::Container::~Container - Destructor.


virtual ~Container();
This deletes all of the owned objects in the container.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::append - Append an element to the end of the container.


iterator append(const T& data);
Memory for the element will be allocated and the container will own the new element.

Parameters:
ParameterDescription
const T& dataThe item to append.

Return value:
iterator- The iterator correspinding to the appended object.

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.



FrameCPP::Version_3_4_5::Container::append - Append an element to the end of the container.


iterator append(const T* data);
Memory for the element will be allocated and the container will own the new element.

Parameters:
ParameterDescription
const T* dataThe item to append.

Return value:
iterator- The iterator corresponding to the appended object.

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.



FrameCPP::Version_3_4_5::Container::append - Append an element to the end of the container.


iterator append(T* data, bool allocate = true, bool owns = true);
The user may also specifiy whether or not memory is allocated for the element (i.e., the element is copied) and if the container owns the element.

Parameters:
ParameterDescription
const T& dataThe item to append.
bool copyTrue if memory should be allocated and the element copied into the container (default: true).
bool ownsTrue if the container will own the element (default: true).

Return value:
iterator- The iterator corresponding to the appended object.

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.



FrameCPP::Version_3_4_5::Container::back - Returns the last item in the container.


T* back();

Return value:
T*- Last item.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::back - Returns the last item in the container.


const T* back() const;

Return value:
const T*- Last item.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::begin - Returns an iterator at the beginning of the container.


iterator begin();

Return value:
Container< T >::iterator- Beginning iterator.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::begin - Returns an iterator at the beginning of the container.


const_iterator begin() const;

Return value:
Container< T >::const_iterator- Beginning iterator.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::end - Returns an iterator at the end of the container.


iterator end();

Return value:
Container< T >::iterator- End iterator.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::end - Returns an iterator at the end of the container.


const_iterator end() const;

Return value:
Container< T >::const_iterator- End iterator.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::erase - Erase an element.


void erase(unsigned int index);
This erases an element at the specified index. If the index is out of range then nothing happens.

Parameters:
ParameterDescription
unsigned int indexElement index.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::erase - Erases a range of elements.


void erase(iterator start, iterator finish);
If end is less thatn start or any of the iterators are out of range then nothing will happen.

Parameters:
ParameterDescription
iterator startRange start.
iterator finishRange end.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::front - Returns the first item in the container.


T* front();

Return value:
T*- First item.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::front - Returns the first item in the container.


const T* front() const;

Return value:
const T*- First item.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::getSize


inline unsigned int getSize() const;



FrameCPP::Version_3_4_5::Container::insert - Insert an element into the container.


iterator insert(iterator iter, const T& data);
The element will be copied and the container will own the new element.

Parameters:
ParameterDescription
iterator iterAn iterator pointing to the location where the element should be added.
const T& dataThe item to add.

Return value:
iterator- An iterator pointing to the added item.

Exceptions:
ExceptionDescription
std::bad_allocMemory could not be allocated for the element.



FrameCPP::Version_3_4_5::Container::insert - Insert an element into the container.


iterator insert(iterator iter, const T* data);
The element will be copied and the container will own the new element.

Parameters:
ParameterDescription
iterator iterAn iterator pointing to the location where the element should be added.
const T* dataThe item to add.

Return value:
iterator- An iterator pointing to the added item.

Exceptions:
ExceptionDescription
std::bad_allocMemory could not be allocated for the element.



FrameCPP::Version_3_4_5::Container::insert - Insert an element into the container.


iterator insert(iterator iter, T* data, bool allocate = true, bool owns = true);

Parameters:
ParameterDescription
iterator iterAn iterator pointing to the location where the element should be added.
T* dataThe item to add.
bool copyDuplicate passed data or not.
bool ownsDestroy the data when container is destroyed or not.

Return value:
iterator- An iterator pointing to the added item.

Exceptions:
ExceptionDescription
std::bad_allocMemory could not be allocated for the element.



FrameCPP::Version_3_4_5::Container::insert - Insert an element into the container.


iterator insert(size_t index, const T& data);
The element will be copied and the container will own the new element.

Parameters:
ParameterDescription
size_t indexThe index at which the element should be added. If the index is out of range then the element will be inserted at the end.
const T& dataThe item to add.

Return value:
iterator- An iterator pointing to the added item.

Exceptions:
ExceptionDescription
std::bad_allocMemory could not be allocated for the element.



FrameCPP::Version_3_4_5::Container::insert - Insert an element into the container.


iterator insert(size_t index, const T* data);
The element will be copied and the container will own the new element.

Parameters:
ParameterDescription
size_t indexThe index at which the element should be added. If the index is out of range then the element will be inserted at the end.
const T* dataThe item to add.

Return value:
iterator- An iterator pointing to the added item.

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.



FrameCPP::Version_3_4_5::Container::insert - Insert an element into the container.


iterator insert(size_t index, T* data, bool allocate = true, bool owns = true);

Parameters:
ParameterDescription
size_t indexThe index at which the element should be added. If the index is out of range then the element will be inserted at the end.
T* dataThe item to add.
bool copyDuplicate passed data or not.
bool ownsDestroy the data when container is destroyed or not.

Return value:
iterator- An iterator pointing to the added item.

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.



FrameCPP::Version_3_4_5::Container::isOwned - Returns the ownership of an element.


bool isOwned(const_iterator iter) const;
Currently, no range checking is done.

Parameters:
ParameterDescription
const_iterator iterA constant iterator pointing to an element in the container.

Return value:
bool- True if the object is owned by the container.


FrameCPP::Version_3_4_5::Container::isOwned - Returns the ownership of an element.


bool isOwned(size_t index) const;
Currently, no range checking is done.

Parameters:
ParameterDescription
size_t indexIndex.

Return value:
bool- True if the object is owned by the container.


FrameCPP::Version_3_4_5::Container::operator !=


bool operator !=(const Container< T >& c) const;
Inequality operator. This chacks to see if two containers do not contain identical elements. The ownership of the elements does not matter.

Parameters:
ParameterDescription
const Container< T >& cThe container to compare with.

Return value:
bool- true if the containers are not equal.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::operator += - += Assignment operator.


const Container< T >& operator +=(const Container< T >& c);
This concatenates another container to this one.

Parameters:
ParameterDescription
const Container< T >& cThe container to assign from.

Return value:
const Container< T >&- This container.

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.
frame_mismatch`T' mismatch.



FrameCPP::Version_3_4_5::Container::operator = - Assignment operator.


const Container< T >& operator =(const Container< T >& c);
This copies another container to this one. Ownership is handled in the same manner as in the copy constructor.

Parameters:
ParameterDescription
const Container< T >& cThe container to assign from.

Return value:
const Container< T >&- This container.

Exceptions:
ExceptionDescription
std::bad_allocMemory allocation failed.



FrameCPP::Version_3_4_5::Container::operator == - Equality operator.


bool operator ==(const Container< T >& c) const;
This checks to see if two containers contain identical elements. The ownership of the elements does not matter.

Parameters:
ParameterDescription
const Container< T >& cThe container to compare with.

Return value:
bool- true if the containers are equal.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::operator []


virtual T* operator [](unsigned int index);
Array access operator. This returns the element at the specified index or a null pointer if the index is out-of-range.

Parameters:
ParameterDescription
size_t indexThe index of the desired element.

Return value:
T*- A pointer to the object stored at the index. T* -- A constant pointer to the object stored at the index.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::operator []


virtual const T* operator [](unsigned int index) const;
Array access operator. This returns the element at the specified index or a null pointer if the index is out-of-range.

Parameters:
ParameterDescription
size_t indexThe index of the desired element.

Return value:
const T*- A constant pointer to the object stored at the index.

Exceptions:
ExceptionDescription
None.



FrameCPP::Version_3_4_5::Container::setOwnership - Set Ownership


void setOwnership(iterator iter, bool owns);
Sets the ownsership for the element pointed to by iter.

Parameters:
ParameterDescription
iterator iterThe element whose ownership will be modified.
bool ownstrue if the container should own the data, false otherwise.



FrameCPP::Version_3_4_5::Container::setOwnership - Set Ownership.


void setOwnership(size_t index, bool owns);
Sets the ownsership for the element at the given index.

Parameters:
ParameterDescription
size_t indexThe element whose ownership will be modified.
bool ownsTrue if the container should own the data, false otherwise.



FrameCPP::Version_3_4_5::Container::size - Returns the size of the container.


unsigned int size() const;

Return value:
size_t- The number of objects in the container.

Exceptions:
ExceptionDescription
None.



Variable Member Descriptions:


FrameCPP::Version_3_4_5::Container::mData - Contained objects.

std::vector< T* > mData;

FrameCPP::Version_3_4_5::Container::mOwns - True if an object is owned by the container.

std::vector< bool > mOwns;