# The "j" Package

These routines are meant to provide general purpose associative array support (also know as lists of joined pairs). This can save a lot of code when you maintain lists of pairs of items (e.g. pairs of names and objects)

Library: karma
Link With: -lkarma
Note:

- THIS PACKAGE IS WORK IN PROGRESS. THE INTERFACE MAY CHANGE IN THE NEXT RELEASE, POSSIBLY WITHOUT NOTICE.

  #### Functions

  j_create | Create a general purpose associative array of key-value pairs.
  j_destroy | Destroy an associative array.
  j_get_info | Get information attached to associative array.
  j_put_pair | Add a key-value pair to an associative array.
  j_get_pair | Find a key-value pair in an associative array.
  j_destroy_pair | Remove a key-value pair from an associative array.
  j_get_all_pairs | Get all the key-value pairs on an associative array.
  j_get_pair_info | Get key and value information for a key-value pair.

  #### Prototype Functions

  j_PROTO_key_compare_func | This routine will compare two keys.
  j_PROTO_key_copy_func | This routine will copy a key.
  j_PROTO_key_destroy_func | This routine will destroy keys.
  j_PROTO_value_copy_func | This routine will copy a value.
  j_PROTO_value_destroy_func | This routine will destroy values.

  #### Tables

  j_REPLACEMENT_POLICIES | List of replacement policies when adding keys

  ## Functions

  KJoinedPairList j_create (void *info, int (*key_compare_func) (CONST void *key1, CONST void *key2), void *(*key_copy_func) (CONST void *key, uaddr length, flag *ok), void (*key_destroy_func) (void *key))

  Create a general purpose associative array of key-value pairs.

  Parameters:

  - info : Arbitrary information to be stored with the associative array.
  - key_compare_func : The function used to compare two keys. The prototype function is j_PROTO_key_compare_func. If this is NULL, pointer values are compared.
  - key_copy_func : The function used to copy keys. The prototype function is j_PROTO_key_copy_func.
  - key_destroy_func : The function used to destroy keys. The prototype function is j_PROTO_key_destroy_func.
  Returns: An associative array on success, else NULL.
  Multithreading Level: Unsafe

  void j_destroy (KJoinedPairList list)

  Destroy an associative array.

  Parameters:

  - list : The associative array.
  Returns: Nothing.
  Multithreading Level: Unsafe

  void * j_get_info (KJoinedPairList list)

  This routine will get the arbitrary information pointer stored with an associative array.

  Parameters:

  - list : The associative array.
  Returns: The arbitrary information pointer.
  Multithreading Level: Unsafe

  KJoinedPair j_put_pair (KJoinedPairList list, CONST void *key, uaddr key_length, CONST void *value, uaddr value_length, void *(*value_copy_func) (CONST void *value, uaddr length, flag *ok), void (*value_destroy_func) (void *value), unsigned int replacement_policy, flag front)

  Add a key-value pair to an associative array.

  Parameters:

  - list : The associative array.
  - key : The key.
  - key_length : The length of the key, in bytes. If this is 0 and the key_copy_func is NULL, the key pointer is copied directly. If this is greater than zero and the key_copy_func is NULL, the specified number of bytes are copied.
  - value : The value.
  - value_length : The length of the value, in bytes. If this is 0 and the value_copy_func is NULL, the value pointer is copied directly. If this is greater than zero and the value_copy_func is NULL, the specified number of bytes are copied.
  - value_copy_func : The function used to copy values. The prototype function is j_PROTO_value_copy_func.
  - value_destroy_func : The function used to destroy values. The prototype function is j_PROTO_value_destroy_func.
  - replacement_policy : The policy to use when adding the pair. See j_REPLACEMENT_POLICIES for a list of legal values.
  - front : If TRUE and the key is new, place the pair at the front of the array. If FALSE and the key is new, place the pair at the end of the array.
  Returns: A KJoinedPair object on success, else NULL.
  Multithreading Level: Unsafe

  KJoinedPair j_get_pair (KJoinedPairList list, CONST void *key, void **value)

  Find a key-value pair in an associative array.

  Parameters:

  - list : The associative array.
  - key : The key.
  - value : The value found will be written here on success.
  Returns: A KJoinedPair object if the key was found, else NULL.
  Multithreading Level: Unsafe

  void j_destroy_pair (KJoinedPair pair)

  This routine will remove a key-value pair from an associative array and will destroy all storage allocated for the pair.

  Parameters:

  - pair : The key-value pair.
  Returns: Nothing.
  Multithreading Level: Unsafe

  KJoinedPair * j_get_all_pairs (KJoinedPairList list, unsigned int *num_pairs)

  Get all the key-value pairs on an associative array.

  Parameters:

  - list : The associative array.
  - num_pairs : The number of pairs found is written here. If no pairs are found NULL is written here.
  Returns: An array of key-value pairs on success, else NULL. If num_pairs is non-zero, an error occurred.
  Multithreading Level: Unsafe
  Note:
  - The return value must be freed with the free function, not the m_free function.

  void j_get_pair_info (KJoinedPair pair, void **key, uaddr *key_length, void **value, uaddr *value_length)

  This routine will get the key and value information for a key-value pair in an associative array.

  Parameters:

  - pair : The key-value pair.
  - key : The key will be written here.
  - key_length : The length of the key will be written here.
  - value : The value will be written here.
  - value_length : The length of the value will be written here.
  Returns: Nothing.
  Multithreading Level: Unsafe

  ## Prototype Functions

  int j_PROTO_key_compare_func (void *key1, void *key2)

  This routine will compare two keys.

  Parameters:

  - key1 : The first key.
  - key2 : The second key.
  Returns: 0 if the keys match, a negative number if key1 is less than key2, a positive number if key1 is greater than key2.
  Multithreading Level: Unsafe

  void * j_PROTO_key_copy_func (void *key, uaddr length, flag *ok)

  This routine will copy a key.

  Parameters:

  - key : The key to copy.
  - length : The length of the key in bytes.
  - ok : The value TRUE will be written here on success, else FALSE is written here.
  Returns: A copy of the key on success.
  Multithreading Level: Unsafe

  void j_PROTO_key_destroy_func (void *key)

  This routine will destroy keys.

  Parameters:

  - key : The key to destroy.
  Returns: Nothing.
  Multithreading Level: Unsafe

  void * j_PROTO_value_copy_func (void *value, uaddr length, flag *ok)

  This routine will copy a value.

  Parameters:

  - value : The value to copy.
  - length : The length of the value in bytes.
  - ok : The value TRUE will be written here on success, else FALSE is written here.
  Returns: A copy of the value on success.
  Multithreading Level: Unsafe

  void j_PROTO_value_destroy_func (void *value)

  This routine will destroy values.

  Parameters:

  - value : The value to destroy.
  Returns: Nothing.
  Multithreading Level: Unsafe
  Note:
  - If the value_length is greater than 0 and the value_copy_func was not supplied, then the value pointer is internally freed.

  ## Tables

  j_REPLACEMENT_POLICIES List of replacement policies when adding keys

  Policy Name | Meaning
  KJ_REPLACEMENT_POLICY_NEW | Fail if existing key found
  KJ_REPLACEMENT_POLICY_UPDATE | Fail if no existing key found
  KJ_REPLACEMENT_POLICY_PUT | Add pair, remove old key if exists

  Back to Karma Home Page