Array that can own or reference a dynamically allocated C array. More...

#include <DRArray.h>

Inheritance diagram for Util::DRArray< Data >:

Public Member Functions
	DRArray ()
	Default constructor.
	DRArray (int capacity)
	Allocating constructor.
	DRArray (DRArray< Data > const &other)
	Copy constructor.
	~DRArray ()
	Destructor.
DRArray< Data > &	operator= (DRArray< Data > const &other)
	Assignment from another DRArray<Data> container.
DRArray< Data > &	operator= (Array< Data > const &other)
	Assignment from an Array<Data> container.
void	allocate (int capacity)
	Allocate an underlying C array, which this container then owns.
void	deallocate ()
	Dellocate an underlying C array that is owned by this container.
void	associate (DRArray< Data > &arr, int beginId, int capacity)
	Associate this object with a slice of a different DRArray.
void	dissociate ()
	Dissociate this object from an externally owned array slice.
bool	isAllocated () const
	Return true if this container has data, false otherwise.
bool	isOwner () const
	Does this container own a dynamically allocated C array?
bool	isAssociated () const
	Is this container associated with a C array it does not own?
Public Member Functions inherited from Util::Array< Data >
int	capacity () const
	Return allocated size.
void	begin (ArrayIterator< Data > &iterator)
	Set an iterator to begin this Array.
void	begin (ConstArrayIterator< Data > &iterator) const
	Set a const iterator to begin this Array.
Data &	operator[] (int i)
	Get an element by non-const reference.
Data const &	operator[] (int i) const
	Get an element by const reference.
Data *	cArray ()
	Return a pointer to the underlying C array.
Data const *	cArray () const
	Return pointer to const to the underlying C array.

Protected Attributes
ReferenceCounter	refCounter_
	Counter for any containers that reference data owned by this.
CountedReference	ref_
	Reference to a container that owns memory referenced by this.
Protected Attributes inherited from Util::Array< Data >
Data *	data_
	Pointer to an array of Data elements.
int	capacity_
	Allocated size of the data_ array.

Additional Inherited Members
Protected Member Functions inherited from Util::Array< Data >
	Array ()
	Constructor (protected to provent direct instantiation).
	~Array ()
	Destructor (protected to prevent direct destruction).

Detailed Description

template<typename Data>
class Util::DRArray< Data >

Array that can own or reference a dynamically allocated C array.

A DRArray<Data> object wraps a dynamically allocated C array with elements of type Data, and stores the array capacity. A DRArray may either own a C array that it is responsible for de-allocating, or it may reference a slice of an array that is owned by another DRArray. In either case, individual elements may be accessed via a subscript operator (an overloaded operator []) that is inherited from the Array<Data> base class. Member functions for memory management allow a DRArray to allocate or deallocate a C array that it owns, or to become associated with or dissociated from an array slice that it does not own.

A DRArray may be in any of three states:

(1) Unallocated: In this state, there is no associated memory, so capacity() returns 0, while isAllocated(), isOwner() and isAssociated() all return false.

(2) A data owner: In this case, this object owns a C array that it is responsible for de-allocating. In this state, capacity() returns a positive integer, isAllocated() and isOwner() return true, and isAssociated() returns false.

(3) A data user: In this case, this object has a pointer to a C array that is owned by a different DRArray object. We describe this by saying that this DRArray (the data user) is "associated" with a C array that is owned by another object (the data owner), or that the data user "references" that array. In this state, capacity() returns a positive value, isAllocated() and isAssociated() return true, and isOwner() returns false.

A DRArray that owns a C array that is referenced by one or more other associated DRArray objects maintains a count of how many other such objects reference its data. This counter is automatically incremented when a reference is created and decremented when an existing reference is destroyed.

It is a logical error to invoke the deallocate() member function of a DRArray that is unallocated or that references data that it does not own. In either case, an Exception is thrown. It is also an error to attempt to deallocate a C array that is owned by one DRArray but also referenced by one or more other associated DRArray objects. Attempts to deallocate such a shared array will either cause an Exception to be thrown, if deallocation is attempted by invoking the deallocate() member function, or cause an error message to be written to std::cout, if deallocation is attempted during destruction of the data owner object. Such references must instead be released by invoking the dissociate() member function of every associated data user object before the data owner is destroyed.

Definition at line 73 of file DRArray.h.

Constructor & Destructor Documentation

◆ DRArray() [1/3]

template<typename Data>

Util::DRArray< Data >::DRArray ( )

Default constructor.

Definition at line 261 of file DRArray.h.

Referenced by associate(), DRArray(), operator=(), and operator=().

◆ DRArray() [2/3]

template<typename Data>

Util::DRArray< Data >::DRArray ( int capacity )

Allocating constructor.

This function calls allocate(capacity) internally.

Parameters

capacity number of elements to allocate

Definition at line 269 of file DRArray.h.

References allocate(), and Util::Array< Data >::capacity().

◆ DRArray() [3/3]

template<typename Data>

Util::DRArray< Data >::DRArray ( DRArray< Data > const & other )

Copy constructor.

Parameters

other the DRArray to be copied

Definition at line 277 of file DRArray.h.

References allocate(), Util::Array< Data >::capacity_, Util::Array< Data >::data_, DRArray(), and isAllocated().

◆ ~DRArray()

template<typename Data>

Util::DRArray< Data >::~DRArray ( )

Destructor.

Deletes any C array that is owned by this object, and releases any association with a C Array that is referred to but not owned by this object. If this object owns an array that is referred to by one or more other DRArray objects, an error message is written to std::cout.

Definition at line 293 of file DRArray.h.

References Util::Array< Data >::capacity_, Util::Array< Data >::data_, Util::Memory::deallocate(), ref_, and refCounter_.

Member Function Documentation

◆ operator=() [1/2]

template<typename Data>

DRArray< Data > & Util::DRArray< Data >::operator= ( DRArray< Data > const & other )

Assignment from another DRArray<Data> container.

Performs a deep copy, by copying values of all elements of another DRArray<Data> container. If this LHS array is already allocated on entry, it must have the same capacity as the other RHS array. If this LHS array is not allocated on entry, required memory is allocated before copying values. After exit, isAllocated() and isOwner() return true, while isAssociated() returns false.

Exceptions

Exception	if other array is not allocated
Exception	if arrays are allocated with unequal capacities

Parameters

other array container on RHS of assigment (input)

Definition at line 317 of file DRArray.h.

References allocate(), Util::Array< Data >::capacity(), Util::Array< Data >::capacity_, Util::Array< Data >::data_, DRArray(), isAllocated(), and UTIL_CHECK.

◆ operator=() [2/2]

template<typename Data>

DRArray< Data > & Util::DRArray< Data >::operator= ( Array< Data > const & other )

Assignment from an Array<Data> container.

Performs a deep copy, by copying values of all elements of an Array<Data> container. If this (LHS) array is already allocated on entry, it must have the same capacity as the other (RHS) array. If this LHS array is not allocated on entry, required memory is allocated before copying values. After exit, isAllocated() and isOwner() return true, while isAssociated() returns false.

Exceptions

Exception	if other array is not allocated
Exception	if arrays are allocated with unequal capacities

Parameters

other array container on RHS of assigment (input)

Definition at line 343 of file DRArray.h.

References allocate(), Util::Array< Data >::capacity(), Util::Array< Data >::capacity_, Util::Array< Data >::data_, DRArray(), isAllocated(), and UTIL_CHECK.

◆ allocate()

template<typename Data>

void Util::DRArray< Data >::allocate ( int capacity )

Allocate an underlying C array, which this container then owns.

On entry, this object must be unallocated, i.e., it must not have data that it either owns or references. After exit, isAllocated() and isOwner() will return true, while isAssociated() will return false.

Exceptions

Exception if this array is allocated on entry.

Parameters

capacity number of elements to allocate

Definition at line 369 of file DRArray.h.

References Util::Memory::allocate(), Util::Array< Data >::capacity(), Util::Array< Data >::capacity_, Util::Array< Data >::data_, isAllocated(), and UTIL_THROW.

Referenced by DRArray(), DRArray(), operator=(), and operator=().

◆ deallocate()

template<typename Data>

void Util::DRArray< Data >::deallocate ( )

Dellocate an underlying C array that is owned by this container.

After exit, isAllocated(), isOwner(), and isAssociated() will all return false.

Exceptions

Exception if this object does not own data.

Definition at line 385 of file DRArray.h.

References Util::Array< Data >::capacity_, Util::Array< Data >::data_, Util::Memory::deallocate(), ref_, refCounter_, and UTIL_CHECK.

◆ associate()

template<typename Data>

void Util::DRArray< Data >::associate	(	DRArray< Data > &	arr,
		int	beginId,
		int	capacity )

Associate this object with a slice of a different DRArray.

On entry, this object must be not be allocated, i.e., it must not have data that it either owns or references. After exit, isAllocated() and isAssociated() will return true, while isOwner() will return false.

Exceptions

Exception if this array is allocated on entry.

Parameters

arr	parent array that owns the data
beginId	index in the parent array at which this array starts
capacity	number of elements associated with this container

Definition at line 398 of file DRArray.h.

References Util::Array< Data >::capacity(), Util::Array< Data >::capacity_, Util::Array< Data >::cArray(), Util::Array< Data >::data_, DRArray(), isAllocated(), isOwner(), ref_, refCounter_, and UTIL_CHECK.

◆ dissociate()

template<typename Data>

void Util::DRArray< Data >::dissociate ( )

Dissociate this object from an externally owned array slice.

After exit, isAllocated(), isOwner(), and isAssociated() will all return false.

Exceptions

Exception if this is not associated with external data

Definition at line 426 of file DRArray.h.

References Util::Array< Data >::capacity_, Util::Array< Data >::data_, ref_, and UTIL_CHECK.

◆ isAllocated()

template<typename Data>

bool Util::DRArray< Data >::isAllocated ( ) const

inline

Return true if this container has data, false otherwise.

A DRArray is considered allocated if it has non-null pointer to a C array, which may either be an array that it owns or a slice of an array that is owned by another DRArray object.

Definition at line 238 of file DRArray.h.

References Util::Array< Data >::data_.

Referenced by allocate(), associate(), DRArray(), operator=(), and operator=().