| # Examples 8.15.1.1: REFERENCE |

The features of the required library class REFERENCE are used in individual examples. None of the examples given is a complete class nor necessarily a 'complete' method.

NOTE | The class REFERENCE is opaque. The reader is warned not to impose any model of references as some kind of pointer or table index or, indeed, any other 'kind' of object on the examples given in these notes. It is inevitable that the majority of use of such objects will be associated with operating system services of one kind or another, possibly even in an environment-dependent interface class. The mechanism used by a Sather implementation need not necessarily bear any relation to the way in which libraries for other programming languages are defined.

#### create_from_value

This routine takes some immutable value and converts it into a reference as, for example, in

ref : REFERENCE := REFERENCE::create_from_value(42)

The most important point to note about such a creation expression is that it is meaningless out of context. The programmer writing this must have contextual knowledge that such a conversion has meaning at run time. A more sensible use of this routine is illustrated in a rather longer fragment under the int example.

#### create_from_object

This feature is frequently useful when interfacing to external code and needing a reference to some object to use in an interface method call, thus where buffer is some kind of array one could write -

LOWLEVEL::export(REFERENCE::create_from_object(buffer))

to export some buffer for which the low level class provides an interface routine called export.

#### create_from_foreign

This feature is frequently useful when interfacing to external code when needing to manipulate external (foreign - ie in an external class) data structures. To obtain a reference to the foreign object it is merely necessary to write the expression -

REFERENCE::create_from_foreign(foreign_object)

Note that this routine is doing things which are completely outside the semantics of a Sather program. Whether this is meaningful or not is entirely in the user's control.

#### is_immutable

This predicate is provided in order to help the programmer not to make stupid mistakes. A prefatory test of sensibility could be written as something like

if REFERENCE::is_immutable(object) then
return REFERENCE::create_from_value(object)
else
return REFERENCE::create_from_object(object)
end

While this seems sensible at first sight, it is not necessarily meaningful in practice - dependent on context and environment.

### Conversion from references

The remaining four routines are provided to convert from some external reference to a Sather object or value where such a conversion is meaningful.

The creation of an object from a reference requires three things when called at run-time

1. The type of the object being created.
2. The size of the object being created.
3. A reference which is actually a reference to that type and size of object.

There are two possible sets of circumstances which make such a conversion possible.

#### make_object

This routine is for use when it is possible for the compiler to determine both type and size statically. The simplest call would then be something like

label : FILE_LABEL := ref.make_object

using the library class FILE_LABEL purely for purposes of illustration!

##### make_object

This routine is for use when it is possible for the compiler to determine only the type statically. Such circumstances would be most likely to arise when an external interface service has created some kind of array object, the size of which is only determinable at run time. Under these circumstances the following code fragment could be used in some Unix-like environment for example.

number : CARD ;
arg_ref : REFERENCE := OS::get_args(out number) ;
args : ARRAY{STR} := arg_ref.make_object(number)

in which the class OS is entirely fictitious!

### From references to values

One of the commonest occurrences when interfacing to an underlying environment is the way in which a returned 'value' has two possible domains - at the same time! Some single or even small set of values indicates a number, others a reference. Different operating systems provide both signed and unsigned numbers or references - for different services.

#### card

This feature caters for the unsigned number case, thus -

res : REFERENCE := OS::some_operation ;
if res.card = CARD::zero then -- operation was unsuccessful
return void
else
return res
end

#### int

This feature caters for the signed number case, thus -

res : INT := OS::some_operation ;
if res < INT::zero then
-- operation was unsuccessful
return void
else
return REFERENCE::create_from_value(res)
end

| Specification Index |  | Language Index |  | Section 8 Index

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