⎕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.