S-Lang Run-Time Library Reference: Version 2.0.4: Functions that Manipulate Structures

Next Previous Contents

## 6. Functions that Manipulate Structures

## 6.1 __add_binary

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);

  > `

See Also

  `__add_unary, __add_string, __add_destroy`

## 6.2 __add_string

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]

  > `

See Also

  `__add_unary, __add_binary, __add_destroy`

## 6.3 __add_unary

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);

  > `

See Also

  `__add_binary, __add_string, __add_destroy`

## 6.4 get_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`.

Example

  The following example illustrates how this function may be used to to print the value of a structure.

  > `

  >           define print_struct (s)
  >           {
  >              variable name;

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

  > `

See Also

  `set_struct_field, get_struct_field_names, array_info`

## 6.5 get_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 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));
  >                }
  >           }

  > `

See Also

  `_push_struct_field_values, get_struct_field`

## 6.6 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. If the object is neither, 0 will be returned.

See Also

  `typeof, _typeof, _is_struct_type`

## 6.7 _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.

See Also

  `get_struct_field_names, get_struct_field`

## 6.8 set_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`.

See Also

  `get_struct_field, get_struct_field_names, set_struct_fields, array_info`

## 6.9 set_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);

  > `

See Also

  `set_struct_field, get_struct_field_names`

Next Previous Contents