Class CollectionHelper

Provides helper methods for collections.

Inheritance

CollectionHelper

Namespace: Unity.Collections

Syntax

public static class CollectionHelper

Fields

CacheLineSize

The size in bytes of the current platform's L1 cache lines.

Declaration

public const int CacheLineSize = 64

Field Value

Type	Description
Int32	The size in bytes of the current platform's L1 cache lines.

Methods

Align(Int32, Int32)

Returns an allocation size in bytes that factors in alignment.

Declaration

public static int Align(int size, int alignmentPowerOfTwo)

Parameters

Type	Name	Description
Int32	size	The size to align.
Int32	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
Int32	The smallest integer that is greater than or equal to `size` and is a multiple of `alignmentPowerOfTwo`.

Examples

    // 55 aligned to 16 is 64.
    int size = CollectionHelper.Align(55, 16);

Exceptions

Type	Condition
ArgumentException	Thrown if `alignmentPowerOfTwo` is not a non-zero, positive power of two.

Align(UInt64, UInt64)

Returns an allocation size in bytes that factors in alignment.

Declaration

public static ulong Align(ulong size, ulong alignmentPowerOfTwo)

Parameters

Type	Name	Description
UInt64	size	The size to align.
UInt64	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
UInt64	The smallest integer that is greater than or equal to `size` and is a multiple of `alignmentPowerOfTwo`.

Examples

    // 55 aligned to 16 is 64.
    ulong size = CollectionHelper.Align(55, 16);

Exceptions

Type	Condition
ArgumentException	Thrown if `alignmentPowerOfTwo` is not a non-zero, positive power of two.

CheckReflectionDataCorrect<T>(IntPtr)

Checks that reflection data was properly registered for a job.

Declaration

[Conditional("ENABLE_UNITY_COLLECTIONS_CHECKS")]
public static void CheckReflectionDataCorrect<T>(IntPtr reflectionData)

Parameters

Type	Name	Description
IntPtr	reflectionData	The reflection data pointer.

Type Parameters

Name	Description
T	Job type

Remarks

This should be called before instantiating JobsUtility.JobScheduleParameters in order to report to the user if they need to take action.

ConvertExistingDataToNativeArray<T>(Void*, Int32, AllocatorManager.AllocatorHandle, Boolean)

Convert existing data into a NativeArray.

Declaration

public static NativeArray<T> ConvertExistingDataToNativeArray<T>(void *dataPointer, int length, AllocatorManager.AllocatorHandle allocator, bool setTempMemoryHandle = false)
    where T : struct

Parameters

Type	Name	Description
Void*	dataPointer	Pointer to the data to be converted.
Int32	length	The count of elements.
AllocatorManager.AllocatorHandle	allocator	The Allocator to use.
Boolean	setTempMemoryHandle	Use temporary memory atomic safety handle.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

Remarks

The caller is still the owner of the data.

ConvertExistingNativeListToNativeArray<T>(ref NativeList<T>, Int32, AllocatorManager.AllocatorHandle)

Convert NativeList into a NativeArray.

Declaration

public static NativeArray<T> ConvertExistingNativeListToNativeArray<T>(ref NativeList<T> nativeList, int length, AllocatorManager.AllocatorHandle allocator)
    where T : struct

Parameters

Type	Name	Description
NativeList<T>	nativeList	NativeList to be converted.
Int32	length	The count of elements.
AllocatorManager.AllocatorHandle	allocator	The Allocator to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

Remarks

There is a caveat if users would like to transfer memory ownership from the NativeList to the converted NativeArray. NativeList implementation includes two memory allocations, one holds its header, another holds the list data. After convertion, the converted NativeArray holds the list data and dispose the array only free the list data. Users need to manually free the list header to avoid memory leaks, for example after convertion call, AllocatorManager.Free(allocator, nativeList.m_ListData);

CreateNativeArray<T>(T[], AllocatorManager.AllocatorHandle)

Create a NativeArray from a managed array, using a provided AllocatorHandle.

Declaration

[ExcludeFromBurstCompatTesting("Managed array")]
public static NativeArray<T> CreateNativeArray<T>(T[] array, AllocatorManager.AllocatorHandle allocator)
    where T : struct

Parameters

Type	Name	Description
T[]	array	The managed array to make a copy of.
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

CreateNativeArray<T>(Int32, AllocatorManager.AllocatorHandle, NativeArrayOptions)

Create a NativeArray, using a provided AllocatorHandle.

Declaration

public static NativeArray<T> CreateNativeArray<T>(int length, AllocatorManager.AllocatorHandle allocator, NativeArrayOptions options = NativeArrayOptions.ClearMemory)
    where T : struct

Parameters

Type	Name	Description
Int32	length	The number of elements to allocate.
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle to use.
NativeArrayOptions	options	Options for allocation, such as whether to clear the memory.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

CreateNativeArray<T>(NativeArray<T>, AllocatorManager.AllocatorHandle)

Create a NativeArray from another NativeArray, using a provided AllocatorHandle.

Declaration

public static NativeArray<T> CreateNativeArray<T>(NativeArray<T> array, AllocatorManager.AllocatorHandle allocator)
    where T : struct

Parameters

Type	Name	Description
NativeArray<T>	array	The NativeArray to make a copy of.
AllocatorManager.AllocatorHandle	allocator	The AllocatorHandle to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.

CreateNativeArray<T, U>(T[], ref U)

Create a NativeArray from a managed array, using a provided Allocator.

Declaration

[ExcludeFromBurstCompatTesting("Managed array")]
public static NativeArray<T> CreateNativeArray<T, U>(T[] array, ref U allocator)
    where T : struct where U : struct, AllocatorManager.IAllocator

Parameters

Type	Name	Description
T[]	array	The managed array to make a copy of.
U	allocator	The Allocator to use.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.
U	The type of allocator.

CreateNativeArray<T, U>(Int32, ref U, NativeArrayOptions)

Create a NativeArray, using a provided allocator that implements IAllocator.

Declaration

public static NativeArray<T> CreateNativeArray<T, U>(int length, ref U allocator, NativeArrayOptions options = NativeArrayOptions.ClearMemory)
    where T : struct where U : struct, AllocatorManager.IAllocator

Parameters

Type	Name	Description
Int32	length	The number of elements to allocate.
U	allocator	The allocator to use.
NativeArrayOptions	options	Options for allocation, such as whether to clear the memory.

Returns

Type	Description
NativeArray<T>	Returns the NativeArray that was created.

Type Parameters

Name	Description
T	The type of the elements.
U	The type of allocator.

CreateNativeMultiHashMap<TKey, TValue, U>(Int32, ref U)

Create a NativeMultiHashMap from a managed array, using a provided Allocator.

Declaration

public static NativeMultiHashMap<TKey, TValue> CreateNativeMultiHashMap<TKey, TValue, U>(int length, ref U allocator)
    where TKey : struct, IEquatable<TKey> where TValue : struct where U : struct, AllocatorManager.IAllocator

Parameters

Type	Name	Description
Int32	length	The desired capacity of the NativeMultiHashMap.
U	allocator	The Allocator to use.

Returns

Type	Description
NativeMultiHashMap<TKey, TValue>	Returns the NativeMultiHashMap that was created.

Type Parameters

Name	Description
TKey	The type of the keys.
TValue	The type of the values.
U	The type of allocator.

Hash(Void*, Int32)

Returns a (non-cryptographic) hash of a memory block.

Declaration

public static uint Hash(void *ptr, int bytes)

Parameters

Type	Name	Description
Void*	ptr	A buffer.
Int32	bytes	The number of bytes to hash.

Returns

Type	Description
UInt32	A hash of the bytes.

Remarks

The hash function used is djb2.

IsAligned(UInt64, Int32)

Returns true if an offset has a given alignment.

Declaration

public static bool IsAligned(ulong offset, int alignmentPowerOfTwo)

Parameters

Type	Name	Description
UInt64	offset	An offset
Int32	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
Boolean	True if the offset is a multiple of `alignmentPowerOfTwo`.

Exceptions

Type	Condition
ArgumentException	Thrown if `alignmentPowerOfTwo` is not a non-zero, positive power of two.

IsAligned(Void*, Int32)

Returns true if the address represented by the pointer has a given alignment.

Declaration

public static bool IsAligned(void *p, int alignmentPowerOfTwo)

Parameters

Type	Name	Description
Void*	p	The pointer.
Int32	alignmentPowerOfTwo	A non-zero, positive power of two.

Returns

Type	Description
Boolean	True if the address is a multiple of `alignmentPowerOfTwo`.

Exceptions

Type	Condition
ArgumentException	Thrown if `alignmentPowerOfTwo` is not a non-zero, positive power of two.

IsPowerOfTwo(Int32)

Returns true if a positive value is a non-zero power of two.

Declaration

public static bool IsPowerOfTwo(int value)

Parameters

Type	Name	Description
Int32	value	A positive value.

Returns

Type	Description
Boolean	True if the value is a non-zero, positive power of two.

Remarks

Result is invalid if value < 0.

Log2Ceil(Int32)

Returns the binary logarithm of the value, but the result is rounded up to the nearest integer.

Declaration

public static int Log2Ceil(int value)

Parameters

Type	Name	Description
Int32	value	The value.

Returns

Type	Description
Int32	The binary logarithm of the `value`, but the result is rounded up to the nearest integer.

Log2Floor(Int32)

Returns the binary logarithm of the value, but the result is rounded down to the nearest integer.

Declaration

public static int Log2Floor(int value)

Parameters

Type	Name	Description
Int32	value	The value.

Returns

Type	Description
Int32	The binary logarithm of the `value`, but the result is rounded down to the nearest integer.