xHarbour Reference Documentation > Function Reference

HClone()

Creates an entire copy of a hash.

Syntax

HClone( <hHash> ) --> hClone

Arguments

<hHash>

A variable referencing the hash to copy.

Return

The function returns a new Hash reference containing the same key/value pairs as <hHash>.

Description

This function creates a new Hash value and populates it with key/value pairs of the original hash. The new hash receives copies of the original values when they are of simple data types Character, Date, Logic, Numeric and NIL.

When data types are represented by references, the reference is copied, so that the new hash holds the same (identical) value as the original. This applies to data types Array, Code block, Hash and Object.

The attributes for case sensitivity and automatic element creation of <hHash> is transferred to the new hash as well.

Important:  <hHash> must not reference itself in any of its key/value pairs.

Info

See also:	Hash(), HCopy(), HGet(), HGetAutoAdd(), HDel(), HEval(), HSet(), HSetCaseMatch()
Category:	Hash functions , xHarbour extensions
Source:	vm\hash.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example demonstrates how the values of key/value pairs
// of a hash are copied to a new hash

   PROCEDURE Main
      LOCAL hHash := {=>}
      LOCAL hClone

      ? HGetCaseMatch( hHash )         // result: .T.

      HSetCaseMatch( hHash, .F. )

      // create a hash with all data types
      hHash:A := { 1, 2 }
      hHash:B := {|x| QOut(x) }
      hHash:C := "Hello World"
      hHash:D := Date()
      hHash:H := Hash( "OPT1", 10, "OPT2", 20 )
      hHash:L := .T.
      hHash:N := 12345
      hHash:O := GetNew()

      hClone  := HCLone( hHash )

      // clone is not identical with original
      ? hClone == hHash                // result: .F.
      ? HGetCaseMatch( hClone )        // result: .T.

      // clone holds same array reference
      ? ValToPrg( hClone:A )           // result: { 1, 2 }
      AAdd( hHash:A, 3 )
      ? ValToPrg( hClone:A )           // result: { 1, 2, 3 }

      // All values are identical
      ? "A", hClone:A == hHash:A       // result: .T.
      ? "B", hClone:B == hHash:B       // result: .T.
      ? "C", hClone:C == hHash:C       // result: .T.
      ? "D", hClone:D == hHash:D       // result: .T.
      ? "H", hClone:H == hHash:H       // result: .T.
      ? "L", hClone:L == hHash:L       // result: .T.
      ? "N", hClone:N == hHash:N       // result: .T.
      ? "O", hClone:O == hHash:O       // result: .T.
   RETURN