ajlist.c

Datatypes: AjPList AjIList AjPList AjIList

Datatype: AjPList

Lists

Sections: Constructors Adding values Modifiers Removing data Element retrieval Trace functions Destructors unused exit

Section: Constructors

Constructors for lists

Functions: ajListNew ajListNewListref ajListNewRef

Synopsis

Prototype

AjPList ajListNew (
      void
);

Type Name Read/Write Description

AjPList RETURN new list;

Type	Name	Read/Write	Description
AjPList		RETURN	new list;

Returns

AjPList:

new list;

Description

Creates a new general list.

Availability

In release 6.4.0

Function ajListNewListref

Copy a list.

WARNING: pointers to the data are copied, NOT the data so be careful when cleaning up after copy.

Synopsis

Prototype

AjPList ajListNewListref (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input list to be copied

AjPList RETURN new copied list.

Type	Name	Read/Write	Description
const AjPList	list	Input	list to be copied
AjPList		RETURN	new copied list.

Input

list:

(Input)

list to be copied

Returns

AjPList:

new copied list.

Description

Copy a list.

WARNING: pointers to the data are copied, NOT the data so be careful when cleaning up after copy.

Availability

In release 6.4.0

Function ajListNewRef

Makes a reference-counted copy of any list

Synopsis

Prototype

AjPList ajListNewRef (
      AjPList list
);

Type Name Read/Write Description

AjPList list Modify list to be given a new reference

AjPList RETURN new list;

Type	Name	Read/Write	Description
AjPList	list	Modify	list to be given a new reference
AjPList		RETURN	new list;

Input & Output

list:

(Modify)

list to be given a new reference

Returns

AjPList:

new list;

Description

Makes a reference-counted copy of any list

Availability

In release 6.4.0

Section: Adding values

Functions: ajListPush ajListPushAppend ajListPushlist

Function ajListPush

Add a new node at the start of the list and add the data pointer.

Synopsis

Prototype

void ajListPush (
      AjPList list,
      void* x
);

Type Name Read/Write Description

AjPList list Modify list to be changed.

void* x Modify Pointer to data.

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	list to be changed.
void*	x	Modify	Pointer to data.
void		RETURN

Input & Output

list:	(Modify)	list to be changed.
x:	(Modify)	Pointer to data.

Returns

void:

No return value

Description

Add a new node at the start of the list and add the data pointer.

Availability

In release 6.4.0

Function ajListPushAppend

Add a new node at the end of the list and add the data pointer.

Synopsis

Prototype

void ajListPushAppend (
      AjPList list,
      void* x
);

Type Name Read/Write Description

AjPList list Modify List to be changed.

void* x Modify Pointer to data to append.

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List to be changed.
void*	x	Modify	Pointer to data to append.
void		RETURN

Input & Output

list:	(Modify)	List to be changed.
x:	(Modify)	Pointer to data to append.

Returns

void:

No return value

Description

Add a new node at the end of the list and add the data pointer.

Availability

In release 6.4.0

Function ajListPushlist

Adds a list to the start of the current list, then deletes the second list.

Synopsis

Prototype

void ajListPushlist (
      AjPList list,
      AjPList* Plist
);

Type Name Read/Write Description

AjPList list Modify List.

AjPList* Plist Delete List to be merged.

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
AjPList*	Plist	Delete	List to be merged.
void		RETURN

Output

Plist:

(Delete)

List to be merged.

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Adds a list to the start of the current list, then deletes the second list.

Availability

In release 6.4.0

Section: Modifiers

Functions: ajListMap ajListPurge ajListReverse ajListSort ajListSortTwo ajListSortTwoThree ajListSortTwoUnique ajListSortUnique

Function ajListMap

For each node in the list call function apply.

Synopsis

Prototype

void ajListMap (
      AjPList list,
      void function apply,
      void* cl
);

Type Name Read/Write Description

AjPList list Modify List.

void function apply Function Function to call for each list item.

void* cl Modify Standard, usually NULL.

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
void function	apply	Function	Function to call for each list item.
void*	cl	Modify	Standard, usually NULL.
void		RETURN

Input

apply:

(Function)

Function to call for each list item.

Input & Output

list:	(Modify)	List.
cl:	(Modify)	Standard, usually NULL.

Returns

void:

No return value

Description

For each node in the list call function apply.

Availability

In release 6.4.0

Synopsis

Prototype

void ajListPurge (
      AjPList list,
      AjBool* function test,
      void* function nodedelete
);

Type Name Read/Write Description

AjPList list Modify List.

AjBool* function test Function Function to test whether to delete

void* function nodedelete Function Wrapper function for item destructor

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
AjBool* function	test	Function	Function to test whether to delete
void* function	nodedelete	Function	Wrapper function for item destructor
void		RETURN

Input

test:	(Function)	Function to test whether to delete
nodedelete:	(Function)	Wrapper function for item destructor

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Garbage collect a list

Availability

In release 6.4.0

Function ajListReverse

Reverse the order of the nodes in an abstract list.

Synopsis

Prototype

void ajListReverse (
      AjPList list
);

Type Name Read/Write Description

AjPList list Modify List

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List
void		RETURN

Input & Output

list:

(Modify)

List

Returns

void:

No return value

Description

Reverse the order of the nodes in an abstract list.

Availability

In release 6.4.0

Function ajListSort

Sort the items in a list.

Synopsis

Prototype

void ajListSort (
      AjPList list,
      int* function sort1
);

Type Name Read/Write Description

AjPList list Modify List.

int* function sort1 Function Function to compare two list items.

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
int* function	sort1	Function	Function to compare two list items.
void		RETURN

Input

sort1:

(Function)

Function to compare two list items.

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Sort the items in a list.

Availability

In release 6.4.0

Function ajListSortTwo

Sort the items in a list using 2 fields in the same object hierarchy.

Synopsis

Prototype

void ajListSortTwo (
      AjPList list,
      int* function sort1,
      int* function sort2
);

Type Name Read/Write Description

AjPList list Modify List.

int* function sort1 Function 1st function to compare two list items.

int* function sort2 Function 2nd function to compare two list items.

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
int* function	sort1	Function	1st function to compare two list items.
int* function	sort2	Function	2nd function to compare two list items.
void		RETURN

Input

sort1:	(Function)	1st function to compare two list items.
sort2:	(Function)	2nd function to compare two list items.

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Sort the items in a list using 2 fields in the same object hierarchy.

Availability

In release 6.4.0

Function ajListSortTwoThree

Sort the items in a list using 3 fields in the same object hierarchy.

Synopsis

Prototype

void ajListSortTwoThree (
      AjPList list,
      int* function sort1,
      int* function sort2,
      int* function sort3
);

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
int* function	sort1	Function	1st function to compare two list items.
int* function	sort2	Function	2nd function to compare two list items.
int* function	sort3	Function	3rd function to compare two list items.
void		RETURN

Input

sort1:	(Function)	1st function to compare two list items.
sort2:	(Function)	2nd function to compare two list items.
sort3:	(Function)	3rd function to compare two list items.

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Sort the items in a list using 3 fields in the same object hierarchy.

Availability

In release 6.4.0

Function ajListSortTwoUnique

Double-sort the items in a list, and remove duplicates

Synopsis

Prototype

void ajListSortTwoUnique (
      AjPList list,
      int* function sort1,
      int* function sort2,
      void* function nodedelete
);

Type Name Read/Write Description

AjPList list Modify List.

int* function sort1 Function Function to compare two list items.

int* function sort2 Function Function to compare two list items.

void* function nodedelete Function Function to delete an item

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
int* function	sort1	Function	Function to compare two list items.
int* function	sort2	Function	Function to compare two list items.
void* function	nodedelete	Function	Function to delete an item
void		RETURN

Input

sort1:	(Function)	Function to compare two list items.
sort2:	(Function)	Function to compare two list items.
nodedelete:	(Function)	Function to delete an item

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Double-sort the items in a list, and remove duplicates

Availability

In release 6.4.0

Function ajListSortUnique

Sort the items in a list, and remove duplicates

Synopsis

Prototype

void ajListSortUnique (
      AjPList list,
      int* function sort1,
      void* function nodedelete
);

Type Name Read/Write Description

AjPList list Modify List.

int* function sort1 Function Function to compare two list items.

void* function nodedelete Function Function to delete an item

void RETURN

Type	Name	Read/Write	Description
AjPList	list	Modify	List.
int* function	sort1	Function	Function to compare two list items.
void* function	nodedelete	Function	Function to delete an item
void		RETURN

Input

sort1:	(Function)	Function to compare two list items.
nodedelete:	(Function)	Function to delete an item

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Sort the items in a list, and remove duplicates

Availability

In release 6.4.0

Section: Removing data

Functions: ajListPop ajListPopLast

Function ajListPop

remove the first node but set pointer to data first.

Synopsis

Prototype

AjBool ajListPop (
      AjPList list,
      void** x
);

Type Name Read/Write Description

AjPList list Modify List

void** x Output pointer to pointer to data

AjBool RETURN ajTrue on success.

Type	Name	Read/Write	Description
AjPList	list	Modify	List
void**	x	Output	pointer to pointer to data
AjBool		RETURN	ajTrue on success.

Output

(Output)

pointer to pointer to data

Input & Output

list:

(Modify)

List

Returns

AjBool:

ajTrue on success.

Description

remove the first node but set pointer to data first.

Availability

In release 6.4.0

Function ajListPopLast

remove the last node but set pointer to data first.

Synopsis

Prototype

AjBool ajListPopLast (
      AjPList list,
      void** x
);

Type Name Read/Write Description

AjPList list Modify List

void** x Output pointer to pointer to data

AjBool RETURN ajTrue on success.

Output

(Output)

pointer to pointer to data

Input & Output

list:

(Modify)

List

Returns

AjBool:

ajTrue on success.

Description

remove the last node but set pointer to data first.

Availability

In release 6.4.0

Section: Element retrieval

Functions: ajListGetLength ajListMapfind ajListMapread ajListPeek ajListPeekFirst ajListPeekLast ajListPeekNumber ajListToarray ajListToindex

Function ajListGetLength

get the number of nodes in the linked list.

Synopsis

Prototype

ajuint ajListGetLength (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input List

ajuint RETURN Number of nodes in list.

Input

list:

(Input)

List

Returns

ajuint:

Number of nodes in list.

Description

get the number of nodes in the linked list.

Availability

In release 6.4.0

Function ajListMapfind

For each node in the list call function 'apply' and return ajTrue when any node is matched by the function.

Synopsis

Prototype

AjBool ajListMapfind (
      const AjPList list,
      AjBool function apply,
      void* cl
);

Type Name Read/Write Description

const AjPList list Input List

AjBool function apply Function Function to call to test each list item.

void* cl Modify Standard, usually NULL.

AjBool RETURN ajTrue on success.

Input

list:	(Input)	List
apply:	(Function)	Function to call to test each list item.

Input & Output

cl:

(Modify)

Standard, usually NULL.

Returns

AjBool:

ajTrue on success.

Description

For each node in the list call function 'apply' and return ajTrue when any node is matched by the function.

Availability

In release 6.4.0

Function ajListMapread

For each node in the list call function apply. The apply function must not modify the list elements.

Synopsis

Prototype

void ajListMapread (
      const AjPList list,
      void function apply,
      void* cl
);

Type Name Read/Write Description

const AjPList list Input List.

void function apply Function Function to call for each list item.

void* cl Modify Standard, usually NULL.

void RETURN

Input

list:	(Input)	List.
apply:	(Function)	Function to call for each list item.

Input & Output

cl:

(Modify)

Standard, usually NULL.

Returns

void:

No return value

Description

For each node in the list call function apply. The apply function must not modify the list elements.

Availability

In release 6.4.0

Function ajListPeek

Return the first node but keep it on the list

Synopsis

Prototype

AjBool ajListPeek (
      const AjPList list,
      void** x
);

Type Name Read/Write Description

const AjPList list Input List

void** x Output pointer to pointer to data

AjBool RETURN ajTrue on success.

Input

list:

(Input)

List

Output

(Output)

pointer to pointer to data

Returns

AjBool:

ajTrue on success.

Description

Return the first node but keep it on the list

Availability

In release 6.4.0

Function ajListPeekFirst

Set pointer to first node's data. Does NOT remove the first node.

Synopsis

Prototype

AjBool ajListPeekFirst (
      const AjPList list,
      void** x
);

Type Name Read/Write Description

const AjPList list Input List

void** x Output pointer to pointer to data

AjBool RETURN ajTrue on success.

Input

list:

(Input)

List

Output

(Output)

pointer to pointer to data

Returns

AjBool:

ajTrue on success.

Description

Set pointer to first node's data. Does NOT remove the first node.

Availability

In release 6.4.0

Function ajListPeekLast

Set pointer to last node's data. Does NOT remove the last node.

Synopsis

Prototype

AjBool ajListPeekLast (
      const AjPList list,
      void** x
);

Type Name Read/Write Description

const AjPList list Input List

void** x Output pointer to pointer to data

AjBool RETURN ajTrue on success.

Input

list:

(Input)

List

Output

(Output)

pointer to pointer to data

Returns

AjBool:

ajTrue on success.

Description

Set pointer to last node's data. Does NOT remove the last node.

Availability

In release 6.4.0

Function ajListPeekNumber

Set pointer to last node's nth data item. 0 <= n < number of elements.

Synopsis

Prototype

AjBool ajListPeekNumber (
      const AjPList list,
      ajuint ipos,
      void** x
);

Type Name Read/Write Description

const AjPList list Input List

ajuint ipos Input element of the list

void** x Output pointer to pointer to data

AjBool RETURN ajTrue on success.

Input

list:	(Input)	List
ipos:	(Input)	element of the list

Output

(Output)

pointer to pointer to data

Returns

AjBool:

ajTrue on success.

Description

Set pointer to last node's nth data item. 0 <= n < number of elements.

Availability

In release 6.4.0

Function ajListToarray

Create an array of the pointers to the data.

Synopsis

Prototype

ajuint ajListToarray (
      const AjPList list,
      void*** array
);

Type Name Read/Write Description

const AjPList list Input List

void*** array Output Array of pointers to list items.

ajuint RETURN Size of array of pointers.

Input

list:

(Input)

List

Output

array:

(Output)

Array of pointers to list items.

Returns

ajuint:

Size of array of pointers.

Description

Create an array of the pointers to the data.

Availability

In release 6.4.0

Function ajListToindex

Create an array of the pointers to the data.

Synopsis

Prototype

ajuint ajListToindex (
      const AjPList list,
      ajuint* lind,
      int* function sort1
);

Type Name Read/Write Description

const AjPList list Input List

ajuint* lind Output Populated ndex array to be sorted

int* function sort1 Function Function to compare two list items.

ajuint RETURN Size of index array.

Input

list:	(Input)	List
sort1:	(Function)	Function to compare two list items.

Output

lind:

(Output)

Populated ndex array to be sorted

Returns

ajuint:

Size of index array.

Description

Create an array of the pointers to the data.

Availability

In release 6.4.0

Section: Trace functions

Functions: ajListProbe ajListProbeData ajListTrace

Function ajListProbe

Test list for memory allocation conflicts

Synopsis

Prototype

void ajListProbe (
      AjPList const* Plist
);

Type Name Read/Write Description

AjPList const* Plist Input List

void RETURN

Input

Plist:

(Input)

List

Returns

void:

No return value

Description

Test list for memory allocation conflicts

Availability

In release 6.4.0

Function ajListProbeData

Test list and data for memory allocation conflicts

Synopsis

Prototype

void ajListProbeData (
      AjPList const* Plist
);

Type Name Read/Write Description

AjPList const* Plist Input List

void RETURN

Input

Plist:

(Input)

List

Returns

void:

No return value

Description

Test list and data for memory allocation conflicts

Availability

In release 6.4.0

Function ajListTrace

Traces through a list and validates it

Synopsis

Prototype

void ajListTrace (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input list to be traced.

void RETURN

Input

list:

(Input)

list to be traced.

Returns

void:

No return value

Description

Traces through a list and validates it

Availability

In release 6.4.0

Section: Destructors

Functions: ajListFree ajListFreeData

Function ajListFree

Free all nodes in the list. NOTE: The data is only freed with a specified list type. For undefined data types we recommend you to use ajListMap with a routine to free the memory.

Synopsis

Prototype

void ajListFree (
      AjPList* Plist
);

Type Name Read/Write Description

AjPList* Plist Delete List

void RETURN

Output

Plist:

(Delete)

List

Returns

void:

No return value

Description

Free all nodes in the list. NOTE: The data is only freed with a specified list type. For undefined data types we recommend you to use ajListMap with a routine to free the memory.

Availability

In release 6.4.0

Function ajListFreeData

Free all nodes in the list. Free all the data values. For more complex data objects use ajListMap with a routine to free the object memory.

Synopsis

Prototype

void ajListFreeData (
      AjPList* Plist
);

Type Name Read/Write Description

AjPList* Plist Delete List

void RETURN

Output

Plist:

(Delete)

List

Returns

void:

No return value

Description

Free all nodes in the list. Free all the data values. For more complex data objects use ajListMap with a routine to free the object memory.

Availability

In release 6.4.0

Section: unused

Functions: ajListUnused

Function ajListUnused

Dummy function to catch all unused functions defined in ajlist

Synopsis

Prototype

void ajListUnused (
      void** array
);

Type Name Read/Write Description

void** array Input Array needed by ajListArrayTrace

void RETURN

Input

array:

(Input)

Array needed by ajListArrayTrace

Returns

void:

No return value

Description

Dummy function to catch all unused functions defined in ajlist

Availability

In release 6.4.0

Section: exit

Functions called on exit from the program by ajExit to do any necessary cleanup and to report internal statistics to the debug file

Functions: ajListExit

Function ajListExit

Prints a summary of list usage with debug calls

Synopsis

Prototype

void ajListExit (
      void
);

Type Name Read/Write Description

void RETURN

Returns

void:

No return value

Description

Prints a summary of list usage with debug calls

Availability

In release 6.4.0

Datatype: AjIList

List iterators

Sections: constructors tests destructors stepping modifiers Trace functions

Section: constructors

Functions: ajListIterNew ajListIterNewBack ajListIterNewread ajListIterNewreadBack

Function ajListIterNew

Creates an iterator to operate from start to end of list.

Synopsis

Prototype

AjIList ajListIterNew (
      AjPList list
);

Type Name Read/Write Description

AjPList list Modify List Not const in practice - the iterator can insert and delete entries

AjIList RETURN New list iterator

Input & Output

list:

(Modify)

List Not const in practice - the iterator can insert and delete entries

Returns

AjIList:

New list iterator

Description

Creates an iterator to operate from start to end of list.

Availability

In release 6.4.0

Function ajListIterNewBack

Creates an iterator to operate from end to start of the list.

Synopsis

Prototype

AjIList ajListIterNewBack (
      AjPList list
);

Type Name Read/Write Description

AjPList list Modify List Not const - the iterator can insert and delete entries

AjIList RETURN New list iterator

Input & Output

list:

(Modify)

List Not const - the iterator can insert and delete entries

Returns

AjIList:

New list iterator

Description

Creates an iterator to operate from end to start of the list.

Availability

In release 6.4.0

Function ajListIterNewread

Creates an iterator to operate from start to end of read-only list.

Synopsis

Prototype

AjIList ajListIterNewread (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input List Not const in practice - the iterator can insert and delete entries

AjIList RETURN New list iterator

Input

list:

(Input)

List Not const in practice - the iterator can insert and delete entries

Returns

AjIList:

New list iterator

Description

Creates an iterator to operate from start to end of read-only list.

Availability

In release 6.4.0

Function ajListIterNewreadBack

Creates an iterator to operate from end to start of the list.

Synopsis

Prototype

AjIList ajListIterNewreadBack (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input List

AjIList RETURN New list iterator

Input

list:

(Input)

List

Returns

AjIList:

New list iterator

Description

Creates an iterator to operate from end to start of the list.

Availability

In release 6.4.0

Section: tests

Functions: ajListIterDone ajListIterDoneBack

Function ajListIterDone

Tests whether an iterator has completed yet.

Synopsis

Prototype

AjBool ajListIterDone (
      const AjIList iter
);

Type Name Read/Write Description

const AjIList iter Input List iterator.

AjBool RETURN ajTrue if the iterator is exhausted.

Input

iter:

(Input)

List iterator.

Returns

AjBool:

ajTrue if the iterator is exhausted.

Description

Tests whether an iterator has completed yet.

Availability

In release 6.4.0

Function ajListIterDoneBack

Tests whether a backwards iterator has completed yet.

Synopsis

Prototype

AjBool ajListIterDoneBack (
      const AjIList iter
);

Type Name Read/Write Description

const AjIList iter Input List iterator.

AjBool RETURN ajTrue if the iterator is exhausted.

Input

iter:

(Input)

List iterator.

Returns

AjBool:

ajTrue if the iterator is exhausted.

Description

Tests whether a backwards iterator has completed yet.

Availability

In release 6.4.0

Section: destructors

Functions: ajListIterDel

Function ajListIterDel

Destructor for a list iterator.

Synopsis

Prototype

void ajListIterDel (
      AjIList* iter
);

Type Name Read/Write Description

AjIList* iter Delete List iterator.

void RETURN

Output

iter:

(Delete)

List iterator.

Returns

void:

No return value

Description

Destructor for a list iterator.

Availability

In release 6.4.0

Section: stepping

Functions: ajListIterGet ajListIterGetBack

Function ajListIterGet

Returns next item using iterator, or steps off the end.

Synopsis

Prototype

void* ajListIterGet (
      AjIList iter
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

void* RETURN Data item returned.

Input & Output

iter:

(Modify)

List iterator.

Returns

void*:

Data item returned.

Description

Returns next item using iterator, or steps off the end.

Availability

In release 6.4.0

Function ajListIterGetBack

Returns next item using back iterator.

Synopsis

Prototype

void* ajListIterGetBack (
      AjIList iter
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

void* RETURN Data item returned.

Input & Output

iter:

(Modify)

List iterator.

Returns

void*:

Data item returned.

Description

Returns next item using back iterator.

Availability

In release 6.4.0

Section: modifiers

Functions: ajListIterInsert ajListIterRemove ajListIterRewind

Function ajListIterInsert

Insert an item in a list, using an iterator (if not null) to show which position to insert. Otherwise, simply push.

Synopsis

Prototype

void ajListIterInsert (
      AjIList iter,
      void* x
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

void* x Modify Data item to insert.

void RETURN

Input & Output

iter:	(Modify)	List iterator.
x:	(Modify)	Data item to insert.

Returns

void:

No return value

Description

Insert an item in a list, using an iterator (if not null) to show which position to insert. Otherwise, simply push.

Availability

In release 6.4.0

Function ajListIterRemove

Remove an item from a list, using an iterator (if not null) to show which item. Otherwise remove the first item.

We want to remove the item just fetched by the iterator.

Synopsis

Prototype

void ajListIterRemove (
      AjIList iter
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

void RETURN

Input & Output

iter:

(Modify)

List iterator.

Returns

void:

No return value

Description

Remove an item from a list, using an iterator (if not null) to show which item. Otherwise remove the first item.

We want to remove the item just fetched by the iterator.

Availability

In release 6.4.0

Function ajListIterRewind

Resets iterator to start position

Synopsis

Prototype

void ajListIterRewind (
      AjIList iter
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

void RETURN

Input & Output

iter:

(Modify)

List iterator.

Returns

void:

No return value

Description

Resets iterator to start position

Availability

In release 6.4.0

Section: Trace functions

Functions: ajListIterTrace

Function ajListIterTrace

Traces a list iterator and validates it.

Synopsis

Prototype

void ajListIterTrace (
      const AjIList iter
);

Type Name Read/Write Description

const AjIList iter Input list iterator to be traced.

void RETURN

Input

iter:

(Input)

list iterator to be traced.

Returns

void:

No return value

Description

Traces a list iterator and validates it.

Availability

In release 6.4.0

Datatype: AjPList

String lists

Sections: Constructors Adding values Modifiers Removing data Element retrieval Trace functions Destructors

Section: Constructors

Constructors for lists

Functions: ajListstrNew ajListstrNewList ajListstrNewListref

Function ajListstrNew

Creates a new string list.

Synopsis

Prototype

AjPList ajListstrNew (
      void
);

Type Name Read/Write Description

AjPList RETURN new list;

Returns

AjPList:

new list;

Description

Creates a new string list.

Availability

In release 6.4.0

Function ajListstrNewList

Copy a list, with copies of all the string values.

General data cannot be copied so this is a string-only function

Synopsis

Prototype

AjPList ajListstrNewList (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input list to be copied

AjPList RETURN new copied list.

Input

list:

(Input)

list to be copied

Returns

AjPList:

new copied list.

Description

Copy a list, with copies of all the string values.

General data cannot be copied so this is a string-only function

Availability

In release 6.4.0

Function ajListstrNewListref

Copy a string list.

WARNING: pointers to the data are copied, NOT the data so be careful when cleaning up after copy.

Synopsis

Prototype

AjPList ajListstrNewListref (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input List to be copied

AjPList RETURN New, copied, list.

Input

list:

(Input)

List to be copied

Returns

AjPList:

New, copied, list.

Description

Copy a string list.

WARNING: pointers to the data are copied, NOT the data so be careful when cleaning up after copy.

Availability

In release 6.4.0

Section: Adding values

Functions: ajListstrPush ajListstrPushAppend ajListstrPushlist

Function ajListstrPush

Add a new node at the start of a string list.

Synopsis

Prototype

void ajListstrPush (
      AjPList list,
      AjPStr x
);

Type Name Read/Write Description

AjPList list Modify list to be changed.

AjPStr x Modify String data.

void RETURN

Input & Output

list:	(Modify)	list to be changed.
x:	(Modify)	String data.

Returns

void:

No return value

Description

Add a new node at the start of a string list.

Availability

In release 6.4.0

Function ajListstrPushAppend

Add a new node at the end of the list and add the data pointer.

Synopsis

Prototype

void ajListstrPushAppend (
      AjPList list,
      AjPStr x
);

Type Name Read/Write Description

AjPList list Modify List to be changed.

AjPStr x Modify String to append.

void RETURN

Input & Output

list:	(Modify)	List to be changed.
x:	(Modify)	String to append.

Returns

void:

No return value

Description

Add a new node at the end of the list and add the data pointer.

Availability

In release 6.4.0

Function ajListstrPushlist

Adds a list to the start of the current list, then deletes the second list.

Synopsis

Prototype

void ajListstrPushlist (
      AjPList list,
      AjPList* Plist
);

Type Name Read/Write Description

AjPList list Modify List.

AjPList* Plist Delete List to be merged.

void RETURN

Output

Plist:

(Delete)

List to be merged.

Input & Output

list:

(Modify)

List.

Returns

void:

No return value

Description

Adds a list to the start of the current list, then deletes the second list.

Availability

In release 6.4.0

Section: Modifiers

Functions: ajListstrMap ajListstrReverse

Function ajListstrMap

For each node in the list call function apply, with the address of the string and a client pointer.

Synopsis

Prototype

void ajListstrMap (
      AjPList list,
      void function apply,
      void* cl
);

Type Name Read/Write Description

AjPList list Modify List.

void function apply Function Function to call for each list item.

void* cl Modify Standard, usually NULL.

void RETURN

Input

apply:

(Function)

Function to call for each list item.

Input & Output

list:	(Modify)	List.
cl:	(Modify)	Standard, usually NULL.

Returns

void:

No return value

Description

For each node in the list call function apply, with the address of the string and a client pointer.

Availability

In release 6.4.0

Function ajListstrReverse

Reverse the order of the nodes in a string list.

Synopsis

Prototype

void ajListstrReverse (
      AjPList list
);

Type Name Read/Write Description

AjPList list Modify List

void RETURN

Input & Output

list:

(Modify)

List

Returns

void:

No return value

Description

Reverse the order of the nodes in a string list.

Availability

In release 6.4.0

Section: Removing data

Functions: ajListstrPop ajListstrPopLast

Function ajListstrPop

Remove the first node but set pointer to data first.

Synopsis

Prototype

AjBool ajListstrPop (
      AjPList list,
      AjPStr* Pstr
);

Type Name Read/Write Description

AjPList list Modify List

AjPStr* Pstr Output String

AjBool RETURN ajTrue on success.

Output

Pstr:

(Output)

String

Input & Output

list:

(Modify)

List

Returns

AjBool:

ajTrue on success.

Description

Remove the first node but set pointer to data first.

Availability

In release 6.4.0

Function ajListstrPopLast

Remove the last node but set pointer to data first.

Synopsis

Prototype

AjBool ajListstrPopLast (
      AjPList list,
      AjPStr* Pstr
);

Type Name Read/Write Description

AjPList list Modify List

AjPStr* Pstr Output String

AjBool RETURN ajTrue on success.

Output

Pstr:

(Output)

String

Input & Output

list:

(Modify)

List

Returns

AjBool:

ajTrue on success.

Description

Remove the last node but set pointer to data first.

Availability

In release 6.4.0

Section: Element retrieval

Functions: ajListstrGetLength ajListstrMapfind ajListstrMapread ajListstrPeek ajListstrToarray ajListstrToarrayAppend

Function ajListstrGetLength

get the number of nodes in the linked list.

Synopsis

Prototype

ajuint ajListstrGetLength (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input List

ajuint RETURN Number of nodes in list.

Input

list:

(Input)

List

Returns

ajuint:

Number of nodes in list.

Description

get the number of nodes in the linked list.

Availability

In release 6.4.0

Function ajListstrMapfind

For each node in the list call function apply and return ajTrue when any node is matched by the function.

Synopsis

Prototype

AjBool ajListstrMapfind (
      const AjPList list,
      AjBool function apply,
      void* cl
);

Input

list:	(Input)	List
apply:	(Function)	Function to call to test each list item.

Input & Output

cl:

(Modify)

Standard, usually NULL.

Returns

AjBool:

ajTrue on success.

Description

For each node in the list call function apply and return ajTrue when any node is matched by the function.

Availability

In release 6.4.0

Function ajListstrMapread

For each node in the list call function apply, with the address of the string and a client pointer. The apply function must not modify the list elements.

Synopsis

Prototype

void ajListstrMapread (
      const AjPList list,
      void* function apply,
      void* cl
);

Type Name Read/Write Description

const AjPList list Input List.

void* function apply Function Function to call for each list item.

void* cl Modify Standard, usually NULL.

void RETURN

Input

list:	(Input)	List.
apply:	(Function)	Function to call for each list item.

Input & Output

cl:

(Modify)

Standard, usually NULL.

Returns

void:

No return value

Description

For each node in the list call function apply, with the address of the string and a client pointer. The apply function must not modify the list elements.

Availability

In release 6.4.0

Function ajListstrPeek

Return the first node but keep it on the list.

Synopsis

Prototype

AjBool ajListstrPeek (
      const AjPList list,
      AjPStr* Pstr
);

Type Name Read/Write Description

const AjPList list Input List

AjPStr* Pstr Output String

AjBool RETURN ajTrue on success.

Input

list:

(Input)

List

Output

Pstr:

(Output)

String

Returns

AjBool:

ajTrue on success.

Description

Return the first node but keep it on the list.

Availability

In release 6.4.0

Function ajListstrToarray

create an array of the pointers to the data.

Synopsis

Prototype

ajuint ajListstrToarray (
      const AjPList list,
      AjPStr** array
);

Type Name Read/Write Description

const AjPList list Input List

AjPStr** array Output Array of Strings.

ajuint RETURN Size of array of pointers.

Input

list:

(Input)

List

Output

array:

(Output)

Array of Strings.

Returns

ajuint:

Size of array of pointers.

Description

create an array of the pointers to the data.

Availability

In release 6.4.0

Function ajListstrToarrayAppend

append to an array of the pointers to the data.

Synopsis

Prototype

ajuint ajListstrToarrayAppend (
      const AjPList list,
      AjPStr** array
);

Type Name Read/Write Description

const AjPList list Input List

AjPStr** array Output Array of Strings.

ajuint RETURN Size of array of pointers.

Input

list:

(Input)

List

Output

array:

(Output)

Array of Strings.

Returns

ajuint:

Size of array of pointers.

Description

append to an array of the pointers to the data.

Availability

In release 6.4.0

Section: Trace functions

Functions: ajListstrTrace

Function ajListstrTrace

Traces through a string list and validates it

Synopsis

Prototype

void ajListstrTrace (
      const AjPList list
);

Type Name Read/Write Description

const AjPList list Input list to be traced.

void RETURN

Input

list:

(Input)

list to be traced.

Returns

void:

No return value

Description

Traces through a string list and validates it

Availability

In release 6.4.0

Section: Destructors

Functions: ajListstrFree ajListstrFreeData

Function ajListstrFree

Free the list. Do not attempt to free the nodes. For use where the node data has been saved elsewhere, for example by ajListToarray or where the list is a temporary structure referring to permanent data.

Synopsis

Prototype

void ajListstrFree (
      AjPList* Plist
);

Type Name Read/Write Description

AjPList* Plist Delete List

void RETURN

Output

Plist:

(Delete)

List

Returns

void:

No return value

Description

Availability

In release 6.4.0

Function ajListstrFreeData

Free all nodes in a string list. Also deletes all the strings. If these are to be preserved, use ajListstrDel instead.

Synopsis

Prototype

void ajListstrFreeData (
      AjPList* Plist
);

Type Name Read/Write Description

AjPList* Plist Delete List

void RETURN

Output

Plist:

(Delete)

List

Returns

void:

No return value

Description

Free all nodes in a string list. Also deletes all the strings. If these are to be preserved, use ajListstrDel instead.

Availability

In release 6.4.0

Datatype: AjIList

String list iterators

Sections: stepping modifiers Trace functions

Section: stepping

Functions: ajListstrIterGet ajListstrIterGetBack

Function ajListstrIterGet

Returns next item using iterator, or steps off the end.

Synopsis

Prototype

AjPStr ajListstrIterGet (
      AjIList iter
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

AjPStr RETURN Data item returned.

Input & Output

iter:

(Modify)

List iterator.

Returns

AjPStr:

Data item returned.

Description

Returns next item using iterator, or steps off the end.

Availability

In release 6.4.0

Function ajListstrIterGetBack

Returns next item using back iterator.

Synopsis

Prototype

AjPStr ajListstrIterGetBack (
      AjIList iter
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

AjPStr RETURN Data item returned.

Input & Output

iter:

(Modify)

List iterator.

Returns

AjPStr:

Data item returned.

Description

Returns next item using back iterator.

Availability

In release 6.4.0

Section: modifiers

Functions: ajListstrIterInsert ajListstrIterRemove

Function ajListstrIterInsert

Insert an item in a list, using an iterator (if not null) to show which position to insert. Otherwise, simply push.

Synopsis

Prototype

void ajListstrIterInsert (
      AjIList iter,
      AjPStr str
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

AjPStr str Modify String to insert.

void RETURN

Input & Output

iter:	(Modify)	List iterator.
str:	(Modify)	String to insert.

Returns

void:

No return value

Description

Insert an item in a list, using an iterator (if not null) to show which position to insert. Otherwise, simply push.

Availability

In release 6.4.0

Function ajListstrIterRemove

Remove an item from a list, using an iterator (if not null) to show which item. Otherwise remove the first item.

We want to remove the item just fetched by the iterator.

Synopsis

Prototype

void ajListstrIterRemove (
      AjIList iter
);

Type Name Read/Write Description

AjIList iter Modify List iterator.

void RETURN

Input & Output

iter:

(Modify)

List iterator.

Returns

void:

No return value

Description

Remove an item from a list, using an iterator (if not null) to show which item. Otherwise remove the first item.

We want to remove the item just fetched by the iterator.

Availability

In release 6.4.0

Section: Trace functions

Functions: ajListstrIterTrace

Function ajListstrIterTrace

Traces a list iterator and validates it

Synopsis

Prototype

void ajListstrIterTrace (
      const AjIList iter
);

Type Name Read/Write Description

const AjIList iter Input List iterator to be traced.

void RETURN

Input

iter:

(Input)

List iterator to be traced.

Returns

void:

No return value

Description

Traces a list iterator and validates it

Availability

In release 6.4.0

Type	Name	Read/Write	Description
const AjIList	iter	Input	List iterator.
AjBool		RETURN	ajTrue if the iterator is exhausted.

Type	Name	Read/Write	Description
AjIList	iter	Modify	List iterator.
void*		RETURN	Data item returned.

ajlist.c

Synopsis

Prototype

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Returns

Description

See Also

Availability

Synopsis

Prototype

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Output

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Input & Output

Returns

Description

See Also

Availability

Synopsis

Prototype

Input

Input & Output

Returns

Description