HashMap

UpdatedOct 1, 2026

HashMap<K, V>

import { HashMap } from "@alloy/std/collections"

local prices = $map[["sword", 10], ["pet", 25]]
local m: HashMap<string, number> = new HashMap()
m:set("gem", 5)
for key, value in m:entries() do end

A map with methods, from the std. Any value that is not nil is a key. new HashMap() is empty, HashMap.from(t) copies a table's pairs, and $map[[k, v], ...] is the literal. for key, value in m walks the pairs.

Statics

HashMap.new

HashMap.new<K, V>(t: { [K]: V }?): HashMap<K, V>

An empty map, or with t the map HashMap.from(t) gives. The annotation on the binding fixes K and V, since an empty map infers neither.

import { HashMap } from "@alloy/std/collections"

local prices: HashMap<string, number> = new HashMap()
prices:set("sword", 10)

HashMap.from

HashMap.from<K, V>(t: { [K]: V }): HashMap<K, V>

A new map with the pairs of a plain table. The table itself is left alone.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ sword = 10, pet = 25 })
print(prices:len())

Methods

HashMap:get

HashMap:get(key: K): V?

The value under key, or nil when the map has no such key. The result is optional, so guard it or end the chain with ??.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ sword = 10 })
local price = prices:get("sword") ?? 0
print(price)

HashMap:set

HashMap:set(key: K, value: V): HashMap<K, V>

Stores value under key and returns the map, so calls chain. A set to nil removes the key and drops the count, so len stays true.

import { HashMap } from "@alloy/std/collections"

local prices: HashMap<string, number> = new HashMap()
prices:set("gem", 5):set("sword", 10)
print(prices:len())

HashMap:has

HashMap:has(key: K): boolean

Whether the map holds key. A key whose value is nil is not held.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5 })
if prices:has("gem") then
    print("in stock")
end

HashMap:remove

HashMap:remove(key: K): V?

Removes key and returns the value it held, or nil when there was none.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5 })
local old = prices:remove("gem")
print(old)

HashMap:len

HashMap:len(): number

The number of keys. The map counts as keys come and go, so this costs the same at any size.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5, sword = 10 })
print(prices:len())

HashMap:keys

HashMap:keys(): K[]

The keys as an array, in no set order. The array carries the Array methods.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5 })
print(prices:keys():join(", "))

HashMap:values

HashMap:values(): V[]

The values as an array, in the order keys gives.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5 })
print(prices:values():len())

HashMap:entries

HashMap:entries(): () -> (K?, V)

An iterator over the pairs, for a for loop. The order is the table's own. for key, value in map walks the same pairs.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5 })
for key, value in prices:entries() do
    print(key, value)
end

HashMap:get_or_insert

HashMap:get_or_insert(key: K, default: V): V

The value under key. When there is none the map stores default first, so the result is never nil.

import { HashMap } from "@alloy/std/collections"

local counts: HashMap<string, number> = new HashMap()
local n = counts:get_or_insert("hits", 0)
print(n)

HashMap:clear

HashMap:clear()

Removes every key and sets the count to zero. The map itself stays, so every reference to it sees the empty map.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5 })
prices:clear()

HashMap:to_table

HashMap:to_table(): { [K]: V }

The map's own table, not a copy: a write through it changes the map. Such a write skips the count, so use set when len must stay true.

import { HashMap } from "@alloy/std/collections"

local prices = HashMap.from({ gem = 5 })
local t = prices:to_table()
print(t.gem)