LLIST (RPGLE)

Linked List Implementation
Details ....

Copybooks  

LLIST_IN_H
Linked List : Internal Prototypes
LLIST_H
Linked List Prototypes
LLIST_SO_H
Linked List : Sorting Algorithms Prototypes
CEEAPI_H
ILE CEE API Prototypes

Procedures  

getListEntryDsexported
Get list entry data structure
internal_swapexported
isLinkedListImplexported
Check for linked list implementation
list_abortIterationexported
Abort iteration
list_addexported
Add list entry
list_addAllexported
Add all elements of a list
list_addBooleanexported
Add boolean list entry
list_addDateexported
Add date list entry
list_addDecimalexported
Add packed decimal list entry
list_addDoubleexported
Add double list entry
list_addFirstexported
Add list entry to the top of the list
list_addFloatexported
Add float list entry
list_addIntegerexported
Add integer list entry
list_addLastexported
Add list entry to the end of the list
list_addLongexported
Add long list entry
list_addShortexported
Add short list entry
list_addStringexported
Add character list entry
list_clearexported
Clear list
list_containsexported
Contains entry
list_copyexported
Create a copy of a list
list_createexported
Create list
list_disposeexported
Dispose list
list_foreachexported
Execute procedure for every list item
list_frequencyexported
Frequency of a value in the list
list_getexported
Get entry
list_getBooleanexported
Get boolean entry
list_getDateexported
Get date entry
list_getDecimalexported
Get packed decimal entry
list_getDoubleexported
Get double entry
list_getFirstexported
Get first entry
list_getFloatexported
Get float entry
list_getIntegerexported
Get integer entry
list_getLastexported
Get last entry
list_getLongexported
Get long entry
list_getNextexported
Get next entry
list_getPrevexported
Get previous entry
list_getShortexported
Get short entry
list_getStringexported
Get character entry
list_indexOfexported
Index of entry
list_isEmptyexported
Check if list is empty
list_lastIndexOfexported
Last index of entry
list_mergeexported
Merge lists
list_removeexported
Remove list entry
list_removeFirstexported
Remove first list entry
list_removeLastexported
Remove last list entry
list_removeRangeexported
Remove range of elements
list_replaceexported
Replaces an entry in the list
list_reverseexported
Reverse list
list_rotateexported
Rotate list by n positions
list_sizeexported
Get list size
list_sortexported
Sort list
list_splitexported
Split character string
list_sublistexported
Create sublist
list_swapexported
Swap list items
list_toCharArrayexported
To character array
list_toStringexported
Return character representation of list
sendEscapeMessageexported
Send Escape Message

Detailed Description  

This is a typical Doubly-Linked List (Two-Way Linked List) Implementation using dynamic memory allocation. The list is particular suitable for character values but does also work with any other data (f. e. data structures).

Values are stored as null-terminated chars.

Operations that index into the list will traverse the list from the beginning or the end, whichever is closer to the specified index.

Iteration: With the procedure getNext the list is traversable in the top-bottom direction. Each call to getNext will return the next entry of the list till the end of the list. If the walk through the list should be stopped early (before the end of the list) the method abortIteration should be called. If the list is structurally modified at any time after an iteration has begun in any way, the result of the iteration can not be safely determined. If an iteration is not going to continue the procedure abortIteration should be called. After that call it is safe to modify the list again.

Throughout this service program a zero-based index is used.

This list implementation is not thread-safe.
Author:
Mihael Schmidt
Date:
20.12.2007

Procedure Documentation  

getListEntryDs  

pointergetListEntryDs(pointer, integer)
Returns the data structure of a list entry.
Parameter:
pointer   constPointer to the list
numeric (integer) (10)   constList position (zero-based)
Return value:
pointerPointer to list entry or *null
Exported.
Author:
Mihael Schmidt
Date:
23.12.2007

internal_swap  

voidinternal_swap()
Exported.

isLinkedListImpl  

booleanisLinkedListImpl(pointer)
Checks if the pointer points to a linked list implementation. The linked list implementation of this service program has an id in the first 20 bytes of the list header.

If the pointer does not point to a list implementation an escape message will be sent.
Parameter:
pointer   constPointer to the list
Return value:
boolean*on = is linked list implementation
*off = is no linked list implementation (escape message)
Exported.
Author:
Mihael Schmidt
Date:
23.12.2007

list_abortIteration  

voidlist_abortIteration(pointer)
If the iteration through the list should be aborted early this procedure should be called.
Parameter:
pointer   constPointer to the list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_add  

booleanlist_add(pointer, pointer, unsigned, unsigned)
Adds an entry at an exact position in the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
pointer   constPointer to the new value
numeric (unsigned) (10)   constLength of the new value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_addAll  

booleanlist_addAll(pointer, pointer)
Adds all elements of the passed list to the end of this list. Elements will not be referenced but storage newly allocated.
Parameter:
pointer   constPointer to the destination list
pointer   constPointer to the source list
Return value:
boolean*on = all elements added to list
*off = not all or none elements added
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_addBoolean  

booleanlist_addBoolean(pointer, boolean, unsigned)
Adds a boolean entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
boolean   constBoolean value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addDate  

booleanlist_addDate(pointer, date, unsigned)
Adds a date entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
date   constDate value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addDecimal  

booleanlist_addDecimal(pointer, packed, unsigned)
Adds a packed decimal entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
numeric (packed) (15,5)   constPacked decimal value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addDouble  

booleanlist_addDouble(pointer, float, unsigned)
Adds a double entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
numeric (float) (8,)   constDouble value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addFirst  

booleanlist_addFirst(pointer, pointer, unsigned)
Parameter:
pointerPointer to the list
pointer   constPointer to new value
numeric (unsigned) (10)   constLength of new value
Return value:
boolean*on = successful
*off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_addFloat  

booleanlist_addFloat(pointer, float, unsigned)
Adds a float entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
numeric (float) (4,)   constFloat value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addInteger  

booleanlist_addInteger(pointer, integer, unsigned)
Adds an integer entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
numeric (integer) (10)   constInteger value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addLast  

booleanlist_addLast(pointer, pointer, unsigned)
Parameter:
pointer   constPointer to the list
pointer   constPointer to new value
numeric (unsigned) (10)   constLength of new value
Return value:
boolean*on = successful
*off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_addLong  

booleanlist_addLong(pointer, integer, unsigned)
Adds a long entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
numeric (integer) (20)   constLong value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addShort  

booleanlist_addShort(pointer, integer, unsigned)
Adds a short entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
numeric (integer) (5)   constShort value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_addString  

booleanlist_addString(pointer, character, unsigned)
Adds a character entry to the list. If the position is outside the list the procedure returns *off. The current entry of the list at that position will be pushed one position down the list.

If no position is passed to the procedure then the entry will be appended to the end of the list (like addLast).
Parameter:
pointer   constPointer to the list
character (65535)   const   variable sizeCharacter value
numeric (unsigned) (10)   const   optionalList position for the new value (optional)
Return value:
boolean*on = entry added the list
*off = error
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_clear  

booleanlist_clear(pointer)
Deletes all entries in the list.
Parameter:
pointer   constPointer to the list
Return value:
boolean*on = successful
*off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_contains  

booleanlist_contains(pointer, pointer, unsigned)
Checks if this list contains the passed entry.
Parameter:
pointer   constPointer to the list
pointer   constPointer to value
numeric (unsigned) (10)   constLength of value
Return value:
boolean*on = list contains value
*off = list does not contain value
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_copy  

pointerlist_copy(pointer)
Creates a list with copies of all elements of the list.
Parameter:
pointer   constPointer to the list
Return value:
pointerPointer to the new list
Exported.
Author:
Mihael Schmidt
Date:
7.4.2008

list_create  

pointerlist_create()
Creates a list. A header is generated for the list and the pointer to the list returned.

A list must be disposed via the procedure dispose to free all allocated memory.
Return value:
pointerPointer to the list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_dispose  

voidlist_dispose(pointer)
The memory for whole list are is released (deallocated). The list pointer is set to *null;

If the passed pointer is already *null the procedure simply returns.
Parameter:
pointerPointer to the list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_foreach  

voidlist_foreach(pointer, pointer, pointer)
The passed procedure will be executed for every item in the list.

The user can pass data through a pointer to the procedure. The pointer will not be touched by this procedure itself, so it can be *null.

The value of list entry can be changed through the passed procedure but not the size of the entry/allocated memory.
Parameter:
pointer   constPointer to the list
pointer   constProcedure pointer
pointer   constPointer to user data
Exported.
Author:
Mihael Schmidt
Date:
23.01.2008

list_frequency  

unsignedlist_frequency(pointer, pointer, unsigned)
Returns the number of times the passed value can be found in the list.
Parameter:
pointer   constPointer to the list
pointer   constPointer to the value
numeric (unsigned) (10)   constLength of the value
Return value:
numeric (unsigned) (10)number of copies of passed value in the list
Exported.
Author:
Mihael Schmidt
Date:
05.04.2008

list_get  

pointerlist_get(pointer, unsigned)
Returns a list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
pointerPointer to a null terminated string or *null if an error occured or there is no entry at that position
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_getBoolean  

booleanlist_getBoolean(pointer, unsigned)
Returns a boolean list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
booleanBoolean value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getDate  

datelist_getDate(pointer, unsigned)
Returns a date list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
dateDate value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getDecimal  

packedlist_getDecimal(pointer, unsigned)
Returns a packed decimal list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
numeric (packed) (15,5)Packed decimal value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getDouble  

floatlist_getDouble(pointer, unsigned)
Returns a double list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
numeric (float) (8,)Double value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getFirst  

pointerlist_getFirst(pointer)
Returns the first entry of the list.
Parameter:
pointer   constPointer to the list
Return value:
pointerPointer to a null terminated string or *null if the list is empty or an error occured
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_getFloat  

floatlist_getFloat(pointer, unsigned)
Returns a float list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
numeric (float) (4,)Float value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getInteger  

integerlist_getInteger(pointer, unsigned)
Returns an integer list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
numeric (integer) (10)Integer value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getLast  

pointerlist_getLast(pointer)
Returns the last entry of the list.
Parameter:
pointer   constPointer to the list
Return value:
pointerPointer to a null terminated string or *null if the list is empty or an error occured
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_getLong  

integerlist_getLong(pointer, unsigned)
Returns a long list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
numeric (integer) (20)Long value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getNext  

pointerlist_getNext(pointer)
Iterates through the list and gets the next entry. If the iterator is at the end of the list this method will return null. The iteration can be aborted early with the procedure list_abortIteration.
Parameter:
pointer   constPointer to the list
Return value:
pointerPointer to entry or *null if no more entries in list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_getPrev  

pointerlist_getPrev(pointer)
Iterates through the list and gets the previous entry. If the iterator is before the start of the list this method will return null. The iteration can be aborted early with the procedure list_abortIteration.
Parameter:
pointer   constPointer to the list
Return value:
pointerPointer to entry or *null if no more entries in list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_getShort  

integerlist_getShort(pointer, unsigned)
Returns a short list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
numeric (integer) (5)Short value of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_getString  

characterlist_getString(pointer, unsigned)
Returns a character list entry specified by the passed index.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList position
Return value:
character (65535)Character string of the specified position
Exported.
Author:
Mihael Schmidt
Date:
21.09.2008

list_indexOf  

integerlist_indexOf(pointer, pointer, unsigned)
Returns the index of the passed entry or -1 if the entry could not be found in the list.
Parameter:
pointer   constPointer to the list
pointer   constPointer to the value
numeric (unsigned) (10)   constLength of the value
Return value:
numeric (integer) (10)index of the entry or -1 if entry not in list
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_isEmpty  

booleanlist_isEmpty(pointer)
Checks if the list is empty.
Parameter:
pointer   constPointer to the list
Return value:
boolean*on = list is empty
*off = list is not empty
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_lastIndexOf  

integerlist_lastIndexOf(pointer, pointer, unsigned)
Returns the last indes of the passed entry or -1 if the entry could not be found in the list.
Parameter:
pointer   constPointer to the list
pointer   constPointer to the value
numeric (unsigned) (10)   constLength of the value
Return value:
numeric (integer) (10)index of the entry or -1 if entry not in list
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_merge  

voidlist_merge(pointer, pointer)
Merges the elements of second list with the first list. Elements which are already in the first list are not added.
Parameter:
pointer   constDestination list
pointer   constSource list
Exported.
Author:
Mihael Schmidt
Date:
15.12.2009

list_remove  

booleanlist_remove(pointer, unsigned)
Removes an entry from the list at the given position. If the position is outside of the list the return value will be *off.

The index is 0 (zero) based.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constindex of the entry in the list (zero-based)
Return value:
boolean*on = entry removed *off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_removeFirst  

booleanlist_removeFirst(pointer)
Removes the first entry from the list.
Parameter:
pointer   constPointer to the list
Return value:
boolean*on = entry removed
*off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_removeLast  

booleanlist_removeLast(pointer)
Removes the last entry from the list.
Parameter:
pointer   constPointer to the list
Return value:
boolean*on = entry removed
*off = error (escape message)
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_removeRange  

voidlist_removeRange(pointer, unsigned unsigned)
Removes a number of elements from the list.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10) numeric (unsigned) (10)   constStarting index
Number of elements to remove
Exported.

list_replace  

booleanlist_replace(pointer, pointer, unsigned, unsigned)
An element in the list will be replaced. If there is no element at that position the return value will be *off.
Parameter:
pointer   constPointer to the list
pointer   constPointer to new value
numeric (unsigned) (10)   constLength of new value
numeric (unsigned) (10)   constindex of new value
Return value:
boolean*on = entry successfully replaced
*off = error
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_reverse  

voidlist_reverse(pointer)
Reverse the order of the list by simply switching the previous and next pointers of each element.
Parameter:
pointer   constPointer to the list
Exported.

list_rotate  

voidlist_rotate(pointer, integer)
Rotates items in the list by the given number.

The elements from the end will be pushed to the front. A rotation of one will bring the last element to the first position and the first element will become the second element (pushed one position down the list).

Only a forward rotation is possible. No negative number of rotations are valid.

The number of rotations may even be greater than the size of the list. Example: List size 4, rotation number 5 = rotation number 1.
Parameter:
pointer   constPointer to the list
numeric (integer) (10)   constNumber positions to rotate list
Exported.
Author:
Mihael Schmidt
Date:
23.01.2008

list_size  

unsignedlist_size(pointer)
Returns the number elements in the list.
Parameter:
pointer   constPointer to the list
Return value:
numeric (unsigned) (10)number of elements in the list or -1 if an error occurs
Exported.
Author:
Mihael Schmidt
Date:
16.01.2008

list_sort  

voidlist_sort(pointer pointer)
Sorts the list with the passed procedure.
The passed procedure should have the list pointer as its only parameter (const) and should sort the list in-place.
Parameter:
pointer pointer   constPointer to the list
Procedure pointer to the sort procedure
Exported.

list_split  

pointerlist_split(character, character)
The passed character string will be split into tokens by either a passed or the default separator. All tokens will be added to a new list which will be returned.

Empty (but not blank) values will be dropped silently.
Parameter:
character (65535)   const   variable sizeCharacter string (null-terminated)
character (1)   const   optionalSeparator (default: ;)
Return value:
pointerPointer to the filled list
Exported.
Author:
Mihael Schmidt
Date:
08.02.2008

list_sublist  

pointerlist_sublist(pointer, unsigned, unsigned)
Creates a list with copies of a part of the passed list.
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   conststart of the index to copy
numeric (unsigned) (10)   const   optionalnumber of elements to copy
Return value:
pointernew list
Exported.
Author:
Mihael Schmidt
Date:
16.1.2008

list_swap  

voidlist_swap(pointer, unsigned, unsigned)
Parameter:
pointer   constPointer to the list
numeric (unsigned) (10)   constList item to swap
numeric (unsigned) (10)   constList item to swap
Exported.
Author:
Mihael Schmidt
Date:
23.01.2008

list_toCharArray  

voidlist_toCharArray(pointer, pointer, unsigned, unsigned)
Copies all entries of this list to the passed array. Entries will be truncated if they are too big for the array. If the array is not big enough, the last entries will be silently dropped.
Parameter:
pointer   constPointer to the list
pointer   constPointer to the array
numeric (unsigned) (10)   constElement count
numeric (unsigned) (10)   constElement length
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_toString  

characterlist_toString(pointer, character, character character, Character)
Returns a string with the list items separated either by the passed or default separator. The items can be enclosed by a passed character. The maximum character length returned is 65535. Every character/item after that will be dropped silently. Items will not be trimmed for this operation.

If the third parameter is passed, the third parameter will be pre- and appended to the item. If the fourth parameter is also passed the third parameter will be prepended to the item and the fourth parameter will be appended to the item.
Parameter:
pointer   constPointer to the list
character (1)   const   varying   optional   omissibleseparator (default: ,)
character (100) character (100)   const   varying   optionalenclosing character (default: nothing)
Character (100)enclosing character at the end of item (default: nothing)
Return value:
character (65535)character representation of all list items
Exported.
Author:
Mihael Schmidt
Date:
08.02.2008

sendEscapeMessage  

voidsendEscapeMessage(integer)
Sends an escape message with the specified id.
Parameter:
numeric (integer) (10)   constMessage id
Exported.
Author:
Mihael Schmidt
Date:
23.12.2007