This class contains a variable length array of arbitrary memory blocks. More...

#include <array.h>

Inheritance diagram for PAbstractArray:

Collaboration diagram for PAbstractArray:

Public Member Functions
Construction
	PAbstractArray (PINDEX elementSizeInBytes, PINDEX initialSize=0)
	Create a new dynamic array of `initalSize` elements of `elementSizeInBytes` bytes each. More...

	PAbstractArray (PINDEX elementSizeInBytes, const void *buffer, PINDEX bufferSizeInElements, PBoolean dynamicAllocation)
	Create a new dynamic array of `bufferSizeInElements` elements of `elementSizeInBytes` bytes each. More...

Overrides from class PObject
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...

virtual Comparison	Compare (const PObject &obj) const
	Get the relative rank of the two arrays. More...

Overrides from class PContainer
virtual PBoolean	SetSize (PINDEX newSize)
	Set the size of the array in elements. More...

New functions for class
void	Attach (const void *buffer, PINDEX bufferSize)
	Attach a pointer to a static block to the base array type. More...

void *	GetPointer (PINDEX minSize=1)
	Get a pointer to the internal array and assure that it is of at least the specified size. More...

const void *	GetPointer () const

virtual PINDEX	GetLength () const
	Retrun the length in bytes for the array. More...

PBoolean	Concatenate (const PAbstractArray &array)
	Concatenate one array to the end of this array. More...

Public Member Functions inherited from PContainer
	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...

virtual PINDEX	GetSize () const
	Get the current size of the container. More...

__inline size_t	size () const

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

Protected Member Functions
PBoolean	InternalSetSize (PINDEX newSize, PBoolean force)

virtual void	PrintElementOn (ostream &stream, PINDEX index) const

virtual void	ReadElementFrom (istream &stream, PINDEX index)

	PAbstractArray (PContainerReference &reference, PINDEX elementSizeInBytes)

Protected Member Functions inherited from PContainer
	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
PINDEX	elementSize
	Size of an element in bytes. More...

char *	theArray
	Pointer to the allocated block of memory. More...

PBoolean	allocatedDynamically
	Flag indicating the array was allocated on the heap. More...

Protected Attributes inherited from PContainer
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

This class contains a variable length array of arbitrary memory blocks.

These can be anything from individual bytes to large structures. Note that that does not include class objects that require construction or destruction. Elements in this array will not execute the contructors or destructors of objects.

An abstract array consists of a linear block of memory sufficient to hold PContainer::GetSize() elements of elementSize bytes each. The memory block itself will automatically be resized when required and freed when no more references to it are present.

The PAbstractArray class would very rarely be descended from directly by the user. The PBASEARRAY macro would normally be used to create a class and any new classes descended from that. That will instantiate the template based on PBaseArray or directly declare and define a class (using inline functions) if templates are not being used.

The PBaseArray class or PBASEARRAY macro will define the correctly typed operators for pointer access (operator const T *) and subscript access (operator[]).

Constructor & Destructor Documentation

PAbstractArray::PAbstractArray	(	PINDEX	elementSizeInBytes,
		PINDEX	initialSize = `0`
	)

Create a new dynamic array of initalSize elements of elementSizeInBytes bytes each.

The array memory is initialised to zeros.

If the initial size is zero then no memory is allocated. Note that the internal pointer is set to NULL, not to a pointer to zero bytes of memory. This can be an important distinction when the pointer is obtained via an operator created in the PBASEARRAY macro.

Parameters

elementSizeInBytes	Size of each element in the array. This must be > 0 or the constructor will assert.
initialSize	Number of elements to allocate initially.

PAbstractArray::PAbstractArray	(	PINDEX	elementSizeInBytes,
		const void *	buffer,
		PINDEX	bufferSizeInElements,
		PBoolean	dynamicAllocation
	)

Create a new dynamic array of bufferSizeInElements elements of elementSizeInBytes bytes each.

The contents of the memory pointed to by buffer is then used to initialise the newly allocated array.

If the initial size is zero then no memory is allocated. Note that the internal pointer is set to NULL, not to a pointer to zero bytes of memory. This can be an important distinction when the pointer is obtained via an operator created in the PBASEARRAY macro.

If the dynamicAllocation parameter is false then the pointer is used directly by the container. It will not be copied to a dynamically allocated buffer. If the SetSize() function is used to change the size of the buffer, the object will be converted to a dynamic form with the contents of the static buffer copied to the allocated buffer.

Parameters

elementSizeInBytes	Size of each element in the array. This must be > 0 or the constructor will assert.
buffer	Pointer to an array of elements.
bufferSizeInElements	Number of elements pointed to by buffer.
dynamicAllocation	Buffer is copied and dynamically allocated.

PAbstractArray::PAbstractArray	(	PContainerReference &	reference,
		PINDEX	elementSizeInBytes
	)

protected

Member Function Documentation

void PAbstractArray::Attach	(	const void *	buffer,
		PINDEX	bufferSize
	)

Attach a pointer to a static block to the base array type.

The pointer is used directly and will not be copied to a dynamically allocated buffer. If the SetSize() function is used to change the size of the buffer, the object will be converted to a dynamic form with the contents of the static buffer copied to the allocated buffer.

Any dynamically allocated buffer will be freed.

Parameters

buffer	Pointer to an array of elements.
bufferSize	Number of elements pointed to by buffer.

Referenced by PBaseArray< PHashTableList >::Attach().

virtual Comparison PAbstractArray::Compare ( const PObject & obj ) const

virtual

Get the relative rank of the two arrays.

The following algorithm is employed for the comparison:

EqualTo if the two array memory blocks are identical in length and contents.
LessThan if the array length is less than the obj parameters array length.
GreaterThan if the array length is greater than the obj parameters array length.

If the array sizes are identical then the memcmp() function is used to rank the two arrays.

Returns: Comparison of the two objects, EqualTo for same, LessThan for obj logically less than the object and GreaterThan for obj logically greater than the object.

Parameters

obj	Other `PAbstractArray` to compare against.

Reimplemented from PObject.

Reimplemented in PString.

PBoolean PAbstractArray::Concatenate ( const PAbstractArray & array )

Concatenate one array to the end of this array.

This function will allocate a new array large enough for the existing contents and the contents of the parameter. The parameters contents is then copied to the end of the existing array.

Note this does nothing and returns false if the target array is not dynamically allocated, or if the two arrays are of base elements of different sizes.

Returns: true if the memory allocation succeeded.

Parameters

array Array to concatenate.

Referenced by PBaseArray< PHashTableList >::Concatenate().

virtual PINDEX PAbstractArray::GetLength ( ) const

virtual

Retrun the length in bytes for the array.

Reimplemented in PStringStream, and PString.

void* PAbstractArray::GetPointer ( PINDEX minSize = 1 )

Get a pointer to the internal array and assure that it is of at least the specified size.

This is useful when the array contents are being set by some external or system function eg file read.

It is unsafe to assume that the pointer is valid for very long after return from this function. The array may be resized or otherwise changed and the pointer returned invalidated. It should be used for simple calls to atomic functions, or very careful examination of the program logic must be performed.

Returns: Pointer to the array memory.

Parameters

minSize Minimum size the array must be.

const void* PAbstractArray::GetPointer ( ) const

inline

References theArray.

Referenced by PString::c_str(), PString::data(), PBaseArray< PHashTableList >::GetPointer(), PString::substr(), and PTones::Write().

PBoolean PAbstractArray::InternalSetSize	(	PINDEX	newSize,
		PBoolean	force
	)

protected

virtual void PAbstractArray::PrintElementOn	(	ostream &	stream,
		PINDEX	index
	)		const

protectedvirtual

Reimplemented in PBaseArray< T >.

virtual void PAbstractArray::PrintOn ( ostream & strm ) const

virtual

Output the contents of the object to the stream.

The exact output is dependent on the exact semantics of the descendent class. This is primarily used by the standard operator<< function.

The default behaviour is to print the class name.

Reimplemented from PObject.

Reimplemented in PHexDump, PBYTEArray, and PCharArray.

virtual void PAbstractArray::ReadElementFrom	(	istream &	stream,
		PINDEX	index
	)

protectedvirtual

Reimplemented in PScalarArray< T >.

virtual void PAbstractArray::ReadFrom ( istream & strm )

virtual

Input the contents of the object from the stream.

The exact input is dependent on the exact semantics of the descendent class. This is primarily used by the standard operator>> function.

The default behaviour is to do nothing.

Reimplemented from PObject.

Reimplemented in PBYTEArray, and PCharArray.

virtual PBoolean PAbstractArray::SetSize ( PINDEX newSize )

virtual

Set the size of the array in elements.

A new array may be allocated to accomodate the new number of elements. If the array increases in size then the new bytes are initialised to zero. If the array is made smaller then the data beyond the new size is lost.

Returns: true if the memory for the array was allocated successfully.

Parameters

newSize New size of the array in elements.

Implements PContainer.

Reimplemented in PBitArray, PString, and PTones.

Member Data Documentation

PBoolean PAbstractArray::allocatedDynamically

protected

Flag indicating the array was allocated on the heap.

PINDEX PAbstractArray::elementSize

protected

Size of an element in bytes.

char* PAbstractArray::theArray

protected

Pointer to the allocated block of memory.

Referenced by PBYTEArray::GetAs(), PBaseArray< PHashTableList >::GetAt(), GetPointer(), PString::operator std::string(), PBaseArray< unsigned >::operator unsignedconst *(), PBaseArray< PHashTableList >::operator[](), and PBaseArray< PHashTableList >::SetAt().

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

array.h

Public Member Functions

Protected Member Functions

Protected Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation