An Overview of the Value Class

 

    Value objects can be constructed from C++ scalars or arrays.   For example,

    Value* v = new Value( 5 );

assigns to v a Value object representing the integer 5, while

    double* x = new double[3];
    x[0] = 1.0;
    x[1] = 3.14;
    x[2] = 4.56;
    Value* v = new Value( x, 3 );

assigns to v the equivalent of the Glish value [1, 3.14, 4.56]. By default, Value objects constructed from arrays ``take over" the array: they will realloc() the array if it grows larger and delete it when the Value object is destroyed. The class library also provides mechanisms for specifying that an array should not be altered or should first be copied (see § 13.6, page , below).  

The Value class provides a number of member functions for manipulating values:

• Type     returns the type of an object.
• Length     returns the length of an object.
• IntVal     interprets one element of the value as a single integer, performing type conversions as necessary, and similar functions are provided for boolean, floating-point, and string interpretations.
• IntPtr     returns a pointer to a C++ array of integers that can then be used for direct access to the value's underlying elements. A related member function,     CoerceToIntArray, returns either the underlying array if already of type integer or else a copy of the array converted to integer. Again, these functions have counterparts for the other basic Glish types.
• AttributePtr         and ModAttributePtr provide access to the value's attributes the first returns a constant version of the attributes and the second retuns a modifiable version. AssignAttribute     allows attributes to be set.
• Polymorph     converts the value from its present type to a new type.
• Analogs to these functions are available for directly accessing and setting a record's fields.
• The     (non-member) function create_record() returns a new, empty record.
• The     (non-member) function copy_value( Value* v ) returns a complete copy of the Value object v. reference values are de-referenced. All of the attributes are copied along with the Value itself. However, the underlying data is itself reference counted, and a physical copy is not done until some operation forces it, i.e. copy on write.

A key point concerning the Value class is that it makes it easy to wrap   Glish values around an existing program's data structures. These data structures can then be made available to other programs by sending them as event values.

Note           also that both the Value and Client classes use reference-counting for memory management. The Ref() and Unref() functions manipulate each object's reference count. When the count reaches zero the object is deleted and any objects it refers to are Unref()'d. You must always delete Value and Client objects   using Unref(); never using delete.

Unref()'ing a record   until its reference count is zero will result in the record being destroyed and each of its fields being Unref()'d. Individual record fields should not be otherwise Unref()'d unless you Ref()'d them earlier.