Abstract class to embody the base functionality of a container. More...

#include <contain.h>

Inheritance diagram for PContainer:

Collaboration diagram for PContainer:

Public Member Functions
Construction
	PContainer (PINDEX initialSize=0)
	Create a new unique container. More...

	PContainer (const PContainer &cont)
	Create a new refernce to container. More...

PContainer &	operator= (const PContainer &cont)
	Assign one container reference to another. More...

virtual	~PContainer ()
	Destroy the container class. More...

Common functions for containers
virtual PINDEX	GetSize () const
	Get the current size of the container. More...

__inline size_t	size () const

virtual PBoolean	SetSize (PINDEX newSize)=0
	Set the new current size of the container. More...

PBoolean	SetMinSize (PINDEX minSize)
	Set the minimum size of container. More...

virtual PBoolean	IsEmpty () const
	Determine if the container is empty. More...

__inline bool	empty () const

PBoolean	IsUnique () const
	Determine if container is unique reference. More...

virtual PBoolean	MakeUnique ()
	Make this instance to be the one and only reference to the container contents. More...

Public Member Functions inherited from PObject
__inline unsigned	GetTraceContextIdentifier () const
	Get PTRACE context identifier. More...

__inline void	SetTraceContextIdentifier (unsigned id)

__inline void	SetTraceContextIdentifier (const PObject &obj)

__inline void	SetTraceContextIdentifier (const PObject *obj)

__inline void	CopyTraceContextIdentifier (PObject &obj) const

__inline void	CopyTraceContextIdentifier (PObject *obj) const

virtual	~PObject ()

__inline const char *	GetClass () const

__inline bool	IsClass (const char *name) const

__inline const PObject *	PTraceObjectInstance () const

virtual PObject *	Clone () const
	Create a copy of the class on the heap. More...

template<class CLS >
CLS *	CloneAs () const
	As for Clone() but converts to specified type. More...

virtual PINDEX	HashFunction () const
	This function yields a hash value required by the `PDictionary` class. More...

virtual Comparison	Compare (const PObject &obj) const
	Compare the two objects and return their relative rank. More...

virtual Comparison	CompareObjectMemoryDirect (const PObject &obj) const
	Determine the byte wise comparison of two objects. More...

bool	operator== (const PObject &obj) const
	Compare the two objects. More...

bool	operator!= (const PObject &obj) const
	Compare the two objects. More...

bool	operator< (const PObject &obj) const
	Compare the two objects. More...

bool	operator> (const PObject &obj) const
	Compare the two objects. More...

bool	operator<= (const PObject &obj) const
	Compare the two objects. More...

bool	operator>= (const PObject &obj) const
	Compare the two objects. More...

virtual void	PrintOn (ostream &strm) const
	Output the contents of the object to the stream. More...

virtual void	ReadFrom (istream &strm)
	Input the contents of the object from the stream. More...

Protected Member Functions
	PContainer (int dummy, const PContainer *cont)
	Constructor used in support of the Clone() function. More...

	PContainer (PContainerReference &reference)
	Construct using static PContainerReference. More...

virtual void	DestroyContents ()=0
	Destroy the container contents. More...

virtual void	AssignContents (const PContainer &c)
	Copy the container contents. More...

void	CopyContents (const PContainer &c)
	Copy the container contents. More...

void	CloneContents (const PContainer *src)
	Create a duplicate of the container contents. More...

void	Destruct ()
	Internal function called from container destructors. More...

virtual void	DestroyReference ()
	Destroy the PContainerReference instance. More...

Protected Member Functions inherited from PObject
	PObject ()
	Constructor for PObject, made protected so cannot ever create one on its own. More...

Protected Attributes
PContainerReference *	reference

Protected Attributes inherited from PObject
unsigned	m_traceContextIdentifier

Additional Inherited Members
Public Types inherited from PObject
enum	Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
	Result of the comparison operation performed by the `Compare()` function. More...

Static Public Member Functions inherited from PObject
static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject &to, const PObject *from)

static __inline void	CopyTraceContextIdentifier (PObject *to, const PObject &from)

static __inline void	CopyTraceContextIdentifier (PObject to, const PObject from)

static __inline const char *	Class ()

static __inline const PObject *	PTraceObjectInstance (const char *)

static __inline const PObject *	PTraceObjectInstance (const PObject *obj)

template<typename T >
static Comparison	Compare2 (T v1, T v2)
	Compare two types, returning Comparison type. More...

static Comparison	InternalCompareObjectMemoryDirect (const PObject obj1, const PObject obj2, PINDEX size)
	Internal function caled from CompareObjectMemoryDirect() More...

Detailed Description

Abstract class to embody the base functionality of a container.

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.

Constructor & Destructor Documentation

PContainer::PContainer ( PINDEX initialSize = 0 )

Create a new unique container.

Parameters

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.

Parameters

cont	Container to create a new reference from.

virtual PContainer::~PContainer ( )

inlinevirtual

Destroy the container class.

This will decrement the reference count on the contents and if unique, will destroy it using the DestroyContents() function.

References Destruct().

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.

Parameters

dummy	Dummy to prevent accidental use of the constructor.
cont	Container class to clone.

PContainer::PContainer ( PContainerReference & reference )

protected

Construct using static PContainerReference.

Member Function Documentation

virtual void PContainer::AssignContents ( const PContainer & c )

protectedvirtual

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 PStringStream, PString, PHTML, PFilePath, PSharedPtr< T >, and PSharedPtr< PExternalThread >.

Referenced by PSharedPtr< PExternalThread >::AssignContents().

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 PCONTAINERINFO() 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.

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 PCONTAINERINFO() 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.

virtual void PContainer::DestroyContents ( )

protectedpure 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 PCONTAINERINFO() 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 PHashTableInfo, PSharedPtr< T >, and PSharedPtr< PExternalThread >.

virtual void PContainer::DestroyReference ( )

protectedvirtual

Destroy the PContainerReference instance.

Override if passing a static vallue in via ctor.

void PContainer::Destruct ( )

protected

Internal function called from container destructors.

This will conditionally call DestroyContents() to destroy the container contents.

Referenced by PDirectory::Destruct(), ~PContainer(), PHashTableInfo::~PHashTableInfo(), and PSharedPtr< PExternalThread >::~PSharedPtr().

__inline bool PContainer::empty ( ) const

inline

References IsEmpty().

virtual 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.

Returns: number of objects in container.

Reimplemented in PBitArray, and PArrayObjects.

Referenced by PString::capacity(), PHashTableInfo::Clone(), PBaseArray< PHashTableList >::Clone(), PCharArray::Clone(), PBYTEArray::Clone(), P_WXWINDOWS_DEVICE_CLASS::FrameComplete(), PBYTEArray::GetAs(), PSound::GetFormatInfoSize(), PXMLElement::HasAttributes(), PSSLCipherContext::SetIV(), PSSLCipherContext::SetKey(), size(), PStack< T >::Top(), and PTones::Write().

virtual PBoolean PContainer::IsEmpty ( ) const

virtual

Determine if the container is empty.

Determine if the container that this object references contains any elements.

Returns: true if GetSize() returns zero.

Reimplemented in PString.

Referenced by PSortedList< PString >::begin(), empty(), PXMLElement::HasSubObjects(), and PSortedList< PString >::rbegin().

PBoolean PContainer::IsUnique ( ) const

Determine if container is unique reference.

Determine if this instance is the one and only reference to the container contents.

Returns: true if the reference count is one.

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.

Returns: true if the instance was already unique.

Reimplemented in PString, PSharedPtr< T >, and PSharedPtr< PExternalThread >.

Referenced by PSharedPtr< PExternalThread >::MakeUnique(), PStringOptions::RemoveAt(), and PStringOptions::SetAt().

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.

Parameters

cont	Container to create a new reference from.

Referenced by PStringOptions::operator=().

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.

Parameters

minSize Possible, new size for the container.

Referenced by PBaseArray< PHashTableList >::operator[](), and PBaseArray< PHashTableList >::SetAt().

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 true always and the new value is ignored.

Returns: true if the size was successfully changed. The value false usually indicates failure due to insufficient memory.

Parameters

newSize New size for the container.

Implemented in PBitArray, PAbstractSortedList, PArrayObjects, PString, PHashTable, PAbstractArray, PTones, PAbstractList, PSharedPtr< T >, and PSharedPtr< PExternalThread >.

__inline size_t PContainer::size ( ) const

inline

References GetSize().

Member Data Documentation

PContainerReference* PContainer::reference

protected

Referenced by PQueue< PXMLElement >::PQueue(), PSet< PString >::PSet(), and PStack< T >::PStack().

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

contain.h

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation