Package org.plumelib.util

Class ArraySet<E extends @UnknownSignedness @Nullable Object>

java.lang.Object

java.util.AbstractCollection<E>

java.util.AbstractSet<E>

org.plumelib.util.ArraySet<E>

Type Parameters:

E - the type of the set elements

All Implemented Interfaces:

Cloneable, Iterable<E>, Collection<E>, Set<E>

public class ArraySet<E extends @UnknownSignedness @Nullable Object>
extends AbstractSet<E>
implements Cloneable

A set backed by an array. It permits null values and its iterator has deterministic ordering.

Compared to a HashSet or LinkedHashSet: For very small sets, this uses much less space, has comparable performance, and (like a LinkedHashSet) is deterministic, with elements returned in the order they were inserted. For large sets, this is significantly less performant than other set implementations.

Compared to a TreeSet: This uses somewhat less space, and it does not require defining a comparator. This isn't sorted but does have deterministic ordering. For large sets, this is significantly less performant than other set implementations.

Other ArraySet implementations include:

• https://docs.oracle.com/en/database/oracle/oracle-database/19/olapi/oracle/olapi/ArraySet.html
• https://developer.android.com/reference/android/util/ArraySet
• https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/CopyOnWriteArraySet.html

All of those use the GPL or the Apache License, version 2.0, whereas this implementation is licensed under the more libral MIT License. In addition, some of those implementations forbid nulls or nondeterministically reorder the contents, and others don't specify their behavior regarding nulls and ordering. CopyOnWriteArraySet uses an ArrayList, not an array, as its representation.

Constructor Summary

Constructors

Constructor	Description
ArraySet()	Constructs an empty ArraySet with the default initial capacity.
ArraySet(int initialCapacity)	Constructs an empty ArraySet with the specified initial capacity.
ArraySet(@Nullable Collection<? extends E> m)	Constructs a new ArraySet with the same elements as the given collection.

Method Summary

Modifier and Type	Method	Description
boolean	add(E value)
boolean	addAll(Collection<? extends E> c)
void	clear()
ArraySet<E>	clone()	Returns a copy of this.
boolean	contains(@GuardSatisfied @Nullable @UnknownSignedness Object value)
void	forEach(Consumer<? super E> action)
boolean	isEmpty()
Iterator<E>	iterator()
static <E extends @Nullable @UnknownSignedness Object> Set<E>	newArraySetOrHashSet(int capacity)	Returns a new ArraySet or HashSet with the given capacity.
static <E extends @Nullable @UnknownSignedness Object> Set<E>	newArraySetOrHashSet(Collection<E> s)	Returns a new ArraySet or HashSet with the given elements.
static <E extends @Nullable @UnknownSignedness Object> Set<E>	newArraySetOrLinkedHashSet(int capacity)	Returns a new ArraySet or LinkedHashSet with the given capacity.
static <E extends @Nullable @UnknownSignedness Object> Set<E>	newArraySetOrLinkedHashSet(Collection<E> s)	Returns a new ArraySet or LinkedHashSet with the given elements.
boolean	remove(@GuardSatisfied @Nullable @UnknownSignedness Object value)
boolean	removeAll(Collection<?> c)
@org.checkerframework.checker.index.qual.NonNegative int	size()
void	sort()	Sorts the internal representation of this.
void	sort(Comparator<? super E> comparator)	Sorts the internal representation of this, using the given comparator.

Methods inherited from class java.util.AbstractSet

equals, hashCode

Methods inherited from class java.util.AbstractCollection

containsAll, retainAll, toArray, toArray, toString

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.util.Collection

parallelStream, removeIf, stream, toArray

Methods inherited from interface java.util.Set

containsAll, retainAll, spliterator, toArray, toArray

Constructor Details

ArraySet

@SideEffectFree
public ArraySet(int initialCapacity)

Constructs an empty ArraySet with the specified initial capacity.

Parameters:

initialCapacity - the initial capacity

Throws:

IllegalArgumentException - if the initial capacity is negative

ArraySet

@SideEffectFree
public ArraySet()

Constructs an empty ArraySet with the default initial capacity.

ArraySet

@SideEffectFree
public ArraySet(@Nullable Collection<? extends E> m)

Constructs a new ArraySet with the same elements as the given collection.

Parameters:

m - the collection whose elements are to be placed in the new set

Throws:

NullPointerException - if the given set is null

Method Details

newArraySetOrHashSet

public static <E extends @Nullable @UnknownSignedness Object>
Set<E> newArraySetOrHashSet(int capacity)

Returns a new ArraySet or HashSet with the given capacity. Uses an ArraySet if the capacity is small, and a HashSet otherwise.

Type Parameters:

E - the type of the elements

Parameters:

capacity - the expected maximum number of elements in the set

Returns:

a new ArraySet or HashSet with the given capacity

newArraySetOrHashSet

public static <E extends @Nullable @UnknownSignedness Object>
Set<E> newArraySetOrHashSet(Collection<E> s)

Returns a new ArraySet or HashSet with the given elements. Uses an ArraySet if the capacity is small, and a HashSet otherwise.

Type Parameters:

E - the type of the elements

Parameters:

s - the elements to put in the returned set

Returns:

a new ArraySet or HashSet with the given elements

newArraySetOrLinkedHashSet

public static <E extends @Nullable @UnknownSignedness Object>
Set<E> newArraySetOrLinkedHashSet(int capacity)

Returns a new ArraySet or LinkedHashSet with the given capacity. Uses an ArraySet if the capacity is small, and a LinkedHashSet otherwise.

Type Parameters:

E - the type of the elements

Parameters:

capacity - the expected maximum number of elements in the set

Returns:

a new ArraySet or LinkedHashSet with the given capacity

newArraySetOrLinkedHashSet

public static <E extends @Nullable @UnknownSignedness Object>
Set<E> newArraySetOrLinkedHashSet(Collection<E> s)

Returns a new ArraySet or LinkedHashSet with the given elements. Uses an ArraySet if the capacity is small, and a LinkedHashSet otherwise.

Type Parameters:

E - the type of the elements

Parameters:

s - the elements to put in the returned set

Returns:

a new ArraySet or LinkedHashSet with the given elements

size

@Pure
public @org.checkerframework.checker.index.qual.NonNegative int size()

Specified by:

size in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

size in interface Set<E extends @UnknownSignedness @Nullable Object>

Specified by:

size in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

isEmpty

@Pure
public boolean isEmpty()

Specified by:

isEmpty in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

isEmpty in interface Set<E extends @UnknownSignedness @Nullable Object>

Overrides:

isEmpty in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

contains

@Pure
public boolean contains(@GuardSatisfied @Nullable @UnknownSignedness Object value)

Specified by:

contains in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

contains in interface Set<E extends @UnknownSignedness @Nullable Object>

Overrides:

contains in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

add

public boolean add(E value)

Specified by:

add in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

add in interface Set<E extends @UnknownSignedness @Nullable Object>

Overrides:

add in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

remove

public boolean remove(@GuardSatisfied @Nullable @UnknownSignedness Object value)

Specified by:

remove in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

remove in interface Set<E extends @UnknownSignedness @Nullable Object>

Overrides:

remove in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

addAll

public boolean addAll(Collection<? extends E> c)

Specified by:

addAll in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

addAll in interface Set<E extends @UnknownSignedness @Nullable Object>

Overrides:

addAll in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

removeAll

public boolean removeAll(Collection<?> c)

Specified by:

removeAll in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

removeAll in interface Set<E extends @UnknownSignedness @Nullable Object>

Overrides:

removeAll in class AbstractSet<E extends @UnknownSignedness @Nullable Object>

clear

public void clear()

Specified by:

clear in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

clear in interface Set<E extends @UnknownSignedness @Nullable Object>

Overrides:

clear in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

iterator

public Iterator<E> iterator()

Specified by:

iterator in interface Collection<E extends @UnknownSignedness @Nullable Object>

Specified by:

iterator in interface Iterable<E extends @UnknownSignedness @Nullable Object>

Specified by:

iterator in interface Set<E extends @UnknownSignedness @Nullable Object>

Specified by:

iterator in class AbstractCollection<E extends @UnknownSignedness @Nullable Object>

forEach

public void forEach(Consumer<? super E> action)

Specified by:

forEach in interface Iterable<E extends @UnknownSignedness @Nullable Object>

clone

@SideEffectFree
public ArraySet<E> clone()

Returns a copy of this.

Overrides:

clone in class Object

Returns:

a copy of this

sort

public void sort()

Sorts the internal representation of this. Side-effects the representation, but not the abstract value, of this. Requires that the elements of this are comparable.

sort

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

Sorts the internal representation of this, using the given comparator. Side-effects the representation, but not the abstract value, of this.

Parameters:

comparator - imposes an ordering on the elements of this