## ŚREF Force reference result

Implemented for Internal and External classes. Not implemented for System classes.

Syntax:

objref „ objref.ŚREF
objref „ objref.method.ŚREF
objref „ classref.ŚREF
objref „ classref.method.ŚREF
objref „ ŚREF (Within user-defined method, same as ŚTHIS.ŚREF)

ŚREF is a special modifier method which can be used to force another method to return an object reference rather than 'unbox' the data before it is returned to APL. It can be used with either niladic or monadic external system methods, or on external objects directly.

When used on an object which would normally be returned to APL as an object reference, the niladic system method ŚREF does nothing; it simply returns the reference to the object (or class definition) unchanged, as a scalar.

Where ŚREF becomes useful is for cases where the data would normally be converted from an object in an external architecture, to a native APL data type. The two most common cases are strings and arrays. For example, if a method in an external class returns a string object, it is normally converted to an APL character vector and this data is returned to APL:

          DT„'.net' ŚNEW 'System.DateTime' 2005 12 3 13 45 21
          DT.ToLongDateString
    03 December 2005
          ˝DT.ToLongDateString
    16
          ŚDR DT.ToLongDateString
    4

Whilst this default behavior is usually desirable, there are occasionally cases where it is better to leave the string as an external object, and return a reference to it instead. ŚREF forces this to happen:

          ExtString„DT.ToLongDateString.ŚREF
          ExtString
    [.net:String]
          ExtString.Length
    16

In the above example, `ExtString` is a scalar reference to a `String` object which exists in the .Net environment.

There are several reasons why you might want to use ŚREF:

- If the data is about to be passed to another external method, and you are not interested in the contents of the intermediate variable, it is more efficient to pass just a reference back to APL, rather than copying the data contents twice.
- Some values or precision may be lost in converting the data from the external subsystem to APL. For example, the external data may comprise 64-bit integers; if you are running a 32-bit version of APLX, these will by default be converted to floating-point form, and may therefore lose precision.
- You may want to keep it as object so that you can run methods, defined for the external object class, directly on it.

See also ŚVAL which does the opposite: it attempts to 'unbox' data which would otherwise be returned as an object reference.

Topic: APLX Help : Help on APL language : System Methods : ŚREF Force reference result

[ Previous | Next | Contents | Index ]