Struct ScyllaBitArrayDOTS

DOTS/Burst-compatible fixed-capacity bit array backed by a NativeArray<ulong> word array. Provides the same bitwise operations as ScyllaBitArray in an unmanaged struct that is safe to use inside Burst-compiled jobs and on the job thread.

Implements

IDisposable

Inherited Members

ValueType.Equals(object)

ValueType.GetHashCode()

ValueType.ToString()

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Scylla.Core.Structures

Assembly: ScyllaCore.dll

Syntax

[BurstCompile]
public struct ScyllaBitArrayDOTS : IDisposable

Remarks

Bits are packed 64 per ulong word. The actual Capacity is always rounded up to the nearest multiple of 64 to keep word-aligned access branchless. All single-bit operations are O(1); bitwise combinators (And(ScyllaBitArrayDOTS), Or(ScyllaBitArrayDOTS), Xor(ScyllaBitArrayDOTS), Not()) are O(Capacity/64).

This struct is decorated with [BurstCompile] and is fully usable inside IJob, IJobFor, and similar Unity DOTS job types. It is not marked with [NativeContainer] because safety tracking is delegated to the inner Unity.Collections.NativeArray<T>, which already carries its own AtomicSafetyHandle and DisposeSentinel in the Unity editor.

Like all native containers, ScyllaBitArrayDOTS must be explicitly disposed via Dispose() or a using statement when it is no longer needed to avoid native memory leaks. Check IsCreated before use when the struct may not have been initialized.

For managed, non-job scenarios prefer ScyllaBitArray, which avoids the allocation and lifetime management overhead of native memory.

// Direct construction with a temp-job allocator
var bits = new ScyllaBitArrayDOTS(256, Allocator.TempJob);
bits.Set(7);
bool isSet = bits.Get(7); // true
bits.Dispose();
// Using the fluent builder with a persistent allocator
using var bits = ScyllaBitArrayDOTS.CreateBuilder()
.WithCapacity(1024)
.WithAllocator(Allocator.Persistent)
.Build();

Constructors

ScyllaBitArrayDOTS(int, Allocator)

Initializes a new ScyllaBitArrayDOTS with the specified bit capacity, allocating the native word buffer with the given allocator. All bits are initially set to 0.

Declaration

public ScyllaBitArrayDOTS(int capacity, Allocator allocator)

Parameters

Type	Name	Description
int	capacity	The desired number of bits. Values less than 1 are silently clamped to 1. The actual Capacity is rounded up to the nearest multiple of 64 to fill complete ulong words.
Allocator	allocator	The Unity memory allocator to use for the internal native buffer. Use Allocator.TempJob for short-lived job data, Allocator.Persistent for long-lived data, or Allocator.Temp for single-frame allocations. Must not be Allocator.None or Allocator.Invalid.

Exceptions

Type	Condition
ArgumentException	Thrown when allocator is Allocator.None or Allocator.Invalid.

Properties

Capacity

The total number of bits this array can hold.

Declaration

public int Capacity { get; }

Property Value

Type	Description
int	The effective bit capacity, rounded up to a multiple of 64.

Remarks

Always a multiple of 64 because the capacity is rounded up to the nearest full ulong word boundary during construction. After Dispose() is called this value is reset to 0.

Count

The number of bits currently set to 1.

Declaration

public int Count { get; }

Property Value

Type	Description
int	The population count of set bits, in the range [0, Capacity].

Remarks

Maintained as an incremental counter on single-bit mutations and recomputed after bulk word operations. Accessing this property is always O(1). After Dispose() this value is reset to 0.

IsCreated

Returns true if the underlying Unity.Collections.NativeArray<T> has been allocated (i.e., the struct was constructed with a valid capacity and allocator and has not yet been disposed).

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
bool	true if the native buffer is valid and the struct is ready for use; false if the struct was default-initialized or has been disposed.

Remarks

Always check IsCreated before calling any method when the struct may have been default-initialized (as a field, in a collection, or via default(ScyllaBitArrayDOTS)) rather than through the constructor. All mutating and read operations call Scylla.Core.Structures.ScyllaBitArrayDOTS.RequireCreated() internally, which throws InvalidOperationException when this property is false.

IsEmpty

Returns true when no bits are set (i.e., Count is zero).

Declaration

public bool IsEmpty { get; }

Property Value

Type	Description
bool	true if the array contains no set bits; otherwise false.

Methods

And(ScyllaBitArrayDOTS)

Performs an in-place bitwise AND of this array with other.

Declaration

public void And(ScyllaBitArrayDOTS other)

Parameters

Type	Name	Description
ScyllaBitArrayDOTS	other	The DOTS bit array to AND with. Must be created (i.e., IsCreated of other should be true).

Remarks

Only the overlapping word range (up to min(this.words, other.words)) is ANDed. Any words in this array that extend beyond other's capacity are cleared to 0, because ANDing with an implicitly-zero word always yields zero.

Count is recalculated in full after the operation via Scylla.Core.Structures.ScyllaBitArrayDOTS.RecalculatePopCount().

Exceptions

Type	Condition
InvalidOperationException	Thrown when this array has not been created or has already been disposed.

Clear()

Sets all bits to 0 and resets Count to zero.

Declaration

public void Clear()

Remarks

Iterates each word and writes 0 directly, which is compatible with Burst. Capacity is unchanged.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed (i.e., IsCreated is false).

CreateBuilder()

Creates and returns a new ScyllaBitArrayDOTS.Builder instance for configuring and constructing a ScyllaBitArrayDOTS using a fluent API.

Declaration

public static ScyllaBitArrayDOTS.Builder CreateBuilder()

Returns

Type	Description
ScyllaBitArrayDOTS.Builder	A new ScyllaBitArrayDOTS.Builder with default settings.

See Also

ScyllaBitArrayDOTS.Builder

Dispose()

Releases the underlying Unity.Collections.NativeArray<T> back to the allocator and resets Capacity and Count to 0.

Declaration

public void Dispose()

Remarks

After Dispose() returns, IsCreated is false and all subsequent method calls will throw InvalidOperationException. Calling Dispose() on an already-disposed or default-initialized instance is safe; the guard checks _words.IsCreated before releasing.

Get(int)

Returns true if the bit at index is set to 1.

Declaration

public bool Get(int index)

Parameters

Type	Name	Description
int	index	Zero-based bit index in the range [0, Capacity - 1].

Returns

Type	Description
bool	true if the bit at index is 1; false if it is 0.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed (i.e., IsCreated is false).
ArgumentOutOfRangeException	Thrown when index is negative or greater than or equal to Capacity.

GetEnumerator()

Returns an ScyllaBitArrayDOTS.Enumerator value-type enumerator that iterates over the zero-based indices of all bits currently set to 1, in ascending order.

Declaration

public ScyllaBitArrayDOTS.Enumerator GetEnumerator()

Returns

Type	Description
ScyllaBitArrayDOTS.Enumerator	A ScyllaBitArrayDOTS.Enumerator positioned before the first set-bit index.

Remarks

The returned ScyllaBitArrayDOTS.Enumerator is a value type, so no heap allocation occurs when iterating with foreach. The enumerator is Burst-compatible and can be used inside Unity jobs. It does not support mutation of the array during enumeration.

Not()

Inverts every bit in-place (bitwise NOT), turning all 1s into 0s and all 0s into 1s.

Declaration

public void Not()

Remarks

Because Capacity is always a multiple of 64, all bits in every word are meaningful. After the operation Count equals Capacity - Count (the complement of the previous population count). Count is recalculated in full after the operation via Scylla.Core.Structures.ScyllaBitArrayDOTS.RecalculatePopCount().

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed (i.e., IsCreated is false).

Or(ScyllaBitArrayDOTS)

Performs an in-place bitwise OR of this array with other.

Declaration

public void Or(ScyllaBitArrayDOTS other)

Parameters

Type	Name	Description
ScyllaBitArrayDOTS	other	The DOTS bit array to OR with. Must be created (i.e., IsCreated of other should be true).

Remarks

Only the overlapping word range is ORed. Words in this array beyond other's capacity are left unchanged because ORing with an implicitly-zero word has no effect.

Count is recalculated in full after the operation via Scylla.Core.Structures.ScyllaBitArrayDOTS.RecalculatePopCount().

Exceptions

Type	Condition
InvalidOperationException	Thrown when this array has not been created or has already been disposed.

PopCount()

Returns the population count - the number of bits currently set to 1.

Declaration

public int PopCount()

Returns

Type	Description
int	The number of set bits, in the range [0, Capacity].

Remarks

This is an O(1) property read of the cached counter maintained by all mutation methods. It is equivalent to reading Count and is provided as a named method to match the nomenclature of the managed counterpart PopCount(). Uses math.countbits from Unity.Mathematics for the full recount triggered by bulk word operations.

Set(int)

Sets the bit at index to 1. If the bit is already set this method is a no-op and Count is not incremented twice.

Declaration

public void Set(int index)

Parameters

Type	Name	Description
int	index	Zero-based bit index in the range [0, Capacity - 1].

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed (i.e., IsCreated is false).
ArgumentOutOfRangeException	Thrown when index is negative or greater than or equal to Capacity.

Set(int, bool)

Sets or clears the bit at index according to value. Delegates to Set(int) when value is true and to Unset(int) when false, so all validation and count maintenance rules of those methods apply.

Declaration

public void Set(int index, bool value)

Parameters

Type	Name	Description
int	index	Zero-based bit index in the range [0, Capacity - 1].
bool	value	true to set the bit to 1; false to clear it to 0.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed.
ArgumentOutOfRangeException	Thrown when index is out of range.

SetAll()

Sets all bits to 1 and updates Count to Capacity.

Declaration

public void SetAll()

Remarks

Every backing word is written to ulong.MaxValue (all 64 bits set), then Scylla.Core.Structures.ScyllaBitArrayDOTS.RecalculatePopCount() recomputes the cached count. The total set-bit count after this call equals Capacity because the capacity is always a multiple of 64 and every word is fully saturated.

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed (i.e., IsCreated is false).

Toggle(int)

Flips the bit at index: a 0 becomes 1 and a 1 becomes 0. Count is adjusted accordingly.

Declaration

public void Toggle(int index)

Parameters

Type	Name	Description
int	index	Zero-based bit index in the range [0, Capacity - 1].

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed (i.e., IsCreated is false).
ArgumentOutOfRangeException	Thrown when index is negative or greater than or equal to Capacity.

Unset(int)

Clears the bit at index to 0. If the bit is already clear this method is a no-op and Count is not decremented below its current value.

Declaration

public void Unset(int index)

Parameters

Type	Name	Description
int	index	Zero-based bit index in the range [0, Capacity - 1].

Exceptions

Type	Condition
InvalidOperationException	Thrown when the array has not been created or has already been disposed (i.e., IsCreated is false).
ArgumentOutOfRangeException	Thrown when index is negative or greater than or equal to Capacity.

Xor(ScyllaBitArrayDOTS)

Performs an in-place bitwise XOR of this array with other.

Declaration

public void Xor(ScyllaBitArrayDOTS other)

Parameters

Type	Name	Description
ScyllaBitArrayDOTS	other	The DOTS bit array to XOR with. Must be created (i.e., IsCreated of other should be true).

Remarks

Only the overlapping word range is XORed. Words beyond other's capacity are unaffected because XORing with zero is an identity operation.

XOR is commonly used to toggle a set of bits atomically or to compute the symmetric difference of two sets.

Count is recalculated in full after the operation via Scylla.Core.Structures.ScyllaBitArrayDOTS.RecalculatePopCount().

Exceptions

Type	Condition
InvalidOperationException	Thrown when this array has not been created or has already been disposed.

Implements

IDisposable

See Also

ScyllaBitArray