Main Page | Class List | Directories | File List | Class Members | File Members

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_Listadt_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 $ O(1) $ 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 $ 0 \leq $ 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 $ 0 \leq $ 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 $ 0 \leq $ 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).


Generated on Mon Sep 26 10:55:18 2005 for MDX by  doxygen 1.4.4