xHarbour Reference Documentation > Operator Reference

{=>}

Literal hash.

Syntax

{[<key1>] => [<value1>][,<keyN> => <valueN>]}

Arguments

<key1> .. <keyN>

<key> is one or more key values to initialize the Hash with. Key values may be of data type Character, Date or Numeric. Other data types are not allowed for <key>.

<value1> .. <valueN>

<value> is one or more values of any data type associated with <key> when the Hash is initialized. Multiple key/value pairs are separated with commas.

Description

An empty literal Hash is created with the characters {=>}. The Hash can be initialized with key => value pairs upon creation.

A Hash is similar to a two column array where the keys are stored in the left and the associated values in the right column. For this reason, a Hash is often referred to as "associative array". A Hash, however, is a genuine data type in xHarbour and allows for different operations than with the Array data type. The most significant difference between Hash and Array is that while values stored in an array are retrieved using a numeric ordinal position of an array element, a Hash value is retrieved by its associated key, and not by its ordinal position.

For this reason, data types for keys must be orderable. This restricts keys to the data types Character, Date and Numeric. A key, however, can be associated with a value of any data type, including Hash.

The most common data type for keys is Character. This makes a Hash to a kind of "lightweight object" that has only data and no methods. Since the key strings are used to retrieve the associated values, a key string can be understood like a message sent to an object.

The "dual" nature of the Hash data type, being partly similar to arrays and partly to objects, finds its expression also in the syntactical notation that can be used for retrieving a value from a Hash. Both operators are supported, the array element operator [ ] and the : send message operator. The latter, however, requires keys to be of data type Character.

Important:  when using the : send message operator to create or retrieve a value from a Hash, the message is case-sensitive unless HSetCaseMatch() is set to .F. (false) for the Hash.

Info

See also:	{ }, Array(), CLASS, Hash()
Category:	Operators , Special operators , xHarbour extensions
LIB:	xhb.lib
DLL:	xhbdll.dll

Examples

// The example demonstrates how to create and populate hash values.

   PROCEDURE Main                      // literal hash
      LOCAL hHash := { "COM1" => 1, "COM2" => 2 }

      // object notation
      ? hHash:COM1                     // result: 1

      // array notation
      ? hHash["COM2"]                  // result: 2

      // adding a new key/value pair using object notation
      hHash:COM3 := 3

      ? hHash:COM3                     // result: 3

      ? hHash:COM4                     // runtime error
   RETURN

// The example demonstrates comparison operators with hashes

   PROCEDURE Main
      LOCAL hHash1 := { "A" => 1, "B" => 2, "C" => 3, "D" => 4 }
      LOCAL hHash2 := { "B" => 5, "C" => 6, "E" => 7, "F" => 8 }
      LOCAL hHash3 := hHash1

      ? hHash1 == hHash2      // result: .F.
      ? hHash1 <> hHash2      // result: .T.

      ? hHash1 == hHash3      // result: .T.
      ? hHash1 <> hHash3      // result: .F.
   RETURN

// The example demonstrates set-oriented operations with hashes
// using Plus and Minus operators

   PROCEDURE Main
      LOCAL hHash1 := { "A" => 1, "B" => 2, "C" => 3, "D" => 4 }
      LOCAL hHash2 := { "B" => 5, "C" => 6, "E" => 7, "F" => 8 }
      LOCAL hHash3

      hHash3 := hHash1 + hHash2
      ? ValToPrg( hHash3 )
      // { "A" => 1, "B" => 5, "C" => 6, "D" => 4, "E" => 7, "F" => 8 }

      hHash3 := hHash1 - hHash2
      ? ValToPrg( hHash3 )
      // { "A" => 1, "D" => 4 }
   RETURN