Class Array<T>

Namespace

Godot.Collections

Assembly

GodotSharp.dll

Typed wrapper around Godot's Array class, an array of Variant typed elements allocated in the engine in C++. Useful when interfacing with the engine. Otherwise prefer .NET collections such as arrays or List<T>.

public sealed class Array<T> : IList<T>, ICollection<T>, IReadOnlyList<T>, IReadOnlyCollection<T>, IEnumerable<T>, IEnumerable

Type Parameters

T

The type of the array.

Inheritance

object

Array<T>

Implements

IList<T>

ICollection<T>

IReadOnlyList<T>

IReadOnlyCollection<T>

IEnumerable<T>

IEnumerable

Inherited Members

object.GetType()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

Array()

Constructs a new empty Array<T>.

public Array()

Array(Array)

Constructs a typed Array<T> from an untyped Array.

public Array(Array array)

Parameters

array Array

The untyped array to construct from.

Exceptions

ArgumentNullException

The array is null.

Array(IEnumerable<T>)

Constructs a new Array<T> from the given collection's elements.

public Array(IEnumerable<T> collection)

Parameters

collection IEnumerable<T>

The collection of elements to construct from.

Exceptions

ArgumentNullException

The collection is null.

Array(T[])

Constructs a new Array<T> from the given items.

public Array(T[] array)

Parameters

array T[]

The items to put in the new array.

Exceptions

ArgumentNullException

The array is null.

Properties

Count

Returns the number of elements in this Array<T>. This is also known as the size or length of the array.

public int Count { get; }

Property Value

int

The number of elements.

IsReadOnly

Returns true if the array is read-only. See MakeReadOnly().

public bool IsReadOnly { get; }

Property Value

bool

this[int]

Returns the item at the given index.

public T this[int index] { get; set; }

Parameters

index int

Property Value

T

The Variant item at the given index.

Exceptions

InvalidOperationException

The property is assigned and the array is read-only.

ArgumentOutOfRangeException

index is less than 0 or greater than the array's size.

Methods

Add(T)

Adds an item to the end of this Array<T>. This is the same as append or push_back in GDScript.

public void Add(T item)

Parameters

item T

The Variant item to add.

Exceptions

InvalidOperationException

The array is read-only.

AddRange(IEnumerable<T>)

Adds the elements of the specified collection to the end of this Array<T>.

public void AddRange(IEnumerable<T> collection)

Parameters

collection IEnumerable<T>

Collection of Variant items to add.

Exceptions

InvalidOperationException

The array is read-only.

ArgumentNullException

The collection is null.

BinarySearch(int, int, T)

Finds the index of an existing value using binary search. If the value is not present in the array, it returns the bitwise complement of the insertion index that maintains sorting order. Note: Calling BinarySearch(int, int, T) on an unsorted array results in unexpected behavior.

public int BinarySearch(int index, int count, T item)

Parameters

index int

The starting index of the range to search.

count int

The length of the range to search.

item T

The object to locate.

Returns

int

The index of the item in the array, if item is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than item or, if there is no larger element, the bitwise complement of Count.

Exceptions

ArgumentOutOfRangeException

index is less than 0. -or- count is less than 0.

ArgumentException

index and count do not denote a valid range in the Array<T>.

BinarySearch(T)

Finds the index of an existing value using binary search. If the value is not present in the array, it returns the bitwise complement of the insertion index that maintains sorting order. Note: Calling BinarySearch(T) on an unsorted array results in unexpected behavior.

public int BinarySearch(T item)

Parameters

item T

The object to locate.

Returns

int

The index of the item in the array, if item is found; otherwise, a negative number that is the bitwise complement of the index of the next element that is larger than item or, if there is no larger element, the bitwise complement of Count.

Clear()

Clears the array. This is the equivalent to using Resize(int) with a size of 0

public void Clear()

Exceptions

InvalidOperationException

The array is read-only.

Contains(T)

Returns true if the array contains the given value.

public bool Contains(T item)

Parameters

item T

The item to look for.

Returns

bool

Whether or not this array contains the given item.

Examples

var arr = new Godot.Collections.Array<string> { "inside", "7" };
GD.Print(arr.Contains("inside")); // True
GD.Print(arr.Contains("outside")); // False
GD.Print(arr.Contains(7)); // False
GD.Print(arr.Contains("7")); // True

CopyTo(T[], int)

Copies the elements of this Array<T> to the given C# array, starting at the given index.

public void CopyTo(T[] array, int arrayIndex)

Parameters

array T[]

The C# array to copy to.

arrayIndex int

The index to start at.

Exceptions

ArgumentNullException

The array is null.

ArgumentOutOfRangeException

arrayIndex is less than 0 or greater than the array's size.

ArgumentException

The destination array was not long enough.

Duplicate(bool)

Duplicates this Array<T>.

public Array<T> Duplicate(bool deep = false)

Parameters

deep bool

If true, performs a deep copy.

Returns

Array<T>

A new Godot Array.

Fill(T)

Assigns the given value to all elements in the array. This can typically be used together with Resize(int) to create an array with a given size and initialized elements. Note: If value is of a reference type (GodotObject derived, Array or Dictionary, etc.) then the array is filled with the references to the same object, i.e. no duplicates are created.

public void Fill(T value)

Parameters

value T

The value to fill the array with.

Examples

var array = new Godot.Collections.Array<int>();
array.Resize(10);
array.Fill(0); // Initialize the 10 elements to 0.

Exceptions

InvalidOperationException

The array is read-only.

GetEnumerator()

Gets an enumerator for this Array<T>.

public IEnumerator<T> GetEnumerator()

Returns

IEnumerator<T>

An enumerator.

GetSliceRange(int, int, int, bool)

Returns the slice of the Array<T>, from start (inclusive) to end (exclusive), as a new Array<T>. The absolute value of start and end will be clamped to the array size. If either start or end are negative, they will be relative to the end of the array (i.e. arr.GetSliceRange(0, -2) is a shorthand for arr.GetSliceRange(0, arr.Count - 2)). If specified, step is the relative index between source elements. It can be negative, then start must be higher than end. For example, [0, 1, 2, 3, 4, 5].GetSliceRange(5, 1, -2) returns [5, 3]. If deep is true, each element will be copied by value rather than by reference.

public Array<T> GetSliceRange(int start, int end, int step = 1, bool deep = false)

Parameters

start int

The zero-based index at which the range starts.

end int

The zero-based index at which the range ends.

step int

The relative index between source elements to take.

deep bool

If true, performs a deep copy.

Returns

Array<T>

A new array that contains the elements inside the slice range.

IndexOf(T)

Searches the array for a value and returns its index or -1 if not found.

public int IndexOf(T item)

Parameters

item T

The Variant item to search for.

Returns

int

The index of the item, or -1 if not found.

IndexOf(T, int)

Searches the array for a value and returns its index or -1 if not found.

public int IndexOf(T item, int index)

Parameters

item T

The Variant item to search for.

index int

The initial search index to start from.

Returns

int

The index of the item, or -1 if not found.

Exceptions

ArgumentOutOfRangeException

index is less than 0 or greater than the array's size.

Insert(int, T)

Inserts a new element at a given position in the array. The position must be valid, or at the end of the array (pos == Count - 1). Existing items will be moved to the right.

public void Insert(int index, T item)

Parameters

index int

The index to insert at.

item T

The Variant item to insert.

Exceptions

InvalidOperationException

The array is read-only.

ArgumentOutOfRangeException

index is less than 0 or greater than the array's size.

LastIndexOf(Variant)

Searches the array for a value in reverse order and returns its index or -1 if not found.

public int LastIndexOf(Variant item)

Parameters

item Variant

The Variant item to search for.

Returns

int

The index of the item, or -1 if not found.

LastIndexOf(Variant, int)

Searches the array for a value in reverse order and returns its index or -1 if not found.

public int LastIndexOf(Variant item, int index)

Parameters

item Variant

The Variant item to search for.

index int

The initial search index to start from.

Returns

int

The index of the item, or -1 if not found.

Exceptions

ArgumentOutOfRangeException

index is less than 0 or greater than the array's size.

MakeReadOnly()

Makes the Array<T> read-only, i.e. disabled modying of the array's elements. Does not apply to nested content, e.g. content of nested arrays.

public void MakeReadOnly()

Max()

Returns the maximum value contained in the array if all elements are of comparable types. If the elements can't be compared, default is returned.

public T Max()

Returns

T

The maximum value contained in the array.

Min()

Returns the minimum value contained in the array if all elements are of comparable types. If the elements can't be compared, default is returned.

public T Min()

Returns

T

The minimum value contained in the array.

PickRandom()

Returns a random value from the target array.

public T PickRandom()

Returns

T

A random element from the array.

Examples

var array = new Godot.Collections.Array<int> { 1, 2, 3, 4 };
GD.Print(array.PickRandom()); // Prints either of the four numbers.

RecursiveEqual(Array<T>)

Compares this Array<T> against the otherArray<T> recursively. Returns true if the sizes and contents of the arrays are equal, false otherwise.

public bool RecursiveEqual(Array<T> other)

Parameters

other Array<T>

The other array to compare against.

Returns

bool

true if the sizes and contents of the arrays are equal, false otherwise.

Remove(T)

Removes the first occurrence of the specified item from this Array<T>.

public bool Remove(T item)

Parameters

item T

The value to remove.

Returns

bool

A bool indicating success or failure.

Exceptions

InvalidOperationException

The array is read-only.

RemoveAt(int)

Removes an element from the array by index. To remove an element by searching for its value, use Remove(T) instead.

public void RemoveAt(int index)

Parameters

index int

The index of the element to remove.

Exceptions

InvalidOperationException

The array is read-only.

ArgumentOutOfRangeException

index is less than 0 or greater than the array's size.

Resize(int)

Resizes this Array<T> to the given size.

public Error Resize(int newSize)

Parameters

newSize int

The new size of the array.

Returns

Error

Ok if successful, or an error code.

Exceptions

InvalidOperationException

The array is read-only.

Reverse()

Reverses the order of the elements in the array.

public void Reverse()

Exceptions

InvalidOperationException

The array is read-only.

Shuffle()

Shuffles the array such that the items will have a random order. This method uses the global random number generator common to methods such as Randi(). Call Randomize() to ensure that a new seed will be used each time if you want non-reproducible shuffling.

public void Shuffle()

Exceptions

InvalidOperationException

The array is read-only.

Slice(int)

Creates a shallow copy of a range of elements in the source Array<T>.

public Array<T> Slice(int start)

Parameters

start int

The zero-based index at which the range starts.

Returns

Array<T>

A new array that contains the elements inside the slice range.

Exceptions

ArgumentOutOfRangeException

start is less than 0 or greater than the array's size.

Slice(int, int)

Creates a shallow copy of a range of elements in the source Array<T>.

public Array<T> Slice(int start, int length)

Parameters

start int

The zero-based index at which the range starts.

length int

The length of the range.

Returns

Array<T>

A new array that contains the elements inside the slice range.

Exceptions

ArgumentOutOfRangeException

start is less than 0 or greater than the array's size. -or- length is less than 0 or greater than the array's size.

Sort()

Sorts the array. Note: The sorting algorithm used is not stable. This means that values considered equal may have their order changed when using Sort(). Note: Strings are sorted in alphabetical order (as opposed to natural order). This may lead to unexpected behavior when sorting an array of strings ending with a sequence of numbers. To sort with a custom predicate use OrderBy<TSource, TKey>(IEnumerable<TSource>, Func<TSource, TKey>).

public void Sort()

Examples

var strings = new Godot.Collections.Array<string> { "string1", "string2", "string10", "string11" };
strings.Sort();
GD.Print(strings); // Prints [string1, string10, string11, string2]

Exceptions

InvalidOperationException

The array is read-only.

ToString()

Converts this Array<T> to a string.

public override string ToString()

Returns

string

A string representation of this array.

Operators

operator +(Array<T>, Array<T>)

Concatenates two Array<T>s together, with the right being added to the end of the Array<T> specified in left. For example, [1, 2] + [3, 4] results in [1, 2, 3, 4].

public static Array<T> operator +(Array<T> left, Array<T> right)

Parameters

left Array<T>

The first array.

right Array<T>

The second array.

Returns

Array<T>

A new Godot Array with the contents of both arrays.

explicit operator Array(Array<T>)

Converts this typed Array<T> to an untyped Array.

public static explicit operator Array(Array<T> from)

Parameters

from Array<T>

The typed array to convert.

Returns

Array

A new Godot Array, or null if was null.

explicit operator Array<T>(Variant)

public static explicit operator Array<T>(Variant from)

Parameters

from Variant

Returns

Array<T>

implicit operator Variant(Array<T>)

public static implicit operator Variant(Array<T> from)

Parameters

from Array<T>

Returns

Variant