The built-in functions in the HashMap package allow you to manipulate the HashMap ( hash map ) data type. A HashMap is a map for associating arbitrary key/value pairs. A HashMap differs from a Record in that the keys are less expensive to add and remove, the keys can be data types other than Strings, and the keys are sorted by key comparison rather than by some fixed order. Unlike an Assoc, HashMap keys are treated as case sensitive.

Each HashMap has an "undefined value" that is returned when a nonexistent key is referenced. This "undefined value" is usually Undefined by default, but any other value may be used.

A HashMap is formally created with HashMap.CreateHashMap(), however OScript has a convenience feature in that this is automatically invoked when a HashMap is declared so that it can be used right away. This does not happen with a Record since, while HashMap is meant to be a tool for relating data in an OScript program, Record is meant to be a tool for accessing database table data.

Class Attributes

FIFO

Constant flag used in ToAssoc() to indicate that the first value is to be used in the case where the HashMap contains multiple keys differing only in case.

HashMapType

The constant type identifier for the HashMap data type.

LIFO

Constant flag used in ToAssoc() to indicate that the last value is to be used in the case where the HashMap contains multiple keys differing only in case.

Class Methods

Copy( HashMap src )

Allocates a new Bytes of the given size.

CreateHashMap( Dynamic value )

Returns a new HashMap.

Delete( HashMap a, HashMap key )

Removes a key/value pair from a HashMap.

FromRecord( Record rec )

Converts a Record to a HashMap.

IsKey( HashMap a, Dynamic key )

Returns true if the HashMap contains key.

Items( HashMap a )

Returns a List of all the values in a HashMap.

Keys( HashMap a )

Returns a List of all the keys in a HashMap

Merge( HashMap hashmap1, HashMap hashmap2 )

Merges hashmap2 into hashmap1.

ToAssoc( HashMap a, Boolean flag )

Converts a HashMap into an Assoc.

ToRecord( HashMap a )

Converts a HashMap into a Record.

UndefinedValue( HashMap a )

Returns and optionally sets the "undefined value" of a HashMap.

Class Attributes

Boolean FIFO

Constant flag used in ToAssoc() to indicate that the first value is to be used in the case where the HashMap contains multiple keys differing only in case.

Integer HashMapType

The type number for the HashMap data type.

Boolean LIFO

Constant flag used in ToAssoc() to indicate that the last value is to be used in the case where the HashMap contains multiple keys differing only in case.

Class Methods

Copy

HashMap Copy( HashMap src )

Creates and returns a shallow copy of the specified source HashMap. This is necessary since HashMaps are passed by reference, meaning that simple assignment does not copy a HashMap as it does with an Integer. The copying process follows the same conventions used in function parameter passing. Thus the contents of the copy will contain copies of those values in the source which are passed by value, and and references to those values in the source which are passed by reference.

Parameters

src

The HashMap to copy.

Returns:

The new HashMap copy.

Example

The following example illustrates this:

HashMap a, b, b2, c
Dynamic key
c.ok = TRUE
a.( 2006 ) = c
a.count = 1
b = HashMap.copy( a )   // copy
b2 = b          // assignment does not copy
b2.a = "a"      // modify the reference
b.alert = "Stop!"   // modify the copy itself
b.count += 1        // modify copy value
b.( 2006 ).ok = FALSE   // modify copy reference.
for key in HashMap.keys( b )
    Echo( "a.", key, " = ", a.( key ) )
    Echo( "b.", key, " = ", b.( key ) )
end

a.a = ?
b.a = a             // b2 mod referenced b
a.alert = ?
b.alert = Stop!         // copy mod local
a.count = 1
b.count = 2         // value mod local
a.2006 = A<1,?,'ok'=false>
b.2006 = A<1,?,'ok'=false>  // reference mod not local

CreateHashMap

HashMap CreateHashMap( Dynamic value )

Returns a new, empty HashMap whose "undefined value" will be Undefined or value if value is specified. The "undefined value" is the value returned by a HashMap when referenced by a key it does not contain.

Parameters

value

The "undefined value" of the returned HashMap, which will be Undefined if this argument is not specified.

Returns:

A new, empty HashMap.

Delete

Dynamic Delete( HashMap a,
HashMap key )

Removes the specified key from the HashMap if that HashMap contains the key.

Parameters

The HashMap to remove a key/value pair from.

key

The key for the key/value pair to remove.

Returns:

The value removed, or the "undefined value" if the key was not found.

FromRecord

HashMap FromRecord( Record rec )

Creates and returns a new HashMap containing the field names and corresponding columns of the specified Record as its String keys and associated values. As with HashMap.Copy(), the new HashMap returned will be a shallow copy of the Record.

Parameters

rec

The Record from which a HashMap will be created.

Returns:

A new HashMap, copied from the Record.

IsKey

IsKey( HashMap a,
Dynamic key )

Returns true if the specified HashMap contains the specified key.

Parameters

The HashMap whose key set is tested.

key

The key to test.

Returns:

Items

List Items( HashMap a )

Returns a List of the keyed values in a.

Parameters

The HashMap whose values are returned in a List.

Returns:

A List of the keyed values in the HashMap.

Keys

List Keys( HashMap a )

Returns a List of the keys in a.

Parameters

The HashMap whose keys are returned in a List.

Returns:

A List of keys in the HashMap.

Merge

Merge( HashMap hashmap1,
HashMap hashmap2 )

The two HashMaps are merged by copying the contents of hashmap2 into hashmap1. The copy process is the same as used for HashMap.Copy().

Parameters

hashmap1

Destination HashMap for merge.

hashmap2

HashMap whose contents are copied into hashmap1.

Returns:

Example

If a key is common to both HashMaps, then the associated value in hashmap1 will be replaced by that in hashmap2, as shown by the following example:

HashMap     a, b, c
Dynamic     key
a.value = "a"
a.count = 1
b.value = "b"
b.ok = FALSE
c = HashMap.Merge( a, b )
for key in HashMap.Keys( a )
    Echo( "a.", key, " = ", a.( key ) )
end

a.count = 1 // only in a before merge
a.ok = false    // only in b before merge
a.value = b // in both before merge, b superceded.

ToAssoc

Assoc ToAssoc( HashMap a,
Boolean flag )

Creates a new Assoc and returns it after copying the values of the given HashMap into it.

Parameters

The HashMap to convert into a new Assoc.

flag

Flag to determine how multiple HashMap key, differing only in case, is mapped to the Assoc. If this parameter does not exists then the default value, HashMap.LIFO, is used indicating that the last value is used. The other option is HashMap.FIFO indicating that the first value is used.

Returns:

A new Assoc copied from the HashMap.

ToRecord

Record ToRecord( HashMap a )

Creates a new Record and returns it after copying the values of the given HashMap into it, translating String keys and values into field names and column entries. The HashMap should only contain String keys. As with HashMap.Copy(), the new HashMap returned will be a shallow copy of the Record.

Parameters

The HashMap to convert into a new Record.

Returns:

A new Record copied from the HashMap.

UndefinedValue

Dynamic UndefinedValue( HashMap a )

Returns the "undefined value" for the specified HashMap. If value is specified than the "undefined value" for the HashMap will be changed to value (meaning value will be returned).

Parameters

The HashMap whose "undefined value" is queried and optionally set.

Returns:

The "undefined value" for the HashMap.