---

3.1.1.4 Variable Size Data Array Library

• Data structure node size retriever.

  int x1f4_base_??line(unsigned *)
  

  sets $1 to the number of bytes required by an ??line node (the associative array node and the allocated data corresponding the node are allocated as a single object, data starting immediately after the node record. The address provided by the memory allocator will be used as the node record address, same address added as many byte as stored by the function at $1 as the application data address)

  returns 0

• Data structure size retriever.

  int x1f4_call_??line(unsigned *)
  

  sets $1 to the number of bytes required by an ??line object (sort of sizeof(??line))

  returns 0

• Data structure state retriever.

  int x1f4_case_??line(void *)
  

  returns 0 if the $1 associative array is empty, non zero otherwise

• Plain data deletion routine.

  int x1f4_cast_??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.

  same as x1f4_pass_??line except for the return

  returns 0 for success (deletion success that is), X1f4_??LINE_MISS_CLASS for nonexistent matching node, one of the defined errors for failure

• Record retriever.

  int x1f4_ever_??line(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_??line(void *, unsigned, struct x1f4_??line_type *)
  

  sets up a newly allocated ??line object, stored at $1, according the $2 bits (see ??line attribute bit definitions) and $3 setup values

  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

• Plain search routine.

  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

• Associative array regular destructor routine.

  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

• Associative array destructor routine.

  int x1f4_flat_??line(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_??line(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_??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

• Plain data insertion routine.

  int x1f4_land_??line
      (void *, void *, int (*)(void *, void *), unsigned, unsigned,
       void **)
  

  insert a new element in the $1 associative array, 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 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.

  same as x1f4_post_??line, only allowing for duplicates

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

• Record retriever / iterator routine.

  int x1f4_last_??line(void **, void *)
  

  stores the address of the data (i.e. payload) of the associative array node preceding the associative array node for which the address of data (i.e. payload) is $2 at $1

  return 0 if such preceding associative array node does not exist, 1 if such preceding associative array node exists

• Record retriever.

  int x1f4_lead_??line(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_??line(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

• Plain data deletion routine.

  int x1f4_near_??line
      (void *, void *, int (*)(void *, void *), unsigned, void *,
       int (*)(void *, 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, deletes the found associative array element if $6 called with $5 and the start address data of the to be removed element returns 0.

  $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.

  same as x1f4_shut_??line except for the return

  returns 0 for success (deletion success or nonexistent matching node), one of the defined errors for failure

• Record retriever / iterator routine.

  int x1f4_next_??line(void **, void *)
  

  stores the address of the data (i.e. payload) of the associative array node succeeding the associative array node for which the address of data (i.e. payload) is $2 at $1

  return 0 if such succeeding associative array node does not exist, 1 if such succeeding associative array node exists

• Plain data deletion routine.

  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.

  same as x1f4_cast_??line except for the return

  returns 0 for success (deletion success or nonexistent matching node), one of the defined errors for failure

• Plain data insertion routine.

  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:

  • - $1: void *

    the associative array

  • - $2: void *

    the key

  • - $3: int (*)(void *, void *)

    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.

  • - $4: unsigned

    some offset (expressed in bytes) to add the start address of the associative array elements data when passing to $3

  • - $5: unsigned

    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)

  • - $6: void **

    the address where to store the address of the allocated item data if one is allocated

  same as x1f4_land_??line, only not allowing for duplicates

  returns 0 if a new element was inserted, X1f4_??LINE_EVER_MATCH if a match was found, one of the defined errors for failure

• Supporting tree visiting routine.

  int x1f4_scan_??line(void *, void *, int (*)(void *, void *, unsigned))
  

  calls $3 for each element is the $1 associative array, with $2, the data 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 (like a binary search tree). It makes 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

• Plain data deletion routine.

  int x1f4_shut_??line
      (void *, void *, int (*)(void *, void *), unsigned, void *,
       int (*)(void *, 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, deletes the found associative array element if $6 called with $5 and the start address data of the to be removed element returns 0.

  $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.

  same as x1f4_near_??line except for the return

  returns 0 for success (deletion success that is), X1f4_??LINE_MISS_CLASS for nonexistent matching node, one of the defined errors for failure (X1f4_??LINE_CALL_ERROR is returned if $6 returned non zero)

• Data deletion routine.

  int x1f4_side_??line(void *, void *)
  

  removes the associative array node for which the address of data (i.e. payload) is $2 from the $1 associative array

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

• Memory allocator replacer routine.

  int x1f4_skew_??line(void *, void *)
  

  replaces the memory allocator definition for the $1 associative array with the one described by the struct x1f4_trans_type record to be found at $2 address

  See struct x1f4_trans_type.

  returns 0