Fixed Size Data Array Library (libx1f4l2)

3.2.1.4 Fixed Size Data Array Library

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

returns 0
Data structure state retriever.
```
int x1f4_case_??fset(void *)
```
returns 0 if the $1 associative array is empty, non zero otherwise
Plain data deletion routine.
```
int x1f4_cast_??fset(void *, void *)
```
looks for some $1 associative array item matching the $2 key. Upon look up success, deletes the found associative array element.

returns 0 for success (deletion success that is), X1f4_??FSET_MISS_CLASS for nonexistent matching node, one of the defined errors for failure
Data backward traversal routine.
```
int x1f4_draw_??fset(void *, void *, int (*)(void *, void *))
```
calls $3 for each element in the $1 associative array, from the last to the first, 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. associative array is empty) or if $3 never returned non zero, the non zero return of $3 otherwise
Record retriever.
```
int x1f4_ever_??fset(void *, void **)
```
stores the address of the data (i.e. payload) of the $1 associative array last element at $2

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

See Fixed Size Data Array Types.

See Fixed Size Data Array Definitions.

returns 0 for success, one of the defined errors for failure
Plain search routine.
```
int x1f4_find_??fset(void *, void *, void **)
```
looks for some $1 associative array item matching the $2 key. Upon success, the start address of the found associative array element data is stored at $3.

returns 0 if no match was found, non zero otherwise
Associative array regular destructor routine.
```
int x1f4_fini_??fset(void **)
```
destroys the associative array whose address is stored at $1 - dismantles it all and frees the associative array object

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

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

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

See Fixed Size Data Array Types.

See Fixed Size Data Array Definitions.

returns 0 for success, one of the defined errors for failure
Associative array consolidation routine.
```
int x1f4_join_??fset(void *, void *)
```
moves all content of the $2 associative array to the $1 associative array. The two collections are assumed of the same memory allocator. The first key of $2 assumed greater than then last key of $1.
Record retriever.
```
int x1f4_lead_??fset(void *, void **)
```
stores the address of the data (i.e. payload) of the $1 associative array first element at $2

returns 0 for success, one of the defined errors for failure
Data traversal routine.
```
int x1f4_lime_??fset(void *, void *, int (*)(void *, void *))
```
calls $3 for each element in the $1 associative array, 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. associative array is empty) or if $3 never returned non zero, the non zero return of $3 otherwise
Data copy routine.
```
int x1f4_line_??fset
    (void *, void *, int (*)(void *, void *, const void *),
     int (*)(void *, void *), void *)
```
copies the content of the $2 associative array in the $1 associative array 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 associative array copying is aborted. $4 is called to free the copied elements if something went wrong (either no memory was available for associative array 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 associative array copying failed efforts are made to return the $1 associative array to its previous state.

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

returns 0 for success, one of the defined errors for failure
Data methods replacement routine.
```
int x1f4_norm_??fset(void *, const struct x1f4_??norm_type *)
```
replaces the $1 associative array data specific methods with the ones collected by $2

returns 0
Plain data insertion routine.
```
int x1f4_post_??fset(void *, void *, void **)
```
looks for some $1 associative array item matching the $2 key. Upon look up success, the start address of the found associative array element data is stored at $3. Upon look up failure, inserts a new element, corresponding the $2 key and stores the start address of the new element data at $3.

or:

inserts a new item corresponding the $2 key if none present, retrieves the corresponding item otherwise.

arguments:
- - $1: void *
  the associative array
- - $2: void *
  the key
- - $3: void **
  the address where to store the address of the allocated item data if one is allocated
returns 0 if a new element was inserted, X1f4_??FSET_EVER_MATCH if a match was found, one of the defined errors for failure
Data deletion routine.
```
int x1f4_rest_??fset(void *, void *, unsigned)
```
removes the first elements from the $1 associative array up until an item matching the $2 key, if one exists, the first greater otherwise. The found matching item is deleted if $3 does not set the X1f4_??FSET_KEEP_FOUND bit.

returns 0 for success, one of the defined errors for failure
Data deletion routine.
```
int x1f4_sink_??fset(void *, void *, unsigned)
```
removes the last elements from the $1 associative array down until an item matching the $2 key, if one exists, the last less otherwise. The found matching item is deleted if $3 does not set the X1f4_??FSET_KEEP_FOUND bit.

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

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

returns 0 for success, one of the defined errors for failure
Associative array partition routine.
```
int x1f4_tear_??fset(void *, void *, int, void *)
```
moves all content starting with the first element matching or greater than the $2 key if $3 is zero and greater than $2 if $3 is not zero from the $1 associative array to the empty $4 associative array.

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

returns 0 for success