/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_Hash()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Returns a hash table
   $SYNTAX$
      hb_Hash( [ <Key1>, <Value1> ], [ <KeyN>, <ValueN> ], ... ) -> hTable
   $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

      Equivalent to:
      ```
      hTable := { => }
      hTable := { <Key1> => <Value1>, <Key2> => <Value2>, <KeyN> => <ValueN> }
      ```
   $RETURNS$
      A hash table built from the initial key/value pairs
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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( <hTable>, <Key> ) -> lExists
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HPos()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Locates the index of a key within a hash table
   $SYNTAX$
      hb_HPos( <hTable>, <Key> ) -> nPosition
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HGet()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Returns a hash value
   $SYNTAX$
      hb_HGet( <hTable>, <Key> ) -> <Value>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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( <hTable>, <Key>, [<DefaultValue>] ) -> <Value>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HSet()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Sets a hash value
   $SYNTAX$
      hb_HSet( <hTable>, <Key>, <Value> ) -> <hTable>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HDel()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Removes a key/value pair from a hash table
   $SYNTAX$
      hb_HDel( <hTable>, <Key> ) -> <hTable>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HKeyAt()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Gets a hash table key at a given position
   $SYNTAX$
      hb_HKeyAt( <hTable>, <nPosition> ) -> <Key>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HValueAt()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Gets/sets a hash value at a given position
   $SYNTAX$
      hb_HValueAt( <hTable>, <nPosition>, [<NewValue>] ) -> <Value>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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( <hTable>, <nPosition> ) -> <aKeyValue>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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( <hTable>, <nPosition> ) -> <hTable>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HKeys()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Returns an array of the keys of a hash table
   $SYNTAX$
      hb_HKeys( <hTable> ) -> <aKeys>
   $ARGUMENTS$
      <hTable> a hash table
   $RETURNS$
      An array of all the hash table keys
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HValues()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Returns an array of the values of a hash table
   $SYNTAX$
      hb_HValues( <hTable> ) -> <aValues>
   $ARGUMENTS$
      <hTable> a hash table
   $RETURNS$
      An array of all the hash values
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HFill()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Fills a hash table with a value
   $SYNTAX$
      hb_HFill( <hTable>, <Value> ) -> <hTable>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HClone()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Creates a copy of a hash table
   $SYNTAX$
      hb_HClone( <hTable> ) -> <hsDestination>
   $ARGUMENTS$
      <hTable> a hash table
   $RETURNS$
      A cloned copy of the hash table
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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

      <hsSource> a source hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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

      <hsSource> a source hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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( <hTable>, <bBlock>, [<nStart>], [<nCount>] ) -> <hTable>
   $ARGUMENTS$
      <hTable> a hash table

      <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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HScan()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Scans a hash table
   $SYNTAX$
      hb_HScan( <hTable>, <Value>, [<nStart>], [<nCount>, [<lExact>] ) -> nPosition
   $ARGUMENTS$
      <hTable> a hash table

      <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 value indicating whether the comparison
      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$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $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( <hTable> ) -> <hsSortedTable>
   $ARGUMENTS$
      <hTable> a hash table
   $RETURNS$
      The hash table sorted

      TODO: is the original table altered?
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HCaseMatch()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Sets the 'case match' flag for the hash table
   $SYNTAX$
      hb_HCaseMatch( <hTable>, [<lFlag>] ) -> <lPreviousFlag>
   $ARGUMENTS$
      <hTable> a hash table

      <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 old flag
      lFlag := hb_HCaseMatch( hsTable, .T. )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HBinary()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Sets the 'binary' flag for the hash table
   $SYNTAX$
      hb_HBinary( <hTable>, [<lFlag>] ) -> <lPreviousFlag>
   $ARGUMENTS$
      <hTable> a hash table

      <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 old flag
      lFlag := hb_HBinary( hsTable, .T. )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HAutoAdd()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Sets the 'auto add' flag for the hash table
   $SYNTAX$
      hb_HAutoAdd( <hTable>, [<lFlag>] ) -> <lPreviousFlag>
   $ARGUMENTS$
      <hTable> a hash table

      <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 old flag
      lFlag := hb_HAutoAdd( hsTable, .T. )
   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$
   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Procedure
   $NAME$
      hb_HAllocate()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Preallocates a hash table
   $SYNTAX$
      hb_HAllocate( <hTable>, <nItems> )
   $ARGUMENTS$
      <hTable> a hash table

      <nItems> number of items to preallocate in the hash table
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$

   $END$
 */

/* $DOC$
   $AUTHOR$
      Copyright 2009 April White <bright.tigra gmail.com>
   $TEMPLATE$
      Function
   $NAME$
      hb_HDefault()
   $CATEGORY$
      API
   $SUBCATEGORY$
      Hash table
   $ONELINER$
      Returns/sets a default value for a hash table.
   $SYNTAX$
      hb_HDefault( <hTable>, <DefaultValue> ) -> <OldDefaultValue>
   $ARGUMENTS$
      <hTable> a hash table

      <DefaultValue>
   $RETURNS$
      The previous default value assigned to the hash table
   $DESCRIPTION$

   $EXAMPLES$

   $STATUS$
      R
   $COMPLIANCE$
      H
   $PLATFORMS$

   $FILES$

   $SEEALSO$

   $END$
 */