Next: String Key Pointer Value Array Search Library, Previous: String Key Pointer Value Array Definitions, Up: String Key Pointer Value Array Interface [Index]
int x1f4_bind_??deck(void *, const char *, const void ***)
looks for some $1 associative array node matching the $2 name. Upon look up success, stores the start address of the data (i.e. payload) of the found array element at $3. Upon look up failure, inserts a new element, corresponding the $2 name, and stores the start address of the new element data at $3.
The element data is const void * typed, hence the address at which is
stored is conventionally typed code void **.
returns 0 if a new element was inserted, X1f4_??DECK_EVER_MATCH if a
match was found, one of the defined errors for failure
int x1f4_bind_??path(void *, const char *, unsigned, const void ***)
looks for some $1 associative array node matching the $3 bytes long $2 name. Upon look up success, stores the start address of the data (i.e. payload) of the found array element at $4. Upon look up failure, inserts a new element, corresponding the $3 bytes long $2 name, and stores the start address of the new element data at $4.
The element data is const void * typed, hence the address at which is
stored is conventionally typed code void **.
returns 0 if a new element was inserted, X1f4_??DECK_EVER_MATCH if a
match was found, one of the defined errors for failure
int x1f4_case_??deck(void *)
returns 0 if the $1 associative array is empty, non zero otherwise
int x1f4_cast_??deck(void *, const char *)
looks for some $1 associative array node matching the $2 name. Upon look up success, deletes the found associative array element.
same as x1f4_pass_??deck except for return
returns 0 for success (deletion success that is), X1f4_??DECK_MISS_CLASS
for nonexistent matching node, one of the defined errors for failure
int x1f4_cast_??path(void *, const char *, unsigned)
looks for some $1 associative array node matching the $3 bytes long $2 name. Upon look up success, deletes the found associative array element.
same as x1f4_pass_??path except for return
returns 0 for success (deletion success that is), X1f4_??DECK_MISS_CLASS
for nonexistent matching node, one of the defined errors for failure
int x1f4_copy_??deck(void **, void *)
copies the $2 associative array and stores the address of the newly created associative array at $1.
returns 0 for success, one of the defined errors for failure
int x1f4_ever_??deck(void *, const void **)
stores the pointer stored by the $1 associative array last element at $2
returns 0 for success, one of the defined errors for failure
int x1f4_fast_??deck(void *, unsigned, struct x1f4_??deck_type *)
sets up a newly allocated ??deck object, stored at $1, according the $2
bits (see ??deck attribute bit definitions) and $3 setup values
The setup values in the struct x1f4_??deck_type record pointed to by
the $3 argument are only used if so requested by $2, the $3 argument is not
considered otherwise.
See String Key Pointer Value Array Types.
See String Key Pointer Value Array Definitions.
returns 0 for success, one of the defined errors for failure
int x1f4_fill_??deck(void *, void *)
copies the content of the $2 associative array in the $1 associative array if $1 is empty.
returns 0 for success, one of the defined errors for failure
int x1f4_find_??deck(void *, const char *, const void **)
looks for some $1 associative array node matching the $2 name. Upon success, the pointer stored by the found element is stored at $3.
returns 0 if no match was found, non zero otherwise
int x1f4_find_??path(void *, const char *, unsigned, const void **)
looks for some $1 associative array node matching the $3 bytes long $2 name. Upon success, the pointer stored by the found element is stored at $4.
returns 0 if no match was found, non zero otherwise
int x1f4_fini_??deck(void **)
destroys the associative array whose address is stored at $1 - dismantles it all and frees the object
returns 0 for success, one of the defined errors for failure
int x1f4_flat_??deck(void *)
dismantles the $1 associative array without freeing the memory for the object
returns 0 for success, one of the defined errors for failure
int x1f4_flow_??deck(void *)
checks the $1 associative array for integrity - useful only for debugging this library
return 0 for success, non 0 for failure to complete the integrity tests
int x1f4_high_??deck(void *)
empties the $1 associative array (removes all nodes / content)
returns 0 for success, one of the defined errors for failure
int x1f4_hook_??deck
(void *, void *, int (*)(void *, const void *, const char *, unsigned),
char *)
calls $3 for each element in the $1 associative array, with $2, the data (the stored pointer, that is) for the element, the name corresponding the element and its size expressed in bytes as arguments, in this order, until $3 returns non zero. The name will be a null terminated string. The name is constructed in the space pointed to by $4, hence at least as many bytes as needed to store the longest null terminated name need be storable at $4.
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
int x1f4_init_??deck(void **, unsigned, struct x1f4_??deck_type *)
creates a ??deck object, according the $2 bits (see ??deck
attribute bit definitions) and $3 setup values and stores the address of the
newly created associative array at $1
The setup values in the struct x1f4_??deck_type record pointed to by
the $3 argument are only used if so requested by $2, the $3 argument is not
considered otherwise.
See String Key Pointer Value Array Types.
See String Key Pointer Value Array Definitions.
returns 0 for success, one of the defined errors for failure
int x1f4_jack_??deck(void *, void *)
stores the $1 associative array memory allocator struct x1f4_trans_type
definition at $2
returns 0
int x1f4_join_??deck(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.
int x1f4_lead_??deck(void *, const void **)
stores the pointer stored by the $1 associative array first element at $2
returns 0 for success, one of the defined errors for failure
int x1f4_lift_??deck(void *, const void **, char **, unsigned *, unsigned *)
stores the pointer stored by the $1 associative array first element at $2, its corresponding string key at some address to be found at $3 and the string key length at $4.
The function expects some storage space available at the pointer readable at $3
and its capacity recorded at $5. The minimum expect storage capacity is 1
byte. If the space available at the pointer readable at $3 is large enough to
store the string key, the x1f4_lift_??deck function uses it for the
string key storage. If not, it reallocates the storage space large enough for
the string key storage, stores the string key in the reallocated space and
records the new storage space address and size back at $3 and $5.
The memory at the address stored at $3 may be modified even for function failures.
returns 0 for success, one of the defined errors for failure
int x1f4_lime_??deck(void *, void *, int (*)(void *, void *))
calls $3 for each element in the $1 associative array, with $2 and the data (the stored pointer, that is) 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
int x1f4_line_??deck
(void *, void *, int (*)(void *, const void **, const void *),
int (*)(void *, const void *), void *)
copies the content of the $2 associative array in the $1 string key pointer value associative array if $1 is empty. $3 is used to copy element data and is passed $5, the address at which the data for the new copy element is to be stored 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 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.
Data for the associative arrays is pointer data and a trivial $3 copy method would store the data to be copied (its third parameter) at the address where copy data is expected (its second parameter). Its respective trivial $4 free routine would do nothing.
returns 0 for success, one of the defined errors for failure
int x1f4_list_??deck
(void *, void *, int (*)(void *, const char *, unsigned), char *)
calls $3 for each element in the $1 associative array, with $2, the name corresponding the element and its size expressed in bytes as arguments, in this order, until $3 returns non zero. The name will be a null terminated string. The name is constructed in the space pointed to by $4, hence at least as many bytes as needed to store the longest null terminated name need be storable at $4.
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
int x1f4_mind_??deck(void *)
removes the first element from the $1 associative array
returns 0 for success, one of the defined errors for failure
int x1f4_note_??deck
(void *, void *, int (*)(void *, const char *, unsigned))
calls $3 for each element in the $1 associative array, with $2, the name corresponding the element and its size expressed in bytes as arguments, in this order, until $3 returns non zero. The name will be a null terminated string.
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
int x1f4_pass_??deck(void *, const char *)
looks for some $1 associative array node matching the $2 name. Upon look up success, deletes the found associative array element.
same as x1f4_cast_??deck except for return
returns 0 for success (deletion success or nonexistent matching node), one of the defined errors for failure
int x1f4_pass_??path(void *, const char *, unsigned)
looks for some $1 associative array node matching the $3 bytes long $2 name. Upon look up success, deletes the found associative array element.
returns 0 for success (deletion success or nonexistent matching node), one of the defined errors for failure
int x1f4_pick_??deck(void *, const char *, const void ***)
looks for some $1 associative array node matching the $2 name. Upon success, the address of the found node payload (that is, the address at which the pointer stored by the found element is stored) is stored at $3.
returns 0 if no match was found, non zero otherwise
int x1f4_pick_??path(void *, const char *, unsigned, const void ***)
looks for some $1 associative array node matching the $3 bytes long $2 name. Upon success, the address of the found node payload (that is, the address at which the pointer stored by the found element is stored) is stored at $4.
returns 0 if no match was found, non zero otherwise
int x1f4_plot_??deck(void *, const void **, char **, unsigned *, unsigned *)
stores the pointer stored by the $1 associative array last element at $2, its corresponding string key at some address to be found at $3 and the string key length at $4.
The function expects some storage space available at the pointer readable at $3
and its capacity recorded at $5. The minimum expect storage capacity is 1
byte. If the space available at the pointer readable at $3 is large enough to
store the string key, the x1f4_plot_??deck function uses it for the
string key storage. If not, it reallocates the storage space large enough for
the string key storage, stores the string key in the reallocated space and
records the new storage space address and size back at $3 and $5.
The memory at the address stored at $3 may be modified even for function failures.
returns 0 for success, one of the defined errors for failure
int x1f4_post_??deck(void *, const char *, const void *)
looks for some $1 associative array node matching the $2 name. Upon look up failure, inserts a new element, corresponding the $2 name and storing the $3 pointer.
returns 0 if a new element was inserted, X1f4_??DECK_EVER_MATCH if a
match was found, one of the defined errors for failure
int x1f4_post_??path(void *, const char *, unsigned, const void *)
looks for some $1 associative array node matching the $3 bytes long $2 name. Upon look up failure, inserts a new element, corresponding the $3 bytes long $2 name and storing the $4 pointer.
returns 0 if a new element was inserted, X1f4_??DECK_EVER_MATCH if a
match was found, one of the defined errors for failure
int x1f4_rush_??deck(void *, unsigned, void *, int (*)(void *, ...))
calls $4 for each (internal) tree node in the $1 associative array, with $3 and zero or more of
unsigned depth
the depth of root is 0, of its children 1, and so forth
unsigned fanout
unsigned size
the used size of the node in bytes (i.e. the size that was requested of the memory allocator)
until $4 returns non zero.
$2 specializes the statistics collection.
the interface suggests that the associative arrays is supported by a tree structure. The function has little use beyond profiling the tree.
returns 0 if $4 was never called (i.e. associative array is empty) or if $4 never returned non zero, the non zero return of $4 otherwise
int x1f4_scan_??deck(void *, void *, int (*)(void *, const void *, unsigned))
calls $3 for each element in the $1 associative array, with $2, the data (the stored pointer, that is) and the depth for the element as arguments, until $3 returns non zero (the depth of root is 0, of its children 1, and so forth)
the interface suggests that the associative arrays is supported by a tree structure. The function has little use beyond profiling the tree.
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
int x1f4_slip_??deck(void *)
removes the last element from the $1 associative array
returns 0 for success, one of the defined errors for failure
int x1f4_span_??deck
(void *, void *, int (*)(void *, const void *, const char *, unsigned))
calls $3 for each element in the $1 associative array, with $2, the data (the stored pointer, that is) for the element, the name corresponding the element and its size expressed in bytes as arguments, in this order, until $3 returns non zero. The name will be a null terminated string.
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
int x1f4_tear_??path(void *, const char *, unsigned, int, void *)
moves all content starting with the first element matching or greater than $3 bytes long $2 if $4 is zero and with the first element greater than $2 if $4 is not zero from the $1 associative array to the empty $5 associative array.
returns 0 for success, one of the defined errors for failure
int x1f4_text_??deck
(void **, void *, int (*)(void *, const void **, const void *),
int (*)(void *, const void *), void *)
creates a copy of the $2 associative array and stores the address of the newly created associative array at $1.
$3 is used to copy element data and is passed $5, the address at which the data for the new copy element is to be stored 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 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.
Data for the associative arrays is pointer data and a trivial $3 copy method would store the data to be copied (its third parameter) at the address where copy data is expected (its second parameter). Its respective trivial $4 free routine would do nothing.
The x1f4_copy_??deck interface describes trivial associative array copy routines, having the same effect as the ones described by x1f4_text_??deck when used with trivial copy/free methods.
returns 0 for success, one of the defined errors for failure