Struct NativeBitArray

An arbitrarily-sized array of bits.

Namespace: Unity.Collections

Syntax

[NativeContainer]
public struct NativeBitArray : INativeDisposable, IDisposable

Remarks

The number of allocated bytes is always a multiple of 8. For example, a 65-bit array could fit in 9 bytes, but its allocation is actually 16 bytes.

Constructors

NativeBitArray(Int32, AllocatorManager.AllocatorHandle, NativeArrayOptions)

Initializes and returns an instance of NativeBitArray.

Declaration

public NativeBitArray(int numBits, AllocatorManager.AllocatorHandle allocator, NativeArrayOptions options = NativeArrayOptions.ClearMemory)

Parameters

Type	Name	Description
Int32	numBits	The number of bits.
AllocatorManager.AllocatorHandle	allocator	The allocator to use.
NativeArrayOptions	options	Whether newly allocated bytes should be zeroed out.

Properties

Capacity

Returns the capacity number of bits.

Declaration

public readonly int Capacity { get; }

Property Value

Type	Description
Int32	The capacity number of bits.

IsCreated

Whether this array has been allocated (and not yet deallocated).

Declaration

public readonly bool IsCreated { get; }

Property Value

Type	Description
Boolean	True if this array has been allocated (and not yet deallocated).

IsEmpty

Whether the container is empty.

Declaration

public readonly bool IsEmpty { get; }

Property Value

Type	Description
Boolean	True if the container is empty or the container has not been constructed.

Length

Returns the number of bits.

Declaration

public readonly int Length { get; }

Property Value

Type	Description
Int32	The number of bits.

Methods

AsNativeArray<T>()

Returns a native array that aliases the content of this array.

Declaration

public NativeArray<T> AsNativeArray<T>()
    where T : struct

Returns

Type	Description
NativeArray<T>	A native array that aliases the content of this array.

Type Parameters

Name	Description
T	The type of elements in the aliased array.

Exceptions

Type	Condition
InvalidOperationException	Thrown if the number of bits in this array is not evenly divisible by the size of T in bits (sizeof(T) * 8).

AsReadOnly()

Returns a readonly version of this NativeBitArray instance.

Declaration

public NativeBitArray.ReadOnly AsReadOnly()

Returns

Type	Description
NativeBitArray.ReadOnly	ReadOnly instance for this.

Remarks

ReadOnly containers point to the same underlying data as the NativeBitArray it is made from.

Clear()

Sets all the bits to 0.

Declaration

public void Clear()

Copy(Int32, Int32, Int32)

Copies a range of bits from this array to another range in this array.

Declaration

public void Copy(int dstPos, int srcPos, int numBits)

Parameters

Type	Name	Description
Int32	dstPos	Index of the first bit to set.
Int32	srcPos	Index of the first bit to copy.
Int32	numBits	Number of bits to copy.

Remarks

The bits to copy run from index srcPos up to (but not including) srcPos + numBits. The bits to set run from index dstPos up to (but not including) dstPos + numBits.

The ranges may overlap, but the result in the overlapping region is undefined.

Exceptions

Type	Condition
ArgumentException	Thrown if either dstPos + numBits or srcPos + numBits exceed the length of this array.

Copy(Int32, ref NativeBitArray, Int32, Int32)

Copies a range of bits from an array to a range of bits in this array.

Declaration

public void Copy(int dstPos, ref NativeBitArray srcBitArray, int srcPos, int numBits)

Parameters

Type	Name	Description
Int32	dstPos	Index of the first bit to set.
NativeBitArray	srcBitArray	The source array.
Int32	srcPos	Index of the first bit to copy.
Int32	numBits	The number of bits to copy.

Remarks

The bits to copy in the source array run from index srcPos up to (but not including) srcPos + numBits. The bits to set in the destination array run from index dstPos up to (but not including) dstPos + numBits.

When the source and destination are the same array, the ranges may still overlap, but the result in the overlapping region is undefined.

Exceptions

Type	Condition
ArgumentException	Thrown if either dstPos + numBits or srcBitArray + numBits exceed the length of this array.

CountBits(Int32, Int32)

Returns the number of bits in a range that are 1.

Declaration

public int CountBits(int pos, int numBits = 1)

Parameters

Type	Name	Description
Int32	pos	Index of the bit at which to start searching.
Int32	numBits	Number of bits to test. Defaults to 1.

Returns

Type	Description
Int32	The number of bits in a range of bits that are 1.

Exceptions

Type	Condition
ArgumentException	Thrown if pos is out of bounds or numBits is less than 1.

Dispose()

Releases all resources (memory and safety handles).

Declaration

public void Dispose()

Dispose(JobHandle)

Creates and schedules a job that will dispose this array.

Declaration

public JobHandle Dispose(JobHandle inputDeps)

Parameters

Type	Name	Description
JobHandle	inputDeps	The handle of a job which the new job will depend upon.

Returns

Type	Description
JobHandle	The handle of a new job that will dispose this array. The new job depends upon inputDeps.

Implements

INativeDisposable.Dispose(JobHandle)

Find(Int32, Int32)

Finds the first length-N contiguous sequence of 0 bits in this bit array.

Declaration

public int Find(int pos, int numBits)

Parameters

Type	Name	Description
Int32	pos	Index at which to start searching.
Int32	numBits	Number of contiguous 0 bits to look for.

Returns

Type	Description
Int32	The index in this array where the sequence is found. The index will be greater than or equal to pos. Returns -1 if no occurrence is found.

Find(Int32, Int32, Int32)

Finds the first length-N contiguous sequence of 0 bits in this bit array. Searches only a subsection.

Declaration

public int Find(int pos, int count, int numBits)

Parameters

Type	Name	Description
Int32	pos	Index at which to start searching.
Int32	count	Number of bits to search.
Int32	numBits	Number of contiguous 0 bits to look for.

Returns

Type	Description
Int32	The index in this array where the sequence is found. The index will be greater than or equal to pos but less than pos + count. Returns -1 if no occurrence is found.

GetBits(Int32, Int32)

Returns a ulong which has bits copied from this array.

Declaration

public ulong GetBits(int pos, int numBits = 1)

Parameters

Type	Name	Description
Int32	pos	Index of the first bit to get.
Int32	numBits	Number of bits to get (must be between 1 and 64).

Returns

Type	Description
UInt64	A ulong which has bits copied from this array.

Remarks

The source bits in this array run from index pos up to (but not including) pos + numBits. No exception is thrown if pos + numBits exceeds the length.

The first source bit is copied to the lowest bit of the ulong; the second source bit is copied to the second-lowest bit of the ulong; and so forth. Any remaining bits in the ulong will be 0.

Exceptions

Type	Condition
ArgumentException	Thrown if pos is out of bounds or if numBits is not between 1 and 64.

IsSet(Int32)

Returns true if the bit at an index is 1.

Declaration

public bool IsSet(int pos)

Parameters

Type	Name	Description
Int32	pos	Index of the bit to test.

Returns

Type	Description
Boolean	True if the bit at the index is 1.

Exceptions

Type	Condition
ArgumentException	Thrown if pos is out of bounds.

Resize(Int32, NativeArrayOptions)

Sets the length, expanding the capacity if necessary.

Declaration

public void Resize(int numBits, NativeArrayOptions options = NativeArrayOptions.UninitializedMemory)

Parameters

Type	Name	Description
Int32	numBits	The new length in bits.
NativeArrayOptions	options	Whether newly allocated data should be zeroed out.

Set(Int32, Boolean)

Sets the bit at an index to 0 or 1.

Declaration

public void Set(int pos, bool value)

Parameters

Type	Name	Description
Int32	pos	Index of the bit to set.
Boolean	value	True for 1, false for 0.

SetBits(Int32, Boolean, Int32)

Sets a range of bits to 0 or 1.

Declaration

public void SetBits(int pos, bool value, int numBits)

Parameters

Type	Name	Description
Int32	pos	Index of the first bit to set.
Boolean	value	True for 1, false for 0.
Int32	numBits	Number of bits to set.

Remarks

The range runs from index pos up to (but not including) pos + numBits. No exception is thrown if pos + numBits exceeds the length.

Exceptions

Type	Condition
ArgumentException	Thrown if pos is out of bounds or if numBits is less than 1.

SetBits(Int32, UInt64, Int32)

Copies bits of a ulong to bits in this array.

Declaration

public void SetBits(int pos, ulong value, int numBits = 1)

Parameters

Type	Name	Description
Int32	pos	Index of the first bit to set.
UInt64	value	Unsigned long from which to copy bits.
Int32	numBits	Number of bits to set (must be between 1 and 64).

Remarks

The destination bits in this array run from index pos up to (but not including) pos + numBits. No exception is thrown if pos + numBits exceeds the length.

The lowest bit of the ulong is copied to the first destination bit; the second-lowest bit of the ulong is copied to the second destination bit; and so forth.

Exceptions

Type	Condition
ArgumentException	Thrown if pos is out of bounds or if numBits is not between 1 and 64.

SetCapacity(Int32)

Sets the capacity.

Declaration

public void SetCapacity(int capacityInBits)

Parameters

Type	Name	Description
Int32	capacityInBits	The new capacity.

TrimExcess()

Sets the capacity to match what it would be if it had been originally initialized with all its entries.

Declaration

public void TrimExcess()