int x1f4_init_??line(void **, unsigned, struct x1f4_??line_type *)
creates a ??line object, according the $2 bits (see ??line
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_??line_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 Array Types.
See Variable Size Data Array Definitions.
returns 0 for success, one of the defined errors for failure
int x1f4_post_??line
(void *, void *, int (*)(void *, void *), unsigned, unsigned,
void **)
looks for some $1 associative array 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 associative array element data is stored at $6. Upon look up 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 associative array element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the associative array element.
or:
inserts a new item corresponding the $2 key if none present, retrieves the corresponding item otherwise.
arguments:
the associative array
the key
the comparison method, receives the $2 key and the start address of the data of the element being examined biased by $4 as arguments, in this order, returns a negative number if the key is less than the associative array element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the associative array element.
some offset (expressed in bytes) to add the start address of the associative array elements data when passing to $3
the minimum size (expressed in bytes) of the item to allocate if one is to be allocated (if no item corresponding the $2 is already present, that is)
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_??LINE_EVER_MATCH if a
match was found, one of the defined errors for failure
int x1f4_find_??line
(void *, void *, unsigned, int (*)(void *, void *), void **)
looks for some $1 associative array 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 associative array element data is stored at $5.
$4 is expected to return a negative number if the key is less than the associative array element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the associative array element.
returns 0 if no match was found, non zero otherwise
int x1f4_pass_??line
(void *, void *, int (*)(void *, void *), unsigned)
looks for some $1 associative array 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, deletes the found associative array element.
$3 is expected to return a negative number if the key is less than the associative array element (as indicated by its second argument), 0 if the element is fine and a positive number if the key is greater than the associative array element.
returns 0 for success (deletion success or nonexistent matching node), one of the defined errors for failure
int x1f4_fini_??line(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