com.badlogic.gdx.utils
Class Array<T>

java.lang.Object
  com.badlogic.gdx.utils.Array<T>

All Implemented Interfaces:

Iterable<T>

Direct Known Subclasses:

DelayedRemovalArray, SnapshotArray

public class Array<T>
extends Object
implements Iterable<T>

A resizable, ordered or unordered array of objects. If unordered, this class avoids a memory copy when removing elements (the last element is moved to the removed element's position).

Author:

Nathan Sweet

Nested Class Summary

static class	Array.ArrayIterable<T>
static class	Array.ArrayIterator<T>

Field Summary

T[]	items Provides direct access to the underlying array.
boolean	ordered
int	size

Constructor Summary

Array()
Creates an ordered array with a capacity of 16.

Array(Array<? extends T> array)
Creates a new array containing the elements in the specified array.

Array(boolean ordered, int capacity)

Array(boolean ordered, int capacity, Class arrayType)
Creates a new array with items of the specified type.

Array(boolean ordered, T[] array, int start, int count)
Creates a new array containing the elements in the specified array.

Array(Class arrayType)
Creates an ordered array with items of the specified type and a capacity of 16.

Array(int capacity)
Creates an ordered array with the specified capacity.

Array(T[] array)
Creates a new ordered array containing the elements in the specified array.

Method Summary

void	add(T value)
void	addAll(Array<? extends T> array)
void	addAll(Array<? extends T> array, int offset, int length)
void	addAll(T... array)
void	addAll(T[] array, int offset, int length)
void	clear()
boolean	contains(T value, boolean identity) Returns if this array contains value.
T[]	ensureCapacity(int additionalCapacity) Increases the size of the backing array to accommodate the specified number of additional items.
boolean	equals(Object object)
T	first() Returns the first item.
T	get(int index)
int	indexOf(T value, boolean identity) Returns an index of first occurrence of value in array or -1 if no such value exists
void	insert(int index, T value)
Iterator<T>	iterator() Returns an iterator for the items in the array.
int	lastIndexOf(T value, boolean identity) Returns an index of last occurrence of value in array or -1 if no such value exists.
static <T> Array<T>	of(boolean ordered, int capacity, Class<T> arrayType)
static <T> Array<T>	of(Class<T> arrayType)
T	peek() Returns the last item.
T	pop() Removes and returns the last item.
T	random() Returns a random item from the array, or null if the array is empty.
boolean	removeAll(Array<? extends T> array, boolean identity) Removes from this array all of elements contained in the specified array.
T	removeIndex(int index) Removes and returns the item at the specified index.
void	removeRange(int start, int end) Removes the items at the specified indices, inclusive.
boolean	removeValue(T value, boolean identity) Removes the first instance of the specified value in the array.
void	reverse()
Iterable<T>	select(Predicate<T> predicate) Returns an iterable for the selected items in the array.
T	selectRanked(Comparator<T> comparator, int kthLowest) Selects the nth-lowest element from the Array according to Comparator ranking.
int	selectRankedIndex(Comparator<T> comparator, int kthLowest)
void	set(int index, T value)
T[]	shrink() Reduces the size of the backing array to the size of the actual items.
void	shuffle()
void	sort() Sorts this array.
void	sort(Comparator<? super T> comparator) Sorts the array.
void	swap(int first, int second)
T[]	toArray() Returns the items as an array.
<V> V[]	toArray(Class type)
String	toString()
String	toString(String separator)
void	truncate(int newSize) Reduces the size of the array to the specified size.
static <T> Array<T>	with(T... array)

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

items

public T[] items

Provides direct access to the underlying array. If the Array's generic type is not Object, this field may only be accessed if the Array(boolean, int, Class) constructor was used.

size

public int size

ordered

public boolean ordered

Constructor Detail

Array

public Array()

Creates an ordered array with a capacity of 16.

Array

public Array(int capacity)

Creates an ordered array with the specified capacity.

Array

public Array(boolean ordered,
             int capacity)

Parameters:

ordered - If false, methods that remove elements may change the order of other elements in the array, which avoids a memory copy.

capacity - Any elements added beyond this will cause the backing array to be grown.

Array

public Array(boolean ordered,
             int capacity,
             Class arrayType)

Creates a new array with items of the specified type.

Parameters:

ordered - If false, methods that remove elements may change the order of other elements in the array, which avoids a memory copy.

capacity - Any elements added beyond this will cause the backing array to be grown.

Array

public Array(Class arrayType)

Creates an ordered array with items of the specified type and a capacity of 16.

Array

public Array(Array<? extends T> array)

Creates a new array containing the elements in the specified array. The new array will have the same type of backing array and will be ordered if the specified array is ordered. The capacity is set to the number of elements, so any subsequent elements added will cause the backing array to be grown.

Array

public Array(T[] array)

Creates a new ordered array containing the elements in the specified array. The new array will have the same type of backing array. The capacity is set to the number of elements, so any subsequent elements added will cause the backing array to be grown.

Array

public Array(boolean ordered,
             T[] array,
             int start,
             int count)

Creates a new array containing the elements in the specified array. The new array will have the same type of backing array. The capacity is set to the number of elements, so any subsequent elements added will cause the backing array to be grown.

Parameters:

ordered - If false, methods that remove elements may change the order of other elements in the array, which avoids a memory copy.

Method Detail

add

public void add(T value)

addAll

public void addAll(Array<? extends T> array)

addAll

public void addAll(Array<? extends T> array,
                   int offset,
                   int length)

addAll

public void addAll(T... array)

addAll

public void addAll(T[] array,
                   int offset,
                   int length)

get

public T get(int index)

set

public void set(int index,
                T value)

insert

public void insert(int index,
                   T value)

swap

public void swap(int first,
                 int second)

contains

public boolean contains(T value,
                        boolean identity)

Returns if this array contains value.

Parameters:

identity - If true, == comparison will be used. If false, .equals() comparison will be used.

Returns:

true if array contains value, false if it doesn't

indexOf

public int indexOf(T value,
                   boolean identity)

Returns an index of first occurrence of value in array or -1 if no such value exists

Parameters:

identity - If true, == comparison will be used. If false, .equals() comparison will be used.

Returns:

An index of first occurrence of value in array or -1 if no such value exists

lastIndexOf

public int lastIndexOf(T value,
                       boolean identity)

Returns an index of last occurrence of value in array or -1 if no such value exists. Search is started from the end of an array.

Parameters:

identity - If true, == comparison will be used. If false, .equals() comparison will be used.

Returns:

An index of last occurrence of value in array or -1 if no such value exists

removeValue

public boolean removeValue(T value,
                           boolean identity)

Removes the first instance of the specified value in the array.

Parameters:

identity - If true, == comparison will be used. If false, .equals() comparison will be used.

Returns:

true if value was found and removed, false otherwise

removeIndex

public T removeIndex(int index)

Removes and returns the item at the specified index.

removeRange

public void removeRange(int start,
                        int end)

Removes the items at the specified indices, inclusive.

removeAll

public boolean removeAll(Array<? extends T> array,
                         boolean identity)

Removes from this array all of elements contained in the specified array.

Parameters:

identity - True to use ==, false to use .equals().

Returns:

true if this array was modified.

pop

public T pop()

Removes and returns the last item.

peek

public T peek()

Returns the last item.

first

public T first()

Returns the first item.

clear

public void clear()

shrink

public T[] shrink()

Reduces the size of the backing array to the size of the actual items. This is useful to release memory when many items have been removed, or if it is known that more items will not be added.

Returns:

items

ensureCapacity

public T[] ensureCapacity(int additionalCapacity)

Increases the size of the backing array to accommodate the specified number of additional items. Useful before adding many items to avoid multiple backing array resizes.

Returns:

items

sort

public void sort()

Sorts this array. The array elements must implement Comparable. This method is not thread safe (uses Sort.instance()).

sort

public void sort(Comparator<? super T> comparator)

Sorts the array. This method is not thread safe (uses Sort.instance()).

selectRanked

public T selectRanked(Comparator<T> comparator,
                      int kthLowest)

Selects the nth-lowest element from the Array according to Comparator ranking. This might partially sort the Array. The array must have a size greater than 0, or a GdxRuntimeException will be thrown.

Parameters:

comparator - used for comparison

kthLowest - rank of desired object according to comparison, n is based on ordinal numbers, not array indices. for min value use 1, for max value use size of array, using 0 results in runtime exception.

Returns:

the value of the Nth lowest ranked object.

See Also:

Select

selectRankedIndex

public int selectRankedIndex(Comparator<T> comparator,
                             int kthLowest)

Parameters:

comparator - used for comparison

kthLowest - rank of desired object according to comparison, n is based on ordinal numbers, not array indices. for min value use 1, for max value use size of array, using 0 results in runtime exception.

Returns:

the index of the Nth lowest ranked object.

See Also:

selectRanked(java.util.Comparator, int)

reverse

public void reverse()

shuffle

public void shuffle()

iterator

public Iterator<T> iterator()

Returns an iterator for the items in the array. Remove is supported. Note that the same iterator instance is returned each time this method is called. Use the Array.ArrayIterator constructor for nested or multithreaded iteration.

Specified by:

iterator in interface Iterable<T>

select

public Iterable<T> select(Predicate<T> predicate)

Returns an iterable for the selected items in the array. Remove is supported, but not between hasNext() and next(). Note that the same iterable instance is returned each time this method is called. Use the Predicate.PredicateIterable constructor for nested or multithreaded iteration.

truncate

public void truncate(int newSize)

Reduces the size of the array to the specified size. If the array is already smaller than the specified size, no action is taken.

random

public T random()

Returns a random item from the array, or null if the array is empty.

toArray

public T[] toArray()

Returns the items as an array. Note the array is typed, so the Array(Class) constructor must have been used. Otherwise use toArray(Class) to specify the array type.

toArray

public <V> V[] toArray(Class type)

equals

public boolean equals(Object object)

Overrides:

equals in class Object

toString

public String toString()

Overrides:

toString in class Object

toString

public String toString(String separator)

of

public static <T> Array<T> of(Class<T> arrayType)

See Also:

Array(Class)

of

public static <T> Array<T> of(boolean ordered,
                              int capacity,
                              Class<T> arrayType)

See Also:

Array(boolean, int, Class)

with

public static <T> Array<T> with(T... array)

See Also:

Array(Object[])