Main Page | Modules | Alphabetical List | Data Structures | File List | Data Fields | Related Pages

Lists


Detailed Description

A list container.

A list is a sequence of data objects where the data items are usually access from the beginning of list. The head of a list is the first data item and the tail is a list containing the remaining objects.

Data Structures

Defines

Functions


Define Documentation

#define freeListCell   memFree
 

this is used to debug the cell deallocation for Lists.

It expands to _freeCell when BLAH is compiled with -DLIST_DEBUG or to the normal memFree function.

See also:
newCell
Definition at line 86 of file list.c.

Referenced by listDelete(), listDeleteElement(), listDeleteLastElement(), and listForEachDelete().

#define newListCell   (List)memMalloc(sizeof(ListStruct))
 

this is used to debug the cell allocation for Lists.

It expands to _newCell when BLAH is compiled with -DLIST_DEBUG or to the normal memMalloc function.

See also:
_newCell, freeListCell
Definition at line 66 of file list.c.

Referenced by listAppendElement(), listClone(), listDeepClone(), listInsertSorted(), listInsertSortedWithData(), and listPrependElement().


Function Documentation

List listAddUniqueElement List  l,
Pointer  item
 

adds an item to the list if and only if it is not already present.

Parameters:
l the list to which the specified item has to be added.
item the item that has to be added to the list l.
Returns:
the new list after the addition of the item if its unique.
Definition at line 420 of file list.c.

References listAppendElement(), and listContains().

List listAppendElement List  l,
Pointer  item
 

appends an item to the end of a list.

Parameters:
l the list to which an item has to be appended.
item the item that has to be appended to the end of the list l.
Returns:
the new list after appending.
Definition at line 269 of file list.c.

References newListCell.

Referenced by laInsert(), listAddUniqueElement(), listAppendElements(), listFilter(), and strAppend().

List listAppendElements List  oldList,
  ...
 

appends a couple of items to the end of a list.

Parameters:
oldList the list to which a couple of items are to be appended.
... the list of items are to be appended to the end of the list.
Definition at line 314 of file list.c.

References listAppendElement().

List listAppendList List  front,
List  rear
 

appends a list to another list.

Parameters:
front a list to whose end another list rear is appended.
rear a list which is appended to the tail of the front list
Returns:
the new list after appending.
Definition at line 247 of file list.c.

List listClone List  l  ) 
 

clones a list.

This doesn't clone the items.

Parameters:
l the list that has to be cloned.
Returns:
a newly allocated list after cloning.
Definition at line 158 of file list.c.

References newListCell.

Referenced by listCopy().

Boolean listContains List  l,
Pointer  p
 

checks if the list contains a particular item.

Parameters:
l the list in which the existance of the specified item has to be checked.
p specifies the item that has to be checked for in the list l.
Returns:
TRUE if the list contains the item or FALSE otherwise.
Definition at line 490 of file list.c.

Referenced by listAddUniqueElement().

List listCopy List  dst,
List  src
 

set list-items of dst to those of src by reusing old buckets.

It works as follows:

  • if dst has more buckets than src then these are freed
  • if dst has less buckets than src then new once are allocated
  • if dst is NULL then listCopy is equivalent to listClone
  • if src is NULL then listCopy is equivalent to listDelete

Parameters:
dst the resulting list
src the originating list
Returns:
the dst List
Definition at line 204 of file list.c.

References listClone(), and listDelete().

List listDeepClone List  l,
PointerFunction *  p
 

Clones a list, performing a deep copy of all items via P.

Definition at line 176 of file list.c.

References newListCell.

void listDelete List  l  ) 
 

frees list, does NOT free elements.

Parameters:
l the list that needs to be freed.
Returns:
nothing.
Definition at line 558 of file list.c.

References freeListCell.

Referenced by laInsert(), listCopy(), and strAppend().

List listDeleteElement List  l,
Pointer  p
 

deletes all occurences of item from list.

Parameters:
l the list from which all the occurances of a specified item has to be deleted.
p the particular item whose occurances in the list l has to be deleted.
Returns:
the new list after deleting the item from the list.
Definition at line 576 of file list.c.

References freeListCell.

List listDeleteLastElement List  l  ) 
 

deletes the last item from the list.

Parameters:
l the list from which the last item has to be deleted.
Returns:
the new list after deleting the last item form the list l.
Definition at line 612 of file list.c.

References freeListCell.

Pointer listElement List  l  ) 
 

returns first item in list.

Parameters:
l the list whose first item has to be returned.
Returns:
the first item in the list l.
Definition at line 109 of file list.c.

Referenced by laBest(), laDelete(), laInsert(), laIteratorNew(), laIteratorNextElement(), laRemoveBest(), listReverse(), strFinalize(), and strFromList().

List listFilter List  l,
BooleanFunction *  f
 

filters list, returns new (sub-)list.

Parameters:
l the list on which the function is evaluated.
f the function that is evaluated in the list l to generate a (sub-) list
Returns:
an independent list consisting of all the elements of the given list l that make function 'f' evaluate to TRUE
Definition at line 539 of file list.c.

References listAppendElement().

void listForEach List  l,
VoidFunction *  f
 

calls function `f' for each list element.

Parameters:
l the list in which the function 'f' is called.
f the function which is called for each element in the list l.
Definition at line 504 of file list.c.

void listForEachDelete List  l,
VoidFunction *  f
 

like listForEach, but frees list, list becomes inaccessible.

Parameters:
l the list in which the function 'f' has to be called.
f the function that is called for each element in the list l.
Definition at line 518 of file list.c.

References freeListCell.

int listIndex List  l,
Pointer  item
 

find a particular item in a list .

Parameters:
l the list from which the specified item has to be found.
item the item that has to be found from the list l.
Returns:
the index of the item if found else zero.
Definition at line 666 of file list.c.

List listInsertSorted List  list,
Pointer  item,
BooleanFunction *  f
 

inserts an item keeping an order defined by f.

Parameters:
list the list into which a specified item has to be inserted.
item the item that has to be inserted into the list l.
f the function that defines the ordering of the during insertion.
Returns:
the new list after insertion operation.
Definition at line 359 of file list.c.

References newListCell.

List listInsertSortedWithData List  list,
Pointer  item,
BooleanFunction *  f,
Pointer  clientData
 

inserts an item keeping an order defined by f and some extra data.

Parameters:
list the list into which a specified item has to be inserted.
item the item that has to be inserted into the list l.
'f' the function that defines the ordering of the during insertion.
clientData the data that determines the ordering along with the function 'f'
Returns:
the new list after insertion operation.
Definition at line 390 of file list.c.

References newListCell.

Boolean listIsEqual List  list1,
List  list2
 

compare two lists item per item.

Parameters:
list1 the first list whose items are to be compared.
list2 the second list whose items are compared with the list 1.
Returns:
TRUE if the items are all equal and FALSE otherwise.
Definition at line 689 of file list.c.

References listSize().

Pointer listLastElement List  l  ) 
 

returns last item in list.

Parameters:
l the list from which the last item has to be retrieved.
Returns:
the last item of the list l.
Definition at line 471 of file list.c.

List listNew  ) 
 

get a new list.

A new List is represented by NULL.

Returns:
NULL
Definition at line 98 of file list.c.

List listNext List  l  ) 
 

returns the tail of the list.

Parameters:
l the list whose tail has to be returned.
Returns:
the last item of the list.
Definition at line 120 of file list.c.

Referenced by laDelete(), laInsert(), laIteratorNextElement(), laRemoveBest(), listReverse(), strFinalize(), and strFromList().

Pointer listNthElement List  l,
int  n
 

returns nth item in list.

Parameters:
l the list whose 'n'th item has to be retrieved.
n the number that idicates the item that has to be retrieved.
Returns:
the item in the 'n'th position of the list.
Definition at line 453 of file list.c.

List listPrependElement List  l,
Pointer  item
 

prepends an item to a list.

Parameters:
l the list to which an item has to be prepended.
item the item that has to be prepended to the list l.
Returns:
the new list after prepending.
Definition at line 296 of file list.c.

References newListCell.

Referenced by hashListOfKeys(), laInsert(), laIteratorNew(), listPrependElements(), listReverse(), and vectorToList().

List listPrependElements List  oldList,
  ...
 

prepends a couple of items to the end of a list.

Parameters:
oldList the list to which the items are prepended.
... the list of items that are to be prepended to the list l.
Returns:
the new list after prepending.
Definition at line 336 of file list.c.

References listPrependElement().

List listReverse List  l  ) 
 

return a new reverse list.

Parameters:
l the list whose data items are to be reversed.
Returns:
a new list after reversing the list l.
Definition at line 753 of file list.c.

References listElement(), listNext(), and listPrependElement().

Pointer listSetElement List  l,
Pointer  value
 

set the item of the current list cell.

Parameters:
l the list from which the specified item has to be set.
value the value of the item in the list that has to be set.
Returns:
the list after setting the specified item.
Definition at line 132 of file list.c.

Referenced by laIteratorNextElement().

Pointer listSetNext List  l,
List  m
 

set the next of the current list cell.

Parameters:
l the list from which the specified item has to be set.
m next of the current list cell
Definition at line 144 of file list.c.

Referenced by laInsert(), and laIteratorNextElement().

int listSize List  l  ) 
 

retrieves number of items in the list.

Parameters:
l the list whose size has to be retrieved.
Returns:
the total number of items in the list l.
Definition at line 435 of file list.c.

Referenced by listIsEqual(), listToVector(), strFinalize(), and strFromList().

List listSort List  l,
BooleanFunction *  f
 

sorts a list, using a user-specified compare function.

Parameters:
l the list that has to be sorted using the function 'f'
f the compare function that is used for the sorting of the list l.
Returns:
the new list after sorting using the function 'f'
Definition at line 713 of file list.c.

References listToVector(), vectorDelete(), vectorSort(), and vectorToList().

List listSortWithData List  l,
BooleanFunction *  f,
void *  data
 

sorts a list, using a user-specified compare function and some data.

Parameters:
l the list that has to be sorted using the function 'f'
f the compare function that is used for the sorting of the list l.
data the data that defines the sorting along with the function 'f'
Returns:
the new list after sorting using the function 'f' and the data.
Definition at line 734 of file list.c.

References listToVector(), vectorDelete(), vectorSortWithData(), and vectorToList().

Vector listToVector List  l  ) 
 

converts a list into a vector.

Parameters:
l the list that has to be converted into a vector v.
Returns:
the vector v corresponding to the list l.
Definition at line 642 of file list.c.

References listSize(), vectorNew(), and vectorSetElement().

Referenced by listSort(), and listSortWithData().


BLAH 0.95 (20 Oct 2004)