0f365f1a5d
* doc/en/command.txt
* doc/en/datetime.txt
* doc/en/dbdelim.txt
* doc/en/dbsdf.txt
* doc/en/dbstrux.txt
* doc/en/dir.txt
* doc/en/diskspac.txt
* doc/en/eval.txt
* doc/en/garbage.txt
* doc/en/gtslang.txt
* doc/en/hashes.txt
* doc/en/hb_api.txt
* doc/en/hb_apier.txt
* doc/en/hb_apigt.txt
* doc/en/hb_apiit.txt
* doc/en/hb_apiln.txt
* doc/en/hb_apird.txt
* doc/en/hb_compa.txt
* doc/en/hb_date.txt
* doc/en/hb_macro.txt
* doc/en/hb_set.txt
* doc/en/hb_vm.txt
* doc/en/idle.txt
* doc/en/input.txt
* doc/en/lang.txt
* doc/en/macro.txt
* doc/en/math.txt
* doc/en/memo.txt
* doc/en/memvar2.txt
* doc/en/misc.txt
* doc/en/string.txt
* doc/en/var.txt
* fixes
* doc/en/*.txt
* set mime-type to UTF-8
1191 lines
24 KiB
Plaintext
1191 lines
24 KiB
Plaintext
/*
|
|
* $Id$
|
|
*/
|
|
|
|
/*
|
|
* Harbour Project source code:
|
|
* Hash table type and functions
|
|
*
|
|
* Copyright 2009 April White <april@users.sourceforge.net>
|
|
* www - http://harbour-project.org
|
|
*
|
|
* Based on the content of hashfunc.c and hashes.c
|
|
* Copyright 2007 Przemyslaw Czerpak <druzus / at / priv.onet.pl>
|
|
*
|
|
* This program is free software; you can redistribute it and/or modify
|
|
* it under the terms of the GNU General Public License as published by
|
|
* the Free Software Foundation; either version 2, or (at your option)
|
|
* any later version.
|
|
*
|
|
* This program is distributed in the hope that it will be useful,
|
|
* but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
* GNU General Public License for more details.
|
|
*
|
|
* You should have received a copy of the GNU General Public License
|
|
* along with this software; see the file COPYING. If not, write to
|
|
* the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
|
|
* Boston, MA 02111-1307 USA (or visit the web site http://www.gnu.org/).
|
|
*
|
|
* As a special exception, the Harbour Project gives permission for
|
|
* additional uses of the text contained in its release of Harbour.
|
|
*
|
|
* The exception is that, if you link the Harbour libraries with other
|
|
* files to produce an executable, this does not by itself cause the
|
|
* resulting executable to be covered by the GNU General Public License.
|
|
* Your use of that executable is in no way restricted on account of
|
|
* linking the Harbour library code into it.
|
|
*
|
|
* This exception does not however invalidate any other reasons why
|
|
* the executable file might be covered by the GNU General Public License.
|
|
*
|
|
* This exception applies only to the code released by the Harbour
|
|
* Project under the name Harbour. If you copy code from other
|
|
* Harbour Project or Free Software Foundation releases into a copy of
|
|
* Harbour, as the General Public License permits, the exception does
|
|
* not apply to the code that you add in this way. To avoid misleading
|
|
* anyone as to the status of such modified files, you must delete
|
|
* this exception notice from them.
|
|
*
|
|
* If you write modifications of your own for Harbour, it is your choice
|
|
* whether to permit this exception to apply to your modifications.
|
|
* If you do not wish that, delete this exception notice.
|
|
*
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HASH()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Returns a hash table
|
|
* $SYNTAX$
|
|
* HB_HASH( [ <Key1>, <Value1> ], [ <KeyN>, <ValueN> ], ... ) -> hsTable
|
|
* $ARGUMENTS$
|
|
* <Key1> entry key;
|
|
* can be of type: number, date, datetime, string, pointer
|
|
*
|
|
* <Value1> entry value; can be of type: block, string, numeric, date/datetime, logical, nil, pointer, array, hash table
|
|
* $RETURNS$
|
|
* A hash table built from the initial key/value pairs
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HHASKEY()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Determines whether a hash table has an entry with a give key
|
|
* $SYNTAX$
|
|
* HB_HHASKEY( <hsTable>, <Key> ) -> lExists
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Key> a key value to be queried for;
|
|
* can be of type: number, date, datetime, string, pointer
|
|
* $RETURNS$
|
|
* A logical value indicating whether the key exists within the hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HPOS()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Locates the index of a key within a hash table
|
|
* $SYNTAX$
|
|
* HB_HPOS( <hsTable>, <Key> ) -> nPosition
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Key> key for which its position is to be determined;
|
|
* can be of type: number, date, datetime, string, pointer
|
|
* $RETURNS$
|
|
* A integer number being the index position of the key within the hash table.
|
|
*
|
|
* TODO: what is the return value if the key does not exist? zero (0)? RTE?
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HGET()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Returns a hash value
|
|
* $SYNTAX$
|
|
* HB_HGET( <hsTable>, <Key> ) -> <Value>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Key> key to be retrieve from the hash table;
|
|
* can be of type: number, date, datetime, string, pointer
|
|
* $RETURNS$
|
|
* Either the value within the hash table for the given key.
|
|
*
|
|
* An array access error occurs of the key is not found
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HGETDEF()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Returns a hash value, or a default value if the key is not present
|
|
* $SYNTAX$
|
|
* HB_HGETDEF( <hsTable>, <Key>, [<DefaultValue>] ) -> <Value>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Key> key to be retrieve from the hash table;
|
|
* can be of type: number, date, datetime, string, pointer
|
|
*
|
|
* <DefaultValue> a default value to be returned if the
|
|
* hash table does not contain the key
|
|
* $RETURNS$
|
|
* Either the value within the hash table for the given key,
|
|
* or the default value.
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HSET()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Sets a hash value
|
|
* $SYNTAX$
|
|
* HB_HSET( <hsTable>, <Key>, <Value> ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Key> the key of the entry to be set;
|
|
* can be of type: number, date, datetime, string, pointer
|
|
*
|
|
* <Value> the entry value
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HDEL()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Removes a key/value pair from a hash table
|
|
* $SYNTAX$
|
|
* HB_HDEL( <hsTable>, <Key> ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Key> key to be removed from the hash table;
|
|
* can be of type: number, date, datetime, string, pointer
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HKEYAT()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Gets a hash table key at a given position
|
|
* $SYNTAX$
|
|
* HB_HKEYAT( <hsTable>, <nPosition> ) -> <Key>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <nPosition> the position of an entry within the hash table that will
|
|
* be returned
|
|
* $RETURNS$
|
|
* The key at the given position of the hash table;
|
|
* the type will be one: number, date, datetime, string, pointer
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HVALUEAT()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Gets/sets a hash value at a given position
|
|
* $SYNTAX$
|
|
* HB_HVALUEAT( <hsTable>, <nPosition>, [<NewValue>] ) -> <Value>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <nPosition> the position of an entry within the hash table that will
|
|
* be returned
|
|
*
|
|
* <NewValue> a new value to be assigned to the hash table at the given
|
|
* position
|
|
* $RETURNS$
|
|
* The existing value, or the new value if it is given
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HPAIRAT()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Returns a two-dimensional array of a hash table entry key/value pair
|
|
* $SYNTAX$
|
|
* HB_HPAIRAT( <hsTable>, <nPosition> ) -> <aKeyValue>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <nPosition> the position of an entry within the hash table that will
|
|
* be returned
|
|
* $RETURNS$
|
|
* A two-dimensional array of the key/value pair entry of the hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HDELAT()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Removes an entry from a hash table based on its index position
|
|
* $SYNTAX$
|
|
* HB_HDELAT( <hsTable>, <nPosition> ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <nPosition> the position of an entry within the hash table that will
|
|
* be deleted
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HKEYS()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Returns an array of the keys of a hash table
|
|
* $SYNTAX$
|
|
* HB_HKEYS( <hsTable> ) -> <aKeys>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
* $RETURNS$
|
|
* An array of all the hash table keys
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HVALUES()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Returns an array of the values of a hash table
|
|
* $SYNTAX$
|
|
* HB_HVALUES( <hsTable> ) -> <aValues>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
* $RETURNS$
|
|
* An array of all the hash values
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HFILL()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Fills a hash table with a value
|
|
* $SYNTAX$
|
|
* HB_HFILL( <hsTable>, <Value> ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Value> fill value; can be of type: block, string, numeric, date/datetime, logical, nil, pointer, array, hash table
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HCLONE()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Creates a copy of a hash table
|
|
* $SYNTAX$
|
|
* HB_HCLONE( <hsTable> ) -> <hsDestination>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
* $RETURNS$
|
|
* A cloned copy of the hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HCOPY()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Adds entries from the source hash table to the destination hash table
|
|
* $SYNTAX$
|
|
* HB_HCOPY( <hsDestination>, <hsSource>, [<nStart>], [<nCount>] ) -> <hsDestination>
|
|
* $ARGUMENTS$
|
|
* <hsDestination> a destination hash table, created by HB_HASH()
|
|
*
|
|
* <hsSource> a source hash table, created by HB_HASH()
|
|
*
|
|
* <nStart> starting index, defaults to 1 if omitted
|
|
*
|
|
* <nCount> counter, defaults to (length) - <nStart> is omitted
|
|
* $RETURNS$
|
|
* The destination hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HMERGE()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Merges a source hash table into a destination hash table
|
|
* $SYNTAX$
|
|
* HB_HMERGE( <hsDestination>, <hsSource>, <bBlock>|<nPosition> ) -> <hsDestination>
|
|
* $ARGUMENTS$
|
|
* <hsDestination> a destination hash table, created by HB_HASH()
|
|
*
|
|
* <hsSource> a source hash table, created by HB_HASH()
|
|
*
|
|
* <bBlock> a code block that will be evaluated for each entry within the
|
|
* source hash table; the code block will be passed the entry key, value and
|
|
* position; if the code block returns a true value, the entry will be added to
|
|
* the destination hash table
|
|
*
|
|
* <nPosition> the position of an entry within the source hash table that will
|
|
* be appended to the destination hash table
|
|
*
|
|
* TODO: the source code passes either a number or HB_HASH_UNION; research this
|
|
* $RETURNS$
|
|
* The destination hash table with the contents of the source hash table merged
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HEVAL()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Evaluate a code block across the contents of a hash table
|
|
* $SYNTAX$
|
|
* HB_HEVAL( <hsTable>, <bBlock>, [<nStart>], [<nCount>] ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <bBlock> code block to be evaluated
|
|
*
|
|
* <nStart> starting index, defaults to 1 if omitted
|
|
*
|
|
* <nCount> counter, defaults to (length) - <nStart> is omitted
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
* The code block is evaluated for every hash table entry starting at
|
|
* <nStart> for <nCount> items.
|
|
*
|
|
* The code block is passed the entry key, value, and numeric position
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HSCAN()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Scans a hash table
|
|
* $SYNTAX$
|
|
* HB_HSCAN( <hsTable>, <Value>, [<nStart>], [<nCount>, [<lExact>] ) -> nPosition
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <Value> to be located within the hash table
|
|
*
|
|
* <nStart> starting index, defaults to 1 if omitted
|
|
*
|
|
* <nCount> counter, defaults to (length) - <nStart> is omitted
|
|
*
|
|
* <lExact> logical valuye indicating whether the comparision
|
|
* is to be be exact or not
|
|
* $RETURNS$
|
|
* The position of the located value within the hash table, or zero (0) if not found.
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HSORT()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Reorganizes the internal list of the hash table to be sorted
|
|
* $SYNTAX$
|
|
* HB_HSORT( <hsTable> ) -> <hsSortedTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
* $RETURNS$
|
|
* The hash table sorted
|
|
*
|
|
* TODO: is the original table altered?
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HCASEMATCH()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Sets the 'case match' flag for the hash table
|
|
* $SYNTAX$
|
|
* HB_HCASEMATCH( <hsTable>, [<lFlag>] ) -> <lPreviousFlag>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <lFlag> a logical value indicating to turn on or off
|
|
* the 'case match' flag of the hash table
|
|
* $RETURNS$
|
|
* The previous value of the 'case match' flag
|
|
* $DESCRIPTION$
|
|
* This function is equivalent to HB_HSETCASEMATCH() but it returns
|
|
* the old flag value rather than the hash table
|
|
* $EXAMPLES$
|
|
* LOCAL hsTable, lFlag
|
|
* hsTable := { "one" => 1, "two" => 2 }
|
|
* // turn 'case match' on for a new hash table, storing ol flag
|
|
* lFlag := hb_HCaseMatch( hsTable, .T. )
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
* HB_HSETCASEMATCH()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HBINARY()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Sets the 'binary' flag for the hash table
|
|
* $SYNTAX$
|
|
* HB_HBINARY( <hsTable>, [<lFlag>] ) -> <lPreviousFlag>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <lFlag> a logical value indicating to turn on or off
|
|
* the 'binary' flag of the hash table
|
|
* $RETURNS$
|
|
* The previous value of the 'binary' flag
|
|
* $DESCRIPTION$
|
|
* This function is equivalent to HB_HBINARY() but it returns
|
|
* the old flag value rather than the hash table
|
|
* $EXAMPLES$
|
|
* LOCAL hsTable, lFlag
|
|
* hsTable := { "one" => 1, "two" => 2 }
|
|
* // turn 'binary' on for a new hash table, storing ol flag
|
|
* lFlag := hb_HBinary( hsTable, .T. )
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
* HB_HSETBINARY()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HAUTOADD()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Sets the 'auto add' flag for the hash table
|
|
* $SYNTAX$
|
|
* HB_HAUTOADD( <hsTable>, [<lFlag>] ) -> <lPreviousFlag>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <lFlag> a logical value indicating to turn on or off
|
|
* the 'auto add' flag of the hash table
|
|
* $RETURNS$
|
|
* The previous value of the 'auto add' flag
|
|
* $DESCRIPTION$
|
|
* This function is equivalent to HB_HAUTOADD() but it returns
|
|
* the old flag value rather than the hash table
|
|
* $EXAMPLES$
|
|
* LOCAL hsTable, lFlag
|
|
* hsTable := { "one" => 1, "two" => 2 }
|
|
* // turn 'auto add' on for a new hash table, storing ol flag
|
|
* lFlag := hb_HAutoAdd( hsTable, .T. )
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
* HB_HSETAUTOADD()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Procedure
|
|
* $NAME$
|
|
* HB_HALLOCATE()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Preallocates a hash table
|
|
* $SYNTAX$
|
|
* HB_HALLOCATE( <hsTable>, <nItems> )
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <nItems> number of items to preallocate in the hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
*
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HDEFAULT()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Returns/sets a default value for a hash table.
|
|
* $SYNTAX$
|
|
* HB_HDEFAULT( <hsTable>, <DefaultValue> ) -> <OldDefaultValye>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <DefaultValue>
|
|
* $RETURNS$
|
|
* The previous default value assigned to the hash table
|
|
* $DESCRIPTION$
|
|
*
|
|
* $EXAMPLES$
|
|
*
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
* TODO: locate and list those methods that use this feature
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HSETAUTOADD()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Sets the 'auto add' flag for the hash table
|
|
* $SYNTAX$
|
|
* HB_HSETAUTOADD( <hsTable>, [<lFlag>] ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <lFlag> a logical value indicating to turn on or off
|
|
* the 'auto add' flag of the hash table
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
* This function is equivalent to HB_HAUTOADD() but it returns
|
|
* the passed hash table rather than the old flag value
|
|
* $EXAMPLES$
|
|
* LOCAL hsTable
|
|
* // turn 'auto add' on for a new hash table
|
|
* hsTable := hb_HSetAutoAdd( { "one" => 1, "two" => 2 }, .T. )
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
* HB_HAUTOADD(),HB_HSETBINARY(),HB_HSETCASEMATCH()
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HSETCASEMATCH()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Sets the 'case match' flag for the hash table
|
|
* $SYNTAX$
|
|
* HB_HSETCASEMATCH( <hsTable>, [<lFlag>] ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <lFlag> a logical value indicating to turn on or off
|
|
* the 'case match' flag of the hash table
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
* This function is equivalent to HB_HCASEMATCH() but it returns
|
|
* the passed hash table rather than the old flag value
|
|
* $EXAMPLES$
|
|
* LOCAL hsTable
|
|
* // turn 'case match' on for a new hash table
|
|
* hsTable := hb_HSetCaseMatch( { "one" => 1, "two" => 2 }, .T. )
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
* HB_HCASEMATCH(),HB_HSETAUTOADD(),HB_HSETBINARY
|
|
* $END$
|
|
*/
|
|
|
|
/* $DOC$
|
|
* $TEMPLATE$
|
|
* Function
|
|
* $NAME$
|
|
* HB_HSETBINARY()
|
|
* $CATEGORY$
|
|
* API
|
|
* $SUBCATEGORY$
|
|
* Hash table
|
|
* $ONELINER$
|
|
* Sets the 'binary' flag for the hash table
|
|
* $SYNTAX$
|
|
* HB_HSETBINARY( <hsTable>, [<lFlag>] ) -> <hsTable>
|
|
* $ARGUMENTS$
|
|
* <hsTable> a hash table, created by HB_HASH()
|
|
*
|
|
* <lFlag> a logical value indicating to turn on or off
|
|
* the 'binary' flag of the hash table
|
|
* $RETURNS$
|
|
* The hash table
|
|
* $DESCRIPTION$
|
|
* This function is equivalent to HB_HBINARY() but it returns
|
|
* the passed hash table rather than the old flag value
|
|
* $EXAMPLES$
|
|
* LOCAL hsTable
|
|
* // turn 'binary' on for a new hash table
|
|
* hsTable := hb_HSetBinary( { "one" => 1, "two" => 2 }, .T. )
|
|
* $TESTS$
|
|
*
|
|
* $STATUS$
|
|
* R
|
|
* $COMPLIANCE$
|
|
* H
|
|
* $PLATFORMS$
|
|
*
|
|
* $FILES$
|
|
*
|
|
* $SEEALSO$
|
|
* HB_HBINARY(),HB_HSETAUTOADD(),HB_HSETCASEMATCH
|
|
* $END$
|
|
*/
|