LIST_INTRO(3)

NAME
xxQS_NAMExx List Library - a library providing generic list functionality and database like list management

DESCRIPTION
The xxQS_NAMExx List Library provides the functionality of a generic list. This means the list functions are applicable to every list based on a number of certain basic types. List definitions are extensible on a per program basis as long as the old fields remain in the list definition.

LIBRARY FUNCTIONS
The list library provides the following functions. These are explained in detail in the stated man pages.

  LIST FUNCTIONS

create a generic list

create a generic list with a certain number of empty elements

free the memory allocated for a generic list and all its sub-lists

copy a generic list with all its sub-lists and strings

concatenate two generic lists

sort a generic list

dump a generic list to file

undump a generic list with all its data from file

write a generic list to stdout

return the name of a generic list

return a pointer to the descriptor of a generic list

return the number of list elements contained in a generic list

return the number of list elements contained in the remainder of a
    generic list after a specified list element

  LIST ELEMENT FUNCTIONS

create a generic list element

frees the memory allocated for a generic list element, its strings and its
    sub-lists

duplicate a list element with all its sub-lists and strings

append a list element to an existing list

insert a list element into an existing list after a specified element

dechain a list element from a list, the dechained element is not freed

get the first list element

get the last list element

get the successor of the list element

get the predecessor of the list element

find the first list element matching specified conditions

find the last list element matching specified conditions

find the next list element starting at a certain list element matching
    specified conditions

find the previous list element starting at a certain list element matching
    specified conditions

dump a list element to file

undump a list element from file into memory

write a list element to stdout

get the field position of a list element field with name 'nm'

  FIELD ACCESS FUNCTIONS

get the value of the specified type from a list element field;
    the element and the field name are delivered as arguments

set the value of the specified type in a corresponding list element field;
    the element, the field name and a new value are delivered as arguments

get the value of the specified type in a corresponding list element field;
    the element and the field position are delivered as arguments

set the value of the specified type in a corresponding list element field;
    the element, the field position and the new value are delivered as arguments

  LIST DESCRIPTOR FUNCTIONS

initialize the name to string conversion

convert an int value specifying a field name to its corresponding name string

convert an int value specifying a field name to its corresponding name string
    using a specified name space

convert a field name to its corresponding field id

convert a field name to its corresponding field id
    using a specified name space

get the number of fields of a descriptor

get the position of the field named 'nm' from the descriptor

dump a list descriptor to a file

undump a list descriptor from a file to memory

write a descriptor to stdout

  LIST DATABASE FUNCTIONS

select returns a list of elements that match the specified conditions.

select reduces a list to those elements matching the specified conditions.

splits a list into two parts. One part contains all elements fulfilling the
    specified condition the other part contains the elements not fulfilling the condition.

join a specified list with one of its sub-lists; one can specify conditions
    for the list and the sub-list. The joined list is returned and the original list is unchanged.

join two lists which fulfill the specified conditions to a new list that
    contains the enumerated fields. The joined list is returned and the original lists are unaltered.

build a lCondition data structure which is used as condition
    for various functions as lSelect or lJoin

build a lCondition data structure which is used as condition
    for various functions as lSelect or lJoin

build a lCondition data structure composed of two conditions
    connected by logical or

build a lCondition data structure composed of two conditions
    connected by logical and

free a lCondition data structure

write a lCondition data structure to stdout

build a lEnumeration data structure which is used to specify the fields that
    are contained in a newly created list element

free a lEnumeration data structure

write a lEnumeration data structure to stdout

count the number of fields in a lEnumeration data structure

  DATA STRUCTURES
The following essential data structures are used by the various list library functions.

lDescr *descriptor
    The descriptor contains the information which fields (name, type) are contained in a list.

lList  *list
    The lList pointer specifies a list created by lCreateList or any of the other functions generating a list. Here the name of the list, a reference to the descriptor, the number of contained list elements and a reference to the first and last list element are stored.

lListElem *list_element
    The lListElem pointer is returned on creation of a new list element and contains the actual data.

lCondition *conditions
    The lCondition pointer is a representation of logically connected compare operations. It serves to decide whether it should be operated on a special list element.

lEnumeration *field_enumerations
    The lEnumeration pointer specifies which fields of a given list element shall be involved in a specified action. It is possible under certain circumstances to specify all fields or no field at all.

lSortOrder *sorting_order
    The lSortOrder pointer is used to specify sorting criteria for a generic list. It is possible to declare combined sorting keys.

SEE ALSO

COPYRIGHT
See for a full statement of rights and permissions.