Variable Size Data Sequence Library (libx1f4l2)

2.1.1.4 Variable Size Data Sequence Library

Data structure size retriever.
```
int x1f4_call_??list(unsigned *)
```
sets $1 to the number of bytes required by a ??list object (sort of sizeof(??list))

returns 0
Data deletion routine.
```
int x1f4_clip_??list(void *, unsigned, void *, int (*)(void *, void *))
```
removes the $2th element from the $1 sequence if $4 called with $3 and the data of the to be removed element returns 0

returns 0 for success, 0 if $4 returned not zero, one of the defined errors for failure
Plain copy routine.
```
int x1f4_copy_??list(void **, void *, int (*)(unsigned *, const void *))
```
copies the $2 sequence and stores the address of the newly created sequence at $1. The size of data stored by sequence nodes is determined by calling $3 and passing it the address at which the size is to be stored as the first argument and the sequence node data as the second argument. The return value of $3 is ignored. The data for sequence nodes is copied dumbly.

returns 0 for success, one of the defined errors for failure
Data rotation routine.
```
int x1f4_deck_??list(void *, int)
```
shifts (rotates/circulates) the $1 sequence (as if it was a circular list) until the ($2 % <sequence size> + <sequence size>) % <sequence size> element becomes the first

returns 0 for success, one of the defined errors for failure (should not fail)
Data exchange routine
```
int x1f4_deux_??list(void *, unsigned, void *, unsigned)
```
exchanges the $2 element of the $1 sequence with the $4 element of the $3 sequence

returns 0 for success, one of the defined errors for failure
Record retriever.
```
int x1f4_ever_??list(void *, void **)
```
stores the address of the data (i.e. payload) of the $1 sequence last element at $2

returns 0 for success, one of the defined errors for failure
Sequence constructor routine.
```
int x1f4_fast_??list(void *, unsigned, struct x1f4_??list_type *)
```
sets up a newly allocated ??list object, stored at $1, according the $2 bits (see ??list attribute bit definitions) and $3 setup values

The setup values in the struct x1f4_??list_type record pointed to by the $3 argument are only used if so requested by $2, the $3 argument is not considered otherwise.

See Variable Size Data Sequence Types.

See Variable Size Data Sequence Definitions.

returns 0 for success, one of the defined errors for failure
Plain search routine
```
int x1f4_find_??list
    (void *, void *, unsigned, int (*)(void *, void *), void **)
```
looks for some $1 sorted sequence item matching the $2 key according to the $4 comparison criterion, which when called is passed the $2 key and the start address of the data of the element being examined biased by $3 as arguments, in this order. Upon success, the start address of the found sequence element data is stored at $5.

$4 is expected to return a negative number if the key is less than the sequence element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the sequence element.

returns 0 if no match was found, non zero otherwise
Data deletion routine.
```
int x1f4_fine_??list(void *, void *, int (*)(void *, void *))
```
removes the first element from the $1 sequence if $3 called with $2 and the data of the to be removed element returns 0

returns 0 for success, X1f4_??LIST_CALL_ERROR if $3 returned not zero, one of the defined errors for failure
Sequence regular destructor routine.
```
int x1f4_fini_??list(void **)
```
destroys the sequence whose address is stored at $1 - dismantles it all and frees the sequence object

returns 0 for success, one of the defined errors for failure
Sequence destructor routine.
```
int x1f4_flat_??list(void *)
```
dismantles the $1 sequence without freeing the memory for the sequence object

returns 0 for success, one of the defined errors for failure
Order reversal routine.
```
int x1f4_flip_??list(void *)
```
reverses the order of the records stored with the $1 sequence (so that the first becomes the last, the last the first, etc)

returns 0
Data structure integrity check routine.
```
int x1f4_flow_??list(void *)
```
checks the $1 sequence for integrity - useful only for debugging this library

return 0 for success, non 0 for failure to complete the integrity tests
Plain data insertion routine
```
int x1f4_head_??list(void *, unsigned, void **)
```
inserts a new element before the previously first in $1 sequence, with $2 usable bytes, to be found at the address stored at $3 after function call

returns 0 for success, one of the defined errors for failure
Data purge routine.
```
int x1f4_high_??list(void *)
```
empties the $1 sequence (removes all nodes / content)

returns 0 for success, one of the defined errors for failure
Sequence regular constructor routine.
```
int x1f4_init_??list(void **, unsigned, struct x1f4_??list_type *)
```
creates an ??list object, according the $2 bits (see ??list attribute bit definitions) and $3 setup values and stores the address of the newly created sequence at $1

The setup values in the struct x1f4_??list_type record pointed to by the $3 argument are only used if so requested by $2, the $3 argument is not considered otherwise.

See Variable Size Data Sequence Types.

See Variable Size Data Sequence Definitions.

returns 0 for success, one of the defined errors for failure
Sort insertion routine.
```
int x1f4_land_??list
    (void *, void *, int (*)(void *, void *), unsigned, unsigned,
     void **)
```
insert a new element in the $1 sorted sequence, just after any element less or matching the $2 key according to the $3 comparison criterion, which when called is passed the $2 key and the start address of the data of the element being examined biased by $4 as arguments, in this order. Address of data for the new element, $5 usable bytes, will be stored at $6.

$3 is expected to return a negative number if the key is less than the sequence element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the sequence element.

returns 0 for success, one of the defined errors for failure
Record retriever / iterator routine.
```
int x1f4_last_??list(void **, void *)
```
stores the address of the data (i.e. payload) of the sequence node preceding the sequence node for which the address of data (i.e. payload) is $2 at $1

return 0 if such preceding sequence node does not exist, 1 if such preceding sequence node exists
Record retriever.
```
int x1f4_lead_??list(void *, void **)
```
stores the address of the data (i.e. payload) of the $1 sequence first element at $2

returns 0 for success, one of the defined errors for failure
Data traversal routine.
```
int x1f4_lime_??list(void *, void *, int (*)(void *, void *))
```
calls $3 for each element in the $1 sequence, with $2 and the data for the element as arguments, in this order, until $3 returns non zero

returns 0 if $3 was never called (i.e. sequence is empty) or if $3 never returned non zero, the non zero return of $3 otherwise
Data copy routine.
```
int x1f4_line_??list
    (void *, void *, int (*)(void *, unsigned *, const void *),
     int (*)(void *, void *, const void *), int (*)(void *, void *),
     void *)
```
copies the content of the $2 sequence in the $1 sequence if $1 is empty. $3 is used to determine the number of bytes to be allocated for a copied element and is passed $6 and the data of the element being copied as the first and third argument. The number of bytes is expected at the address passed as the second argument. Returned value is ignored. $4 is used to copy element data and is passed $6, the data for the copy element and the data for the element being copied as arguments, in this order. If returned value is not zero the sequence copying is aborted. $5 is called to free the copied elements if something went wrong (either no memory was available for sequence infrastructure or $4 returned non zero) and the copying had to be aborted. It is passed $6 and the data for the element to be freed as arguments, in this order.

$6 is otherwise not used.

if sequence copying failed efforts are made to return the $1 sequence to its previous (empty) state.

returns 0 for success, one of the defined errors for failure
Data deletion routine.
```
int x1f4_mind_??list(void *)
```
removes the first element from the $1 sequence

returns 0 for success, one of the defined errors for failure
Plain data deletion routine
```
int x1f4_miss_??list(void *, unsigned)
```
removes the $2th element from the $1 sequence

returns 0 for success, one of the defined errors for failure
Data replacement routine.
```
int x1f4_mode_??list(void *, unsigned, unsigned, void **)
```
replaces the $2th element in the $1 sequence with a new one with $3 usable bytes, to be found at the address stored at $4 after function call

returns 0 for success, one of the defined errors for failure
Data move routine.
```
int x1f4_move_??list(void *, unsigned, unsigned)
```
moves the $2th element in the $1 sequence in the $3th position

both $2 and $3 refer positions before any operation. Thus, moving the first element in the last position is:
```
    x1f4_move_??list(?, 0, size)
```
where size is the sequence size (element count).

returns 0 for success, one of the defined errors for failure
Record retriever / iterator routine.
```
int x1f4_next_??list(void **, void *)
```
stores the address of the data (i.e. payload) of the sequence node succeeding the sequence node for which the address of data (i.e. payload) is $2 at $1

return 0 if such succeeding sequence node does not exist, 1 if such succeeding sequence node exists
Data deletion routine.
```
int x1f4_nice_??list(void *, void *, int (*)(void *, void *))
```
removes the last element from the $1 sequence if $3 called with $2 and the data of the to be removed element returns 0

returns 0 for success, X1f4_??LIST_CALL_ERROR if $3 returned not zero, one of the defined errors for failure
Plain data retrieval routine
```
int x1f4_peek_??list(void *, unsigned, void **)
```
stores the address of the data (i.e. payload) of the $1 sequence $2th element at $3

returns 0 for success, one of the defined errors for failure
Sort insertion routine.
```
int x1f4_post_??list
    (void *, void *, int (*)(void *, void *), unsigned, unsigned,
     void **)
```
looks for some $1 sorted sequence item matching the $2 key according to the $3 comparison criterion, which when called is passed the $2 key and the start address of the data of the element being examined biased by $4 as arguments, in this order. Upon look up success, the start address of the found sequence element data is stored at $6. Upon look failure, inserts a new element, corresponding the $2 key, with $5 usable bytes, and stores the start address of the new element data at $6.

$3 is expected to return a negative number if the key is less than the sequence element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the sequence element.

returns 0 if a new element was inserted, X1f4_??LIST_EVER_MATCH if a match was found, one of the defined errors for failure
Data deletetion routine.
```
int x1f4_pull_??list(void *, unsigned, void *, int (*)(void *, void *))
```
removes the $2th element from the $1 sequence if $4 called with $3 and the data of the to be removed element returns 0

returns 0 for success, X1f4_??LIST_CALL_ERROR if $4 returned not zero, one of the defined errors for failure
Plain data insertion routine
```
int x1f4_push_??list(void *, unsigned, unsigned, void **)
```
inserts a new element in the $2th position in the $1 sequence, with $3 usable bytes, to be found at the address stored at $4 after function call

returns 0 for success, one of the defined errors for failure
Data shuffling routine
```
int x1f4_rand_??list(void *)
```
shuffles the $1 sequence content

returns 0
Data search routine.
```
int x1f4_rank_??list
    (void *, void *, unsigned, int (*)(void *, void *), unsigned *)
```
looks for some $1 sorted sequence item matching the $2 key according to the $4 comparison criterion, which when called is passed the $2 key and the start address of the data of the element being examined biased by $3 as arguments, in this order. Upon success, the index of the found sequence element data is stored at $5.

$4 is expected to return a negative number if the key is less than the sequence element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the sequence element.

returns 0 if no match was found, non zero otherwise
Data search routine.
```
int x1f4_seek_??list
    (void *, void *, unsigned, int (*)(void *, void *), unsigned *,
     void **)
```
looks for some $1 sorted sequence item matching the $2 key according to the $4 comparison criterion, which when called is passed the $2 key and the start address of the data of the element being examined biased by $3 as arguments, in this order. Upon success, the index of the found sequence element data is stored at $5 and the start address of the found sequence element data is stored at $6.

$4 is expected to return a negative number if the key is less than the sequence element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the sequence element.

returns 0 if no match was found, non zero otherwise
Data deletion routine.
```
int x1f4_side_??list(void *, void *)
```
removes the sequence node for which the address of data (i.e. payload) is $2 from the $1 sequence

returns 0 for success, one of the defined errors for failure
Size retriever.
```
int x1f4_size_??list(void *, unsigned *)
```
stores the size (element count) of the $1 sequence at address $2

returns 0
Memory allocator replacer routine.
```
int x1f4_skew_??list(void *, void *)
```
replace the memory allocator definition for the $1 sequence with the one described by the struct x1f4_trans_type record to be found at $2 address

See struct x1f4_trans_type.

returns 0
Data deletion routine.
```
int x1f4_slip_??list(void *)
```
removes the last element from the $1 sequence

returns 0 for success, one of the defined errors for failure
Data sort routine.
```
int x1f4_sort_??list
    (void *, void *, unsigned, int (*)(void *, void *, void *))
```
sorts the content of the $1 sequence according to the $4 sorting criterion, which when called is passed $2 and the start addresses of the data of the two elements being compared biased by $3 as arguments, in this order. $4 is expected to return a negative number if the first element (as indicated by its second argument) is less than the second element (as indicated by its third argument), 0 is the two elements match and a positive number if the first element is greater than the second.

the sorting is stable (i.e. the order of elements that match according the sort criterion is preserved).

returns 0
Data exchange routine.
```
int x1f4_spin_??list(void *, unsigned, unsigned)
```
swaps the $2th and the $3th elements of the $1 sequence

returns 0 for success, one of the defined errors for failure
Plain data insertion routine
```
int x1f4_tail_??list(void *, unsigned, void **)
```
inserts a new element after the previously last in $1 sequence, with $2 usable bytes, to be found at the address stored at $3 after function call

returns 0 for success, one of the defined errors for failure
Plain copy routine.
```
int x1f4_text_??list
    (void **, void *, int (*)(void *, unsigned *, const void *),
     int (*)(void *, void *, const void *), int (*)(void *, void *),
     void *)
```
creates a copy of the $2 sequence and stores the address of the newly created sequence at $1.

$3 is used to determine the number of bytes to be allocated for a copied element and is passed $6 and the data of the element being copied as the first and third argument. The number of bytes is expected at the address passed as the second argument. Returned value is ignored. $4 is used to copy element data and is passed $6, the data for the copy element and the data for the element being copied as arguments, in this order. If returned value is not zero the sequence copying is aborted. $5 is called to free the copied elements if something went wrong (either no memory was available for sequence infrastructure or $4 returned non zero) and the copying had to be aborted. It is passed $6 and the data for the element to be freed as arguments, in this order.

$6 is otherwise not used.

returns 0 for success, one of the defined errors for failure
Record index retrieval routine.
```
int x1f4_tile_??list(unsigned *, void *)
```
stores the index of the sequence node for which the data (i.e. payload) starts at $2 at $1

returns 0
Memory allocator replacer routine.
```
int x1f4_turn_??list(void *)
```
replace the memory allocator definition in the $1 sequence with the default one

returns 0
Data purge routine.
```
int x1f4_well_??list(void *, void *, int (*)(void *, void *))
```
empties the $1 sequence, calling $3 with $2 and the address of node data for each sequence node (element). $3 is expected to return 0 if successful, non 0 otherwise. In the later case the function ceases operations.

returns 0 for success, one of the defined errors for failure
Data move routine.
```
int x1f4_wind_??list(void *, unsigned, void *, unsigned)
```
moves the $2th element in the $1 sequence in the $4th position in the $3 sequence

returns 0 for success, one of the defined errors for failure