#include <contain.h>
Inheritance diagram for PContainer:
Construction | |
| PContainer (PINDEX initialSize=0) | |
| PContainer (const PContainer &cont) | |
| PContainer & | operator= (const PContainer &cont) |
| virtual | ~PContainer () |
Public Member Functions | |
Common functions for containers | |
| virtual PINDEX | GetSize () const |
| virtual PBoolean | SetSize (PINDEX newSize)=0 |
| PBoolean | SetMinSize (PINDEX minSize) |
| virtual PBoolean | IsEmpty () const |
| PBoolean | IsUnique () const |
| virtual PBoolean | MakeUnique () |
Protected Member Functions | |
| PContainer (int dummy, const PContainer *cont) | |
| virtual void | DestroyContents ()=0 |
| virtual void | AssignContents (const PContainer &c) |
| void | CopyContents (const PContainer &c) |
| void | CloneContents (const PContainer *src) |
| void | Destruct () |
Protected Attributes | |
| PContainerReference * | reference |
Fundamentally, a container is an object that contains other objects. There are two main areas of support for tha that are provided by this class. The first is simply to keep a count of the number of things that the container contains. The current size is stored and accessed by members of this class. The setting of size is determined by the semantics of the descendent class and so is a pure function.
The second area of support is for reference integrity. When an instance of a container is copied to another instance, the two instance contain the same thing. There can therefore be multiple references to the same things. When one reference is destroyed this must { not} destroy the contained object as it may be referenced by another instance of a container class. To this end a reference count is provided by the PContainer class. This assures that the container only destroys the objects it contains when there are no more references to them.
In support of this, descendent classes must provide a DestroyContents()# function. As the normal destructor cannot be used, this function will free the memory or unlock the resource the container is wrapping.
| PContainer::PContainer | ( | PINDEX | initialSize = 0 |
) |
Create a new unique container.
| initialSize | Initial number of things in the container. |
| PContainer::PContainer | ( | const PContainer & | cont | ) |
Create a new refernce to container. Create a new container referencing the same contents as the container specified in the parameter.
| cont | Container to create a new reference from. |
| virtual PContainer::~PContainer | ( | ) | [inline, virtual] |
Destroy the container class. This will decrement the reference count on the contents and if unique, will destroy it using the DestroyContents()# function.
| PContainer::PContainer | ( | int | dummy, | |
| const PContainer * | cont | |||
| ) | [protected] |
Constructor used in support of the Clone() function. This creates a new unique reference of a copy of the contents. It does { not} create another reference.
The dummy parameter is there to prevent the contructor from being invoked automatically by the compiler when a pointer is used by accident when a normal instance or reference was expected. The container would be silently cloned and the copy used instead of the container expected leading to unpredictable results.
| dummy | Dummy to prevent accidental use of the constructor. |
| cont | Container class to clone. |
| PINLINE PContainer & PContainer::operator= | ( | const PContainer & | cont | ) |
Assign one container reference to another. Set the current container to reference the same thing as the container specified in the parameter.
Note that the old contents of the container is dereferenced and if it was unique, destroyed using the DestroyContents() function.
| cont | Container to create a new reference from. |
| PINLINE PINDEX PContainer::GetSize | ( | ) | const [virtual] |
Get the current size of the container. This represents the number of things the container contains. For some types of containers this will always return 1.
| virtual PBoolean PContainer::SetSize | ( | PINDEX | newSize | ) | [pure virtual] |
Set the new current size of the container. The exact behavious of this is determined by the descendent class. For instance an array class would reallocate memory to make space for the new number of elements.
Note for some types of containers this does not do anything as they inherently only contain one item. The function returns PTrue always and the new value is ignored.
| newSize | New size for the container. |
Implemented in PAbstractArray, PHashTable, PAbstractList, PAbstractSortedList, PSharedPtr< T >, and PString.
| PBoolean PContainer::SetMinSize | ( | PINDEX | minSize | ) |
Set the minimum size of container. This function will set the size of the object to be at least the size specified. The SetSize()# function is always called, either with the new value or the previous size, whichever is the larger.
| minSize | Possible, new size for the container. |
| PINLINE PBoolean PContainer::IsEmpty | ( | ) | const [virtual] |
| PINLINE PBoolean PContainer::IsUnique | ( | ) | const |
Determine if container is unique reference. Determine if this instance is the one and only reference to the container contents.
| virtual PBoolean PContainer::MakeUnique | ( | ) | [virtual] |
Make this instance to be the one and only reference to the container contents. This implicitly does a clone of the contents of the container to make a unique reference. If the instance was already unique then the function does nothing.
Reimplemented in PSharedPtr< T >, and PString.
| virtual void PContainer::DestroyContents | ( | ) | [protected, pure virtual] |
Destroy the container contents. This function must be defined by the descendent class to do the actual destruction of the contents. It is automatically declared when the PDECLARE_CONTAINER()# macro is used.
For all descendent classes not immediately inheriting off the PContainer itself, the implementation of DestroyContents() should always call its ancestors function. This is especially relevent if many of the standard container classes, such as arrays, are descended from as memory leaks will occur.
Implemented in PSharedPtr< T >.
| virtual void PContainer::AssignContents | ( | const PContainer & | c | ) | [protected, virtual] |
Copy the container contents. This copies the contents from one reference to another.
No duplication of contents occurs, for instance if the container is an array, the pointer to the array memory is copied, not the array memory block itself.
This function will get called by the base assignment operator.
Reimplemented in PFilePath, PSharedPtr< T >, PStringStream, and PHTML.
| PINLINE void PContainer::CopyContents | ( | const PContainer & | c | ) | [protected] |
Copy the container contents. This copies the contents from one reference to another. It is automatically declared when the PDECLARE_CONTAINER()# macro is used.
No duplication of contents occurs, for instance if the container is an array, the pointer to the array memory is copied, not the array memory block itself.
This function will get called once for every class in the heirarchy, so the ancestor function should { not} be called.
Reimplemented in PSharedPtr< T >.
| PINLINE void PContainer::CloneContents | ( | const PContainer * | src | ) | [protected] |
Create a duplicate of the container contents. This copies the contents from one container to another, unique container. It is automatically declared when the PDECLARE_CONTAINER()# macro is used.
This class will duplicate the contents completely, for instance if the container is an array, the actual array memory is copied, not just the pointer. If the container contains objects that descend from PObject#, they too should also be cloned and not simply copied.
This function will get called once for every class in the heirarchy, so the ancestor function should { not} be called.
{ { Note well}}, the logic of the function must be able to accept the passed in parameter to clone being the same instance as the destination object, ie during execution this == src#.
Reimplemented in PSharedPtr< T >.
| void PContainer::Destruct | ( | ) | [protected] |
Internal function called from container destructors. This will conditionally call DestroyContents()# to destroy the container contents.
Reimplemented in PDirectory.
PContainerReference* PContainer::reference [protected] |
1.5.1