Class Index | Cross Index | Namespace Index |
Generic ContainerBasic.
Contained in: FrameCPP
Derived from:
FrameCPP::ContainerBase
Derived by:
none
#include "framecpp/ContainerBasic.hh"
public function member index: |
|||
ContainerBasic | (); | Default constructor. | |
ContainerBasic | (const ContainerBasic< T >& c); | ContainerBasic copy constructor. | |
virtual | ~ContainerBasic | (); | 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, bool owns); | 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. |
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, bool owns); | 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, bool owns); | 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 ContainerBasic< T >& c) const; | |
const ContainerBasic< T >& | operator += | (const ContainerBasic< T >& c); | += Assignment operator. |
const ContainerBasic< T >& | operator = | (const ContainerBasic< T >& c); | Assignment operator. |
bool | operator == | (const ContainerBasic< T >& c) const; | Equality operator. |
virtual T* | operator [] | (unsigned int index); | |
virtual const T* | operator [] | (unsigned int index) const; | |
reverse_iterator | rbegin | (); | |
const_reverse_iterator | rbegin | () const; | |
reverse_iterator | rend | (); | |
const_reverse_iterator | rend | () const; | |
void | setOwnership | (iterator iter, bool owns); | Set Ownership |
void | setOwnership | (size_t index, bool owns); | Set Ownership. |
virtual unsigned int | size | () const; | Returns the size of the container. |
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:
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:
This just creates an empty container.
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:
Parameter | Description |
const ContainerBasic< T >& c | The container to copy from |
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
This deletes all of the owned objects in the container.
Exceptions:
Exception | Description |
None. |
Memory for the element will be allocated and the container will own the new element.
Parameters:
Parameter | Description |
const T& data | The item to append. |
Return value:
iterator- The iterator correspinding to the appended object.
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
Memory for the element will be allocated and the container will own the new element.
Parameters:
Parameter | Description |
const T* data | The item to append. |
Return value:
iterator- The iterator corresponding to the appended object.
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
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:
Parameter | Description |
const T& data | The item to append. |
bool copy | True if memory should be allocated and the element copied into the container (default: true). |
bool owns | True if the container will own the element (default: true). |
Return value:
iterator- The iterator corresponding to the appended object.
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
Return value:
T*- Last item.
Exceptions:
Exception | Description |
None. |
Return value:
const T*- Last item.
Exceptions:
Exception | Description |
None. |
Return value:
ContainerBasic< T >::iterator- Beginning iterator.
Exceptions:
Exception | Description |
None. |
Return value:
ContainerBasic< T >::const_iterator- Beginning iterator.
Exceptions:
Exception | Description |
None. |
Return value:
ContainerBasic< T >::iterator- End iterator.
Exceptions:
Exception | Description |
None. |
Return value:
ContainerBasic< T >::const_iterator- End iterator.
Exceptions:
Exception | Description |
None. |
This erases an element at the specified index. If the index is out of range then nothing happens.
Parameters:
Parameter | Description |
unsigned int index | Element index. |
Exceptions:
Exception | Description |
None. |
If end is less thatn start or any of the iterators are out of range then nothing will happen.
Parameters:
Parameter | Description |
iterator start | Range start. |
iterator finish | Range end. |
Exceptions:
Exception | Description |
None. |
Return value:
T*- First item.
Exceptions:
Exception | Description |
None. |
Return value:
const T*- First item.
Exceptions:
Exception | Description |
None. |
The element will be copied and the container will own the new element.
Parameters:
Parameter | Description |
iterator iter | An iterator pointing to the location where the element should be added. |
const T& data | The item to add. |
Return value:
iterator- An iterator pointing to the added item.
Exceptions:
Exception | Description |
std::bad_alloc | Memory could not be allocated for the element. |
The element will be copied and the container will own the new element.
Parameters:
Parameter | Description |
iterator iter | An iterator pointing to the location where the element should be added. |
const T* data | The item to add. |
Return value:
iterator- An iterator pointing to the added item.
Exceptions:
Exception | Description |
std::bad_alloc | Memory could not be allocated for the element. |
Parameters:
Parameter | Description |
iterator iter | An iterator pointing to the location where the element should be added. |
T* data | The item to add. |
bool copy | Duplicate passed data or not. |
bool owns | Destroy the data when container is destroyed or not. |
Return value:
iterator- An iterator pointing to the added item.
Exceptions:
Exception | Description |
std::bad_alloc | Memory could not be allocated for the element. |
The element will be copied and the container will own the new element.
Parameters:
Parameter | Description |
size_t index | The 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& data | The item to add. |
Return value:
iterator- An iterator pointing to the added item.
Exceptions:
Exception | Description |
std::bad_alloc | Memory could not be allocated for the element. |
The element will be copied and the container will own the new element.
Parameters:
Parameter | Description |
size_t index | The 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* data | The item to add. |
Return value:
iterator- An iterator pointing to the added item.
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
Parameters:
Parameter | Description |
size_t index | The 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* data | The item to add. |
bool copy | Duplicate passed data or not. |
bool owns | Destroy the data when container is destroyed or not. |
Return value:
iterator- An iterator pointing to the added item.
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
Currently, no range checking is done.
Parameters:
Parameter | Description |
const_iterator iter | A constant iterator pointing to an element in the container. |
Return value:
bool- True if the object is owned by the container.
Currently, no range checking is done.
Parameters:
Parameter | Description |
size_t index | Index. |
Return value:
bool- True if the object is owned by the container.
Inequality operator. This chacks to see if two containers do not contain identical elements. The ownership of the elements does not matter.
Parameters:
Parameter | Description |
const ContainerBasic< T >& c | The container to compare with. |
Return value:
bool- true if the containers are not equal.
Exceptions:
Exception | Description |
None. |
This concatenates another container to this one.
Parameters:
Parameter | Description |
const ContainerBasic< T >& c | The container to assign from. |
Return value:
const ContainerBasic< T >&- This container.
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
frame_mismatch | `T' mismatch. |
This copies another container to this one. Ownership is handled in the same manner as in the copy constructor.
Parameters:
Parameter | Description |
const ContainerBasic< T >& c | The container to assign from. |
Return value:
const ContainerBasic< T >&- This container.
Exceptions:
Exception | Description |
std::bad_alloc | Memory allocation failed. |
This checks to see if two containers contain identical elements. The ownership of the elements does not matter.
Parameters:
Parameter | Description |
const ContainerBasic< T >& c | The container to compare with. |
Return value:
bool- true if the containers are equal.
Exceptions:
Exception | Description |
None. |
Array access operator. This returns the element at the specified index or a null pointer if the index is out-of-range.
Parameters:
Parameter | Description |
size_t index | The 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:
Exception | Description |
None. |
Array access operator. This returns the element at the specified index or a null pointer if the index is out-of-range.
Parameters:
Parameter | Description |
size_t index | The index of the desired element. |
Return value:
const T*- A constant pointer to the object stored at the index.
Exceptions:
Exception | Description |
None. |
Sets the ownsership for the element pointed to by iter.
Parameters:
Parameter | Description |
iterator iter | The element whose ownership will be modified. |
bool owns | true if the container should own the data, false otherwise. |
Sets the ownsership for the element at the given index.
Parameters:
Parameter | Description |
size_t index | The element whose ownership will be modified. |
bool owns | True if the container should own the data, false otherwise. |
Return value:
size_t- The number of objects in the container.
Exceptions:
Exception | Description |
None. |