HASH

MANUAL
HASH FUNCTIONS

12-07-2007 1
 HASH

HAllocate()

Pre-allocates memory for a large hash.

Syntax

HAllocate( <hHash>, <nCount> ) --> NIL

Arguments

<hHash>
A variable referencing an empty hash to pre-allocate memory for.
<nCount>
A numeric value specifying the number of key/value pairs to reserve memory for.

Return

The function returns always NIL.

Description

The function is used to pre-allocate memory for an empty hash or to reduce its pre-allocated size.
When the number of key/value pairs to collect in a hash is approximately known in advance, it
can be useful to pre-allocate memory for it so that the time to grow a hash and allocate memory
for it is reduced to a minimum. To reduce memory pre-allocated in excess, call HAllocate() with
a small value for <nCount>.

The function is provided in case huge hashes must be built and performance is at stake. Normally,
the partitioning of hashes using HSetPartition() is more effective in creating large hashes.

12-07-2007 2
 HASH

Hash()

Creates a new hash.

Syntax

Hash( [<xKey1>, <xValue1> [, <xKeyN>, <xValueN>] ] ) --> hHash

Arguments

<xKey1> .. <xKeyN>
<xKey1> is the key value associated with <xValue1> in the hash. The key value is usually of
data type Character, but may be a Date or Numeric value.
<xValue1> .. <xValueN>
<xValue1> is a value in the hash which can be accessed through its key value <xKey1>.

Return

The function returns a new hash, populated with the specified key/value pairs. If no parameter is
passed, an empty hash is returned.

If the function is called with an odd number of arguments, or key values are specified which are
not of data type Character, Date or Numeric, the return value is NIL.

Description

Hash variables are usually initialized within a variable declaration using the literal Hash operator
{=>}. The Hash() function is equivalent to this operator and allows for creating hashes
programmatically outside a variable declaration.

Hashes can be populated with key/value pairs by passing an even number of parameters to the
function. Data representing the key values must be of orderable data types which restricts them to
the data types C, D and N.

12-07-2007 3
 HASH

HClone()

Creates an entire copy of a hash.

Syntax

HClone( <hHash> ) --> hClone

Arguments

<hHash>
A variable referencing the hash to copy.

Return

The function returns a new Hash reference containing the same key/value pairs as <hHash>.

Description

This function creates a new Hash value and populates it with key/value pairs of the original hash.
The new hash receives copies of the original values when they are of simple data types Character,
Date, Logic, Numeric and NIL.

When data types are represented by references, the reference is copied, so that the new hash holds
the same (identical) value as the original. This applies to data types Array, Code block, Hash and
Object.

The attributes for case sensitivity and automatic element creation of <hHash> is transferred to
the new hash as well.

Important: <hHash> must not reference itself in any of its key/value pairs.

12-07-2007 4
 HASH

HCopy()

Copies key/value pairs from a hash into another hash.

Syntax

HCopy( <hSource>, ;
<hTarget>, ;
[<nStart>], ;
[<nCount>], ;
[<xMode>] ) --> hTarget

Arguments

<hSource>
A variable referencing the hash to copy.
<hTarget>
A variable referencing the hash that receives key/value pairs from <hSource>.
<nStart>
A numeric value indicating the first key/value pair of <hSource> to copy to <hTarget>.
It defaults to 1.
<nCount>
A numeric value specifying the number of key/value pairs to copy, starting from position
<nStart>. If <nCount> is omitted, all elements of <hSource> starting at <nStart> are
copied.
<xMode>
<xMode> is either a numeric value or a code block. It specifies how to treat duplicate
keys in both hashes. See description below. The default value is 0.

Return

The function returns a reference to <hTarget>.

12-07-2007 5
 HASH

HDel()

Removes a key/value pair from the hash by its key.

Syntax

HDel( <hHash>, <xKey> ) --> NIL

Arguments

<hHash>
A variable referencing the hash to remove a key/value pair from.
<xKey>
<xKey> is the key to delete from the hash.

Return

The function returns always NIL.

Description

The function removes a key/value pair from the hash <hHash>. If the key <xKey> is not found
in the hash, a runtime error is raised. Use function HHasKey() to determine the existence of a
key.

Note: deleting a key is the only way to change a key in a hash. If the value must be preserved,
use function HGet() to retrieve the value, then remove the key, and finally add the new key with
the preserved value.

12-07-2007 6
 HASH

HDelAt()

Removes a key/value pair from the hash by its key.

Syntax

HDelAt( <hHash>, <nPos> ) --> NIL

Arguments

<hHash>
A variable referencing the hash to remove a key/value pair from.
<nPos>
A numeric value specifying the ordinal position of the key/value pair to remove. It must
be in the range between 1 and Len(<hHash>).

Return

The function returns always NIL.

Description

The function removes a key/value pair from the hash <hHash> by its ordinal position. If <nPos>
is outside the valid range, a runtime error is raised. Use function HGetPos() to determine the
ordinal position of a key.

12-07-2007 7
 HASH

HEval()

Evaluates a code block with each hash element.

Syntax

HEval( <hHash>, <bBlock>, [<nStart>], [<nCount>] ) --> hHash

Arguments

<hHash>
A variable referencing the hash to process.
<bBlock>
This is the codeblock that is evaluated with each key/value pair of <hHash>
<nStart>
A numeric value indicating the first key/value pair of <hHash> to evaluate the code
block with. It defaults to 1.
<nCount>
<nCount> is the nubmer of key/value pairs that are passed to <bBlock>. If omitted,
<nCount> is calculated as 1+Len(<hHash>)-<nStart>.

Return

The function returns a reference to <hHash>.

Description

The function evaluates the code block <bBlock> with the key/value pairs of <hHash>. The code
block receives three parameters: the key, the value and the numeric ordinal position of the current
key/value pair in <hHash>. The return value of the code block is ignored.

12-07-2007 8
 HASH

HFill()

Copies the same value into all key/value pairs.

Syntax

HFILL( <Hash>, <xValue> ) --> NIL

Arguments

<Hash>
A variable referencing the hash to fill with a value.
<xValue>
The value to copy to all key/value pairs of <hHash>

Return

The function returns always NIL.

Description

The function uses a single value <xValue> and copies it to all key/value pairs of a hash. This is
useful when a unified state must be achieved for all items in the hash. Use only simple data types
for <xValue> (C,D,L,N).

12-07-2007 9
 HASH

HGet()

Retrieves the value associated with a specified key.

Syntax

HGet( <hHash>, <xKey> ) --> xValue

Arguments

<hHash>
A variable referencing the hash to retrieve a value from.
<xKey>
<xKey> is the key to retrieve the associated value of.

Return

The function returns the value associated with the key <xKey>.

Description

The function retrieves the value <xValue> from the hash <hHash> associated with the key
<xKey>.

If the key is not found in the hash, a runtime error is raised. Use function HHasKey() to determine
the existence of a key.

12-07-2007 10
 HASH

HGetAutoAdd()

Retrieves the AutoAdd attribute of a hash.

Syntax

HGetAutoAdd( <hHash> ) --> lIsAutoAdd

Arguments

<hHash>
A variable referencing the hash to retrieve the attribute from.

Return

The function returns the AutoAdd attribute of <hHash> as a logical value.

Description

The function retrieves an attribute of a hash that identifies whether or not automatic creation of
key/value pairs is permitted in the context of inline assignments or the HSet() function.

By default, this attribute is .T. (true) when a new hash is created. This causes the assignment of a
value to a non-existent key to create a new key/value pair in the hash. This default behaviour can
be switched off using function HSetAutoAdd().

HGetCaseMatch()

Retrieves the case sensitivity attribute of a hash.

Syntax

HGetCaseMatch( <hHash> ) --> lIsCaseSensitive

Arguments

<hHash>
A variable referencing the hash to retrieve the attribute from.

12-07-2007 11
 HASH
Return

The function returns the case sensitivity attribute of <hHash> as a logical value.

Description

The function retrieves an attribute of a hash that identifies whether or not character string
matching for keys is case sensitive. By default, this attribute is .T. (true) when a new hash is
created. This

12-07-2007 12
 HASH

HGetKeyAt()

Retrieves the key from a hash by its ordinal position.

Syntax

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

Arguments

<hHash>
A variable referencing the hash to retrieve a key from.
<nPos>
A numeric value specifying the ordinal position of the key/value pair to query. It must be
in the range between 1 and Len(<hHash>).

Return

The function returns the key at position <nPos> in the hash <hHash>.

Description

This function retrieves the key from the hash <hHash> at position <nPos>. If <nPos> is outside
the valid range, a runtime error is raised. Use function HGetPos() to determine the ordinal
position of a key.

The keys are inserted into the hash by their sorting order and cannot be moved or changed.

HGetKeys()

Collects all keys from a hash in an array.

Syntax

HGetKeys( <hHash> ) --> aKeys

Arguments

<hHash>
A variable referencing the hash to retrieve all keys from.

12-07-2007 13
 HASH
Return

The function returns a one-dimensional array holding in its elements copies of the keys of
<hHash>.

Description

This function retrieves all keys from a hash and collects them in an array. The ordinal position of
a key in the returned array is identical with the position in the hash.

HGetPairAt()

Retrieves a key/value pair from a hash by its ordinal position.

Syntax

HGetPairAt( <hHash>, <nPos> ) --> { xKey, xValue }

Arguments

<hHash>
A variable referencing the hash to retrieve a key/value pair from.
<nPos>
A numeric value specifying the ordinal position of the key/value pair to retrieve. It must
be in the range between 1 and Len(<hHash>).

Return

The function returns a two-element array with the key and value found at position <nPos> in the
hash <hHash>.

Description

This function retrieves the key/value pair from the hash <hHash> at position <nPos>. If <nPos>
is outside the valid range, a runtime error is raised. Use function HGetPos() to determine the
ordinal position of a key.

12-07-2007 14
 HASH

HGetPartition()

Checks if a hash is partitioned.

Syntax

HGetPartition( <hHash> , ;
[@<nPageSize>], ;
[@<nLevel>] ) --> lIsPartitioned

Arguments

<hHash>
A variable referencing the hash to check for partitioning.
<nPageSize>
If passed by reference, <nPageSize> is assigned a numeric value indicating the size of a
partition.
<nLevel>
If passed by reference, <nLevel> is assigned a numeric value indicating how many levels
deep a hash is partitioned.

Return

The function returns .T. (true) when a hash is partitioned, otherwise .F. (false) is returned.

Description

The function serves informational purposes only and checks if a hash is partitioned with function
HSetPartition().

12-07-2007 15
 HASH

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.

HGetValueAt()

Retrieves the value from a hash by its ordinal position.

Syntax

HGetValueAt( <hHash>, <nPos> ) --> xValue

Arguments

<hHash>

12-07-2007 16
 HASH
A variable referencing the hash to retrieve a value from.
<nPos>
A numeric value specifying the ordinal position of the value to retrieve. It must be in the
range between 1 and Len(<hHash>).

Return

The function returns the value at position <nPos> in the hash <hHash>.

Description

This function retrieves the value from the hash <hHash> at position <nPos>. If <nPos> is
outside the valid range, a runtime error is raised. Use function HGetPos() to determine the ordinal
position of a key/value pair.

Values of key/value pairs can be changed

HGetValues()

Collects all values from a hash in an array.

Syntax

HGetValues( <hHash> ) --> aValues

Arguments

<hHash>
A variable referencing the hash to retrieve all values from.

Return

The function returns a one-dimensional array holding in its elements the values of <hHash>.

Description

This function retrieves all values from a hash and collects them in an array. The ordinal position
of a value in the returned array is identical with the position in the hash.

HHasKey()

Determines if a key is present in a hash.

12-07-2007 17
 HASH
Syntax

HHasKey( <hHash>, <xKey> ) --> lExists

Arguments

<hHash>
<hHash> is identifier of the hash to test for the presence of a key.
<xKey>
This is the key to search for in <hHash>.

Return

The function returns .T. (true) if the <xKey> exists in <hHash>, otherwise .F. (false) is returned.

12-07-2007 18
 HASH

Description

This function tests if a key is present in a hash. HHasKey() is slightly more efficient than
HGetPos(

HMerge()

Merges the contents of an entire hash into another hash.

Syntax

HMerge( <hTarget>, <hSource>, [<xMode>]) --> hTarget

Arguments

<hTarget>
A variable referencing the hash that receives key/value pairs from <hSource>.
<hSource>
A variable referencing the hash to merge into <hTarget>.
<xMode>
<xMode> is either a numeric value or a code block. It specifies how to treat duplicate
keys in both hashes. The default value is 0.

Return

The function returns a reference to <hTarget>.

Description

This function merges the entire contents of the hash <hSource> into the hash <hTarget>,
depending on the value of <xMode>.

This function is a shortcut for:

HCopy( <hSource>, <hTarget>, 1, Len(<hSource>), <xMode> )

Note that <hTarget> and <hSource> are used in different order with HCopy() and HMerge().

For a description of parameter <xMode> refer to function HCopy

12-07-2007 19
 HASH

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.

12-07-2007 20
 HASH

HSet()

Associates a value with a key in a hash.

Syntax

HSet( <hHash>, <xKey>, <xValue> ) --> NIL

Arguments

<hHash>
A variable referencing the hash that receives the key/value pair.
<xKey>
The key of the key/value pair.
<xValue>
The value of the key/value pair.

Return

The function returns always NIL.

Description

HSet() is the functional equivalent of the hash access operator [ ] in conjunction with the inline
assignment operator :=. It provides the same functionality for populating a hash or changing the
value of existing key/value pais, but is slightly less efficient.

HSetAutoAdd()

Changes the AutoAdd attribute of a hash.

Syntax

HSetAutoAdd( <hHash>, <lOnOff> ) --> hHash

Arguments

<hHash>
A variable referencing the hash whose AutoAdd attribute is changed.
<lOnOff>
A logical value. .T. (true) enables automatic creation of key/value pairs, and .F. (false)
disables it.

12-07-2007 21
 HASH
Return

The function returns a reference to <hHash>.

12-07-2007 22
 HASH

Description

The function changes an attribute of a hash that identifies whether or not automatic creation of
key/value pairs is permitted in the context of inline assignments or the Hset() function.

By default, this attribute is .T. (true) when a new hash is created. This causes the assignment of a
value to a non-existent key to create a new key/value pair in the hash. This default behaviour can
be switched off to prevent automatic creation of new key/value pairs.

Use function HGetAutoAdd() to retrieve the current setting of this attribute.

HSetAutoAdd()

Changes the AutoAdd attribute of a hash.

Syntax

HSetAutoAdd( <hHash>, <lOnOff> ) --> hHash

Arguments

<hHash>
A variable referencing the hash whose AutoAdd attribute is changed.
<lOnOff>
A logical value. .T. (true) enables automatic creation of key/value pairs, and .F. (false)
disables it.

Return

The function returns a reference to <hHash>.

Description

The function changes an attribute of a hash that identifies whether or not automatic creation of
key/value pairs is permitted in the context of inline assignments or the Hset() function.

By default, this attribute is .T. (true) when a new hash is created. This causes the assignment of a
value to a non-existent key to create a new key/value pair in the hash. This default behaviour can
be switched off to prevent automatic creation of new key/value pairs.

Use function HGetAutoAdd() to retrieve the current setting of this attribute.

12-07-2007 23
 HASH

12-07-2007 24
 HASH

HSetCaseMatch()

Changes the case sensitivity attribute of a hash.

Syntax

HSetCaseMatch( <hHash>, <lOnOff> ) --> hHash

Arguments

<hHash>
A variable referencing the hash whose case sensitivity attribute is changed.
<lOnOff>
A logical value. .T. (true) enables case sensitivity of a hash, and .F. (false) disables it.

Return

The function returns a reference to <hHash>.

Description

The function changes an attribute of a hash that identifies whether or not character string
matching for keys is case sensitive. By default, this attribute is .T. (true) when a new hash is
created. This causes keys consisting of character strings that differ only in case can be assigned
different values.

Use function HGetCaseMatch() to retrieve the current setting of this attribute.

HSetPartition()

Partitions a linear hash for improved performance.

Syntax

HSetPartition( <hHash>, <nPageSize>, [<nLevel>] ) --> NIL

Arguments

<hHash>
A variable referencing the hash who is partitioned.
<nPageSize>

12-07-2007 25
 HASH
A numeric value specifying the page size of one hash partition.
<nLevel>
A numeric value indicating how many levels deep the hash should be partitioned.

Return

The function returns always NIL.

12-07-2007 26
 HASH

Description

The function partitions a linear hash into <nPageSize> numbers of items. By partitioning a linear
hash, searching and inserting keys is improved. This is advantageous for hashes of more than
1000 key/value pairs. Smaller hashes do not need to be partitioned, unless they are accessed with
a high frequency.

The partitioning of a hash results in a hash of hashes. Keys of a hash are distributed equally in
sub-hashes so that searching or inserting a key becomes faster in a partitioned hash compared to a
linear hash.

Important: this function may only be called on empty hashes. Do not pass a populated hash to it.
To partition a filled hash,

HSetValueAt()

Changes the value in a hash by its ordinal position.

Syntax

HSetValueAt( <hHash>, <nPos>, <xValue> ) --> NIL

Arguments

<hHash>
A variable referencing the hash to change a value in.
<nPos>
A numeric value specifying the ordinal position of the value to change. It must be in the
range between 1 and Len(<hHash>).
<xValue>
<xValue> is the new value to assign at position <nPos> in hash <hHash>.

Return

The function returns always NIL.

Description

This function changes the value of the hash <hHash> at position <nPos>. If <nPos> is outside
the valid range, a runtime error

Len()

12-07-2007 27
 HASH
Returns the number of items contained in an array, hash or string

12-07-2007 28
 HASH

Syntax

Len( <aArray> | <cString> | <hHash> ) --> nCount

Arguments

<aArray>
An array whose number of elements is determined.
<cString>
A character string whose number of characters is determined.
<hHash>
A hash whose number of key/value pairs is determined.

Return

The function returns the number of items stored in the passed parameter as a numeric value.
When the passed parameter is empty (contains no items), the return value is zero.

Description

The function Len() accepts parameters of three different data types: Array, Character string and
Hash. It returns the number

12-07-2007 29