Struct NativeList<T>

An unmanaged, resizable list.

Implements

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 `index`.

Exceptions

Type	Condition
IndexOutOfRangeException	Thrown if `index` is out of bounds.

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 `inputDeps` and releases all resources (memory and safety handles) of this list.

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 `count` is negative.
ArgumentOutOfRangeException	Thrown if `index` is out of bounds.

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 `end < begin`.
ArgumentOutOfRangeException	Thrown if `begin` or `end` are out of bounds.

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 `index` is out of bounds.

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 `index` is out of bounds.

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 `index` is out of bounds, `count` is negative, or `index + count` exceeds the length.

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 `index` is out of bounds, `count` is negative, or `index + count` exceeds the length.

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)