Fixed Size Data Sequence Library (libx1f4l2)

2.2.1.4 Fixed Size Data Sequence Library

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

returns 0
Data structure state retriever.
```
int x1f4_case_??rate(void *)
```
returns 0 if the $1 sequence is void (empty), non zero otherwise
Data deletion routine.
```
int x1f4_dash_??rate(void *, unsigned, unsigned)
```
removes the $2th to $3th elements from the $1 sequence

returns 0 for success, one of the defined errors for failure
Record retriever.
```
int x1f4_ever_??rate(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_??rate(void *, unsigned, struct x1f4_??rate_type *)
```
sets up a newly allocated ??rate object, stored at $1, according the $2 bits (see ??rate attribute bit definitions) and $3 setup values

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

See Fixed Size Data Sequence Types.

See Fixed Size Data Sequence Definitions.

returns 0 for success, one of the defined errors for failure
Sequence regular destructor routine.
```
int x1f4_fini_??rate(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_??rate(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_??rate(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_??rate(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_??rate(void *, void **)
```
inserts a new element before the previously first in $1 sequence, to be found at the address stored at $2 after function call

returns 0 for success, one of the defined errors for failure
Data purge routine.
```
int x1f4_high_??rate(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_??rate(void **, unsigned, struct x1f4_??rate_type *)
```
creates an ??rate object, according the $2 bits (see ??rate attribute bit definitions) and $3 setup values and stores the address of the newly created sequence at $1

See Fixed Size Data Sequence Types.

See Fixed Size Data Sequence Definitions.

returns 0 for success, one of the defined errors for failure
Sequence consolidation routine.
```
int x1f4_join_??rate(void *, void *)
```
moves all content from the $2 sequence to the end of the $1 sequence. Order of the moved elements is preserved. The two sequences ought to be of the same settings.

returns 0 for success, one of the defined errors for failure
Record retriever.
```
int x1f4_lead_??rate(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_??rate(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_??rate
    (void *, 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 copy element data and is passed $5, 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 queue copying is aborted. $4 is called to free the copied elements if something went wrong (either no memory was available for sequence infrastructure or $3 returned non zero) and the copying had to be aborted. It is passed $5 and the data for the element to be freed as arguments, in this order.

$5 is otherwise not used.

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

returns 0 for success, one of the defined errors for failure
Data deletion routine.
```
int x1f4_mind_??rate(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_??rate(void *, unsigned)
```
removes the $2th element from the $1 sequence

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

returns 0 if $5 was never called (i.e. sequence is empty) or if $5 never returned non zero, the non zero return of $5 otherwise
Plain data retrieval routine
```
int x1f4_peek_??rate(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
Data deletetion routine.
```
int x1f4_pull_??rate(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_??RATE_CALL_ERROR if $4 returned not zero, one of the defined errors for failure
Plain data insertion routine
```
int x1f4_push_??rate(void *, unsigned, void **)
```
inserts a new element in the $2th position in the $1 sequence, to be found at the address stored at $3 after function call

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

returns 0
Size retriever.
```
int x1f4_size_??rate(void *, unsigned *)
```
stores the size (element count) of the $1 sequence at address $2

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

returns 0 for success, one of the defined errors for failure
Sequence resizing routine.
```
int x1f4_star_??rate(void *, unsigned)
```
resizes the empty $1 sequence to be $2 long

returns 0 for success, one of the defined errors for failure
Data swap routine.
```
int x1f4_swap_??rate(void *, void *)
```
swaps data and settings for the $1 and $2 sequences

returns 0 for success
Plain data insertion routine
```
int x1f4_tail_??rate(void *, void **)
```
inserts a new element after the previously last in $1 sequence, to be found at the address stored at $2 after function call

returns 0 for success, one of the defined errors for failure
Sequence partition routine.
```
int x1f4_tear_??rate(void *, unsigned, void *)
```
moves all content starting with the $2th element from the $1 sequence to the empty $3 sequence. Order of the moved elements is preserved. The two sequences ought to be of the same settings.

returns 0 for success, one of the defined errors for failure
Plain copy routine.
```
int x1f4_text_??rate
    (void **, 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 copy element data and is passed $5, 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 queue copying is aborted. $4 is called to free the copied elements if something went wrong (either no memory was available for sequence infrastructure or $3 returned non zero) and the copying had to be aborted. It is passed $5 and the data for the element to be freed as arguments, in this order.

$5 is otherwise not used.

returns 0 for success, one of the defined errors for failure
Data insertion routine
```
int x1f4_vamp_??rate(void *, unsigned, int *, unsigned *, void **)
```
inserts as many elements as *$4 in the $2th position in the $1 sequence, store their number and address at $4 and $5. The function will insert at least one element and no more than the b-tree node capacity.

It will store 1 at $3 when it deems that a subsequent multiple insertion at the same position ($2) would fare better than at another position, for an instance $2 + number of inserted elements (final *$4). $3 is not changed otherwise. The hint is meant to be offerred only once during a long insertion that sees multiple calls to x1f4_vamp_??rate. The function expects that $2 changes from call to call during such a long insertion by adding the number of elements inserted in the previous call.

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