xHarbour Reference Documentation > Function Reference

HGetPos()

Retrieves the ordinal position of a key in a hash.

Syntax

HGetPos( <hHash>, <xKey>) --> nPos

Arguments

<hHash>

A variable referencing the hash to search a key in.

<xKey>

This is the key to search for in <hHash>.

Return

The function returns the ordinal position of <xKey> in the hash <hHash>, or 0 if the key is not present in the hash.

Description

This function is mostly used to check if a key is present in a hash. If the return value is greater than zero, the key exists. The return value can then be passed on to function HGetValueAt() to retrieve the associated value. This is more efficient than using the key a second time for retrieving the value.

Info

See also:	Hash(), HDelAt(), HGetKeys(), HGetPairAt(), HGetValueAt(), HHasKey()
Category:	Hash functions , xHarbour extensions
Source:	vm\hash.c
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The function first checks the existence of a key and then
// retrieves the associated value by ordinal position.
// Note that the creation order of key/value pairs does not
// affect their insertion order (which is A B C D).

   PROCEDURE Main
      LOCAL hHash := Hash( "C", 10, "D", 30, "A", 40, "B", 20 )
      LOCAL aKeys := { "C", "D", "E" }
      LOCAL i, nPos

      FOR i:=1 TO Len( aKeys )
          nPos := HGetPos( hHash, aKeys[i] )
          IF nPos > 0
             ? aKey[i], HGetValuAt( hHash, i )
          ELSE
             ? aKey[i], "not present"
          ENDIF
      NEXT
      ** Output:
      // C         40
      // D         20
      // E not present
   RETURN