Class Array

Namespace

Godot.Collections

Assembly

GodotSharp.dll

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 Array or List<T>.

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

Inheritance

object

Array

Implements

IList<Variant>

ICollection<Variant>

IReadOnlyList<Variant>

IReadOnlyCollection<Variant>

IEnumerable<Variant>

ICollection

IEnumerable

IDisposable

Inherited Members

object.GetType()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Constructors

Array()

Constructs a new empty Array.

public Array()

Array(Variant[])

Constructs a new Array from the given objects.

public Array(Variant[] array)

Parameters

array Variant[]

The objects to put in the new array.

Exceptions

ArgumentNullException

The array is null.

Array(IEnumerable<Variant>)

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

public Array(IEnumerable<Variant> collection)

Parameters

collection IEnumerable<Variant>

The collection of elements to construct from.

Exceptions

ArgumentNullException

The collection is null.

Array(ReadOnlySpan<GodotObject>)

Constructs a new Array from the given ReadOnlySpan's elements.

public Array(ReadOnlySpan<GodotObject> array)

Parameters

array ReadOnlySpan<GodotObject>

Exceptions

ArgumentNullException

The array is null.

Array(Span<NodePath>)

Constructs a new Array from the given span's elements.

public Array(Span<NodePath> array)

Parameters

array Span<NodePath>

Exceptions

ArgumentNullException

The array is null.

Array(Span<Rid>)

Constructs a new Array from the given span's elements.

public Array(Span<Rid> array)

Parameters

array Span<Rid>

Exceptions

ArgumentNullException

The array is null.

Array(Span<StringName>)

Constructs a new Array from the given span's elements.

public Array(Span<StringName> array)

Parameters

array Span<StringName>

Exceptions

ArgumentNullException

The array is null.

Properties

Count

Returns the number of elements in this Array. 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 Variant this[int index] { get; set; }

Parameters

index int

Property Value

Variant

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(Variant)

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

public void Add(Variant item)

Parameters

item Variant

The Variant item to add.

Exceptions

InvalidOperationException

The array is read-only.

AddRange<T>(IEnumerable<T>)

Adds the elements of the specified collection to the end of this Array.

public void AddRange<T>(IEnumerable<T> collection)

Parameters

collection IEnumerable<T>

Collection of Variant items to add.

Type Parameters

T

Exceptions

InvalidOperationException

The array is read-only.

ArgumentNullException

The collection is null.

BinarySearch(Variant)

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(Variant) on an unsorted array results in unexpected behavior.

public int BinarySearch(Variant item)

Parameters

item Variant

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.

BinarySearch(int, int, Variant)

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, Variant) on an unsorted array results in unexpected behavior.

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

Parameters

index int

The starting index of the range to search.

count int

The length of the range to search.

item Variant

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.

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(Variant)

Returns true if the array contains the given value.

public bool Contains(Variant item)

Parameters

item Variant

The Variant item to look for.

Returns

bool

Whether or not this array contains the given item.

Examples

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

CopyTo(Variant[], int)

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

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

Parameters

array Variant[]

The 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.

Dispose()

Disposes of this Array.

public void Dispose()

Dispose(bool)

public void Dispose(bool disposing)

Parameters

disposing bool

Duplicate(bool)

Returns a copy of the Array. If deep is true, a deep copy if performed: all nested arrays and dictionaries are duplicated and will not be shared with the original array. If false, a shallow copy is made and references to the original nested arrays and dictionaries are kept, so that modifying a sub-array or dictionary in the copy will also impact those referenced in the source array. Note that any GodotObject derived elements will be shallow copied regardless of the deep setting.

public Array Duplicate(bool deep = false)

Parameters

deep bool

If true, performs a deep copy.

Returns

Array

A new Godot Array.

Fill(Variant)

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(Variant value)

Parameters

value Variant

The value to fill the array with.

Examples

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

Exceptions

InvalidOperationException

The array is read-only.

~Array()

protected ~Array()

GetEnumerator()

Gets an enumerator for this Array.

public IEnumerator<Variant> GetEnumerator()

Returns

IEnumerator<Variant>

An enumerator.

GetSliceRange(int, int, int, bool)

Returns the slice of the Array, from start (inclusive) to end (exclusive), as a new Array. 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 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

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

IndexOf(Variant)

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

public int IndexOf(Variant item)

Parameters

item Variant

The Variant item to search for.

Returns

int

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

IndexOf(Variant, int)

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

public int IndexOf(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.

Insert(int, Variant)

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, Variant item)

Parameters

index int

The index to insert at.

item Variant

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 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, null is returned.

public Variant Max()

Returns

Variant

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, null is returned.

public Variant Min()

Returns

Variant

The minimum value contained in the array.

PickRandom()

Returns a random value from the target array.

public Variant PickRandom()

Returns

Variant

A random element from the array.

Examples

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

RecursiveEqual(Array)

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

public bool RecursiveEqual(Array other)

Parameters

other Array

The other array to compare against.

Returns

bool

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

Remove(Variant)

Removes the first occurrence of the specified item from this Array.

public bool Remove(Variant item)

Parameters

item Variant

The value to remove.

Returns

bool

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(Variant) 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 the array to contain a different number of elements. If the array size is smaller, elements are cleared, if bigger, new elements are null.

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.

public Array Slice(int start)

Parameters

start int

The zero-based index at which the range starts.

Returns

Array

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.

public Array 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

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 { "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 to a string.

public override string ToString()

Returns

string

A string representation of this array.

Operators

operator +(Array, Array)

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

public static Array operator +(Array left, Array right)

Parameters

left Array

The first array.

right Array

The second array.

Returns

Array

A new Godot Array with the contents of both arrays.