list.h File Reference

List container. More...

#include "adt/array.h"

Go to the source code of this file.

Classes
struct	adt_List_t
	List container class. More...
Typedefs
typedef adt_List_t	adt_List
	List container class.
Functions
adt_List *	adt_createList (int elemsz, int len, void *buffer)
	Constructor.
void	adt_destroyList (adt_List *)
	Destructor.
int	adt_getLengthList (adt_List *)
	Returns length of list.
int	adt_getElemsizeList (adt_List *)
	Returns list element size in bytes.
void *	adt_getDataList (adt_List *)
	Returns pointer to list buffer space.
int	adt_appendList (adt_List *, void *pelem)
	Append element to list.
int	adt_deleteList (adt_List *)
	Delete element from list.
void *	adt_indexList (adt_List *, int index)
	Index the list.
int	adt_updateList (adt_List *, int index, void *pelem)
	Update a list element.
int	adt_resizeList (adt_List *, int len)
	Resize the list.
int	adt_initializeList (adt_List *, int elemsz, int len, void *buffer)
	Alternative constructor.
void	adt_cleanupList (adt_List *)
	Alternative destructor.

---

Detailed Description

List container.

Author:

David J. Hardy

Date:

2003-2005

The adt_List class provides a container for an array-based list. It essentially repeats the adt_Array class semantics and extends it with operations that append (adt_appendList() ) and delete (adt_deleteList() ) a single element to and from the end of the array. These operations are implemented so as to provide amortized cost of per operation. This container is ideal for incrementally building an array.

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. Error-checking is necessary only for calls to the constructor adt_createList() (or alternatively adt_initializeList() ), to the resize function adt_resizeList(), and to the two list-specific operations adt_appendList() and adt_deleteList().

---

Typedef Documentation

typedef struct adt_List_t adt_List

List container class. Members should be treated as private.

---

Function Documentation

int adt_appendList (  adt_List *  , void *  pelem )

Append element to list. Parameters: [in]  pelem  Points to the desired element value. Extends the list length by one and performs a deep copy of the value located at elem into the last element location. Returns: 0 on success or ADT_ERROR on failure.

void adt_cleanupList (  adt_List *   )

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

adt_List* adt_createList (  int  elemsz, int  len, void *  buffer )

Constructor. Creates dynamically allocated list object. Parameters: [in]  elemsz  The size in bytes of list elements, must be positive. [in]  len  The length of list 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.

int adt_deleteList (  adt_List *   )

Delete element from list. Removes the last element from the list and decreases the length of the list by one. Attempting to remove an element from a list of length 0 is treated as a bug that terminates the program. Returns: 0 on success or ADT_ERROR on failure.

void adt_destroyList (  adt_List *   )

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

void* adt_getDataList (  adt_List *   )

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

void* adt_indexList (  adt_List *  , int  index )

Index the list. Parameters: [in]  index  The list 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 list element. Typecast to the actual element type in order to use it.

int adt_initializeList (  adt_List *  , int  elemsz, int  len, void *  buffer )

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

int adt_resizeList (  adt_List *  , int  len )

Resize the list. Parameters: [in]  len  The new length for the list. 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_updateList (  adt_List *  , int  index, void *  pelem )

Update a list element. Parameters: [in]  index  The list 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 list element position. Returns: 0 (does not fail).

---