xHarbour Reference Documentation > Function Reference

HCopy()

Copies key/value pairs from a hash into another hash.

Syntax

HCopy( <hSource>, ;
       <hTarget>, ;
      [<nStart>], ;
      [<nCount>], ;
      [<xMode>]   ) --> hTarget

Arguments

<hSource>

A variable referencing the hash to copy.

<hTarget>

A variable referencing the hash that receives key/value pairs from <hSource>.

<nStart>

A numeric value indicating the first key/value pair of <hSource> to copy to <hTarget>. It defaults to 1.

<nCount>

A numeric value specifying the number of key/value pairs to copy, starting from position <nStart>. If <nCount> is omitted, all elements of <hSource> starting at <nStart> are copied.

<xMode>

<xMode> is either a numeric value or a code block. It specifies how to treat duplicate keys in both hashes. See description below. The default value is 0.

Return

The function returns a reference to <hTarget>.

Description

The function copies key/value pairs from a source to a target hash. By default, all key/value pairs are copied. The first key/value pair and the number of them can optionally be specified with <nStart> and <nCount>.

Since keys in a hash must be unique, the <xMode> parameter defines how to treat keys that are present in both hashes. The following numeric values are valid for <xMode>.

Copy modes for HCopy()

Mode	Value	Description
Normal copy *)	0	When a key of <hSource> is present in <hTarget>, the value of <hSource> is copied to <hTarget>. Otherwise, the key/value pair of <hSource> is added to <hTarget>.
XOR copy	1	When a key of <hSource> is present in <hTarget>, the key/value pair is removed from <hTarge>, otherwise it is added to <hTarget>.
AND copy	2	First, all keys in <hTarget> are removed when they are not present in <hSource>. Then, only values of matching keys in <hSource> are copied to <hTarget>. Other elements of <hSource> are not copied.
NOT copy	3	All keys in <hTarget> are removed when they are present in <hSource>. No other key/value pair is added or changed.
*) default mode

As an alternative, a code block can be specified for <xMode> which allows to define even more sophisticated copy rules. The code block receives three parameters: the key, the value and the numeric ordinal position of the current key/value pair in <hSource>. The code block must return a logical value. When it returns .T. (true), the key/value pair is copied to <hTarget> in Normal copy mode. Otherwise, the key/value pair is ignored.

Notes:  when the built in copy rules do not meet your requirements, use a code block for <xMode> that returns always .F. (false), and alter <hTarget> within the code block.

HCopy() does not return a new copy of the <hTarget> hash, but alters it. If you need to preserve the original target hash, create a new reference with HClone() first.

Info

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

Example

// The example demonstrates various copy modes of HCopy()

   PROCEDURE Main
      LOCAL hHash := Hash( "b", 20, "e", 30 )
      LOCAL hSrc, hTgt

      hSrc := Hash( "a", 1, "b", 2, "c", 3, "d", 4 )
      hTgt := HClone( hHash )

      HCopy( hSrc, hTgt )
      ? ValToPrg( hTgt )
      // result: { "a" => 1, "b" => 2, "c" => 3, "d" => 4, "e" => 30 }

      hTgt := HClone( hHash )
      HCopy( hSrc, hTgt,,, 1 )
      ? ValToPrg( hTgt )
      // result: { "a" => 1, "c" => 3, "d" => 4 }

      hTgt := HClone( hHash )
      HCopy( hSrc, hTgt,,, 2 )
      ? ValToPrg( hTgt )
      // result: { "b" => 2 }

      hTgt := HClone( hHash )
      HCopy( hSrc, hTgt,,, 3 )
      ? ValToPrg( hTgt )
      // result: { "e" => 30 }

      hTgt := HClone( hHash )
      HCopy( hSrc, hTgt,,, {|k,v,i| i > 1 .AND. v % 2 == 0 } )
      ? ValToPrg( hTgt )
      // result: { "b" => 2, "d" => 4, "e" => 30 }
   RETURN