HASHMAP

You are here:

HASHMAP

HASHMAP is a structured data type that defines an associative array of unordered elements (buckets), indexed / referenced by keys. In that way, a HashMap pairs keys to values. A key can also be seen as the index / identifier of that element.

Dictionary is an alias of HASHMAP.

Keys: Unlike in JSON, a key can be of any 4GL primitive data type.

Bucket Value: Data are stored in the HashMap bucket, which can be of a primitive data type, structured, or a complex one. You can even nest HashMaps in the HashMap bucket.

Syntax

HASHMAP [OF data-type]

data-type can be a data type, a record definition, a user-defined type, a built-in class, an imported package class, or a Java class.

Defining HASHMAP

DEFINE ht HASHMAP -- is equal to HASHMAP OF VARIANT

DEFINE ht_string HASHMAP OF STRING

DEFINE ht_rec HASHMAP OF RECORD i INT, s STRING END RECORD

Methods

Note: Click the method name to see an example.

Method Name	Description
GetLength()	Returns the number of elements in a hash table.
GetKeys()	Returns a DYNAMIC ARRAY of all keys in the HashMap.
Delete(INT index)	Deletes an element with index. Returns TRUE If the operation is successfully performed, otherwise, it returns FALSE.
Delete(INT first, INT last)	Deletes all elements from the first to last. Returns TRUE If the operation is successfully performed, otherwise, it returns FALSE.
Remove(VARIANT key)	Removes an element with the "key" key. Returns TRUE If the operation is successfully performed, otherwise, it returns FALSE.
Insert(VARIANT key, VARIANT value)	Inserts an element with a defined key and value. It fails if the key already exists. Returns TRUE If the operation is successfully performed, otherwise, it returns FALSE.
Modify(VARIANT key, VARIANT value)	Inserts or updates an element with a defined key and value.
Clear()	Removes all elements from hash table. Returns TRUE If the operation is successfully performed, otherwise, it returns FALSE.
Join(HASHMAP ht)	Appends an element from “ht” hash table.
Find(VARIANT key)	Returns an element with the “key” key.
GetKey(INT index)	Returns a key of an element by index.
GetValue(INT index)	Returns a value of an element by index.
KeySort(INT direction)	Sorts HashMap by key. "direction" > or = 1 - performs the sorting in the ascending order; "direction" < 1 -performs the sorting in the descending order. "direction" is an optional parameter that is equal to 1 by default. Any further operation that modifies data (like Insert, Remove, etc.) will remove the current sorting.
ValueSort(INT direction)	Sorts HashMap by value. "direction" > or = 1 - performs the sorting in the ascending order; "direction" < 1 -performs the sorting in the descending order. "direction" is an optional parameter that is equal to 1 by default. Any further operation that modifies data (like Insert, Remove, etc.) will remove the current sorting.
CustomSort(STRING funcName)	Sorts HashMap using the defined function. This is a binary function that accepts two elements of the HashMap. Any further operation that modifies data (like Insert, Remove, etc.) will remove the current sorting.
ResetSorting()	Resets any sorting.
CopyTo(HASHMAP dst)	Copies all elements of the HashMap into another HashMap.
KeyExists(VARIANT key)	Returns TRUE if data with the defined key exists, otherwise, it returns FALSE.
ValueExists(VARIANT value)	Returns TRUE if data with the defined value exists, otherwise, it returns FALSE.

Element Keys

Elements are identified by a key in HashMap. Similar to a JSON object or an array index, a key allows access to the element it references. A key can be any type that can be converted to a string. Keys must be unique.

Keys are used in HashMap subscripts. The key value must be enclosed in square brackets:

DEFINE ht HASHMAP

LET ht["key1"] = "value1"

DISPLAY ht["key1"]

HashMap variable is passed to function only by reference and not by value. Thus, any changes in function will be applied to a variable from the calling function.

HashMap can be interacted with by INPUT ARRAY or DISPLAY ARRAY. In this case, HashMap is interpreted as:

DYNAMIC ARRAY OF RECORD

key VARIANT,

value <defined-data-type>

END RECORD

Built-in actions INSERT, DELETE, APPEND and UPDATE are prohibited in INPUT/DISPLAY ARRAY with a HashMap variable. But you can modify this variable by defining appropriate custom actions like in the code example below:

MAIN
  DEFINE hm HASHMAP

  LET hm["field1"] = "val1"
  LET hm["field3"] = "val3"
  LET hm[9] = "val9"

  CALL func(hm)
  
  DISPLAY "hm[10] = ", hm[10]
  CALL hm.remove(10)
  
  OPEN FORM f1 FROM "hashmap"
  DISPLAY FORM f1
  
  INPUT ARRAY hm WITHOUT DEFAULTS FROM inp.*  
    ON ACTION "modify"
      LET hm["field2"] = "val2"
    ON ACTION "delete"
      CALL hm.remove("field1")
  END INPUT
  
  DISPLAY ht
END MAIN

FUNCTION func(hm)
  DEFINE hm HASHMAP  
  DISPLAY "hm[9] = ", hm[9]  
  CALL hm.remove(9)
  LET hm[10] = "val10"
END FUNCTION

hashmap.fm2 form:

<?xml version="1.0" encoding="UTF-8"?>

<form.rootContainer>

</TableColumn>

</TableColumn>

</Table>

</CoordPanel>

</form.rootContainer>

<form.screenRecords>

</form.screenRecords>

</form>

Sorting HashMap:

DEFINE hashmap_value TYPE AS
    RECORD
      f1 INT,
      f2 STRING
    END RECORD


MAIN
  DEFINE hm HASHMAP OF hashmap_value
  
  LET hm["key_1"].f1 = 5
  LET hm["key_1"].f2 = "str1"
  LET hm["key_2"].f1 = 2
  LET hm["key_2"].f2 = "str2"
  LET hm["key_3"].f1 = 9
  LET hm["key_3"].f2 = "str3"
  
  DISPLAY "Sorting by key:"
  CALL DisplayHashmap(hm)
  
  DISPLAY "\nSorting by value Asc:"
  CALL hm.ValueSort(1)
  CALL DisplayHashmap(hm)
  
  DISPLAY "\nSorting by value Desc:"
  CALL hm.ValueSort(0)
  CALL DisplayHashmap(hm)

  DISPLAY "\nSorting Asc by 'f2' field using function CompareAsc:"
  CALL hm.CustomSort("CompareAsc")      
  CALL DisplayHashmap(hm)
  
  DISPLAY "\nSorting Asc by 'f2' field using function CompareDesc:"
  CALL hm.CustomSort("CompareDesc")      
  CALL DisplayHashmap(hm)
END MAIN

FUNCTION DisplayHashmap(hm)
  DEFINE hm HASHMAP
  DEFINE i INT
  FOR i = 1 TO hm.GetLength()
    DISPLAY "'", hm.GetKey(i), "' - '", hm.GetValue(i), "'"
  END FOR
END FUNCTION

FUNCTION CompareAsc(a, b)
  DEFINE a, b RECORD key REFERENCE, val dict_value END RECORD
  RETURN a.val.f2 < b.val.f2
END FUNCTION

FUNCTION CompareDesc(a, b)
  DEFINE a, b RECORD key REFERENCE, val dict_value END RECORD
  RETURN a.val.f2 >= b.val.f2
END FUNCTION