DEEP COPY

Copies a pool handle and all of its descendant allocations.

The pool handle may be a pointer to a DEFRECORD, a DEFSTRUCT, a DEFCLASS, or a KCML collection.

Like all pool handles, the copy remains valid until either the pool goes out of scope or the object is explicitly freed with DELETE PTR.

By default, the root allocation for the copy is made onto the memory pool for the current function. This can be overridden with a USING clause, similarly to NEW.

Copies of the descendant allocations will be isomorphic to the source, per this diagram:

Example

 00010 $COMPLIANCE 3
     : 'Main()
     : END
     : 
     : PUBLIC PROTOTYPE 'numeric_fn(n AS Numeric) AS Numeric
     : 
     : DEFSUB 'square(n AS Numeric) AS Numeric
     :     RETURN n * n
     : END SUB
     : 
 00020 DEF CLASS LinkedListItem
     :     FLD n
     :     FLD next AS LinkedListItem
     : END CLASS
     : 
 00030 DEF CLASS LinkedList
     :     FLD head AS LinkedListItem
     :     
     :     DEFMETHOD insert(n AS Numeric)
     :         // add a new element to the start of the list
     :         LOCAL DIM item AS LinkedListItem
     :         item = NEW LinkedListItem USING this
     :         item->n = n
     :         item->next = this->head
     :         this->head = item
     :     END METHOD
     :     
     :     DEFMETHOD map(f AS SYM('numeric_fn)) AS Void
     :         // apply a function to every item in the list
     :         LOCAL DIM item AS LinkedListItem
     :         FOR (item = this->head; item <> NULL; item = item->next)
     :             item->n = 'SYM(*f)(item->n)
     :             END FOR
     :     END METHOD
     :     
     :     DEFMETHOD print() AS Void
     :         LOCAL DIM item AS LinkedListItem
     :         PRINT "[";
     :         FOR (item = this->head; item <> NULL; item = item->next)
     :             PRINT item->n;
     :             END FOR
     :         PRINT "]"
     :     END METHOD
     :     
     : END CLASS
     : 
 00040 DEFSUB 'Main()
     :     LOCAL DIM x AS LinkedList
     :     LOCAL DIM y AS LinkedList
     :     LOCAL DIM i AS Integer
     :     
     :     // build and print the list [ 1 2 3 4 5 ]
     :     x = NEW LinkedList
     :     FOR i = 5 TO 1 STEP -1
     :         x->insert(i)
     :         END FOR
     :     x->Print()
     :     
     :     // get a squared copy and print it [ 1 4 9 16 25 ]
     :     y = DEEP COPY x
     :     y->map(SYM('square))
     :     y->Print()
     :     
     :     // print the original again - it will still be [ 1 2 3 4 5 ]
     :     x->Print()
     : END SUB

Compatibility

Introduced with KCML 7.09. Changed to match the new pool semantics in KCML 7.10.

See also:

NEW DELETE PTR POOL DEFCLASS Tutorial on memory pooling