LLIST   (RPGLE)

Linked List Implementation
More ....

Procedures  [top]

getListEntryDs  
Get list entry data structure
isLinkedListImpl  
Check for linked list implementation
list_abortIteration exported
Abort iteration
list_add exported
Add list entry
list_addAll exported
Add all elements of a list
list_addFirst exported
Add list entry to the top of the list
list_addLast exported
Add list entry to the end of the list
list_clear exported
Clear list
list_contains exported
Contains entry
list_create exported
Create list
list_dispose exported
Dispose list
list_foreach exported
Execute procedure for every list item
list_get exported
Get entry
list_getFirst exported
Get first entry
list_getLast exported
Get last entry
list_getNext exported
Get next entry
list_getPrev exported
Get previous entry
list_indexOf exported
Index of entry
list_isEmpty exported
Check if list is empty
list_lastIndexOf exported
Last index of entry
list_remove exported
Remove list entry
list_removeFirst exported
Remove first list entry
list_removeLast exported
Remove last list entry
list_replace exported
Replaces an entry in the list
list_reverse exported
Reverse list
list_rotate exported
Rotate list by n positions
list_size exported
Get list size
list_split exported
Split character string
list_sublist exported
Create sublist
list_swap exported
Swap list items
list_toCharArray exported
To character array
list_toString exported
Return character representation of list
sendEscapeMessage  
Send Escape Message

Copybooks  [top]

LLIST_H
CEEAPI_H
ILE CEE API Prototypes

Details  [top]

This is a typical Doubly-Linked List (Two-Way Linked List) Implementation using dynamic memory allocation. The list is only able to store values of type character.

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 details  [top]

getListEntryDs  [top]

pointer getListEntryDs ( pointer, integer )
Returns the data structure of a list entry.
Parameter:
pointer — Pointer to the list
numeric (integer (10) — List position (zero-based)
Return value:
pointer — Pointer to list entry or *null
Author:
Mihael Schmidt
Date:
23.12.2007

isLinkedListImpl  [top]

boolean isLinkedListImpl ( 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 — Pointer to the list
Return value:
boolean — *on = is linked list implementation
*off = is no linked list implementation (escape message)
Author:
Mihael Schmidt
Date:
23.12.2007

list_abortIteration  [top]

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

list_add  [top]

boolean list_add ( pointer, pointer, unsigned integer, unsigned integer )
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 — Pointer to the list
pointer — Pointer to the new value
numeric (unsigned integer) (10) — Length of the new value
numeric (unsigned integer) (10) — List 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  [top]

boolean list_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 — Pointer to the destination list
pointer — Pointer 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_addFirst  [top]

boolean list_addFirst ( pointer, pointer, unsigned integer )
Parameter:
pointer — Pointer to the list
pointer — Pointer to new value
numeric (unsigned integer) (10) — Length of new value
Return value:
boolean — *on = successful
*off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_addLast  [top]

boolean list_addLast ( pointer, pointer, unsigned integer )
Parameter:
pointer — Pointer to the list
pointer — Pointer to new value
numeric (unsigned integer) (10) — Length of new value
Return value:
boolean — *on = successful
*off = error
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_clear  [top]

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

list_contains  [top]

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

list_create  [top]

pointer list_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:
pointer — Pointer to the list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_dispose  [top]

list_dispose ( pointer )
The memory for every entry and the header of the list are disposed (deallocated). The list pointer is set to *null;
Parameter:
pointer — Pointer to the list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_foreach  [top]

list_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 — Pointer to the list
pointer — Procedure pointer
pointer — Pointer to user data
Exported.
Author:
Mihael Schmidt
Date:
23.01.2008

list_get  [top]

pointer list_get ( pointer, unsigned integer )
Returns a list entry specified by the passed index.
Parameter:
pointer — Pointer to the list
numeric (unsigned integer) (10) — List position
Return value:
pointer — Pointer 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_getFirst  [top]

pointer list_getFirst ( pointer )
Returns the first entry of the list.
Parameter:
pointer — Pointer to the list
Return value:
pointer — Pointer 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_getLast  [top]

pointer list_getLast ( pointer )
Returns the last entry of the list.
Parameter:
pointer — Pointer to the list
Return value:
pointer — Pointer 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_getNext  [top]

pointer list_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 — Pointer to the list
Return value:
pointer — Pointer to entry or *null if no more entries in list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_getPrev  [top]

pointer list_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 — Pointer to the list
Return value:
pointer — Pointer to entry or *null if no more entries in list
Exported.
Author:
Mihael Schmidt
Date:
18.12.2007

list_indexOf  [top]

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

list_isEmpty  [top]

boolean list_isEmpty ( pointer )
Checks if the list is empty.
Parameter:
pointer — Pointer 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  [top]

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

list_remove  [top]

boolean list_remove ( pointer, unsigned integer )
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 — Pointer to the list
numeric (unsigned integer) (10) — index 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  [top]

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

list_removeLast  [top]

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

list_replace  [top]

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

list_reverse  [top]

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

list_rotate  [top]

list_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 — Pointer to the list
numeric (integer (10) — Number positions to rotate list
Exported.
Author:
Mihael Schmidt
Date:
23.01.2008

list_size  [top]

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

list_split  [top]

pointer list_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) — Character string (null-terminated)
character (1) — Separator (default: ;)
Return value:
pointer — Pointer to the filled list
Exported.
Author:
Mihael Schmidt
Date:
08.02.2008

list_sublist  [top]

pointer list_sublist ( pointer, unsigned integer, unsigned integer )
Creates a list with copies of a part of the passed list.
Parameter:
pointer — Pointer to the list
numeric (unsigned integer) (10) — start of the index to copy
numeric (unsigned integer) (10) — number of elements to copy
Return value:
pointer — new list
Exported.
Author:
Mihael Schmidt
Date:
16.1.2008

list_swap  [top]

boolean list_swap ( pointer, unsigned integer, unsigned integer )
Parameter:
pointer — Pointer to the list
numeric (unsigned integer) (10) — List item to swap
numeric (unsigned integer) (10) — List item to swap
Exported.
Author:
Mihael Schmidt
Date:
23.01.2008

list_toCharArray  [top]

list_toCharArray ( pointer, pointer, unsigned integer, unsigned integer )
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 — Pointer to the list
pointer — Pointer to the array
numeric (unsigned integer) (10) — Element count
numeric (unsigned integer) (10) — Element length
Exported.
Author:
Mihael Schmidt
Date:
19.12.2007

list_toString  [top]

character list_toString ( pointer, 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 — Pointer to the list
character (1) — separator (default: ,)
character (100) — enclosing 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  [top]

sendEscapeMessage ( integer )
Sends an escape message with the specified id.
Parameter:
numeric (integer (10) — Message id
Author:
Mihael Schmidt
Date:
23.12.2007
Created Sat Apr 05 11:23:31 CEST 2008 by Mihael Schmidt