Package org.plumelib.util

Class ArraySet<E extends @UnknownSignedness 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:
Iterable<E>, Collection<E>, Set<E>
public class ArraySet<E extends @UnknownSignedness Object> extends AbstractSet<E>
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.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    private class 
    ArraySet.ArraySetIterator
    An iterator over the ArraySet.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LessThan({"values.length + 1"}),@org.checkerframework.checker.index.qual.IndexOrHigh({"values"}) int
    size
    The number of used slots in the representation of this.
    (package private) int
    sizeModificationCount
    The number of times this set's size has been modified by adding or removing an element.
    private @Nullable E[]
    values
    The values.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
     
    ArraySet()
    Constructs an empty ArraySet with the default initial capacity.
     
    ArraySet(int initialCapacity)
    Constructs an empty ArraySet with the specified initial capacity.
    private
    ArraySet(E[] values, @org.checkerframework.checker.index.qual.LTEqLengthOf({"values"}) int size)
    Private constructor.
     
    ArraySet(Collection<? extends E> m)
    Constructs a new ArraySet with the same elements as the given collection.

  • Method Summary

    Modifier and Type
    Method
    Description
    private boolean
    add(@org.checkerframework.checker.index.qual.GTENegativeOne int index, E value)
    Adds an element to this set.
    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)
     
    private void
    grow()
    Increases the capacity of the array.
    private int
    indexOf(@GuardSatisfied @Nullable @UnknownSignedness Object value)
    Returns the index of the given value, or -1 if it does not appear.
    boolean
    isEmpty()
     
    Iterator<E>
    iterator()
     
    static <E> Set<E>
    newArraySetOrHashSet(int capacity)
    Returns a new ArraySet or HashSet with the given capacity.
    static <E> Set<E>
    newArraySetOrHashSet(Collection<E> s)
    Returns a new ArraySet or HashSet with the given elements.
    static <E> Set<E>
    newArraySetOrLinkedHashSet(int capacity)
    Returns a new ArraySet or LinkedHashSet with the given capacity.
    static <E> 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)
     
    private boolean
    removeIndex(@org.checkerframework.checker.index.qual.GTENegativeOne int index)
    Remove the element at the given index.
    (package private) String
    repr()
    Returns the internal representation, printed.
    @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

  • Field Details

    • values

      private @Nullable E extends @UnknownSignedness Object[] values
      The values. Null if capacity=0.

    • size

      private @org.checkerframework.checker.index.qual.NonNegative,@org.checkerframework.checker.index.qual.LessThan({"values.length + 1"}),@org.checkerframework.checker.index.qual.IndexOrHigh({"values"}) int size
      The number of used slots in the representation of this.

    • sizeModificationCount

      transient int sizeModificationCount
      The number of times this set's size has been modified by adding or removing an element. This field is used to make view iterators fail-fast.

  • 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 private ArraySet(E[] values, @org.checkerframework.checker.index.qual.LTEqLengthOf({"values"}) int size)
      Private constructor. Installs the given objects in this as its representation, without making defensive copies.
      Parameters:
      values - the values
      size - the number of used items in the array; may be less than its length

    • ArraySet

      @SideEffectFree public ArraySet(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> 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> 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> 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> 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

    • add

      private boolean add(@org.checkerframework.checker.index.qual.GTENegativeOne int index, E value)
      Adds an element to this set.
      Parameters:
      index - the index of value in values. If -1, add a new element. Otherwise, do nothing.
      value - the value
      Returns:
      true if the method modified this set

    • grow

      private void grow()
      Increases the capacity of the array.

    • removeIndex

      private boolean removeIndex(@org.checkerframework.checker.index.qual.GTENegativeOne int index)
      Remove the element at the given index. Does nothing if index is -1.
      Parameters:
      index - the index of the element to remove
      Returns:
      true if this set was modified

    • size

      @Pure public @org.checkerframework.checker.index.qual.NonNegative int size()
      Specified by:
      size in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      size in interface Set<E extends @UnknownSignedness Object>
      Specified by:
      size in class AbstractCollection<E extends @UnknownSignedness Object>

    • isEmpty

      @Pure public boolean isEmpty()
      Specified by:
      isEmpty in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      isEmpty in interface Set<E extends @UnknownSignedness Object>
      Overrides:
      isEmpty in class AbstractCollection<E extends @UnknownSignedness Object>

    • indexOf

      @Pure private int indexOf(@GuardSatisfied @Nullable @UnknownSignedness Object value)
      Returns the index of the given value, or -1 if it does not appear. Uses Objects.equals for comparison.
      Parameters:
      value - a value to find
      Returns:
      the index of the given value, or -1 if it does not appear

    • contains

      @Pure public boolean contains(@GuardSatisfied @Nullable @UnknownSignedness Object value)
      Specified by:
      contains in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      contains in interface Set<E extends @UnknownSignedness Object>
      Overrides:
      contains in class AbstractCollection<E extends @UnknownSignedness Object>

    • add

      public boolean add(E value)
      Specified by:
      add in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      add in interface Set<E extends @UnknownSignedness Object>
      Overrides:
      add in class AbstractCollection<E extends @UnknownSignedness Object>

    • remove

      public boolean remove(@GuardSatisfied @Nullable @UnknownSignedness Object value)
      Specified by:
      remove in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      remove in interface Set<E extends @UnknownSignedness Object>
      Overrides:
      remove in class AbstractCollection<E extends @UnknownSignedness Object>

    • addAll

      public boolean addAll(Collection<? extends E> c)
      Specified by:
      addAll in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      addAll in interface Set<E extends @UnknownSignedness Object>
      Overrides:
      addAll in class AbstractCollection<E extends @UnknownSignedness Object>

    • removeAll

      public boolean removeAll(Collection<?> c)
      Specified by:
      removeAll in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      removeAll in interface Set<E extends @UnknownSignedness Object>
      Overrides:
      removeAll in class AbstractSet<E extends @UnknownSignedness Object>

    • clear

      public void clear()
      Specified by:
      clear in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      clear in interface Set<E extends @UnknownSignedness Object>
      Overrides:
      clear in class AbstractCollection<E extends @UnknownSignedness Object>

    • iterator

      public Iterator<E> iterator()
      Specified by:
      iterator in interface Collection<E extends @UnknownSignedness Object>
      Specified by:
      iterator in interface Iterable<E extends @UnknownSignedness Object>
      Specified by:
      iterator in interface Set<E extends @UnknownSignedness Object>
      Specified by:
      iterator in class AbstractCollection<E extends @UnknownSignedness Object>

    • forEach

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

    • clone

      @SideEffectFree public ArraySet<E> clone()
      Returns a copy of this.
      Overrides:
      clone in class Object
      Returns:
      a copy of this

    • repr

      @SideEffectFree String repr()
      Returns the internal representation, printed.
      Returns:
      the internal representation, printed

    • 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