⎕VAL Force value result

Implemented for External classes only.

Syntax:

    data ← objref.⎕VAL

The niladic system method ⎕VAL attempts to force data within an external object to be 'unboxed', so that the value of the data, rather than an object reference, is returned to APLX.

When used on an object which would normally be returned to APL as data, it does nothing; it simply returns the data as normal. Similarly, when used on an object which cannot be converted to simple APL data types, it also does nothing; the object reference is returned.

Where ⎕VAL becomes useful is for cases where you have created an object (using typically ⎕NEW or ⎕REF) in the external environment, and where the object can be represented as ordinary APL data. The two most common cases are strings and arrays, but it can also be used with numeric types (which can be converted to integers or floating-point values).

In this example, we create an array of three strings in .Net:

      StringType←'.net' ⎕GETCLASS 'System.String'    ⍝ Get Type of System.String    
      ArrayType←'.net' ⎕GETCLASS 'System.Array'      ⍝ Get Type of System.Array
                                                     ⍝ so we can call static 
                                                     ⍝ method 'CreateInstance'
      ArrayType.CreateInstance StringType 3          ⍝ Create array of 3 strings
[NULL OBJECT] [NULL OBJECT] [NULL OBJECT]            ⍝ Oops! Array was unboxed            

      A←ArrayType.CreateInstance.⎕REF StringType 3   ⍝ Keep array as object
      A
[.net:String[]]                                      ⍝ Reference to .Net array
      A.SetValue 'First Item' 0                      ⍝ Insert some values
      A.SetValue 'Second Item' 1
      A.SetValue 'Third Item' 2
      
      A                                              ⍝ Still a reference
[.net:String[]]
      A.⎕VAL                                         ⍝ Unbox array to get contents
 First Item Second Item Third Item
      ⎕DISPLAY A.⎕VAL
┌→────────────────────────────────────────┐
│ ┌→─────────┐ ┌→──────────┐ ┌→─────────┐ │
│ │First Item│ │Second Item│ │Third Item│ │
│ └──────────┘ └───────────┘ └──────────┘ │
└∊────────────────────────────────────────┘

This example in R creates a 'factor' and uses ⎕VAL to extract from it the underlying vector of indices:

      r←'r' ⎕new 'r'      
      f←r.factor (⊂'abc' 'def' 'abc')
      f
[r:factor]
      f.⎕val
1 2 1

See also ⎕REF which does the opposite: it attempts to force data, which would otherwise be 'unboxed', to be returned as an object reference.