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
Tables
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
Contact: Richard Gooch
Web Development: Ariel Internet Services