Next Previous Contents

## 7.Functions that Manipulate Structures

Synopsis

Extend a binary operation to a user defined type

Usage

`__add_binary(op, return_type, binary_funct, lhs_type, rhs_type)`

``` String_Type op; Ref_Type binary_funct; DataType_Type return_type, lhs_type, rhs_type; ```

Description

The `__add_binary` function is used to specify a function to be called when a binary operation takes place between specified data types. The first parameter indicates the binary operator and must be one of the following:

``` "+", "-", "*", "/", "==", "!=", ">", ">=", "<", "<=", "^", "or", "and", "&", "|", "xor", "shl", "shr", "mod" ```
The second parameter (`binary_funct`) specifies the function to be called when the binary function takes place between the types `lhs_type` and `rhs_type`. The `return_type` parameter stipulates the return values of the function and the data type of the result of the binary operation.

The data type for `lhs_type` or `rhs_type` may be left unspecified by using `Any_Type` for either of these values. However, at least one of the parameters must correspond to a user-defined datatype.

Example

This example defines a vector data type and extends the "*" operator to the new type:

``` typedef struct { x, y, z } Vector_Type; define vector (x, y, z) { variable v = @Vector_Type; v.x = x; v.y = y; v.z = z; return v; } static define vector_scalar_mul (v, a) { return vector (a*v.x, a*v.y, a*v.z); } static define scalar_vector_mul (a, v) { return vector_scalar_mul (v, a); } static define dotprod (v1,v2) { return v1.x*v2.x + v1.y*v2.y + v1.z*v2.z; } __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type); __add_binary ("*", Vector_Type, &scalar_vector_mul, Any_Type, Vector_Type); __add_binary ("*", Double_Type, &dotprod, Vector_Type, Vector_Type); ```

Synopsis

Specify a string representation for a user-defined type

Usage

`__add_string (DataType_Type user_type, Ref_Type func)`

Description

The `__add_string` function specifies a function to be called when a string representation is required for the specified user-defined datatype.

Example

Consider the `Vector_Type` object defined in the example for the `__add_binary` function.

``` static define vector_string (v) { return sprintf ("[%S,%S,%S]", v.x, v.y, v.z); } __add_string (Vector_Type, &vector_string); ```
Then
``` v = vector (3, 4, 5); vmessage ("v=%S", v); ```
will generate the message:
``` v=[3,4,5] ```

Synopsis

Add a typecast-function for a user-defined type

Usage

`__add_typecast (DataType_Type user_type, DataType_Type totype, Ref_Type func)`

Description

The `__add_typecast` function specifies a function to be called to typecast the user-defined type to an object of type `totype`. The function must be defined to take a single argument (the user-type to be converted) and must return an object of type `totype`.

Synopsis

Extend a unary operator to a user-defined type

Usage

`__add_unary (op, return_type, unary_func, user_type)`

``` String_Type op; Ref_Type unary_func; DataType_Type return_type, user_type; ```

Description

The `__add_unary` function is used to define the action of an unary operation on a user-defined type. The first parameter `op` must be a valid unary operator

``` "-", "not", "~" ```
or one of the following:
``` "++", "--", "abs", "sign", "sqr", "mul2", "_ispos", "_isneg", "_isnonneg", ```
The third parameter, `unary_func` specifies the function to be called to carry out the specified unary operation on the data type `user_type`. The result of the operation is indicated by the value of the `return_type` parameter and must also be the return type of the unary function.

Example

The example for the `__add_binary` function defined a `Vector_Type` object. Here, the unary `"-"` and `"abs"` operators are extended to this type:

``` static define vector_chs (v) { variable v1 = @Vector_Type; v1.x = -v.x; v1.y = -v.y; v1.z = -v.z; return v1; } static define vector_abs (v) { return sqrt (v.x*v.x + v.y*v.y + v.z*v.z); } __add_unary ("-", Vector_Type, &vector_chs, Vector_Type); __add_unary ("abs", Double_Type, &vector_abs, Vector_Type); ```

## 7.5get_struct_field

Synopsis

Get the value associated with a structure field

Usage

`x = get_struct_field (Struct_Type s, String field_name)`

Description

The `get_struct_field` function gets the value of the field whose name is specified by `field_name` of the structure `s`. If the specified name is not a field of the structure, the function will throw an `InvalidParmError` exception.

## 7.6get_struct_field_names

Synopsis

Retrieve the field names associated with a structure

Usage

`String_Type[] = get_struct_field_names (Struct_Type s)`

Description

The `get_struct_field_names` function returns an array of strings whose elements specify the names of the fields of the struct `s`.

Example

The following example illustrates how the `get_struct_field_names` function may be used in conjunction with the `get_struct_field` function to print the value of a structure.

``` define print_struct (s) { variable name, value; foreach (get_struct_field_names (s)) { name = (); value = get_struct_field (s, name); vmessage ("s.%s = %s\n", name, string (value)); } } ```

## 7.7_is_struct_type

Synopsis

Determine whether or not an object is a structure

Usage

`Integer_Type _is_struct_type (X)`

Description

The `_is_struct_type` function returns 1 if the parameter refers to a structure or a user-defined type, or to an array of structures or user-defined types. If the object is neither, 0 will be returned.

## 7.8is_struct_type

Synopsis

Determine whether or not an object is a structure

Usage

`Integer_Type is_struct_type (X)`

Description

The `is_struct_type` function returns 1 if the parameter refers to a structure or a user-defined type. If the object is neither, 0 will be returned.

## 7.9_push_struct_field_values

Synopsis

Push the values of a structure's fields onto the stack

Usage

`Integer_Type num = _push_struct_field_values (Struct_Type s)`

Description

The `_push_struct_field_values` function pushes the values of all the fields of a structure onto the stack, returning the number of items pushed. The fields are pushed such that the last field of the structure is pushed first.

## 7.10set_struct_field

Synopsis

Set the value associated with a structure field

Usage

`set_struct_field (s, field_name, field_value)`

``` Struct_Type s; String_Type field_name; Generic_Type field_value; ```

Description

The `set_struct_field` function sets the value of the field whose name is specified by `field_name` of the structure `s` to `field_value`.

## 7.11set_struct_fields

Synopsis

Set the fields of a structure

Usage

`set_struct_fields (Struct_Type s, ...)`

Description

The `set_struct_fields` function may be used to set zero or more fields of a structure. The fields are set in the order in which they were created when the structure was defined.

Example

``` variable s = struct { name, age, height }; set_struct_fields (s, "Bill", 13, 64); ```