⎕CLONE Create copies of object

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

Syntax:

    objrefs ← objref.⎕CLONE N
    objrefs ← ⎕CLONE N     (Within user-defined method, same as ⎕THIS.⎕CLONE N)

The monadic system method ⎕CLONE creates new copies of an object, and returns a vector of references to the new objects. The right argument N is the number of copies required, as a positive integer (or 0). The new objects have their properties initially set to the same values as the original.

In this example, we create a simple class Point, and create an instance of it. The instance is then cloned four times. Note that the four copies are independent objects; changing a property of one of them does not affect the others:

      'Point' ⎕IC ⎕BOX 'X Y Z'
1 1 1
      PT←⎕NEW 'Point'
      PT.X←34 ⋄ PT.Y←23 ⋄ PT.Z←12
      VEC←PT.⎕CLONE 4
      VEC
[Point] [Point] [Point] [Point]
      VEC.X
34 34 34 34
      VEC[1].X←11
      VEC.X
11 34 34 34

Contrast this with the following example, in which VEC2 contains four references to the same object:

      VEC2←4⍴PT
      VEC2.X
34 34 34 34
      VEC2[1].X←11
      VEC2.X
11 11 11 11

When cloning internal objects, if the properties of the original object contain further object references these sub-objects are not cloned; instead, both the original and cloned objects will point to the same original sub-objects. This is known as a 'shallow' copy operation.

If an object contains file handles or database references, cloning it in this way may not make sense. On the other hand, for simple objects it can be a very useful way of rapidly creating new instances with an initial set of known properties.

⎕CLONE can be used with External classes (but not System classes). However, not all classes implement the operation, and the exact way in which it works may vary according to the architecture and the class:

.Net

In the .Net architecture, ⎕CLONE is mapped to the Clone method of the ICloneable interface. However, many .Net classes do not implement this.

Java

For Java classes, ⎕CLONE is mapped to the Clone method of the Java base object, which may be over-ridden for a particular Java class.

In this example, we create an instance of the Java Date class (which defaults to the current date/time), clone 12 copies of it, and set the month of each copy to a different value:

      date←'java' ⎕NEW 'java.util.Date'
      date
[java:Date]
      dateList←date.⎕CLONE 12
      dateList.setMonth ((⍳12)-⎕IO)
      12 1⍴dateList.⎕DS
 Wed Jan 10 14:33:12 GMT 2007
 Sat Feb 10 14:33:12 GMT 2007
 Sat Mar 10 14:33:12 GMT 2007
 Tue Apr 10 14:33:12 BST 2007
 Thu May 10 14:33:12 BST 2007
 Sun Jun 10 14:33:12 BST 2007
 Tue Jul 10 14:33:12 BST 2007
 Fri Aug 10 14:33:12 BST 2007
 Mon Sep 10 14:33:12 BST 2007
 Wed Oct 10 14:33:12 BST 2007
 Sat Nov 10 14:33:12 GMT 2007
 Mon Dec 10 14:33:12 GMT 2007

R

⎕CLONE is mapped to the duplicate function of R. It can thus be used to create multiple independent copies of R arrays, complex numbers, data frames, factors and so on.

      c←'r' ⎕new 'complex' 2 3
      c
[r:complex]
      c.⎕ds
2+3i
      t←c.⎕clone 5
      t.⎕ds
 2+3i 2+3i 2+3i 2+3i 2+3i
      t
[r:complex] [r:complex] [r:complex] [r:complex] [r:complex]

Ruby

⎕CLONE is mapped to the dup method of the Ruby base object. Again, this may be over-ridden for a particular Ruby class.

In this example, we create a Ruby array (referenced by A), and place three strings in it. We then make a clone of it (referenced by B), which creates an independent copy of the array. Therefore, when we add a fourth element to the array referenced by A, the copy is unchanged:

      A←'ruby' ⎕NEW 'Array'
      dummy←A.push 'First'
      dummy←A.push 'Second'
      dummy←A.push 'Third'
      A.length
3
      A.⎕VAL
 First Second Third
      B←A.⎕CLONE 1
      B.length
3
      B.⎕VAL
 First Second Third
      dummy←A.push 'Fourth'
      A.length
4
      A.⎕VAL
 First Second Third Fourth
      B.length
3
      B.⎕VAL
 First Second Third