Getting Started

Documentation

Glish

Learn More

Programming

Contact Us

Version 1.9 Build 1556

News	FAQ
Search	Home

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 § 15.7, 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. Similar functions are provided for boolean, floating-point, and string interpretations.

• IntPtr returns a pointer to a C++ array of integers that are then 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 not rendered 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 results 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.