Struct NativeList<T> | Collections | 0.6.0-preview.9
docs.unity3d.com
    Show / Hide Table of Contents

    Struct NativeList<T>

    An unmanaged, resizable list.

    Namespace: Unity.Collections
    Syntax
    public struct NativeList<T> : IEnumerable<T>, IEnumerable, IDisposable where T : struct
    Type Parameters
    Name Description
    T

    The type of the elements in the container.

    Constructors

    NativeList(Allocator)

    Constructs a new list using the specified type of memory allocation.

    Declaration
    public NativeList(Allocator allocator)
    Parameters
    Type Name Description
    Allocator allocator

    A member of the Unity.Collections.Allocator enumeration.

    Remarks

    The list initially has a capacity of one. To avoid reallocating memory for the list, specify sufficient capacity up front.

    NativeList(Int32, Allocator)

    Constructs a new list with the specified initial capacity and type of memory allocation.

    Declaration
    public NativeList(int initialCapacity, Allocator allocator)
    Parameters
    Type Name Description
    Int32 initialCapacity

    The initial capacity of the list. If the list grows larger than its capacity, the internal array is copied to a new, larger array.

    Allocator allocator

    A member of the Unity.Collections.Allocator enumeration.

    Properties

    Capacity

    The number of items that can fit in the list.

    Declaration
    public int Capacity { get; set; }
    Property Value
    Type Description
    Int32

    The number of items that the list can hold before it resizes its internal storage.

    Remarks

    Capacity specifies the number of items the list can currently hold. You can change Capacity to fit more or fewer items. Changing Capacity creates a new array of the specified size, copies the old array to the new one, and then deallocates the original array memory. You cannot change the Capacity to a size smaller than Length (remove unwanted elements from the list first).

    Exceptions
    Type Condition
    ArgumentException

    Thrown if Capacity is set smaller than Length.

    IsCreated

    Reports whether memory for the container is allocated.

    Declaration
    public bool IsCreated { get; }
    Property Value
    Type Description
    Boolean

    True if this container object's internal storage has been allocated.

    Remarks

    Note that the container storage is not created if you use the default constructor. You must specify at least an allocation type to construct a usable container.

    Item[Int32]

    Retrieve a member of the contaner by index.

    Declaration
    public T this[int index] { get; set; }
    Parameters
    Type Name Description
    Int32 index

    The zero-based index into the list.

    Property Value
    Type Description
    T

    The list item at the specified index.

    Exceptions
    Type Condition
    IndexOutOfRangeException

    Thrown if index is negative or >= to Length.

    Length

    The current number of items in the list.

    Declaration
    public int Length { get; }
    Property Value
    Type Description
    Int32

    The item count.

    Methods

    Add(T)

    Adds an element to the list.

    Declaration
    public void Add(T value)
    Parameters
    Type Name Description
    T value
    Remarks

    If the list has reached its current capacity, it copies the original, internal array to a new, larger array, and then deallocates the original.

    AddNoResize(T)

    Adds an element to the list.

    Declaration
    public void AddNoResize(T value)
    Parameters
    Type Name Description
    T value

    The value to be added at the end of the list.

    Remarks

    If the list has reached its current capacity, internal array won't be resized, and exception will be thrown.

    AddRange(NativeArray<T>)

    Adds the elements of a NativeArray to this list.

    Declaration
    public void AddRange(NativeArray<T> elements)
    Parameters
    Type Name Description
    NativeArray<T> elements

    The items to add.

    AddRange(Void*, Int32)

    Adds elements from a buffer to this list.

    Declaration
    public void AddRange(void *elements, int count)
    Parameters
    Type Name Description
    Void* elements

    A pointer to the buffer.

    Int32 count

    The number of elements to add to the list.

    AddRangeNoResize(Void*, Int32)

    Adds elements from a buffer to this list.

    Declaration
    public void AddRangeNoResize(void *ptr, int length)
    Parameters
    Type Name Description
    Void* ptr

    A pointer to the buffer.

    Int32 length

    The number of elements to add to the list.

    Remarks

    If the list has reached its current capacity, internal array won't be resized, and exception will be thrown.

    AddRangeNoResize(NativeList<T>)

    Adds elements from a list to this list.

    Declaration
    public void AddRangeNoResize(NativeList<T> list)
    Parameters
    Type Name Description
    NativeList<T> list
    Remarks

    If the list has reached its current capacity, internal array won't be resized, and exception will be thrown.

    AsArray()

    This list as a NativeArray.

    Declaration
    public NativeArray<T> AsArray()
    Returns
    Type Description
    NativeArray<T>

    A NativeArray "view" of the list.

    Remarks

    The array is not a copy; it references the same memory as the original list. You can use the NativeArray API to manipulate the list.

    AsDeferredJobArray()

    Provides a NativeArray that you can pass into a job whose contents can be modified by a previous job.

    Declaration
    public NativeArray<T> AsDeferredJobArray()
    Returns
    Type Description
    NativeArray<T>

    A NativeArray that can be passed to one job as a "promise" that is fulfilled by a previous job.

    Remarks

    Pass a deferred array to a job when the list is populated or modified by a previous job. Using a deferred array allows you to schedule both jobs at the same time. (Without a deferred array, you would have to wait for the results of the first job before you scheduling the second.)

    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 you tried to pass the list directly to the second job, that job would get the contents of the list at the time you schedule the job and would not see any modifications made to the list by the first job.

    using UnityEngine;
    using Unity.Jobs;
    using Unity.Collections;
    
    public class DeferredArraySum : MonoBehaviour
    {
       public struct ListPopulatorJob : IJob
       {
           public NativeList<int> list;
    
           public void Execute()
           {
               for (int i = list.Length; i < list.Capacity; i++)
               {
                   list.Add(i);
               }
           }
       }
    
       public struct ArraySummerJob : IJob
       {
           [ReadOnly] public NativeArray<int> deferredArray;
           public NativeArray<int> sum;
    
           public void Execute()
           {
               sum[0] = 0;
               for (int i = 0; i < deferredArray.Length; i++)
               {
                   sum[0] += deferredArray[i];
               }
           }
       }
    
       void Start()
       {
           var deferredList = new NativeList<int>(100, Allocator.TempJob);
    
           var populateJob = new ListPopulatorJob()
           {
               list = deferredList
           };
    
           var output = new NativeArray<int>(1, Allocator.TempJob);
           var sumJob = new ArraySummerJob()
           {
               deferredArray = deferredList.AsDeferredJobArray(),
               sum = output
           };
    
           var populateJobHandle = populateJob.Schedule();
           var sumJobHandle = sumJob.Schedule(populateJobHandle);
    
           sumJobHandle.Complete();
    
           Debug.Log("Result: " + output[0]);
    
           deferredList.Dispose();
           output.Dispose();
       }
    }

    AsParallelWriter()

    Returns parallel writer instance.

    Declaration
    public NativeList<T>.ParallelWriter AsParallelWriter()
    Returns
    Type Description
    NativeList.ParallelWriter<>

    Clear()

    Clears the list.

    Declaration
    public void Clear()
    Remarks

    List Capacity remains unchanged.

    CopyFrom(T[])

    Overwrites this list with the elements of an array.

    Declaration
    public void CopyFrom(T[] array)
    Parameters
    Type Name Description
    T[] array

    A managed array or NativeArray to copy into this list.

    Dispose()

    Disposes of this container and deallocates its memory immediately.

    Declaration
    public void Dispose()

    Dispose(JobHandle)

    Safely disposes of this container and deallocates its memory when the jobs that use it have completed.

    Declaration
    public JobHandle Dispose(JobHandle inputDeps)
    Parameters
    Type Name Description
    JobHandle inputDeps

    The job handle or handles for any scheduled jobs that use this container.

    Returns
    Type Description
    JobHandle

    A new job handle containing the prior handles as well as the handle for the job that deletes the container.

    Remarks

    You can call this function dispose of the container immediately after scheduling the job. Pass the JobHandle returned by the Job.Schedule method using the jobHandle parameter so the job scheduler can dispose the container after all jobs using it have run.

    GetEnumerator()

    Declaration
    public NativeArray<T>.Enumerator GetEnumerator()
    Returns
    Type Description
    NativeArray.Enumerator<>

    RemoveAtSwapBack(Int32)

    Truncates the list by replacing the item at the specified index with the last item in the list. The list is shortened by one.

    Declaration
    public void RemoveAtSwapBack(int index)
    Parameters
    Type Name Description
    Int32 index

    The index of the item to delete.

    Exceptions
    Type Condition
    ArgumentOutOfRangeException

    If index is negative or >= Length.

    Resize(Int32, NativeArrayOptions)

    Changes the list length, resizing if necessary.

    Declaration
    public void Resize(int length, NativeArrayOptions options)
    Parameters
    Type Name Description
    Int32 length

    The new length of the list.

    NativeArrayOptions options

    Memory should be cleared on allocation or left uninitialized.

    ResizeUninitialized(Int32)

    Changes the container length, resizing if necessary, without initializing memory.

    Declaration
    public void ResizeUninitialized(int length)
    Parameters
    Type Name Description
    Int32 length

    The new length of the container.

    ToArray()

    A copy of this list as a NativeArray.

    Declaration
    public T[] ToArray()
    Returns
    Type Description
    T[]

    A NativeArray containing copies of all the items in the list.

    ToArray(Allocator)

    A copy of this list as a NativeArray allocated with the specified type of memory.

    Declaration
    public NativeArray<T> ToArray(Allocator allocator)
    Parameters
    Type Name Description
    Allocator allocator

    A member of the Unity.Collections.Allocator enumeration.

    Returns
    Type Description
    NativeArray<T>

    A NativeArray containing copies of all the items in the list.

    Operators

    Implicit(NativeList<T> to NativeArray<T>)

    This list as a NativeArray.

    Declaration
    public static implicit operator NativeArray<T>(NativeList<T> nativeList)
    Parameters
    Type Name Description
    NativeList<T> nativeList

    A NativeList instance.

    Returns
    Type Description
    NativeArray<T>

    A NativeArray containing all the items in the list.

    Remarks

    The array is not a copy; it references the same memory as the original list.

    Extension Methods

    NativeArrayExtensions.Contains<T, U>(NativeList<T>, U)
    NativeArrayExtensions.IndexOf<T, U>(NativeList<T>, U)
    JobNativeMultiHashMapVisitKeyValue.Schedule<TJob, TKey, TValue>(TJob, NativeMultiHashMap<TKey, TValue>, Int32, JobHandle)
    JobNativeMultiHashMapVisitKeyMutableValue.Schedule<TJob, TKey, TValue>(TJob, NativeMultiHashMap<TKey, TValue>, Int32, JobHandle)
    NativeSortExtension.Sort<T, U>(NativeList<T>, U)
    JobUnsafeMultiHashMapVisitKeyValue.Schedule<TJob, TKey, TValue>(TJob, UnsafeMultiHashMap<TKey, TValue>, Int32, JobHandle)
    JobUnsafeMultiHashMapVisitKeyMutableValue.Schedule<TJob, TKey, TValue>(TJob, UnsafeMultiHashMap<TKey, TValue>, Int32, JobHandle)
    NativeListUnsafeUtility.GetUnsafePtr<T>(NativeList<T>)
    NativeListUnsafeUtility.GetUnsafeReadOnlyPtr<T>(NativeList<T>)
    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023