evolved.is_pair/is_wildcard functions

2025-12-13 11:38:15 +07:00 · 2025-08-19 02:50:12 +07:00
parent 9e74ddf9c3
commit dcc5190466
3 changed files with 184 additions and 148 deletions
--- a/README.md
+++ b/README.md
@@ -54,6 +54,7 @@
  - [Aliases](#aliases)
  - [Predefs](#predefs)
  - [Functions](#functions)
+  - [Relations](#relations)
  - [Classes](#classes)
    - [Chunk](#chunk)
    - [Builder](#builder)
@@ -1107,9 +1108,6 @@ name :: id... -> string...
 pack :: integer, integer, integer? -> id
 unpack :: id -> integer, integer, integer

-pair :: id, id -> id
-unpair :: id -> id, id
-
 defer :: boolean
 commit :: boolean

@@ -1143,6 +1141,20 @@ batch_destroy :: query... -> ()
 each :: entity -> {each_state? -> fragment?, component?}, each_state?
 execute :: query -> {execute_state? -> chunk?, entity[]?, integer?}, execute_state?

+process :: system... -> ()
+
+debug_mode :: boolean -> ()
+collect_garbage :: ()
+```
+
+### Relations
+
+pair :: id, id -> id
+unpair :: id -> id, id
+
+is_pair :: id -> boolean
+is_wildcard :: id -> boolean
+
 primary :: entity, fragment, integer? -> fragment?, component?
 secondary :: entity, fragment, integer? -> fragment?, component?

@@ -1152,12 +1164,6 @@ secondaries :: entity, fragment -> {secondaries_state? -> fragment?, component?}
 primary_count :: entity, fragment -> integer
 secondary_count :: entity, fragment -> integer

-process :: system... -> ()
-
-debug_mode :: boolean -> ()
-collect_garbage :: ()
-```
-
 ### Classes

 #### Chunk
@@ -1297,7 +1303,7 @@ builder_mt:destruction_policy :: id -> builder

 ### `evolved.DESTRUCTION_POLICY_REMOVE_FRAGMENT`

-## Functions
+## Core Functions

 ### `evolved.id`

@@ -1339,26 +1345,6 @@ function evolved.pack(primary, secondary, options) end
 function evolved.unpack(id) end
 ```

-### `evolved.pair`
-
-```lua
---@param primary evolved.id
---@param secondary evolved.id
---@return evolved.id pair
---@nodiscard
-function evolved.pair(primary, secondary) end
-```
-
-### `evolved.unpair`
-
-```lua
---@param pair evolved.id
---@return evolved.id primary
---@return evolved.id secondary
---@nodiscard
-function evolved.unpair(pair) end
-```
-
 ### `evolved.defer`

 ```lua
@@ -1586,7 +1572,45 @@ function evolved.debug_mode(yesno) end
 function evolved.collect_garbage() end
 ```

-## Relations
+## Relation Functions
+
+### `evolved.pair`
+
+```lua
+---@param primary evolved.id
+---@param secondary evolved.id
+---@return evolved.id pair
+---@nodiscard
+function evolved.pair(primary, secondary) end
+```
+
+### `evolved.unpair`
+
+```lua
+---@param pair evolved.id
+---@return evolved.id primary
+---@return evolved.id secondary
+---@nodiscard
+function evolved.unpair(pair) end
+```
+
+### `evolved.is_pair`
+
+```lua
+---@param id evolved.id
+---@return boolean
+---@nodiscard
+function evolved.is_pair(id) end
+```
+
+### `evolved.is_wildcard`
+
+```lua
+---@param id evolved.id
+---@return boolean
+---@nodiscard
+function evolved.is_wildcard(id) end
+```

 ### `evolved.primary`

--- a/develop/testing/pairs_tests.lua
+++ b/develop/testing/pairs_tests.lua
@@ -1441,6 +1441,3 @@ do
        assert(evo.has(e, evo.pair(p, s)) and evo.get(e, evo.pair(p, s)) == nil)
    end
 end
-
-- TODO:
-- add is_pair/is_wildcard
--- a/evolved.lua
+++ b/evolved.lua
@@ -876,9 +876,6 @@ local __evolved_name
 local __evolved_pack
 local __evolved_unpack

-local __evolved_pair
-local __evolved_unpair
-
 local __evolved_defer
 local __evolved_commit

@@ -917,6 +914,12 @@ local __evolved_process
 local __evolved_debug_mode
 local __evolved_collect_garbage

+local __evolved_pair
+local __evolved_unpair
+
+local __evolved_is_pair
+local __evolved_is_wildcard
+
 local __evolved_primary
 local __evolved_secondary

@@ -937,9 +940,6 @@ local __evolved_builder

 local __id_name

-local __is_pair
-local __is_wildcard
-
 local __primary_wildcard
 local __secondary_wildcard

@@ -949,7 +949,7 @@ local __component_storage
 ---@return string
 ---@nodiscard
 function __id_name(id)
-    if not __is_pair(id) then
+    if not __evolved_is_pair(id) then
        ---@type string?
        local id_name = __evolved_get(id, __NAME)

@@ -981,20 +981,6 @@ function __id_name(id)
    return __lua_string_format('$%d#%d:%d:%d', id, id_primary, id_secondary, id_options)
 end

---@param id evolved.id
---@return boolean
---@nodiscard
-function __is_pair(id)
-    return id % 2 ^ 41 >= 2 ^ 40
-end
-
---@param id evolved.id
---@return boolean
---@nodiscard
-function __is_wildcard(id)
-    return id % 2 ^ 43 >= 2 ^ 41
-end
-
 ---@param secondary evolved.id | integer id or index
 ---@return evolved.id pair (*, secondary)
 ---@nodiscard
@@ -1247,7 +1233,7 @@ local __update_major_chunks_trace
 ---@return evolved.chunk
 ---@nodiscard
 function __new_chunk(chunk_parent, chunk_fragment)
-    if __is_wildcard(chunk_fragment) then
+    if __evolved_is_wildcard(chunk_fragment) then
        __error_fmt('chunk cannot contain wildcard fragments')
    end

@@ -1297,7 +1283,7 @@ function __new_chunk(chunk_parent, chunk_fragment)
        chunk_fragment_list[chunk_fragment_count] = chunk_fragment
    end

-    if __is_pair(chunk_fragment) then
+    if __evolved_is_pair(chunk_fragment) then
        chunk_pair_count = chunk_pair_count + 1
        chunk_pair_list[chunk_pair_count] = chunk_fragment

@@ -1406,7 +1392,7 @@ function __new_chunk(chunk_parent, chunk_fragment)
        __assoc_list_insert(minor_chunks, chunk)
    end

-    if __is_pair(chunk_fragment) then
+    if __evolved_is_pair(chunk_fragment) then
        local major = chunk_fragment
        local major_primary_index, major_secondary_index =
            __evolved_unpack(major)
@@ -1577,7 +1563,7 @@ function __update_chunk_flags(chunk)
    local has_remove_hooks = (chunk_parent ~= nil and chunk_parent.__has_remove_hooks)
        or __evolved_has(chunk_fragment, __ON_REMOVE)

-    local has_pair_major = __is_pair(chunk_fragment)
+    local has_pair_major = __evolved_is_pair(chunk_fragment)
    local has_pair_minors = chunk_parent ~= nil and chunk_parent.__has_pair_fragments
    local has_pair_fragments = has_pair_major or has_pair_minors

@@ -1624,7 +1610,7 @@ end
 ---@param trace fun(chunk: evolved.chunk, ...: any)
 ---@param ... any additional trace arguments
 function __trace_major_chunks(major, trace, ...)
-    if __is_pair(major) then
+    if __evolved_is_pair(major) then
        __error_fmt('trace operations on pair fragments are not supported')
    end

@@ -1701,7 +1687,7 @@ end
 ---@param trace fun(chunk: evolved.chunk, ...: any)
 ---@param ... any additional trace arguments
 function __trace_minor_chunks(minor, trace, ...)
-    if __is_pair(minor) then
+    if __evolved_is_pair(minor) then
        __error_fmt('trace operations on pair fragments are not supported')
    end

@@ -1857,7 +1843,7 @@ local function __chunk_without_fragment(chunk, fragment)
        if without_fragment_edge then return without_fragment_edge end
    end

-    if chunk.__has_pair_fragments and __is_wildcard(fragment) then
+    if chunk.__has_pair_fragments and __evolved_is_wildcard(fragment) then
        local primary_index, secondary_index, fragment_opts =
            __evolved_unpack(fragment)

@@ -2094,7 +2080,7 @@ local function __chunk_has_fragment(chunk, fragment)
        return true
    end

-    if chunk.__has_pair_fragments and __is_wildcard(fragment) then
+    if chunk.__has_pair_fragments and __evolved_is_wildcard(fragment) then
        local primary_index, secondary_index, fragment_opts =
            __evolved_unpack(fragment)

@@ -2377,7 +2363,7 @@ local function __chunk_required_fragments(chunk, req_fragment_set, req_fragment_
        fragment_stack[fragment_stack_size] = nil
        fragment_stack_size = fragment_stack_size - 1

-        if __is_pair(stack_fragment) then
+        if __evolved_is_pair(stack_fragment) then
            stack_fragment = __evolved_unpair(stack_fragment)
        end

@@ -2427,7 +2413,7 @@ local function __fragment_required_fragments(fragment, req_fragment_set, req_fra
        fragment_stack[fragment_stack_size] = nil
        fragment_stack_size = fragment_stack_size - 1

-        if __is_pair(stack_fragment) then
+        if __evolved_is_pair(stack_fragment) then
            stack_fragment = __evolved_unpair(stack_fragment)
        end

@@ -4706,49 +4692,6 @@ function __evolved_unpack(id)
        (id - id % 2 ^ 40) / 2 ^ 40 % 2 ^ 12
 end

---@param primary evolved.id
---@param secondary evolved.id
---@return evolved.id pair
---@nodiscard
-function __evolved_pair(primary, secondary)
-    local options = __PAIR_OPTS
-
-    if primary == __ANY and secondary == __ANY then
-        options = __WILDCARD_OPTS
-    elseif primary == __ANY then
-        options = __PRIMARY_WILDCARD_OPTS
-    elseif secondary == __ANY then
-        options = __SECONDARY_WILDCARD_OPTS
-    end
-
-    return primary % 2 ^ 20
-        + secondary % 2 ^ 20 * 2 ^ 20
-        + options * 2 ^ 40 --[[@as evolved.id]]
-end
-
---@param pair evolved.id
---@return evolved.id primary
---@return evolved.id secondary
---@nodiscard
-function __evolved_unpair(pair)
-    local primary_index = pair % 2 ^ 20
-    local secondary_index = (pair - primary_index) / 2 ^ 20 % 2 ^ 20
-
-    local primary = __freelist_ids[primary_index] --[[@as evolved.id]]
-    if not primary or primary % 2 ^ 20 ~= primary_index then
-        __error_fmt('the pair (%s) is not alive and cannot be unpaired',
-            __id_name(pair))
-    end
-
-    local secondary = __freelist_ids[secondary_index] --[[@as evolved.id]]
-    if not secondary or secondary % 2 ^ 20 ~= secondary_index then
-        __error_fmt('the pair (%s) is not alive and cannot be unpaired',
-            __id_name(pair))
-    end
-
-    return primary, secondary
-end
-
 ---@return boolean started
 function __evolved_defer()
    __defer_depth = __defer_depth + 1
@@ -4856,7 +4799,7 @@ end
 ---@return boolean
 ---@nodiscard
 function __evolved_alive(entity)
-    if not __is_pair(entity) then
+    if not __evolved_is_pair(entity) then
        local entity_index = entity % 2 ^ 20

        if __freelist_ids[entity_index] ~= entity then
@@ -4922,7 +4865,7 @@ end
 ---@return boolean
 ---@nodiscard
 function __evolved_empty(entity)
-    if not __is_pair(entity) then
+    if not __evolved_is_pair(entity) then
        local entity_index = entity % 2 ^ 20

        if __freelist_ids[entity_index] ~= entity then
@@ -4989,7 +4932,7 @@ end
 ---@return boolean
 ---@nodiscard
 function __evolved_has(entity, fragment)
-    if not __is_pair(entity) then
+    if not __evolved_is_pair(entity) then
        local entity_index = entity % 2 ^ 20

        if __freelist_ids[entity_index] ~= entity then
@@ -5026,7 +4969,7 @@ end
 ---@return boolean
 ---@nodiscard
 function __evolved_has_all(entity, ...)
-    if not __is_pair(entity) then
+    if not __evolved_is_pair(entity) then
        local entity_index = entity % 2 ^ 20

        if __freelist_ids[entity_index] ~= entity then
@@ -5063,7 +5006,7 @@ end
 ---@return boolean
 ---@nodiscard
 function __evolved_has_any(entity, ...)
-    if not __is_pair(entity) then
+    if not __evolved_is_pair(entity) then
        local entity_index = entity % 2 ^ 20

        if __freelist_ids[entity_index] ~= entity then
@@ -5100,7 +5043,7 @@ end
 ---@return evolved.component ... components
 ---@nodiscard
 function __evolved_get(entity, ...)
-    if not __is_pair(entity) then
+    if not __evolved_is_pair(entity) then
        local entity_index = entity % 2 ^ 20

        if __freelist_ids[entity_index] ~= entity then
@@ -5139,11 +5082,11 @@ end
 ---@param component evolved.component
 function __evolved_set(entity, fragment, component)
    if __debug_mode then
-        if __is_pair(entity) then
+        if __evolved_is_pair(entity) then
            __error_fmt('the pair (%s) cannot be used as an entity', __id_name(entity))
        end

-        if __is_wildcard(fragment) then
+        if __evolved_is_wildcard(fragment) then
            __error_fmt('the wildcard fragment (%s) cannot be used as a fragment', __id_name(fragment))
        end

@@ -5392,7 +5335,7 @@ function __evolved_remove(entity, ...)
        return
    end

-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs cannot have fragments, nothing to remove
        return
    end
@@ -5515,7 +5458,7 @@ function __evolved_clear(...)
            local entity = __lua_select(argument_index, ...)
            local entity_index = entity % 2 ^ 20

-            if __is_pair(entity) then
+            if __evolved_is_pair(entity) then
                -- pairs cannot have fragments, nothing to clear
            elseif __freelist_ids[entity_index] ~= entity then
                -- this entity is not alive, nothing to clear
@@ -5593,7 +5536,7 @@ function __evolved_destroy(...)
            local entity = __lua_select(argument_index, ...)
            local entity_index = entity % 2 ^ 20

-            if __is_pair(entity) then
+            if __evolved_is_pair(entity) then
                -- pairs cannot be destroyed, nothing to do
            elseif __freelist_ids[entity_index] ~= entity then
                -- this entity is not alive, nothing to destroy
@@ -5636,11 +5579,11 @@ end
 ---@param component evolved.component
 function __evolved_batch_set(query, fragment, component)
    if __debug_mode then
-        if __is_pair(query) then
+        if __evolved_is_pair(query) then
            __error_fmt('the pair (%s) cannot be used as a query', __id_name(query))
        end

-        if __is_wildcard(fragment) then
+        if __evolved_is_wildcard(fragment) then
            __error_fmt('the wildcard fragment (%s) cannot be used as a fragment', __id_name(fragment))
        end

@@ -5843,7 +5786,7 @@ end
 ---@return evolved.each_state? iterator_state
 ---@nodiscard
 function __evolved_each(entity)
-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs cannot be used as entities, nothing to iterate
        return __iterator_fns.__each_iterator
    end
@@ -5881,7 +5824,7 @@ end
 ---@return evolved.execute_state? iterator_state
 ---@nodiscard
 function __evolved_execute(query)
-    if __is_pair(query) then
+    if __evolved_is_pair(query) then
        -- pairs cannot be used as queries, nothing to execute
        return __iterator_fns.__execute_major_iterator
    end
@@ -5910,7 +5853,7 @@ function __evolved_execute(query)
    if query_include_count > 0 then
        local query_major = query_include_list[query_include_count]

-        if __is_wildcard(query_major) then
+        if __evolved_is_wildcard(query_major) then
            local minor_chunks = __minor_chunks[query_major]
            local minor_chunk_list = minor_chunks and minor_chunks.__item_list --[=[@as evolved.chunk[]]=]
            local minor_chunk_count = minor_chunks and minor_chunks.__item_count or 0 --[[@as integer]]
@@ -6081,7 +6024,7 @@ function __evolved_process(...)
        ---@type evolved.system
        local system = __lua_select(argument_index, ...)

-        if __is_pair(system) then
+        if __evolved_is_pair(system) then
            -- pairs cannot be used as systems, nothing to process
        elseif not __evolved_alive(system) then
            -- this system is not alive, nothing to process
@@ -6164,11 +6107,62 @@ function __evolved_collect_garbage()
    __evolved_commit()
 end

---
---
---
---
---
+---@param primary evolved.id
+---@param secondary evolved.id
+---@return evolved.id pair
+---@nodiscard
+function __evolved_pair(primary, secondary)
+    local options = __PAIR_OPTS
+
+    if primary == __ANY and secondary == __ANY then
+        options = __WILDCARD_OPTS
+    elseif primary == __ANY then
+        options = __PRIMARY_WILDCARD_OPTS
+    elseif secondary == __ANY then
+        options = __SECONDARY_WILDCARD_OPTS
+    end
+
+    return primary % 2 ^ 20
+        + secondary % 2 ^ 20 * 2 ^ 20
+        + options * 2 ^ 40 --[[@as evolved.id]]
+end
+
+---@param pair evolved.id
+---@return evolved.id primary
+---@return evolved.id secondary
+---@nodiscard
+function __evolved_unpair(pair)
+    local primary_index = pair % 2 ^ 20
+    local secondary_index = (pair - primary_index) / 2 ^ 20 % 2 ^ 20
+
+    local primary = __freelist_ids[primary_index] --[[@as evolved.id]]
+    if not primary or primary % 2 ^ 20 ~= primary_index then
+        __error_fmt('the primary fragment of the pair (%s) is not alive and cannot be unpaired',
+            __id_name(pair))
+    end
+
+    local secondary = __freelist_ids[secondary_index] --[[@as evolved.id]]
+    if not secondary or secondary % 2 ^ 20 ~= secondary_index then
+        __error_fmt('the secondary fragment of the pair (%s) is not alive and cannot be unpaired',
+            __id_name(pair))
+    end
+
+    return primary, secondary
+end
+
+---@param id evolved.id
+---@return boolean
+---@nodiscard
+function __evolved_is_pair(id)
+    return id % 2 ^ 41 >= 2 ^ 40
+end
+
+---@param id evolved.id
+---@return boolean
+---@nodiscard
+function __evolved_is_wildcard(id)
+    return id % 2 ^ 43 >= 2 ^ 41
+end

 ---@param entity evolved.entity
 ---@param secondary evolved.fragment
@@ -6179,7 +6173,7 @@ end
 function __evolved_primary(entity, secondary, index)
    index = index or 1

-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs are always empty
        return
    end
@@ -6220,7 +6214,7 @@ end
 function __evolved_secondary(entity, primary, index)
    index = index or 1

-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs are always empty
        return
    end
@@ -6258,7 +6252,7 @@ end
 ---@return evolved.primaries_state? iterator_state
 ---@nodiscard
 function __evolved_primaries(entity, secondary)
-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs are always empty
        return __iterator_fns.__primaries_iterator
    end
@@ -6299,7 +6293,7 @@ end
 ---@return evolved.secondaries_state? iterator_state
 ---@nodiscard
 function __evolved_secondaries(entity, primary)
-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs are always empty
        return __iterator_fns.__secondaries_iterator
    end
@@ -6339,7 +6333,7 @@ end
 ---@return integer
 ---@nodiscard
 function __evolved_primary_count(entity, secondary)
-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs are always empty
        return 0
    end
@@ -6364,7 +6358,7 @@ end
 ---@return integer
 ---@nodiscard
 function __evolved_secondary_count(entity, primary)
-    if __is_pair(entity) then
+    if __evolved_is_pair(entity) then
        -- pairs are always empty
        return 0
    end
@@ -6693,7 +6687,7 @@ end
 ---@return evolved.builder builder
 function __builder_mt:set(fragment, component)
    if __debug_mode then
-        if __is_wildcard(fragment) then
+        if __evolved_is_wildcard(fragment) then
            __error_fmt('the wildcard fragment (%s) cannot be used as a fragment', __id_name(fragment))
        end

@@ -7242,7 +7236,7 @@ end)

 ---
 ---
---
+--- Predefs
 ---
 ---

@@ -7282,15 +7276,18 @@ evolved.DESTRUCTION_POLICY = __DESTRUCTION_POLICY
 evolved.DESTRUCTION_POLICY_DESTROY_ENTITY = __DESTRUCTION_POLICY_DESTROY_ENTITY
 evolved.DESTRUCTION_POLICY_REMOVE_FRAGMENT = __DESTRUCTION_POLICY_REMOVE_FRAGMENT

+---
+---
+--- Core Functions
+---
+---
+
 evolved.id = __evolved_id
 evolved.name = __evolved_name

 evolved.pack = __evolved_pack
 evolved.unpack = __evolved_unpack

-evolved.pair = __evolved_pair
-evolved.unpair = __evolved_unpair
-
 evolved.defer = __evolved_defer
 evolved.commit = __evolved_commit

@@ -7324,6 +7321,26 @@ evolved.batch_destroy = __evolved_batch_destroy
 evolved.each = __evolved_each
 evolved.execute = __evolved_execute

+evolved.process = __evolved_process
+
+evolved.debug_mode = __evolved_debug_mode
+evolved.collect_garbage = __evolved_collect_garbage
+
+evolved.chunk = __evolved_chunk
+evolved.builder = __evolved_builder
+
+---
+---
+--- Relation Functions
+---
+---
+
+evolved.pair = __evolved_pair
+evolved.unpair = __evolved_unpair
+
+evolved.is_pair = __evolved_is_pair
+evolved.is_wildcard = __evolved_is_wildcard
+
 evolved.primary = __evolved_primary
 evolved.secondary = __evolved_secondary

@@ -7333,13 +7350,11 @@ evolved.secondaries = __evolved_secondaries
 evolved.primary_count = __evolved_primary_count
 evolved.secondary_count = __evolved_secondary_count

-evolved.process = __evolved_process
-
-evolved.debug_mode = __evolved_debug_mode
-evolved.collect_garbage = __evolved_collect_garbage
-
-evolved.chunk = __evolved_chunk
-evolved.builder = __evolved_builder
+---
+---
+---
+---
+---

 evolved.collect_garbage()