xmake-docs/docs/api/scripts/extension-modules/core/base/hashset.md

hashset

The hashset module provides a hash set data structure (a collection with no duplicate elements) for efficiently storing and querying unique values. This is an extension module of xmake.

::: tip TIP To use this module, you need to import it first: import("core.base.hashset") :::

hashset.new

• Create an empty hash set

Function Prototype

::: tip API

hashset.new()

:::

Parameter Description

No parameters required for this function.

Usage

Creates an empty hash set object.

local set = hashset.new()
print(set:size())   -- Output: 0
print(set:empty())  -- Output: true

hashset.of

• Create hash set from parameter list

Function Prototype

::: tip API

hashset.of(...)

:::

Parameter Description

Parameter	Description
...	Variable number of values to initialize the set

Usage

Creates a hash set from a parameter list, automatically removing duplicate elements.

This is a convenient way to create and initialize a set:

local set = hashset.of(1, 2, 3, 5, 5, 7, 1, 9, 4, 6, 8, 0)
print(set:size())  -- Output: 10 (duplicates 1 and 5 removed)

-- Verify elements
assert(set:has(1))
assert(set:has(5))
assert(not set:has(10))

hashset.from

• Create hash set from array

Function Prototype

::: tip API

hashset.from(array: <table>)

:::

Parameter Description

Parameter	Description
array	Required. Array to create the set from

Usage

Creates a hash set from an array, automatically removing duplicate elements.

Used for deduplicating arrays:

local array = {1, 2, 3, 2, 4, 3, 5}
local set = hashset.from(array)
print(set:size())  -- Output: 5

-- Convert back to array (deduplicated)
local unique_array = set:to_array()

hashset:insert

• Insert an element

Function Prototype

::: tip API

hashset:insert(value: <any>)

:::

Parameter Description

Parameter	Description
value	Required. Element to insert

Return Value

Type	Description
true	Element doesn't exist, insertion successful
false	Element already exists, not inserted

Usage

Inserts an element into the hash set. If the element already exists, it will not be inserted.

local set = hashset.new()

local result = set:insert(1)
print(result)  -- Output: true (insertion successful)

local result = set:insert(1)
print(result)  -- Output: false (element already exists)

print(set:size())  -- Output: 1

Supports inserting various types of values, including strings, numbers, tables, nil, etc.:

local set = hashset.new()
set:insert("hello")
set:insert(123)
set:insert({key = "value"})
set:insert(nil)  -- Can also insert nil value

hashset:remove

• Remove an element

Function Prototype

::: tip API

hashset:remove(value: <any>)

:::

Parameter Description

Parameter	Description
value	Required. Element to remove

Return Value

Type	Description
true	Element exists, removal successful
false	Element doesn't exist, not removed

Usage

Removes an element from the hash set.

local set = hashset.of(1, 2, 3)

local result = set:remove(2)
print(result)  -- Output: true (removal successful)
print(set:size())  -- Output: 2

local result = set:remove(10)
print(result)  -- Output: false (element doesn't exist)

hashset:has

• Check if element exists

Function Prototype

::: tip API

hashset:has(value: <any>)

:::

Parameter Description

Parameter	Description
value	Required. Element to check

Return Value

Type	Description
true	Element exists
false	Element doesn't exist

Usage

Checks if the specified element is in the hash set.

Used for fast element lookup (O(1) time complexity):

local set = hashset.of(1, 2, 3, 4, 5)

if set:has(3) then
    print("Set contains 3")
end

if not set:has(10) then
    print("Set doesn't contain 10")
end

hashset:size

• Get set size

Function Prototype

::: tip API

hashset:size()

:::

Parameter Description

No parameters required for this function.

Usage

Returns the number of elements in the hash set.

local set = hashset.of(1, 2, 3, 4, 5)
print(set:size())  -- Output: 5

set:insert(6)
print(set:size())  -- Output: 6

set:remove(1)
print(set:size())  -- Output: 5

hashset:empty

• Check if set is empty

Function Prototype

::: tip API

hashset:empty()

:::

Parameter Description

No parameters required for this function.

Usage

Returns true if the set is empty (contains no elements).

local set = hashset.new()
print(set:empty())  -- Output: true

set:insert(1)
print(set:empty())  -- Output: false

hashset:clear

• Clear the set

Function Prototype

::: tip API

hashset:clear()

:::

Parameter Description

No parameters required for this function.

Usage

Removes all elements from the set, resetting it to an empty set.

local set = hashset.of(1, 2, 3, 4, 5)
print(set:size())  -- Output: 5

set:clear()
print(set:size())  -- Output: 0
print(set:empty()) -- Output: true

hashset:clone

• Clone the set

Function Prototype

::: tip API

hashset:clone()

:::

Parameter Description

No parameters required for this function.

Usage

Creates a complete copy of the hash set, with the new set being independent of the original.

Used for saving snapshots of the set or creating copies:

local set1 = hashset.of(1, 2, 3)
local set2 = set1:clone()

-- Modifying the copy doesn't affect the original
set2:insert(4)
print(set1:size())  -- Output: 3
print(set2:size())  -- Output: 4

-- Compare sets for equality
set2:remove(4)
assert(set1 == set2)  -- Equal

hashset:to_array

• Convert to array

Function Prototype

::: tip API

hashset:to_array()

:::

Parameter Description

No parameters required for this function.

Usage

Converts the hash set to an array, returning a table containing all elements. nil values are ignored.

Commonly used for array deduplication:

local array = {1, 2, 3, 2, 4, 3, 5, 1}
local set = hashset.from(array)
local unique_array = set:to_array()
-- unique_array contains: {1, 2, 3, 4, 5} (order may vary)

print("Original array size:", #array)         -- 8
print("Deduplicated size:", #unique_array)    -- 5

hashset:items

• Iterate over set elements

Function Prototype

::: tip API

hashset:items()

:::

Parameter Description

No parameters required for this function.

Usage

Returns an iterator function for traversing all elements in the set (unordered).

local set = hashset.of("apple", "banana", "orange")

for item in set:items() do
    print(item)
end
-- Output order is indeterminate: might be apple, orange, banana

Used for checking all elements in the set:

local set = hashset.of(1, 2, 3, 4, 5)

-- Check all elements
for item in set:items() do
    assert(set:has(item))
end

-- Calculate sum
local sum = 0
for item in set:items() do
    sum = sum + item
end
print("Sum:", sum)  -- Output: 15

hashset:orderitems

• Iterate over set elements in order

Function Prototype

::: tip API

hashset:orderitems()

:::

Parameter Description

No parameters required for this function.

Usage

Returns an iterator function for traversing all elements in the set in ascending order.

Suitable for scenarios requiring ordered output:

local set = hashset.of(5, 2, 8, 1, 9, 3)

print("Unordered iteration:")
for item in set:items() do
    print(item)  -- Order is indeterminate
end

print("Ordered iteration:")
for item in set:orderitems() do
    print(item)  -- Output: 1, 2, 3, 5, 8, 9
end

Verify ordering:

local set = hashset.of(9, 1, 5, 3, 7, 2, 8, 4, 6, 0)

local prev = -1
for item in set:orderitems() do
    assert(item > prev)  -- Each element is greater than the previous
    prev = item
end

hashset also supports comparing two sets for equality using the == operator (containing the same elements):

local set1 = hashset.of(1, 2, 3)
local set2 = hashset.of(3, 2, 1)
local set3 = hashset.of(1, 2, 4)

assert(set1 == set2)        -- true (same elements, order irrelevant)
assert(not (set1 == set3))  -- false (different elements)

::: tip TIP hashset provides O(1) time complexity for insert, delete, and lookup operations, much more efficient than linear search using arrays. Suitable for scenarios requiring frequent element existence checks or deduplication. :::

::: warning WARNING

• Elements in hashset are unordered; order is indeterminate when iterating with items()
• Use orderitems() for ordered iteration
• hashset automatically removes duplicate elements
• nil values can be stored in hashset :::