array.h File Reference

Resize array container. More...

Go to the source code of this file.

Classes
struct	adt_Array_t
	Array container class. More...
Defines
#define	ADT_ERROR   (-1)
Typedefs
typedef adt_Array_t	adt_Array
	Array container class.
Functions
adt_Array *	adt_createArray (int elemsz, int len, void *buffer)
	Constructor.
void	adt_destroyArray (adt_Array *)
	Destructor.
int	adt_getLengthArray (adt_Array *)
	Returns length of array.
int	adt_getElemsizeArray (adt_Array *)
	Returns array element size in bytes.
void *	adt_getDataArray (adt_Array *)
	Returns pointer to array buffer space.
void *	adt_indexArray (adt_Array *, int index)
	Index the array.
int	adt_updateArray (adt_Array *, int index, void *pelem)
	Update an array element.
int	adt_resizeArray (adt_Array *, int len)
	Resize the array.
int	adt_initializeArray (adt_Array *, int elemsz, int len, void *buffer)
	Alternative constructor.
void	adt_cleanupArray (adt_Array *)
	Alternative destructor.

---

Detailed Description

Resize array container.

Author:

David J. Hardy

Date:

2003-2005

The adt_Array class provides a container for generic one-dimensional arrays whose length can be resized. Access routines perform error-checking on the index bounds. The array buffer space is by default dynamically allocated, but it is also possible to pass preallocated buffer space to be accessed, however a preallocated buffer cannot be resized.

Functions returning int generally indicate success by returning 0 and failure by returning ADT_ERROR. The access functions that accept an array index will terminate the program if the index is out-of-range. This means that error-checking is necessary only for calls to the constructor adt_createArray() (or alternatively adt_initializeArray() ) and to the resize function adt_resizeArray().

---

Define Documentation

#define ADT_ERROR   (-1)

Return value from failed function call.

---

Typedef Documentation

typedef struct adt_Array_t adt_Array

Array container class. Members should be treated as private.

---

Function Documentation

void adt_cleanupArray (  adt_Array *   )

Alternative destructor. Use to destroy a preallocated array object (i.e. one constructed using adt_initializeArray() )

adt_Array* adt_createArray (  int  elemsz, int  len, void *  buffer )

Constructor. Creates dynamically allocated array object. Parameters: [in]  elemsz  The size in bytes of array elements, must be positive. [in]  len  The length of array measured in number of elements, must be nonnegative. [in]  buffer  Provides a preallocated buffer space to be used. If buffer is NULL, then the array buffer space is dynamically allocated and can be resized. If buffer is not NULL, then the space provided must be at least elemsz times len bytes. The user retains control over buffer space provided (e.g. user must free dynamic allocations). Returns: Pointer to array object or NULL if the parameters are inconsistent or if memory allocation fails.

void adt_destroyArray (  adt_Array *   )

Destructor. Frees dynamically allocated buffer space and dynamically allocated array object.

void* adt_getDataArray (  adt_Array *   )

Returns pointer to array buffer space. This permits direct access of array data for efficiency. Note that resizing the array will most likely change the memory location of the buffer, invalidating earlier calls to this function. NULL indicates an empty buffer.

void* adt_indexArray (  adt_Array *  , int  index )

Index the array. Parameters: [in]  index  The array index using zero-based indexing. Must have index length. An index out-of-range will terminate program with error message. Returns: Pointer to the indicated array element. Typecast to the actual element type in order to use it.

int adt_initializeArray (  adt_Array *  , int  elemsz, int  len, void *  buffer )

Alternative constructor. Use to construct a preallocated array object. See adt_createArray() for a description of expected arguments.

int adt_resizeArray (  adt_Array *  , int  len )

Resize the array. Parameters: [in]  len  The new length for the array. Must have len. Fails if memory allocation is not possible. (Terminates program as a bug if len is illegal or if an attempt is made to resize a user-provided buffer.) Returns: 0 on success or ADT_ERROR on failure.

int adt_updateArray (  adt_Array *  , int  index, void *  pelem )

Update an array element. Parameters: [in]  index  The array index using zero-based indexing. [in]  pelem  Points to the desired element value. Must have index length. An index out-of-range will terminate program with error message. Performs a deep copy of the value located at pelem into the indicated array element position. Returns: 0 (does not fail).

---