xHarbour Reference Documentation > Function Reference

HScan()

Searches a value in a hash.

Syntax

HScan( <hHash>  , ;
       <xValue> , ;
      [<nStart>], ;
      [<nCount>], ;
      [<lExact>], ;
      [<lASCII>]  ) --> nPos

Arguments

<hHash>

A variable referencing the hash to search for a value.

<xValue>

This is either the value to search or a code block specifying the search condition.

<nStart>

A numeric value indicating the first key/value pair of <hHash> to begin the search with. It defaults to 1.

<nCount>

<nCount> is the nubmer of key/value pairs to be searched, beginning at <nStart>. If omitted, <nCount> is calculated as 1+Len(<hHash>)-<nStart>.

<lExact>

This is a logical value and defaults to .T. (true). It is only relevant when a character string is searched in a hash. By default, the string matching rules are applied as if SET EXACT is set to ON. Pass .F. (false) to search values as if SET EXACT is OFF.

<lASCII>

This parameter defaults to .F. (false). If .T. (true) is passed, single character strings are matched with a numeric <xValue> based on their ASCII value.

Return

The function returns the numeric ordinal position of <xValue> in <hHash>, or zero when the value is not found.

Description

The function is used to search a value in a hash. It accepts either the value to search, or a code block that specifies the search condition.

If <xValue> is a code block, it receives three parameters: the key, the value and the numeric ordinal position of the current key/value pair in <hHash>. The code block must return a logical value. When it returns .T. (true), the search condition is satisfied and HScan() returns the ordinal position of the current item in <hHash>.

Info

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

Example

// The example demonstrates various results of HScan()
// using search values and search conditions (code blocks)

   PROCEDURE Main
      LOCAL hHash := {=>}

      hHash[ "a" ] := "Hello"
      hHash[ "b" ] := { 1, 2 }
      hHash[ "c" ] := Date()
      hHash[ "d" ] := 1
      hHash[ "e" ] := { 4, 5 }

      ? HScan( hHash, "Hello" )                  // result: 1

      ? HScan( hHash, 1       )                  // result: 4

      ? HScan( hHash, Date()  )                  // result: 3

      ? HScan( hHash, {|k,v,i| Valtype(v)=="A" .AND. v[1] == 1} )
                                                 // result: 2

      ? HScan( hHash, {|k,v,i| Valtype(v)=="A" .AND. v[1] == 4} )
                                                 // result: 5
   RETURN