nvl_util - Name/Value List Utilities

The NVL_UTIL package manages lists of name/value pairs. A name/value list is essentially an associative array of name/value pairs.

An empty list of name/value pairs is created as follows:

    #include  <stdio.h>				-- Standard I/O definitions.
    #include  "nvl_util.h"			-- Name/value pair lists.
    NVList  list ;
    ...
    nvlCreate (NULL, &list) ;

Name/value pairs are then added to the list using nvlAdd():

    nvlAdd (list, nvpNew ("THIS", NvpDouble, 123.45)) ;
    nvlAdd (list, nvpNew ("THAT", NvpLong, 6789)) ;

The pairs in a list can be retrieved by index:

    int  i ;
    NVPair  pair ;
    ...
    for (i = 0 ;  i < nvlCount (list) ;  i++) {
        pair = nvlGet (list, i) ;
        printf ("%s = %s\n", nvpName (pair), nvpString (pair)) ;
    }

or by name:

    pair = nvlFind (list, "THAT") ;		-- Prints "THAT = 6789".
    printf ("%s = %s\n", nvpName (pair), nvpString (pair)) ;

Individual pairs can be deleted from a list:

    pair = nvlDelete (list, "THIS") ;

Although the pair is removed from the list, the pair itself is not destroyed. In contrast, deleting the entire list in one fell swoop:

    nvlDestroy (list) ;

automatically destroys the remaining pairs via calls to nvpDestroy().

For my own convenience, I added the "Prop" functions, which implement LISP-like property lists using name/value lists and string-valued name/value pairs:

        NVList  myCar ;
        ...
        nvlCreate (NULL, &myCar) ;
        nvlPutProp (myCar, "MAKE", "Triumph") ;
        nvlPutProp (myCar, "MODEL", "TR-4") ;
        nvlPutProp (myCar, "COLOR", "green") ;
        printf ("I wish I had a %s %s %s.\n",
                nvlGetProp (myCar, "COLOR"),
                nvlGetProp (myCar, "MAKE"),
                nvlGetProp (myCar, "MODEL")) ;

Using the "Prop" functions does not preclude using the regular NVL functions on the same list.

History:

The name/value pair, name/value list, and version-independent message stream packages were inspired by Mike Maloney's C++ implementations of named variables and named variable sets, and by Robert Martin's attributed data trees (see "Version-Independent Messages" in Appendix B of his Designing Object-Oriented C++ Applications Using the Booch Method).

Public Procedures

nvlAdd() - adds a name/value pair to a list.

nvlCount() - returns the number of name/value pairs in a list.

nvlCreate() - creates an empty name/value pair list.

nvlDelete() - deletes a name/value pair from a list.

nvlDestroy() - destroys a list.

nvlFind() - retrieves a pair by name from a list.

nvlGet() - retrieves a pair by index from a list.

nvlName() - returns a list's name.

xdr_NVList() - encodes/decodes a name/value pair list in XDR format.

nvlGetProp() - retrieves a property from a list.

nvlPutProp() - adds a property to a list.

nvlRemProp() - removes a property from a list.

Source Files

nvl_util.c

nvl_util.h

(See libnet for the complete source, including support routines and build files.)