| # Section 8.15.1.1: REFERENCE |

###### class REFERENCE < $REFERENCE

#### Formal Types

types
SAME = REFERENCE ;
REFERENCE = token

Instances of this class are references to external objects. An implementation may provide this facility in the most convenient way since it is opaque to the using program.

#### create_from_value

This feature is provided for use in those cases where it is known by the program writer that some external reference is a numeric value, in order to maintain the integrity of the class type safeness of the language.

create_from_value | (
| val : $IMMUTABLE
| ) : SAME

##### Formal Signature

create_from_value(val : $IMMUTABLE) res : SAME

##### Pre-condition

pre is_immutable(val)

This routine converts the value object provided as argument into a reference which is meaningful to the execution environment. The exact form of this is implementation-dependent.

NOTE | The pre-condition is established so that the implementation can indicate that some particular object type or value cannot be converted into a reference.

#### create_from_object

This feature provides a mechanism to convert an object into a reference to it suitable for use in external environment service calls.

create_from_object | (
| obj : $OB
| ) : SAME

##### Formal Signature

create_from_object(obj : $OB) res : SAME

##### Pre-condition

pre not is_immutable(obj)

This routine converts the reference object provided as argument into a reference to it which is meaningful to the execution environment. The exact form of this is implementation-dependent.

NOTE | The pre-condition is established so that the implementation can indicate that some particular object type cannot be converted into a reference.

#### create_from_foreign

This feature creates a reference from a 'foreign' object - ie one defined using the external class mechanism with a named 'foreign' form (ie not being the external class kind 'OS'.

create_from_foreign | (
| obj : $OB
| ) : SAME

##### Formal Signature

create_from_object(obj : $OB) res : SAME

This routine treats the object provided as argument as a reference which is meaningful to the execution environment. The exact form of this is implementation-dependent.

#### is_immutable

This feature is provided as an implementation-dependent predicate to indicate if the object which is its argument is immutable in the sense understood by the underlying execution environment.

is_immutable | (
| obj : $OB
| ) : BOOL

##### Formal Signature

is_immutable(obj : $OB) res : BOOL

##### Post-condition

Note that the auxiliary routine type_of is defined in section 6.9. The set immutables will normally be the set of all concrete classes which sub-type either directly or indirectly from the abstract class $IMMUTABLE.

post res = type_of(obj) in set immutables

This predicate returns true if and only if obj is an immutable object suitable for converting into a reference.

#### make_object

This feature is one of two which perform implementation-dependent object creation from an external reference.

make_object | : $OB

##### Formal Signature

make_object1(self : SAME) res : [$OB]

##### Post-condition

post res = nil
or create_from_object(res) = self

This routine returns a Sather object for which self is a handle and for which the implementation can determine the type from the context in which it is called. If self is not valid then void is returned.

#### make_object

This second make_object feature is provided for making an object the type of which, though not the size, is known when translating the class; the size being known only at run-time.

make_object | (
| size : CARD
| ) : $OB

##### Formal Signature

make_object2(self : SAME, size : CARD) res : $OB

##### Pre-condition

presize > 0

##### Post-condition

post res = nil
or create_from_object(res) = self

This routine returns a Sather object for which self is a handle and for which the implementation can determine the type (but not the size - which is only known at run-time and is the argument to this routine) from the context in which it is called. If self is not valid then void is returned.

#### card

This feature converts the reference into a cardinal number. Whther or not this is semantically meaningful must be decided by the programmer - as the language definition cannot do so.

card | : CARD

##### Formal Signature

card(self : SAME) res : CARD

##### Post-condition

post create_from_value(res) = self

This routine returns the cardinal number expressed by the reference bit_pattern.

#### int

This feature provides the facility to convert the reference into an integer value where this is meaningful within the program. This cannot be specified in the language.

int | : INT

##### Formal Signature

int(self : SAME) res : INT

##### Post-condition

post create_from_value(res) = self

This routine returns the possibly signed integer number expressed by the reference bit_pattern for use where low-level objects may either be a number or a reference.

| Language Index |  | Library Index |  | Sather RT Index

Comments or enquiries should be made to Keith Hopper. Page last modified: Sunday, 21 May 2000. |