nvp_util - Name/Value Pair Utilities

The NVP_UTIL package implements name/value pairs; i.e., binding a name to a value. A name/value pair is initially created without a value:

    #include  "nvp_util.h"			-- Name/value pairs.
    NVPair  pair ;
    ...
    nvpCreate ("pieceOfInfo", &pair) ;

An unbound pair can then be assigned values of different types:

    #include  "tv_util.h"			-- UNIX timeval utilities.
    ...
    nvpAssign (pair, 1, NvpByte, 0x12) ;
    nvpAssign (pair, 1, NvpDouble, 123.45) ;
    nvpAssign (pair, 1, NvpLong, 678) ;
    nvpAssign (pair, 1, NvpTime, tvTOD ()) ;

The pairs above have all been assigned scalar values. Arrays of values can also be assigned to pairs:

    #define  MAX  50
    double  anArray[MAX] ;
    ...
    nvpAssign (pair, MAX, NvpDouble, anArray, NvpVolatile) ;

Strings are null-terminated, so no length needs to be specified:

    nvpAssign (variable, -1, NvpString, "Hello", NvpStatic) ;

An application can specify the storage class of a string or array: static, dynamic, or volatile. In the volatile example above, the name/value pair variable is bound to a copy of the double array; changes made to the bound array are not reflected in the original array and the bound array is free(3)ed when the name/value pair is deleted. Dynamic values are assumed to have already been "copied" (e.g., a strdup(3)ed string) and, like volatile values, will be free(3)ed when the name/value pair is deleted. In contrast, a static value (e.g., the "Hello" string constant above, or a global variable) exists independently of the name/value pair to which it is bound; the name/value pair directly references the value and the value is not free(3)ed when the name/value pair is deleted.

A shorthand means of creating name/value pairs bound to scalars and volatile strings is provided by nvpNew():

    NVPair  tic, tac, toe ;
    ...
    tic = nvpNew ("tic", NvpLong, 123) ;
    tac = nvpNew ("tac", NvpDouble, 4.56) ;
    toe = nvpNew ("toe", NvpString, "automatically duplicated") ;

Various attributes of a pair's value can be retrieved:

    size_t  elementSize = nvpSizeOf (variable) ;
    size_t  numElements = nvpCount (variable) ;
    NvpDataType  type = nvpTypeOf (variable) ;

A pointer to a pair's value is returned by nvpValue(); the application is responsible for casting the pointer to the correct data type before dereferencing it:

    #include  <stdio.h>				-- Standard I/O definitions.
    ...
    printf ("%s = %ld\n", nvpName (tic), *((long *) nvpValue (tic))) ;
    printf ("%s = %g\n", nvpName (tac), *((double *) nvpValue (tac))) ;
    printf ("%s = %s\n", nvpName (toe), (char *) nvpValue (toe)) ;

As with strings, an array value of any type is always returned as a pointer to the base of the array:

    struct  timeval  *array ;
    static  struct  timeval  tv[16] ;
    ...
    nvpAssign (pair, 16, NvpTime, tv, NvpStatic) ;
    nvpValue (pair) ;				-- Returns &tv[0]

Finally, a name/value pair can be destroyed:

    nvpDestroy (pair) ;

Depending on the storage class of the pair's value, the value may be free(3)ed by nvpDestroy().

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

nvpAssign() - assigns a value to a name/value pair.

nvpCount() - returns the number of elements in a pair's value.

nvpCreate() - creates a name/value pair.

nvpDecode() - creates a name/value pair from an ASCII specification.

nvpDestroy() - destroys a name/value pair.

nvpEncode() - returns the ASCII specification of a name/value pair.

nvpName() - returns a variable's name.

nvpNew() - creates a name/value pair with a value.

nvpSizeOf() - returns the size of a scalar value or array element.

nvpTypeOf() - returns the data type of a variable's value.

nvpValue() - returns a variable's value.

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

Source Files

nvp_util.c

nvp_util.h

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