LIST(5)

Table of Contents

• Name
• Synopsis
• Description
• See Also

Name

next

returns the next element in a list

previous

returns the previous element in a list

prepend

adds an element to the front of a list

append

adds an element to the end of a list

delete

deletes an element from a list separator returns the separator between two elements

length

returns the length of a list

Synopsis

ANY next(list)
ANY list;
ANY previous(list)
ANY list;
ANY append(any, ptr2list)
ANY any;
ANY *ptr2list;
ANY prepend(any, ptr2list)
ANY any;
ANY *ptr2list;
ANY delete(any, ptr2list)
ANY any;
ANY *ptr2list;
ANY separator(list)
ANY list;
int length(list)
ANY list;

Description

These components of the run-time library provide a collection of list handling operations. Every sequence item and list-structure definition in a grammar section causes ivy*meta SDTB to create a new data type that can be used to build lists. Elements (the terms node and element are synonymous in this context) of these types contain fields that are accessed by the normal selector macros (see GRAMMAR(2) ), and they also contain fields that are used to structure the list. The lists are doubly-linked lists, so each node refers to the nodes before it and after it in the list. There is no special data type for a list of nodes; a list is simply represented by its first element.

In the case of sequence items, the parser automatically builds the lists (using the operations defined here) as part of the specification parse tree. In the case of liststructures, the SDTool builder must explicitly allocate (see ALLOC(5) ) the elements and build the lists. The SDTool builder can also explicitly create lists of sequence item nodes that are independent of the parse tree. The list

operations described here can be used on both parse tree node lists and list-structure lists.

The next macro returns the next element from a list of nodes. If there is no next element, next returns NULL. The previous macro returns the previous element from a list of nodes. If there is no previous element, previous returns NULL.

The functions append, prepend and delete modify a list by adding or deleting elements. The second parameter to all three must be the address of the list (that is, the address of the first node in the list) being modified. An empty list is represented as a NULL pointer; therefore the address of an empty list must be the address of a NULL pointer. An address must be passed because these three functions have side effects when they change the first element of the list. append inserts a new element at the end of a list; prepend inserts a new element at the beginning of a list; and delete deletes an element from a list. All three routines return the modified list (that is, the first node in the modified list) as their result. These functions assume that the any parameter is not a member of any other list, and they also assume that the next and previous links in the list to be changed are consistent. If an attempt is made to delete a node from an empty list, or from a list that does not contain the node, the list remains unchanged.

The separator macro returns the separating item that follows an element (as specified by a separated-by clause; see GRAMMAR(2) ). NULL is returned if there is no separator item. separator returns a node of type ANY; the node may require casting to the correct type before it can be used. The parent of a separator item is the same as the parent of a list element.

The length function returns the number of elements in the list that begins at element any (elements that are previous to any are not counted).

next, previous and separator are macros that select fields from an element node; their use will generate syntax errors if they are applied to arguments of incorrect type. These three macros cannot be applied to empty lists (that is, to NULL arguments). If they are, the SDTool writes an error message.

See Also

GRAMMAR(2)
FORALL(4)
ALLOC(5)
TRAVERSE(5)