PAbstractArray Class Reference

#include <array.h>

Inheritance diagram for PAbstractArray:

List of all members.

Public Member Functions
Overrides from class PObject
virtual void	PrintOn (ostream &strm) const
virtual void	ReadFrom (istream &strm)
virtual Comparison	Compare (const PObject &obj) const
Overrides from class PContainer
virtual BOOL	SetSize (PINDEX newSize)
New functions for class
void	Attach (const void *buffer, PINDEX bufferSize)
void *	GetPointer (PINDEX minSize=1)
BOOL	Concatenate (const PAbstractArray &array)
Protected Member Functions
BOOL	InternalSetSize (PINDEX newSize, BOOL force)
virtual void	PrintElementOn (ostream &stream, PINDEX index) const
virtual void	ReadElementFrom (istream &stream, PINDEX index)
Protected Attributes
PINDEX	elementSize
	Size of an element in bytes.
char *	theArray
	Pointer to the allocated block of memory.
BOOL	allocatedDynamically
	Flag indicating the array was allocated on the heap.
Friends
class	PArrayObjects

---

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 atuomatically 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,
		BOOL	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	(	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,
		BOOL	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.

---

Member Function Documentation

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.

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.

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: {description} [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. {description}

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.

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

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.

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.

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

BOOL PAbstractArray::InternalSetSize	(	PINDEX	newSize,
		BOOL	force
	)			[protected]

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

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

---

Friends And Related Function Documentation

friend class PArrayObjects [friend]

---

Member Data Documentation

PINDEX PAbstractArray::elementSize [protected]

Size of an element in bytes.

char* PAbstractArray::theArray [protected]

Pointer to the allocated block of memory.

BOOL PAbstractArray::allocatedDynamically [protected]

Flag indicating the array was allocated on the heap.

---

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

• array.h

---