ELEMENT_FUNCS(3)

NAME
lCreateElem, lFreeElem, lCopyElem, lAppendElem, lInsertElem, lDechainElem, lFirst, lLast, lNext, lPrev, lFindFirst, lFindLast, lFindNext, lFindPrev, lDumpElem, lUndumpElem, lWriteElem, lWriteElemTo, lGetPosViaElem

generic list element manipulation and information functions

SYNOPSIS
#include "cull.h"

lListElem* lCreateElem( lDescr *descriptor );

void lFreeElem( lListElem *element );

lListElem* lCopyElem( lListElem *source );

lListElem* lAppendElem( lList *list, lListElem *newelem );

lListElem* lDechainElem(
    lList* list,
    lListElem* element
);

lListElem* lFirst( lList* list );

lListElem* lLast( lList* list );

lListElem* lNext( lListElem* element );

lListElem* lPrev( lListElem* element );

lListElem* lFindFirst(
    lList* list,
    lCondition* condition
);

lListElem* lFindLast(
    lList* list,
    lCondition* condition
);

lListElem* lFindNext(
    lListElem* element,
    lCondition* element
);

lListElem* lFindPrev(
    lListElem* element,
    lCondition* element
);

int lDumpElem(
    FILE *file,
    lListElem *element,
    int indent,
    int number
);

lListElem* lUndumpElem( FILE *file, lDescr *descriptor );

void lWriteElem( lListElem *element );

void lWriteElemTo( lListElem *element, FILE *fp );

int lGetPosViaElem( lListElem *element, int nm );

DESCRIPTION

lCreateElem
    creates a new list element specified by descriptor. In case of success, a pointer to the list element is returned, otherwise the return value is NULL. All list element fields are set to zero. There is memory allocated for the list element, that must be released with lFreeElem.

lFreeElem
    frees the memory allocated by lCreateElem. If there are sub-list or string fields their memory is also released. If the list element is NULL the function simply returns.

lCopyElem
    duplicates a list element with all its sub-lists and strings. If an error occurs NULL is returned, otherwise a pointer to the copied list element is returned. If the copied list element is no longer used, the allocated memory has to be released with lFreeElem.

lAppendElem
    append a list element to a generic list as the last element. The first argument is the list to which the new element shall be appended. The second argument is the new element. Sometimes it may be useful to use a copy of the element to be inserted in the list (see lCopyList).

lInsertElem
    inserts a new element after the specified element in the list. The first argument is the list, the second argument is the list element, after which the new element shall be inserted, and the third element is the new list element. Sometimes it may be useful to use a copy of the element to be inserted in the list (see lCopyList).

lDechainElem
    dechains the specified element from the generic list. A pointer to the list element is returned. The list element is not destroyed. If it shall be destroyed lFreeElem should be called.

lFirst, lLast
    get the first/last element of the specified list. If no list is specified or no elements are contained, NULL is returned. Otherwise a pointer to the first/last list element is returned.

lNext, lPrev
    get the successor/predecessor of the specified element. If the specified element is NULL or the last/first element in the list, NULL is returned. Otherwise a pointer to the successor/predecessor is returned.

lFindFirst, lFindLast
    find the first/last element matching the specified condition. The first argument is the generic list where the requested list element may be contained. The second element is the condition that shall be fulfilled by the element. The list is searched in the order first/last to last/first element. If there is no element that matches the condition NULL is returned. If there is no list specified, the return value is also NULL, otherwise a pointer to the first/last matching list element is returned.

lFindNext, lFindPrev
    find the next/previous element matching the specified condition. The first argument is the list element returned by lFindFirst/lFindLast or lFindNext/lFindPrev. The second argument is the condition which should be equal to the one stated in the corresponding lFindFirst/lFindLast call. The return value is NULL, if the specified list element is NULL or no matching element is found. Otherwise a pointer to the matching list element is returned.

lDumpElem
    dumps a list element in ASCII format to a file. The first argument is a FILE pointer, the second argument is the list element to be dumped, the third argument is the number of indentation units for formatting purposes and the fourth argument is the number of the element. This function is normally called by

lUndumpElem
    undumps a list element from a dump file. The first argument is a FILE pointer of the dump file. The second argument is the descriptor of the list element. If one or both of the function arguments are NULL, NULL is retuned. Otherwise a pointer to the newly created list element is returned. If the element is no longer used, lFreeElem has to be called. This function is normally called by only.

lWriteElem
    writes the contents of a list element with all its sub-lists if Monitoring Level CULL_LAYER is set to info. The only argument is a list element.

lWriteElemTo
    writes the contents of a list element with all its sub-lists to the stream connected with the file pointer fp. The first argument is a list element, the second argument is a file pointer or NULL. If the file pointer is NULL, this function behaves exactly as lWriteElemTo.

lGetPosViaElem
    get the field position of a field with name nm in the list element element. The position of the field named nm is returned. If the field does not exist in the list element -1 is returned.

RETURN VALUES
In case of error the return value is -1 or NULL, otherwise 0 or a valid pointer to the corresponding struct is returned.

ERRORS
The following errors may occur. The affected functions are listed in parentheses.

LECOUNTDESCR
    Counting the descriptor length failed. (lCreateElem, lUndumpElem)

LEMALLOC
    failed. (lCreateElem)

LEELEMNULL
    List element is NULL. (lFreeElem, lCopyElem, lAppendElem, lInsertElem, lDechainElem, lFindNext, lWriteElem, lGetPosViaElem, lDumpElem)

LELISTNULL
    List is NULL. (lAppendElem, lInsertElem, lDechainElem, lFindFirst)

LECREATEELEM
    Creation of a list element failed. (lCopyElem, lUndumpElem)

LEFILENULL
    File pointer is NULL. (lDumpElem, lUndumpElem)

LEDESCRNULL
    List descriptor pointer is NULL. (lUndumpElem)

LECOPYSWITCH
    Copying a list element field failed. (lCopyElem)

LESYNTAX
    A syntax error occurred (missing opening or closing brackets). (lUndumpElem)

SEE ALSO

COPYRIGHT
See for a full statement of rights and permissions.