xHarbour Reference Documentation > Function Reference

HB_Decode()

Provides a functional equivalent for the DO CASE statement.

Syntax

HB_Decode( <xInitVal>, <xCase1>, <xRet1> , ;
                      [<xCaseN>, <xRetN>], ;
                      [<xDefault>]         ) --> xReturn

or

HB_Decode( <xInitVal>, <hHash>, [<xDefault>] ) --> xReturn

Arguments

<xInitVal>

This is an arbitrary value being tested against <xCase1> to <xCaseN> or the keys of <hHash>.

<xCase>, <xRet>

The parameters <xCase> and <xRet> must be specified in pairs. <xCase> is the value compared with <xInitVal>. When both are the same, the return value is <xRet>

<xDefault>

This is an optional default value being returned when no match is found. It defaults to NIL.

<hHash>

Instead of passing pairs of <xCase> and <xRet> parameters, a single Hash() can be passed holding key/value pairs. <xCase> is compared with the hash keys. When a match is found, the hash value is returned.

Return

The function returns the value <xRet> when <xInitValue> matches <xCase>. If no match is found, <xDefault>, if specified, is returned. Otherwise, the return value is NIL.

Description

HB_Decode() can be viewed as a functional equivalent of to DO CASE statement. An initial value <xInitVal> is passed and compared to a list of <xCase> values. When a match is found, the corresponding <xRet> parameter is returned. <xCase> and <xRet> can be specified pairwise or may be combined in a single hash.

Info

See also:	DO CASE, Hash(), HB_DecodeOrEmpty()
Category:	Conversion functions , xHarbour extensions
Source:	rtl\decode.prg
LIB:	xhb.lib
DLL:	xhbdll.dll

Example

// The example illustrates possibilities of using HB_Decode()

   PROCEDURE Main
      LOCAL nChoice, hHash := {=>}

      nChoice := 2
      ? HB_Decode( nChoice, 1, "COM1", 2, "COM2", 3, "COM3", "NUL" )
                                              // result: COM2

      nChoice := 4
      ? HB_Decode( nChoice, 1, "COM1", 2, "COM2", 3, "COM3", "NUL" )
                                              // result: NUL
      hHash := { 0 =>  "Yesterday", ;
                 1 =>  "Today"    , ;
                 2 =>  "Tomorrow"   }

      nChoice := 0
      ? HB_Decode( nChoice, hHash, "Never" )  // result: Yesterday

      nChoice := 3
      ? HB_Decode( nChoice, hHash, "Never" )  // result: Never

   RETURN