-
Notifications
You must be signed in to change notification settings - Fork 1
2.7 Hashes
Harbour has native support for hash arrays (a.k.a. hash tables or associative
arrays). It has it’s own type identifier (H) and a rich set of functions to
operate on them. Additionally, you can access and assign values to hash arrays
elements using arrays syntax, like this:
h := { "x" => 1, "y" => 3, "z" => 2 }
? h[ "x" ] /* 1 */
? h[ "z" ] /* 2 */
? h[ "y" ] /* 3 */
h[ "y" ] := 128 /* Set 128 as the value assigned to key "y" */|
Note
|
Harbour hash arrays can’t be considered pure "hash tables", as the order in wich the elements are stored can be determined, unlike pure "hash tables" where the order in wich elements are stored is irrelevant. |
Creates a hash array and, optionally, populates it with elements (pairs of keys and values).
|
Note
|
It is recommended that a hash array is initialized using a literal
( |
Determines if a key exists in the hash and optionally gives its position. If
the key doesn’t exists then <nPos> will be the position of the smaller
nearest key.
Gets the value associated to a key. See HB_HGetDef() if you don’t want
a RTE when a value doesn’t exists.
Gets the value associated to a key or a default value if the key doesn’t
exist. If a default value isn’t passed will return NIL.
Checks for the existence of a key and, at the same time, retrieving its corresponding value.
If the key is not found, <xValue> is also reset to NIL. Useful to
replace HB_HPos()/HB_HValueAt() calls and temporary variables,
or to avoid multiple hash lookups for the cost of one temporary variable.
Sets the value associated to a key.
|
Important
|
|
Returns the value associated to the key at a given position in a hash.
Optionally, you can set the new value <xNewValue> associated to the key
at that position.
Returns an array with the pair { key, value } at a given position in the
hash. Optionally you can set the new key <xNewKey> and the value
<xNewValue> in that position of the hash.
Deletes the key and it’s associated value stored in the position <nPos>
of the hash.
Returns an array with all the keys (not the associated values) of a hash.
Returns an array with all the associated values (not the keys) of a hash.
Copy elements from <hSrcHash> to <hDstHash>. You can specify the
first element to copy in <nStart> and the number of elements to copy in
<nCount>, otherwise all the elements will be copied.
Merge two hashes. In the 3rd parameter you can specify the merge mode (see
table bellow) or you can pass a codeblock that receives the key, the value
and the position of each element of the <hSrcHash> hash array, and
returs .T. if the element should be copied into <hDstHash>.
The predefined merge methods are (defined in hbhash.ch):
| Constant | Description |
|---|---|
HB_MERGE_UNION |
(DEFAULT) Copy elements that are in |
HB_MERGE_INTERSECT |
Copy elements that are in both |
HB_MERGE_XOR |
Copy elements that don’t exists in both |
HB_MERGE_REMOVE |
Deletes from |
|
Note
|
Copied elements will substitute those with the same key in the destination hash. |
Evaluates a codeblock for each element of the hash. All the elements will be
evaluated, but you can specify a starting element in <nStart> and the
number of elements to be evaluated in <nCount>.
For each element evaluated, the key, the value and the position are passed to the codeblock.
Scans the hash array values searching for <uValue> or you can pass a
codeblock <bBlock> that receives the key, the value and the position of
each element, and returs .T. if a match is found. You can limit the
range of hash items to be scanned by the <nStart> and <nCount>
parameters. If you set <lExact> to .T. and search for strings,
datetime, array and hashes the value must be exactly equal to consider it
found.
Marks hash <hHash> for sorting. Binary and CaseMatch flags will affect
the result.
Pre-allocates space for <nElements> hash items. Useful when you are
going to add a set of new items because you will save the time spent in
grabbing each new element.
|
Note
|
Note that this function will not "truncate" or delete items in the hash
if the |
Sets the KEEPORDER flag in a hash and returns the previous state.
This flag controls the order in wich elements are stored in the hash.
If the KEEPORDER flag is .T. then the order in wich the elements
are created or added will be preserved. If it is .F., then the elements
of the hash 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.
Sets the CASEMATCH flag in a hash and returns the previous state.
This flag controls the case sensitivity when you search or compare hash
keys. By default, hash case matching flag is enabled (.T.).
Sets the BINARY flag in a hash and returns the previous state.
This flag controls when a binary comparison is done when searching and
sorting strings. By default, this flag is enabled (.T.).
By default, when a hash array is created, the AUTOADD flag is enabled to
assign operations (HB_HAUTOADD_ASSIGN), it means that every assign
operation to a key that previously didn’t exist in the hash is automatically
added, as in this example:
/*
You will get Run Time Errors (RTE)
Comment the offending line to see the rest of the test
*/
#include "hbhash.ch"
PROCEDURE Main()
LOCAL h
h := { => } /* New empty hash */
h[ 1 ] := "value" /* auto-add key 1 */
? h[ 1 ] /* => value */
? h[ 2 ] /* => RTE. No auto-add on access */
/* Now set auto-add on access (WARNING: but not on assign) */
HB_HAutoAdd( h, HB_HAUTOADD_ACCESS, "[DEFAULT]" )
? h[ 3 ] /* => [DEFAULT] / NO RTE. Default value added on access */
/* Now set new default value for auto-added elements */
HB_HDefault( h, "[NEWITEM]" )
? h[ 4 ] /* => [NEWITEM] */
/* Don't auto-add in any case */
HB_HAutoAdd( h, HB_HAUTOADD_NEVER )
h[ 5 ] := "fail" /* => RTE. No auto-add on assign */
? h[ 5 ] /* => RTE. No keys auto-added, you must use HB_HSet() */
RETURNYou can set the AUTOADD flags as a numeric value (defined in hbhash.ch)
with the next options:
| Constant | Description |
|---|---|
HB_HAUTOADD_NEVER |
Clears the flag, and don’t automatically add keys in any case |
HB_HAUTOADD_ACCESS |
Auto-add keys on access operations |
HB_HAUTOADD_ASSIGN |
Auto-add keys on assign operations |
HB_HAUTOADD_ALWAYS |
Auto-add keys on access and assign operations (the same as
|
If you pass the second parameter as a logical value, when you pass .T.
it will set the AUTOADD flag to HB_HAUTOADD_ALWAYS if the hash has a
default value assigned and it will set the flag to HB_HAUTOADD_ASSIGN
if it has no default value assigned. In the other hand, if you pass .F.
it will clear the flag (HB_HAUTOADD_NEVER).
You can, optionally, set the default value used when you add a key to a hash
array with xDefault. This is useful to avoid subsequent HB_HDefault()
calls.
This function returns the previous AUTOADD flag in as numeric value (see
the HB_HAUTOADD_* table).
Sets the default value assinged to new keys in a hash array. Specially
useful when AUTOADD is enabled. You can set complex values as
<xDefault> value and they will be cloned on new item addition. [1]
Examples: See example at HB_HAutoAdd()