Home

GEONius.com
29-Feb-2016
E-mail

NVar - Named Variable

The NVar class provides a "lite" implementation of EPOCH's nvar (named variable) class. A named variable is simply a data value to which an arbitrary name is bound. NVar objects are not interchangeable with nvar objects within a program. However, NVar objects are tranferred over network connections in the same XDR format as nvar objects, so a program using the NVar class can talk to a program using the nvar class.

A named variable can be created with or without a name and with or without a value:

    #include  "NVar.h"				// Named variables.
    ...
    NVar  anonymous ;				// No name, no value.
    NVar  anonymous (123456) ;			// No name, integer value.
    NVar  somebody ("ISHMAEL") ;		// Name, but no value.
    NVar  somebody (123456, "ISHMAEL") ;	// Name, integer value.

(The V3 communications library implements vars and nvars; a var is basically a nameless NVar.) Named variables can have scalar values of different types:

    #include  "TimeValue.h"			// Time value class.
    ...
    NVar  variable ((unsigned char) 0x12, "aByte") ;
    NVar  variable ('$', "aCharacter") ;
    NVar  variable (123.456, "aFloating") ;
    NVar  variable (123456, "anInteger") ;
    NVar  variable (TimeValue::TimeOfDay (), "aTime") ;
    NVar  variable ((unsigned long) 123456, "anUnsigned") ;

To create an array of values, you must specify the array, the storage class of the array, and the number of elements in the array:

    #define  MAX  50
    double  lotsOfNumbers[MAX_REALS] ;
    NVar  variable (lotsOfNumbers, NVar::Volatile, MAX, "anArray") ;

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

    NVar  variable ("Hello!", NVar::Static, "aString") ;

An application must 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 delete[]ed when the named variable is deleted. Dynamic values are assumed to have already been "copied" (e.g., a new/strcpy(3)ed string) and, like volatile values, will be deleted[]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 delete[]ed when the named variable is deleted.

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

    char  *name = variable.Name () ;
    int  numElements = variable.Count () ;
    int  elementSize = variable.SizeOf () ;
    NVar::DataType  dataType = variable.TypeOf () ;

Last, but not least, in the attributes of a named variable is its value. This is retrieved by simply casting the variable to the appropriate type; the following examples assume, in each case, that the variable has been assigned a value of the given type:

    char  *string = variable ;			// Get value as string.
    double  real = variable ;			// Get value as floating-point.

Casting a scalar variable of one type to a scalar value of a different type is allowed and the NVar class attempts to convert the value as best it can. For example, casting a time value as a long returns a truncated time in seconds (no microseconds); casting the time value as a double returns the time in seconds, with the fractional portion of the result equal to microseconds / 1000000.0.

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

    long  *integerArray = variable ;		// Get value as integer array.
    struct  timeval  *array = variable ;	// Get value as time array.

Cross-casting of arrays is strongly discouraged.


Public Class Methods

Decode() - creates a variable from its ASCII specification.
xdr_nvar() - decodes/encodes a named variable in XDR format.
xdr_var() - decodes/encodes an unnamed variable in XDR format.

Public Methods

NVar() - creates a value-less variable.
NVar() - creates a variable for a byte value.
NVar() - creates a variable for a byte array.
NVar() - creates a variable for a character value.
NVar() - creates a variable for a string value.
NVar() - creates a variable for a floating-point value.
NVar() - creates a variable for a floating-point array.
NVar() - creates a variable for an integer value (from an int).
NVar() - creates a variable for an integer value (from a long).
NVar() - creates a variable for an integer array.
NVar() - creates a variable for a time value.
NVar() - creates a variable for a time array.
NVar() - creates a variable for an unsigned value.
NVar() - creates a variable for an unsigned array.
NVar() - copy constructor.
~NVar() - destroys a variable.
=() - assignment operator.
Count() - gets the number of elements in a variable's value.
Encode() - returns the ASCII specification for a variable.
Erase() - erases the contents of a variable.
Name() - gets a variable's name.
Name() - sets a variable's name.
SizeOf() - gets the size of an individual element.
String() - returns a variable's value formatted in a string.
TypeOf() - gets the data type of a variable's value.
unsigned char() - gets a variable's value as a byte.
unsigned char *() - gets a variable's value as a byte array.
char() - gets a variable's value as a character.
char *() - gets a variable's value as a string.
double() - gets a variable's value as a floating-point number.
double *() - gets a variable's value as a floating-point array.
int() - gets a variable's value as an integer.
long() - gets a variable's value as an integer.
long *() - gets a variable's value as an integer array.
struct timeval() - gets a variable's value as a time.
struct timeval *() - gets a variable's value as a time array.
unsigned long() - gets a variable's value as an unsigned integer.
unsigned long *() - gets a variable's value as an unsigned array.

Private Methods

Copy() - copies the contents of one variable to another.

Source Files

NVar.cpp
NVar.h