API HashMap

HashMap

Key-value collection built for frequent keyed lookup.

Script API Reference

Overview

HashMap is a key-oriented collection. Primitive keys compare by value and object keys compare by identity. Reading a key that was never set returns null rather than raising an error.

Note

Key iteration order is not guaranteed. Do not rely on the order of keys or values between runs or after mutation.

Quick Reference

Member	Returns	Summary
new HashMap([capacity])	HashMap	Creates an empty map, optionally reserving capacity.
map.keys	array	Snapshot array of the current keys.
map.values	array	Snapshot array of the current values.
map.size	number	Current entry count.
map.has(key)	boolean	Reports whether a key exists.
map.set(key, value)	null	Adds or replaces the value for a key.
map.get(key)	any	Reads the value for a key.
map.getOrInsert(key, value)	any	Reads a value, inserting a default when the key is absent.
map.delete(key)	null	Removes a key.
map.clear()	null	Removes every entry.

Constructors

new HashMap([capacity])

Parameters

Name	Type	Required	Description
capacity	number	No	Initial capacity to reserve.

Returns

HashMap — an empty map.

Behavior

Capacity affects preallocation only. It creates no entries, so size still starts at 0.

Example

var cache = new HashMap(16);
return cache.size; // 0

Properties

map.keys

Returns

array — a new array containing the current keys.

Behavior

Each read builds a fresh snapshot array. Later mutations of the map are not reflected in an array you already captured.

Example

var map = new HashMap();
map.set("left", 1);
return map.keys[0]; // "left"

map.values

Returns

array — a new array containing the current values.

Behavior

Each read builds a fresh snapshot array, in the same order as keys.

Example

var map = new HashMap();
map.set("left", 1);
return map.values[0]; // 1

map.size

Returns

number — the current entry count.

Example

var map = new HashMap();
map.set("a", 1);
map.set("b", 2);
return map.size; // 2

Methods

map.has(key)

Parameters

Name	Type	Required	Description
key	any	Yes	Key to test.

Returns

boolean — whether the key exists.

Behavior

Use has rather than comparing get against null when null is a valid stored value.

Example

var map = new HashMap();
map.set("ready", true);
return map.has("ready"); // true

map.set(key, value)

Parameters

Name	Type	Required	Description
key	any	Yes	Lookup key.
value	any	Yes	Value to store.

Returns

null.

Behavior

Adds the entry, or replaces the value when the key is already present.

Example

var map = new HashMap();
map.set("theme", "dark");
return map.get("theme"); // "dark"

map.get(key)

Parameters

Name	Type	Required	Description
key	any	Yes	Key to read.

Returns

any — the stored value, or null when the key is absent.

Example

var map = new HashMap();
map.set("count", 3);
return map.get("count"); // 3

map.getOrInsert(key, value)

Parameters

Name	Type	Required	Description
key	any	Yes	Lookup key.
value	any	Yes	Value to insert when the key is absent, or a callback that receives the key and produces the value.

Returns

any — the existing value, or the newly inserted value.

Behavior

Passing a callback defers building the default until it is actually needed, which is useful when the default is expensive to produce.

Example

var cache = new HashMap();
var value = cache.getOrInsert("answer", () => 42);
return value; // 42

map.delete(key)

Parameters

Name	Type	Required	Description
key	any	Yes	Key to remove.

Returns

null.

Behavior

Removes the key and its value. Deleting a key that is not present is a no-op and does not create an entry.

Example

var map = new HashMap();
map.set("temporary", 1);
map.delete("temporary");
return map.has("temporary"); // false

map.clear()

Parameters

None.

Returns

null.

Behavior

Removes every entry and resets size to 0.

Example

var map = new HashMap();
map.set("a", 1);
map.clear();
return map.size; // 0