Struct NativeList<T>
An unmanaged, resizable list.
Namespace: Unity.Collections
Assembly: Unity.Collections.dll
Syntax
[NativeContainer]
public struct NativeList<T> : INativeDisposable, INativeList<T>, IIndexable<T> where T : unmanaged
Type Parameters
Name | Description |
---|---|
T | The type of the elements. |
Remarks
The elements are stored contiguously in a buffer rather than as linked nodes.
Constructors
NativeList(int, AllocatorHandle)
Initializes and returns a NativeList.
Declaration
public NativeList(int initialCapacity, AllocatorManager.AllocatorHandle allocator)
Parameters
Type | Name | Description |
---|---|---|
int | initialCapacity | The initial capacity of the list. |
AllocatorManager.AllocatorHandle | allocator | The allocator to use. |
NativeList(AllocatorHandle)
Initializes and returns a NativeList with a capacity of one.
Declaration
public NativeList(AllocatorManager.AllocatorHandle allocator)
Parameters
Type | Name | Description |
---|---|---|
AllocatorManager.AllocatorHandle | allocator | The allocator to use. |
Properties
Capacity
The number of elements that fit in the current allocation.
Declaration
public int Capacity { readonly get; set; }
Property Value
Type | Description |
---|---|
int | The number of elements that fit in the current allocation. |
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | Thrown if the new capacity is smaller than the length. |
IsCreated
Whether this list has been allocated (and not yet deallocated).
Declaration
public readonly bool IsCreated { get; }
Property Value
Type | Description |
---|---|
bool | True if this list has been allocated (and not yet deallocated). |
IsEmpty
Whether this list is empty.
Declaration
public readonly bool IsEmpty { get; }
Property Value
Type | Description |
---|---|
bool | True if the list is empty or if the list has not been constructed. |
this[int]
The element at a given index.
Declaration
public T this[int index] { get; set; }
Parameters
Type | Name | Description |
---|---|---|
int | index | An index into this list. |
Property Value
Type | Description |
---|---|
T | The value to store at the |
Exceptions
Type | Condition |
---|---|
IndexOutOfRangeException | Thrown if |
Length
The count of elements.
Declaration
public int Length { readonly get; set; }
Property Value
Type | Description |
---|---|
int | The current count of elements. Always less than or equal to the capacity. |
Remarks
To decrease the memory used by a list, set Capacity after reducing the length of the list.
Methods
Add(in T)
Appends an element to the end of this list.
Declaration
public void Add(in T value)
Parameters
Type | Name | Description |
---|---|---|
T | value | The value to add to the end of this list. |
Remarks
Length is incremented by 1. If necessary, the capacity is increased.
AddNoResize(T)
Appends an element to the end of this list.
Declaration
public void AddNoResize(T value)
Parameters
Type | Name | Description |
---|---|---|
T | value | The value to add to the end of this list. |
Remarks
Length is incremented by 1. Will not increase the capacity.
Exceptions
Type | Condition |
---|---|
InvalidOperationException | Thrown if incrementing the length would exceed the capacity. |
AddRange(void*, int)
Appends the elements of a buffer to the end of this list.
Declaration
public void AddRange(void* ptr, int count)
Parameters
Type | Name | Description |
---|---|---|
void* | ptr | The buffer to copy from. |
int | count | The number of elements to copy from the buffer. |
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | Thrown if count is negative. |
AddRange(NativeArray<T>)
Appends the elements of an array to the end of this list.
Declaration
public void AddRange(NativeArray<T> array)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<T> | array | The array to copy from. |
Remarks
Length is increased by the number of new elements. Does not increase the capacity.
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | Thrown if the increased length would exceed the capacity. |
AddRangeNoResize(void*, int)
Appends elements from a buffer to the end of this list.
Declaration
public void AddRangeNoResize(void* ptr, int count)
Parameters
Type | Name | Description |
---|---|---|
void* | ptr | The buffer to copy from. |
int | count | The number of elements to copy from the buffer. |
Remarks
Length is increased by the count. Will not increase the capacity.
Exceptions
Type | Condition |
---|---|
InvalidOperationException | Thrown if the increased length would exceed the capacity. |
AddRangeNoResize(NativeList<T>)
Appends the elements of another list to the end of this list.
Declaration
public void AddRangeNoResize(NativeList<T> list)
Parameters
Type | Name | Description |
---|---|---|
NativeList<T> | list | The other list to copy from. |
Remarks
Length is increased by the length of the other list. Will not increase the capacity.
Exceptions
Type | Condition |
---|---|
InvalidOperationException | Thrown if the increased length would exceed the capacity. |
AddReplicate(in T, int)
Appends value count times to the end of this list.
Declaration
public void AddReplicate(in T value, int count)
Parameters
Type | Name | Description |
---|---|---|
T | value | The value to add to the end of this list. |
int | count | The number of times to replicate the value. |
Remarks
Length is incremented by count. If necessary, the capacity is increased.
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | Thrown if count is negative. |
AsArray()
Returns a native array that aliases the content of this list.
Declaration
public NativeArray<T> AsArray()
Returns
Type | Description |
---|---|
NativeArray<T> | A native array that aliases the content of this list. |
AsDeferredJobArray()
Returns an array that aliases this list. The length of the array is updated when the length of this array is updated in a prior job.
Declaration
public NativeArray<T> AsDeferredJobArray()
Returns
Type | Description |
---|---|
NativeArray<T> | An array that aliases this list and whose length can be specially modified across jobs. |
Remarks
Useful when a job populates a list that is then used by another job.
If you pass both jobs the same list, you have to complete the first job before you schedule the second: otherwise, the second job doesn't see the first job's changes to the list's length.
If instead you pass the second job a deferred array that aliases the list, the array's length is kept in sync with the first job's changes to the list's length. Consequently, the first job doesn't have to be completed before you can schedule the second: the second job simply has to depend upon the first.
Examples
The following example populates a list with integers in one job and passes that data to a second job as a deferred array. If we tried to pass the list directly to the second job, that job would not see any modifications made to the list by the first job. To avoid this, we instead pass the second job a deferred array that aliases the list.
using UnityEngine;
using Unity.Jobs;
using Unity.Collections;
public class DeferredArraySum : MonoBehaviour
{
public struct Populate : IJob
{
public NativeList<int> list;
public void Execute()
{
for (int i = list.Length; i < list.Capacity; i++)
{
list.Add(i);
}
}
}
// Sums all numbers from deferred.
public struct Sum : IJob
{
[ReadOnly] public NativeArray<int> deferred;
public NativeArray<int> sum;
public void Execute()
{
sum[0] = 0;
for (int i = 0; i < deferred.Length; i++)
{
sum[0] += deferred[i];
}
}
}
void Start()
{
var list = new NativeList<int>(100, Allocator.TempJob);
var deferred = list.AsDeferredJobArray(),
var output = new NativeArray<int>(1, Allocator.TempJob);
// The Populate job increases the list's length from 0 to 100.
var populate = new Populate { list = list }.Schedule();
// At time of scheduling, the length of the deferred array given to Sum is 0.
// When Populate increases the list's length, the deferred array's length field in the
// Sum job is also modified, even though it has already been scheduled.
var sum = new Sum { deferred = deferred, sum = output }.Schedule(populate);
sum.Complete();
Debug.Log("Result: " + output[0]);
list.Dispose();
output.Dispose();
}
}
AsParallelReader()
Returns a parallel reader of this list.
Declaration
public NativeArray<T>.ReadOnly AsParallelReader()
Returns
Type | Description |
---|---|
NativeArray<T>.ReadOnly | A parallel reader of this list. |
AsParallelWriter()
Returns a parallel writer of this list.
Declaration
public NativeList<T>.ParallelWriter AsParallelWriter()
Returns
Type | Description |
---|---|
NativeList<T>.ParallelWriter | A parallel writer of this list. |
AsReadOnly()
Returns a read only of this list.
Declaration
public NativeArray<T>.ReadOnly AsReadOnly()
Returns
Type | Description |
---|---|
NativeArray<T>.ReadOnly | A read only of this list. |
Clear()
Sets the length to 0.
Declaration
public void Clear()
Remarks
Does not change the capacity.
CopyFrom(in UnsafeList<T>)
Copies all elements of specified container to this container.
Declaration
public void CopyFrom(in UnsafeList<T> other)
Parameters
Type | Name | Description |
---|---|---|
UnsafeList<T> | other | An container to copy into this container. |
CopyFrom(in NativeArray<T>)
Copies all elements of specified container to this container.
Declaration
public void CopyFrom(in NativeArray<T> other)
Parameters
Type | Name | Description |
---|---|---|
NativeArray<T> | other | An container to copy into this container. |
CopyFrom(in NativeList<T>)
Copies all elements of specified container to this container.
Declaration
public void CopyFrom(in NativeList<T> other)
Parameters
Type | Name | Description |
---|---|---|
NativeList<T> | other | An container to copy into this container. |
Dispose()
Releases all resources (memory and safety handles).
Declaration
public void Dispose()
Dispose(JobHandle)
Creates and schedules a job that releases all resources (memory and safety handles) of this list.
Declaration
public JobHandle Dispose(JobHandle inputDeps)
Parameters
Type | Name | Description |
---|---|---|
JobHandle | inputDeps | The dependency for the new job. |
Returns
Type | Description |
---|---|
JobHandle | The handle of the new job. The job depends upon |
ElementAt(int)
Returns a reference to the element at an index.
Declaration
public ref T ElementAt(int index)
Parameters
Type | Name | Description |
---|---|---|
int | index | An index. |
Returns
Type | Description |
---|---|
T | A reference to the element at the index. |
Exceptions
Type | Condition |
---|---|
IndexOutOfRangeException | Thrown if index is out of bounds. |
GetEnumerator()
Returns an enumerator over the elements of this list.
Declaration
public NativeArray<T>.Enumerator GetEnumerator()
Returns
Type | Description |
---|---|
NativeArray<T>.Enumerator | An enumerator over the elements of this list. |
GetUnsafeList()
Returns the internal unsafe list.
Declaration
public UnsafeList<T>* GetUnsafeList()
Returns
Type | Description |
---|---|
UnsafeList<T>* | The internal unsafe list. |
Remarks
Internally, the elements of a NativeList are stored in an UnsafeList.
InsertRange(int, int)
Shifts elements toward the end of this list, increasing its length.
Declaration
public void InsertRange(int index, int count)
Parameters
Type | Name | Description |
---|---|---|
int | index | The index of the first element that will be shifted up. |
int | count | The number of elements to insert. |
Remarks
Right-shifts elements in the list so as to create 'free' slots at the beginning or in the middle.
The length is increased by count
. If necessary, the capacity will be increased accordingly.
If count
equals 0
, the method does nothing.
The element at index index
will be copied to index index + count
, the element at index index + 1
will be copied to index + count + 1
, and so forth.
The indexes index
up to index + count
are not cleared: they will contain whatever values they held prior.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if |
ArgumentOutOfRangeException | Thrown if |
InsertRangeWithBeginEnd(int, int)
Shifts elements toward the end of this list, increasing its length.
Declaration
public void InsertRangeWithBeginEnd(int begin, int end)
Parameters
Type | Name | Description |
---|---|---|
int | begin | The index of the first element that will be shifted up. |
int | end | The index where the first shifted element will end up. |
Remarks
Right-shifts elements in the list so as to create 'free' slots at the beginning or in the middle.
The length is increased by end - begin
. If necessary, the capacity will be increased accordingly.
If end
equals begin
, the method does nothing.
The element at index begin
will be copied to index end
, the element at index begin + 1
will be copied to end + 1
, and so forth.
The indexes begin
up to end
are not cleared: they will contain whatever values they held prior.
Exceptions
Type | Condition |
---|---|
ArgumentException | Thrown if |
ArgumentOutOfRangeException | Thrown if |
RemoveAt(int)
Removes the element at an index, shifting everything above it down by one. Decrements the length by 1.
Declaration
public void RemoveAt(int index)
Parameters
Type | Name | Description |
---|---|---|
int | index | The index of the item to remove. |
Remarks
If you don't care about preserving the order of the elements, RemoveAtSwapBack(int) is a more efficient way to remove elements.
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | Thrown if |
RemoveAtSwapBack(int)
Copies the last element of this list to the specified index. Decrements the length by 1.
Declaration
public void RemoveAtSwapBack(int index)
Parameters
Type | Name | Description |
---|---|---|
int | index | The index to overwrite with the last element. |
Remarks
Useful as a cheap way to remove an element from this list when you don't care about preserving order.
Exceptions
Type | Condition |
---|---|
IndexOutOfRangeException | Thrown if |
RemoveRange(int, int)
Removes N elements in a range, shifting everything above the range down by N. Decrements the length by N.
Declaration
public void RemoveRange(int index, int count)
Parameters
Type | Name | Description |
---|---|---|
int | index | The index of the first element to remove. |
int | count | The number of elements to remove. |
Remarks
If you don't care about preserving the order of the elements, RemoveRangeSwapBackWithBeginEnd
is a more efficient way to remove elements.
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | Thrown if |
RemoveRangeSwapBack(int, int)
Copies the last N elements of this list to a range in this list. Decrements the length by N.
Declaration
public void RemoveRangeSwapBack(int index, int count)
Parameters
Type | Name | Description |
---|---|---|
int | index | The index of the first element to overwrite. |
int | count | The number of elements to copy and remove. |
Remarks
Copies the last count
elements to the indexes index
up to index + count
.
Useful as a cheap way to remove elements from a list when you don't care about preserving order.
Exceptions
Type | Condition |
---|---|
ArgumentOutOfRangeException | Thrown if |
Resize(int, NativeArrayOptions)
Sets the length of this list, increasing the capacity if necessary.
Declaration
public void Resize(int length, NativeArrayOptions options)
Parameters
Type | Name | Description |
---|---|---|
int | length | The new length of this list. |
NativeArrayOptions | options | Whether to clear any newly allocated bytes to all zeroes. |
ResizeUninitialized(int)
Sets the length of this list, increasing the capacity if necessary.
Declaration
public void ResizeUninitialized(int length)
Parameters
Type | Name | Description |
---|---|---|
int | length | The new length of this list. |
Remarks
Does not clear newly allocated bytes.
SetCapacity(int)
Sets the capacity.
Declaration
public void SetCapacity(int capacity)
Parameters
Type | Name | Description |
---|---|---|
int | capacity | The new capacity. |
ToArray(AllocatorHandle)
Returns an array containing a copy of this list's content.
Declaration
public NativeArray<T> ToArray(AllocatorManager.AllocatorHandle allocator)
Parameters
Type | Name | Description |
---|---|---|
AllocatorManager.AllocatorHandle | allocator | The allocator to use. |
Returns
Type | Description |
---|---|
NativeArray<T> | An array containing a copy of this list's content. |
TrimExcess()
Sets the capacity to match the length.
Declaration
public void TrimExcess()
Operators
implicit operator NativeArray<T>(NativeList<T>)
Obsolete. Use AsArray() method to do explicit cast instead.
Declaration
[Obsolete("Implicit cast from `NativeList<T>` to `NativeArray<T>` has been deprecated; Use '.AsArray()' method to do explicit cast instead.", false)]
public static implicit operator NativeArray<T>(NativeList<T> nativeList)
Parameters
Type | Name | Description |
---|---|---|
NativeList<T> | nativeList | The list to alias. |
Returns
Type | Description |
---|---|
NativeArray<T> | A native array that aliases the content of the list. |
Remarks
Returns a native array that aliases the content of a list.