nvr_util - EPOCH Named Variable Utilities

The NVR_UTIL package provides a C language implementation of EPOCH's C++ nvar (named variable) class. A named variable is simply a data value to which an arbitrary name is bound. The xdr_nvar() function encodes/decodes named variables in the same XDR format as EPOCH, thus allowing a C program and a C++ program to exchange named variables through an XDR stream.

A named variable is initially created unbound to a value:

    #include  "nvr_util.h"			-- Named variables.
    NamedVariable  variable ;
    ...
    nvrCreate ("pieceOfInfo", &variable) ;

An unbound value can then be assigned values of different types.

    #include  "tv_util.h"			-- UNIX timeval utilities.
    ...
    nvrAssign (variable, NvrByte, 0x12) ;
    nvrAssign (variable, NvrCharacter, '!') ;
    nvrAssign (variable, NvrFloating, 123.45) ;
    nvrAssign (variable, NvrInteger, 678) ;
    nvrAssign (variable, NvrTime, tvTOD ()) ;
    nvrAssign (variable, NvrUnsigned, 678) ;

The named variables above are all scalar values. A named array can also be created:

    #define  MAX  50
    double  anArray[MAX] ;
    ...
    nvrAssign (variable, NvrFloatingArray, anArray, NvrVolatile, MAX) ;

Strings are a special class of character array: null-terminated, so no length needs to be specified:

    nvrAssign (variable, NvrString, "Hello", NvrStatic) ;

An application can specify the storage class of a string or array: static, dynamic, or volatile. In the volatile example above, the named 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 named variable 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 named variable is deleted. In contrast, a static value (e.g., the "Hello" string constant above, or a global variable) exists independently of the named variable to which it is bound; the named variable directly references the value and the value is not free(3)ed when the named variable is deleted.

A shorthand means of creating named variables bound to integers, reals, or volatile strings is provided by nvrNew():

    NamedVariable  tic, tac, toe ;
    ...
    tic = nvrNew ("tic", NvrInteger, 123) ;
    tac = nvrNew ("tac", NvrFloating, 4.56) ;
    toe = nvrNew ("toe", NvrString, "automatically duplicated") ;

Various attributes of a named variable's value can be retrieved:

    size_t  elementSize = nvrSizeOf (variable) ;
    size_t  numElements = nvrCount (variable) ;
    NvrDataType  type = nvrTypeOf (variable) ;

Last, but not least, in the attributes of a named variable is its value:

    char  *string ;
    double  rvalue ;
    long  ivalue ;
    ...
    nvrAssign (variable, NvrByte, 0x12) ;
    nvrValue (variable, NvrReal, &rvalue) ;	-- Returns 18.0
    nvrValue (variable, NvrInteger, &ivalue) ;	-- Returns 18
    string = nvrString (variable, 0) ;		-- Returns "18"

An array value of any type is always returned as pointer to the base of the array:

    struct  timeval  *array ;
    static  struct  timeval  tv[16] ;
    ...
    nvrAssign (variable, NvrTimeArray, tv, NvrStatic, 16) ;
    nvrValue (variable, NvrTimeArray, &array) ;	-- Returns &tv[0]

Finally, a named variable can be destroyed:

    nvrDestroy (variable) ;

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

Public Procedures

nvrAssign() - assigns a value to a named variable.

nvrCount() - returns the number of elements in a variable.

nvrCreate() - creates a named variable.

nvrDecode() - creates a named variable from an ASCII specification.

nvrDestroy() - destroys a named variable.

nvrEncode() - returns the ASCII specification of a named variable.

nvrName() - returns a variable's name.

nvrNew() - creates a named variable with a value.

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

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

nvrValue() - returns a variable's value.

xdr_nvar() - encodes/decodes a named variable in XDR format.

Source Files

nvr_util.c

nvr_util.h