hb_H

🔙 Home

• Hash Arrays functions (also known as "hash tables" and "associative arrays").
  For a detailed reference about this type of data structure see here and here.
  Basically in Harbour, a 'Hash Array' is an array of <key/value> pairs, where the key operates as named pointer utilized to uniquely identify and obtain the paired value.
  An important point, worth to be remembered, is the Harbour data types used for key/value pairs:

  • Keys can be of type: string, number, date, timestamp, and pointer. Any other type, used as a key, will raise a runtime error!
  • Values can be of (almost) any type that is supported by Harbour: string, numeric, date, timestamp, logical, pointer, array, hash table, code-block, NIL.

  Additional documentation about Harbour hashes can also be found at:
  - Juan Gamero's sandbox
  - Harbour Hash documentation

• hb_Hash([ <Key1>, <Value1> ], [ <KeyN>, <ValueN> ], ...) ➜ hsTable
  Creates a hash table and, optionally, populates it with elements (pairs of keys and values).
  However, the creation of a hash table is recommended to do be done in an inline assignment, using the literal {=>} instead of hb_Hash() function.
  For example:
  hHash := {=>} creates an empty hash table, ready to be populated later
  hHash := {"key1"=>"cValue1", "key2"=>dValue1 } which creates a hash table, initialized with two "key/value" pairs (or two "elements", to get an analogy to arrays).

• hb_HAllocate( <hHash>, <nElements>) ➜ NIL
  Pre-allocates space (memory) for <nElements> hash items. It's useful when you intend to add a set of new items because you will save time spent in grabbing each new element separately; preallocating elements may improve speed execution of program.
  Note: this function will not "truncate" or release (delete) items, if the <nElements> number is less than the actual item count already into the hash table.

• hb_HAutoAdd(<hHash>, [<lFlag>]) ➜ lPreviousFlag
  Sets the 'auto add' flag for the hash table.

• hb_HBinary(<hHash>, [<lFlag>]) ➜ lPreviousFlag
  Sets the 'binary' flag for the hash table.

• hb_HCaseMatch(<hHash>, [<lFlag>]) ➜ lPreviousFlag
  Sets the 'case match' flag for the hash table.

• hb_HClear(<hHash>) ➜ hHash
  Deletes all the elements in <hHash> leaving an empty hash table.

• hb_HClone(<hHash>) ➜ hsDestination
  Creates a copy of a hash table.

• hb_HCopy(<hsDestination>, <hsSource>, [<nStart>], [<nCount>]) ➜ hsDestination
  Adds entries from the source hash table to the destination hash table.

• hb_HDefault(<hHash>, <DefaultValue>) ➜ OldDefaultValye
  Sets the default value assinged to new keys in a hash table. Returns the previous default value (if any).

• hb_HDel(<hHash>, <Key>) ➜ hHash
  Deletes a key and it’s associated value from a hash table.

• hb_HDelAt(<hHash>, <nPosition>) ➜ hHash
  removes an entry from a hash table, based on its index position.

• hb_HEval(<hHash>, <bBlock>, [<nStart>], [<nCount>]) ➜ hHash
  evaluates a code block across the contents of a hash table. It's quite similar to AEval() function but works with hashes, instead of plain arrays.
  The code block receives the key, value, and numeric position of every hash element that is being processed ( e.g.: {|k,v,i| ... } )

• hb_HFill(<hHash>, <Value>) ➜ hHash
  sets the values of all the keys of <hHash> table to <xValue>.

• hb_HGet(<hHash>, <xKey>) ➜ xValue
  returns the value associated to <xKey>. In case that the <xKey> doesn’t exists run-time error (RTE) occurs. (to avoid RTE, you may prefer to use hb_HGetDef() --see below).

• hb_HGetDef(<hHash>, <xKey>, [<DefaultValue>]) ➜ xValue|NIL
  returns either the value associated to the given key within the <hHash> hash table, or the default value <DefaultValue> if the <xKey> doesn’t exist. It returns NIL when both the <xKey> doesn't exist and no <DefaultValue> has given.

• hb_HGetRef(<hHash>, <xKey>, [ @<xValue> ]) ➜ lFound
  returns .T. if <xKey> exists. Optionally stores its associated value to <xValue> which must be passed by reference to retain the stored value. If the <xKey> is not found, <xValue> will become NIL.
  Remark: This function, in functionality terms, might be viewed as a combination of hb_HGet() and hb_HHasKey() functions.

• hb_HHasKey(<hHash>, <xKey> [, @<nPos> ]) ➜ lExists
  returns .T. if <xKey> exists in the hash table and stores its ordinal position to @<nPos> which must be passed by reference to retain the stored position. If the key doesn’t exists then <nPos> will be the position of the smaller nearest key.

• hb_HKeepOrder(<hHash> [ , <lKeepOrder> ]) ➜ lPrevKeepOrder
  Sets the KEEPORDER flag in a hash and returns the previous state. This flag controls the order by which the elements are stored in the hash table. If the KEEPORDER flag is .T. then the order by which the elements are created or added will be preserved. If it is .F., then the elements of the hash table will be sorted (other flags may affect the order such as the BINARY flag, the CASEMATCH flag, etc). This flag is enabled (.T.) by default.

• hb_HKeyAt(<hHash>, <nPosition>) ➜ xKey
  Retrieves the key at a given position in a hash table. The <nPosition> value must be in the range 1...Len( hHash ). If hash table is empty or <nPosition> is zero or greater than Len( hHash ) then a "Bound error" RTE (runtime error) occurs .

• hb_HKeys(<hHash>) ➜ aKeys
  returns an array with all the keys (but not the associated values) of a hash table.

• hb_HMerge(<hsDestination>, <hsSource>, <bBlock>|<nMethod>) ➜ hsDestination
  Merges <hsSource> hash into <hsDestination> hash. With the 3rd parameter can be optionally specified the merge mode. When source elements copied will substitute those with the same key in the destination hash table.

• hb_HPairAt(<hHash>, <nPosition>) ➜ aKeyValue
  returns a two-dimensional array of the key/value pair entry of the hash table.

• hb_HPos(<hHash>, <xKey>) ➜ nPosition
  returns the position of <xKey> within the <hHash> hash. If not found it returns zero.
  NOTE: the value type of <xKey> must be one of the valid for hash keys types (i.e. string, number, date, timestamp or pointer) otherwise a runtime error occurs, e.g., when the <xKey> is NIL.

• hb_HScan(<hHash>, <uValue>|<bBlock> [, <nStart>, <nCount>], <lExact>) ➜ nPosition
  Scans the hash table values searching for <uValue>. Alternatively, you can pass a codeblock <bBlock> that receives the key, the value and the position of each element, and should return .T. if a match is found. The range of hash table items to be scanned can be limited by the <nStart> and <nCount> parameters, otherwise all elements are scanned.
  The logical flag <lExact> determines if an exact matching (or not) shall performed, when searching for strings or datetime or array or hashes.
  Returns the numeric position of the located value within the hash table, or zero (0) if nothing found.

• hb_HSet(<hHash>, <Key>, <Value>) ➜ hHash
  Sets (or adds a new) key/value pair to <hHash> hash table.

• hb_HSetDef(<hHash>, <xKey> [, <xDefVal> ]) ➜ xKeyValue
  This function checks if <xKey> exists and optionally sets the key-value to <xDefVal>.

  • If <xKey> does not exists then adds it to hash array and sets the key-value to <xDefVal>, if passed.
  • If <xKey> exists in hash array and <xDefVal> is given, then it checks if the type of key-value is compatible (i.e. same valtype) with <xDefVal> and if not then replaces key-value with <xDefVal>.
  • If <xKey> exists in hash array and no <xDefVal> is given, then nothing changes.

  This function returns the value associated with xKey, which value (after successful function execution) can be either the initial value or the applied <xDefVal> or NIL (when a new <xKey> added while no <xDefVal> value is given).
  In other words this function it's a combination of hb_HGetDef() and hb_default() and works like the below PRG code:

     FUNCTION hb_HSetDef( hHash, xKey, xDefVal )
        IF xKey $ hHash
           hb_default( @hHash[ xKey ], xDefVal )
        ELSE
           hHash[ xKey ] := xDefVal
        ENDIF
        RETURN  hHash[ xKey ]

  but it is much faster!
  NOTE: that's a new function released with this 2018-01-05 14:12 commit., therefore is not available in earlier Harbour 3.2 versions (AFAIK it doesn't, also, exist in Viktor's (currently archived un-archived) fork, Harbour 3.4).

• hb_HSort(<hHash>) ➜ hHash
  Marks <hHash> hash for sorting. BINARY and CASEMATCH flags will affect the result.

• hb_HValueAt(<hHash>, <nPosition>, [<xNewValue>]) ➜ xValue
  Returns the value associated to the key at a given position in a hash table. Optionally, you can set the new value <xNewValue> associated to the key at that position.

• hb_HValues(<hHash>) ➜ aValues
  returns an array with all the associated values (not the keys) of a hash table.

---

• hb_HexToNum(<cHexNumber>) ➜ nNumber
  converts an hexadecimal number into a decimal number.

• hb_HexToStr(<cHexValues>) ➜
  converts a string of hexadecimal values into it's corresponding bytes stream. The inverse of 'hb_StrToHex()'.

• hb_Hour(<tTimeStamp>) ➜ nHour
  returns the hour (HH) part or "member" of a TimeStamp.

---

• hb_hrbDo(<pHbPCode> [, <...> ]) ➜ xValue
  executes pre-compiled code (p-code) and returns the value resulted by execution (if any). <pHbPCode> is a pointer to harbour p-code previously loaded using hb_hrbLoad() (see below). The optional 2nd parameter <...> is a list of parameters that is passed to and used by executable p-code.
  Note: see also the relevant hb_compile***() functions.

• hb_hrbGetFunList(<pHRB> [, <nType>]) ➜
  returns array of functions defined into p-code that has been loaded in memory pointed by <pHRB>. For available <nType> types, see HB_HRB_FUNC_* constants defined into hbhrb.ch.

• hb_hrbGetFunSym(<pHRB>, <cFuncName>) ➜ sFuncName
  returns symbolic name (type="S") of a function contained into <pHRB> p-code, that is, the 'cFuncName' itself with a prefix '@' and suffix (), e.g.: "myFunc" => @MyFunc().
  The returned symbol can be executed using either of the messages sFuncName:EVAL(...) or sFuncName:EXEC(...) or the function Eval( sFuncName, ... ).
  If the given function name cannot be found, NIL is returned.

This function looks for in HRB module pointed by and returns symbol item which refers to this function or NIL if function cannot be found.

Functions referred by symbol items can be executed using :EVAL() or EXEC() messages, f.e.:

• hb_hrbLoad([ <nOptions>, ] <cHrbFileName> [, <xparamList...> ]) ➜ pHbPCode
  loads <cHrbFileName> and returns a pointer that can be passed to 'hb_hrbDo()' to execute loaded p-code. <cHrbFileName> is a .hrb file, that is, pre-compiled harbour binary (aka 'p-code'). <xparamList...> is list of parameters that will be passed to the INIT PROCEDURE of loaded p-code. <nOptions> is optional parameter (default=cHrbFileName), which affects binding mode of loaded p-code. (inspect HB_HRB_BIND_* constants defined into hbhrb.ch for supported options).

• hb_hrbRun([ <nOptions>, ] <cHrbFileName> [, <xparams,...> ]) ➜ retVal
  gets the the data from a .hrb file, as specified by <cHrbFileName>, runs the p-code contained in it and returns the result of execution (if any). Refer to 'hb_hrbLoad()' above for <nOptions> and <xparams,...> explanation.

• hb_hrbSignature() ➜ cSig
  returns HRB file signature.

• hb_hrbUnload(<pHRB>) ➜ NIL
  unloads (releases) p-code from memory, previously loaded by hb_hrbLoad().

  See also this post about .HBR files and other useful info.

🔙 Home