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_createCreate a general purpose associative array of key-value pairs.
    j_destroyDestroy an associative array.
    j_get_infoGet information attached to associative array.
    j_put_pairAdd a key-value pair to an associative array.
    j_get_pairFind a key-value pair in an associative array.
    j_destroy_pairRemove a key-value pair from an associative array.
    j_get_all_pairsGet all the key-value pairs on an associative array.
    j_get_pair_infoGet key and value information for a key-value pair.

    Prototype Functions

    j_PROTO_key_compare_funcThis routine will compare two keys.
    j_PROTO_key_copy_funcThis routine will copy a key.
    j_PROTO_key_destroy_funcThis routine will destroy keys.
    j_PROTO_value_copy_funcThis routine will copy a value.
    j_PROTO_value_destroy_funcThis routine will destroy values.

    Tables

    j_REPLACEMENT_POLICIESList 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:

    Returns: An associative array on success, else NULL.
    Multithreading Level: Unsafe


    void j_destroy (KJoinedPairList list)

    Destroy an associative array.

    Parameters:

    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:

    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:

    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:

    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:

    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:

    Returns: An array of key-value pairs on success, else NULL. If num_pairs is non-zero, an error occurred.
    Multithreading Level: Unsafe
    Note:


    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:

    Returns: Nothing.
    Multithreading Level: Unsafe


    Prototype Functions


    int j_PROTO_key_compare_func (void *key1, void *key2)

    This routine will compare two keys.

    Parameters:

    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:

    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:

    Returns: Nothing.
    Multithreading Level: Unsafe


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

    This routine will copy a value.

    Parameters:

    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:

    Returns: Nothing.
    Multithreading Level: Unsafe
    Note:


    Tables


    j_REPLACEMENT_POLICIES

    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