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
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
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
free(3)ed when the named variable is deleted. Dynamic values
are assumed to have already been "copied" (e.g., a
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
A shorthand means of creating named variables bound to integers, reals,
or volatile strings is provided by
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 ; ... nvrAssign (variable, NvrTimeArray, tv, NvrStatic, 16) ; nvrValue (variable, NvrTimeArray, &array) ; -- Returns &tv
Finally, a named variable can be destroyed:
nvrDestroy (variable) ;
Depending on the storage class of the variable's value, the value may
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.