Struct UnsafeBitArray

An arbitrarily-sized array of bits.

Namespace: Unity.Collections.LowLevel.Unsafe

Syntax

public struct UnsafeBitArray : 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

UnsafeBitArray(Int32, AllocatorManager.AllocatorHandle, NativeArrayOptions)

Initializes and returns an instance of UnsafeBitArray.

Declaration

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

Parameters

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

UnsafeBitArray(Void*, Int32, AllocatorManager.AllocatorHandle)

Initializes and returns an instance of UnsafeBitArray which aliases an existing buffer.

Declaration

public UnsafeBitArray(void *ptr, int sizeInBytes, AllocatorManager.AllocatorHandle allocator = default(AllocatorManager.AllocatorHandle))

Parameters

Type	Name	Description
Void*	ptr	An existing buffer.
Int32	sizeInBytes	The number of bytes. The length will be sizeInBytes * 8.
AllocatorManager.AllocatorHandle	allocator	The allocator that was used to allocate the bytes. Needed to dispose this array.

Fields

Allocator

The allocator to use.

Declaration

public AllocatorManager.AllocatorHandle Allocator

Field Value

Type	Description
AllocatorManager.AllocatorHandle	The allocator to use.

Capacity

The capacity number of bits.

Declaration

public int Capacity

Field Value

Type	Description
Int32	The capacity number of bits.

Length

The number of bits.

Declaration

public int Length

Field Value

Type	Description
Int32	The number of bits.

Ptr

Pointer to the data.

Declaration

[NativeDisableUnsafePtrRestriction]
public ulong *Ptr

Field Value

Type	Description
UInt64*	Pointer to the data.

Properties

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.

Methods

AsReadOnly()

Returns a readonly version of this UnsafeBitArray instance.

Declaration

public UnsafeBitArray.ReadOnly AsReadOnly()

Returns

Type	Description
UnsafeBitArray.ReadOnly	ReadOnly instance for this.

Remarks

ReadOnly containers point to the same underlying data as the UnsafeBitArray 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 UnsafeBitArray, 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 UnsafeBitArray srcBitArray, int srcPos, int numBits)

Parameters

Type	Name	Description
Int32	dstPos	Index of the first bit to set.
UnsafeBitArray	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.

It's fine if source and destination array are one and the same, even if the ranges 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)

Returns the index of the first occurrence in this array of N contiguous 0 bits.

Declaration

public int Find(int pos, int numBits)

Parameters

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

Returns

Type	Description
Int32	The index of the first occurrence in this array of numBits contiguous 0 bits. Range is pos up to (but not including) the length of this array. Returns -1 if no occurrence is found.

Remarks

The search is linear.

Find(Int32, Int32, Int32)

Returns the index of the first occurrence in this array of a given number of contiguous 0 bits.

Declaration

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

Parameters

Type	Name	Description
Int32	pos	Index of the bit at which to start searching.
Int32	count	Number of indexes to consider as the return value.
Int32	numBits	Number of contiguous 0 bits to look for.

Returns

Type	Description
Int32	The index of the first occurrence in this array of numBits contiguous 0 bits. Range is pos up to (but not including) pos + count. Returns -1 if no occurrence is found.

Remarks

The search is linear.

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.

Set(UInt64*, Int32, Boolean)

Sets the bit at an index to 0 or 1.

Declaration

public static void Set(ulong *ptr, int pos, bool value)

Parameters

Type	Name	Description
UInt64*	ptr	pointer to the bit buffer
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()