Mask¶
Multi-part bitmask abstraction for group filter and category matching operations.
Import¶
import "_IVLS/std-library/nodes/components/mask.ksp"Node: Stl.Mask¶
Uses: Init, FirstLoad
Overview¶
Multi-part bitmask abstraction for group filter and category matching operations.
Implements the Mask ADT as a fixed-width bitmask split across MASK_PART_LIMIT integer parts. Provides bitwise operations (AND, OR, AND-NOT), arithmetic operations (add, subtract), equality and filter-match predicates, and bit-index utilities for working with sparse bit sets.
Masks are used throughout the STL to categorize and filter objects by assigning bit positions to logical categories. The multi-part design extends the effective bit width beyond a single 32-bit integer by partitioning the bit space across MASK_PART_LIMIT parts.
API¶
Nodes¶
| Name | Description |
|---|---|
node Stl.Mask |
Declares the multi-part bitmask node, exposing bitwise, arithmetic, comparison, ... |
Defines¶
| Name | Description |
|---|---|
define Mask.MEMBERS |
Member name list for the Mask ADT type, enumerating the m0, m1, and m2 integer p... |
define MASK_PART_LIMIT |
Maximum number of integer parts in a Mask instance, determining the total bit ca... |
Properties¶
| Name | Description |
|---|---|
property Mask.part |
Indexed get/set accessor for a single integer part of a Mask instance. |
Macros¶
| Name | Description |
|---|---|
Mask.def |
Defines the Mask ADT type structure, declaring its member layout and initial val... |
Functions¶
| Name | Description |
|---|---|
Mask.add(a, b, out) |
Adds corresponding parts of masks a and b, storing the result in out. |
Mask.and(a, b, out) |
Computes the bitwise AND of masks a and b, storing the result in out. |
Mask.and_not(a, b, out) |
Computes the bitwise AND-NOT of masks a and b (a AND NOT b), storing the result ... |
Mask.bit_to_part(true_bit) -> part |
Maps an absolute bit index to the mask part index that contains it. |
Mask.copy_contents(a, b) |
Copies all mask parts from source mask a into destination mask b. |
Mask.equals(a, b) -> result |
Tests whether masks a and b are equal across all parts. |
Mask.get_true_bit(mask, true_bit) -> val |
Retrieves the bit value at position true_bit within the specified mask. |
Mask.match_filter(item, filter) -> result |
Tests whether the item mask satisfies the filter mask, i.e., every bit set in fi... |
Mask.or(a, b, out) |
Computes the bitwise OR of masks a and b, storing the result in out. |
Mask.part_bit(true_bit) -> part |
Computes the bit position within its containing part for an absolute bit index. |
Mask.subtract(a, b, out) |
Subtracts corresponding parts of mask b from mask a, storing the result in out. |
Nodes¶
node Stl.Mask¶
Callbacks: Init, FirstLoad
Declares the multi-part bitmask node, exposing bitwise, arithmetic, comparison, and bit-utility operations.
Defines¶
define Mask.MEMBERS¶
Member name list for the Mask ADT type, enumerating the m0, m1, and m2 integer part fields.
define MASK_PART_LIMIT¶
Maximum number of integer parts in a Mask instance, determining the total bit capacity of the mask.
Properties¶
property Mask.part¶
Indexed get/set accessor for a single integer part of a Mask instance.
get(ref, i) -> resultset(ref, i, value)
Macros¶
Mask.def¶
Defines the Mask ADT type structure, declaring its member layout and initial values.
Side effects:
| Name | Type | Purpose |
|---|---|---|
| Mask.MEMBERS | define | Declares the member names for the Mask type (m0, m1, m2) |
| Mask.INIT[] | integer_array | Declares the zero-initialized values array for Mask instances |
Functions¶
Mask.add(a, b, out)¶
Adds corresponding parts of masks a and b, storing the result in out.
| Parameter | Type | Description |
|---|---|---|
a |
integer | Reference handle of the first operand Mask |
b |
integer | Reference handle of the second operand Mask |
out |
integer | Reference handle of the Mask to receive the result |
Mask.and(a, b, out)¶
Computes the bitwise AND of masks a and b, storing the result in out.
| Parameter | Type | Description |
|---|---|---|
a |
integer | Reference handle of the first operand Mask |
b |
integer | Reference handle of the second operand Mask |
out |
integer | Reference handle of the Mask to receive the result |
Mask.and_not(a, b, out)¶
Computes the bitwise AND-NOT of masks a and b (a AND NOT b), storing the result in out.
| Parameter | Type | Description |
|---|---|---|
a |
integer | Reference handle of the base operand Mask |
b |
integer | Reference handle of the Mask whose complement is ANDed with a |
out |
integer | Reference handle of the Mask to receive the result |
Mask.bit_to_part(true_bit) -> part¶
Maps an absolute bit index to the mask part index that contains it.
| Parameter | Type | Description |
|---|---|---|
true_bit |
integer | Absolute bit index across all mask parts |
Returns: part — Zero-based index of the mask part containing the specified bit
Mask.copy_contents(a, b)¶
Copies all mask parts from source mask a into destination mask b.
| Parameter | Type | Description |
|---|---|---|
a |
integer | Reference handle of the source Mask instance |
b |
integer | Reference handle of the destination Mask instance |
Mask.equals(a, b) -> result¶
Tests whether masks a and b are equal across all parts.
| Parameter | Type | Description |
|---|---|---|
a |
integer | Reference handle of the first Mask to compare |
b |
integer | Reference handle of the second Mask to compare |
Returns: result — 1 if all parts are equal, 0 otherwise
Mask.get_true_bit(mask, true_bit) -> val¶
Retrieves the bit value at position true_bit within the specified mask.
| Parameter | Type | Description |
|---|---|---|
mask |
integer | Reference handle of the Mask instance to inspect |
true_bit |
integer | Absolute bit index across all mask parts |
Returns: val — The bit value (0 or 1) at the specified position
Mask.match_filter(item, filter) -> result¶
Tests whether the item mask satisfies the filter mask, i.e., every bit set in filter is also set in item across all parts.
| Parameter | Type | Description |
|---|---|---|
item |
integer | Reference handle of the Mask being tested |
filter |
integer | Reference handle of the filter Mask defining required bits |
Returns: result — 1 if item matches all bits in filter, 0 otherwise
Mask.or(a, b, out)¶
Computes the bitwise OR of masks a and b, storing the result in out.
| Parameter | Type | Description |
|---|---|---|
a |
integer | Reference handle of the first operand Mask |
b |
integer | Reference handle of the second operand Mask |
out |
integer | Reference handle of the Mask to receive the result |
Mask.part_bit(true_bit) -> part¶
Computes the bit position within its containing part for an absolute bit index.
| Parameter | Type | Description |
|---|---|---|
true_bit |
integer | Absolute bit index across all mask parts |
Returns: part — Bit offset within the containing part (0-31)
Mask.subtract(a, b, out)¶
Subtracts corresponding parts of mask b from mask a, storing the result in out.
| Parameter | Type | Description |
|---|---|---|
a |
integer | Reference handle of the minuend Mask |
b |
integer | Reference handle of the subtrahend Mask |
out |
integer | Reference handle of the Mask to receive the result |
Example¶
// TODO: Add usage example