/*
 * $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.txt.  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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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$

   $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 returns the old flag value
   $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. )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$
   $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. )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$
   $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. )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$
   $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$

   $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$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$
      TODO: locate and list those methods that use this feature
   $END$
 */
