Package com.github.tommyettinger.ds

Interface EnhancedCollection<T>

Type Parameters:
T - the type of items in this collection
All Superinterfaces:
Collection<T>, Iterable<T>
All Known Implementing Classes:
BinaryHeap, CaseInsensitiveMap.CaseInsensitiveKeys, CaseInsensitiveOrderedMap.CaseInsensitiveKeys, CaseInsensitiveOrderedSet, CaseInsensitiveSet, EnumFloatMap.Entries, EnumFloatMap.Keys, EnumFloatOrderedMap.OrderedMapEntries, EnumFloatOrderedMap.OrderedMapKeys, EnumIntMap.Entries, EnumIntMap.Keys, EnumIntOrderedMap.OrderedMapEntries, EnumIntOrderedMap.OrderedMapKeys, EnumLongMap.Entries, EnumLongMap.Keys, EnumLongOrderedMap.OrderedMapEntries, EnumLongOrderedMap.OrderedMapKeys, EnumMap.Entries, EnumMap.Keys, EnumMap.Values, EnumOrderedMap.OrderedMapEntries, EnumOrderedMap.OrderedMapKeys, EnumOrderedMap.OrderedMapValues, EnumOrderedSet, EnumSet, FilteredIterableOrderedSet, FilteredIterableSet, FilteredStringOrderedSet, FilteredStringSet, HolderOrderedSet, HolderSet, IdentityOrderedSet, IdentitySet, IntFloatMap.Entries, IntFloatOrderedMap.OrderedMapEntries, IntIntMap.Entries, IntIntOrderedMap.OrderedMapEntries, IntLongMap.Entries, IntLongOrderedMap.OrderedMapEntries, IntObjectMap.Entries, IntObjectMap.Values, IntObjectOrderedMap.OrderedMapEntries, IntObjectOrderedMap.OrderedMapValues, LongFloatMap.Entries, LongFloatOrderedMap.OrderedMapEntries, LongIntMap.Entries, LongIntOrderedMap.OrderedMapEntries, LongLongMap.Entries, LongLongOrderedMap.OrderedMapEntries, LongObjectMap.Entries, LongObjectMap.Values, LongObjectOrderedMap.OrderedMapEntries, LongObjectOrderedMap.OrderedMapValues, NumberedSet, ObjectBag, ObjectDeque, ObjectFloatMap.Entries, ObjectFloatMap.Keys, ObjectFloatOrderedMap.OrderedMapEntries, ObjectFloatOrderedMap.OrderedMapKeys, ObjectIntMap.Entries, ObjectIntMap.Keys, ObjectIntOrderedMap.OrderedMapEntries, ObjectIntOrderedMap.OrderedMapKeys, ObjectList, ObjectLongMap.Entries, ObjectLongMap.Keys, ObjectLongOrderedMap.OrderedMapEntries, ObjectLongOrderedMap.OrderedMapKeys, ObjectObjectMap.Entries, ObjectObjectMap.Keys, ObjectObjectMap.Values, ObjectObjectOrderedMap.OrderedMapEntries, ObjectObjectOrderedMap.OrderedMapKeys, ObjectObjectOrderedMap.OrderedMapValues, ObjectOrderedSet, ObjectSet
public interface EnhancedCollection<T> extends Collection<T>
Augments Collection with default methods that can usually use the same implementation across subtypes. This generally brings Object-based collections to parity with the default methods provided by the various PrimitiveCollection types.

  • Method Details

    • add

      default boolean add(T item0, T item1)
      Adds all parameters using Collection.add(Object) for each one. Returns true if the set was modified.
      Parameters:
      item0 - a T item
      item1 - a T item
      Returns:
      true if this modified the set

    • add

      default boolean add(T item0, T item1, T item2)
      Adds all parameters using Collection.add(Object) for each one. Returns true if the set was modified.
      Parameters:
      item0 - a T item
      item1 - a T item
      item2 - a T item
      Returns:
      true if this modified the set

    • add

      default boolean add(T item0, T item1, T item2, T item3)
      Adds all parameters using Collection.add(Object) for each one. Returns true if the set was modified.
      Parameters:
      item0 - a T item
      item1 - a T item
      item2 - a T item
      item3 - a T item
      Returns:
      true if this modified the set

    • addAllIterable

      default boolean addAllIterable(Iterable<? extends T> it)
      Gets the Iterable.iterator() from the parameter and delegates to addAll(Iterator).
      Parameters:
      it - an Iterable of items to append to this EnhancedCollection
      Returns:
      true if this collection was modified.

    • addAll

      default boolean addAll(Iterator<? extends T> it)
      Goes through the given Iterator until it is exhausted, adding every item to this EnhancedCollection using Collection.add(Object).
      Parameters:
      it - an Iterator of items to append to this EnhancedCollection
      Returns:
      true if this collection was modified.

    • addAll

      default boolean addAll(T[] array)

    • addAll

      default boolean addAll(T[] array, int offset, int length)

    • addVarargs

      default boolean addVarargs(T... varargs)
      Takes an array of items to add, or more simply 0 or more arguments that will each be added. If varargs is null, this won't add anything and will return false. If you have what is usually an array, consider calling addAll(Object[]) to avoid the possibility of heap pollution from a varargs with a generic type.
      Parameters:
      varargs - 0 or more items to add; may also be an array
      Returns:
      true if this collection was modified

    • removeAllIterable

      default boolean removeAllIterable(Iterable<? extends T> it)
      Gets the Iterable.iterator() from the parameter and delegates to removeAll(Iterator).
      Parameters:
      it - an Iterable of items to remove fully
      Returns:
      true if this collection was modified.

    • removeAll

      default boolean removeAll(Iterator<? extends T> it)
      Removes from this collection all occurrences of any elements contained in the specified Iterator.
      Parameters:
      it - an Iterator of items to remove fully
      Returns:
      true if this collection was modified.

    • removeAll

      default boolean removeAll(Object[] array)
      Removes from this collection all occurrences of any elements contained in the specified array.
      Parameters:
      array - a non-null array of items to remove fully
      Returns:
      true if this collection was modified.

    • removeAll

      default boolean removeAll(Object[] array, int offset, int length)
      Removes from this collection all occurrences of any elements contained in the specified array, but only starts reading elements from the array starting at the given offset and only uses length items.
      Parameters:
      array - a non-null array of items to remove fully
      offset - the first index in array to use
      length - how many items from array should be used
      Returns:
      true if this collection was modified.

    • removeEachIterable

      default boolean removeEachIterable(Iterable<?> other)
      Removes from this collection element-wise occurrences of elements contained in the specified Iterable. Note that if a value is present more than once in this collection, only one of those occurrences will be removed for each occurrence of that value in other. If other has the same contents as this collection or has additional items, then removing each of other will clear this.
      Parameters:
      other - an Iterable of any items to remove one-by-one, such as an ObjectList or ObjectSet
      Returns:
      true if this collection was modified.

    • removeEach

      default boolean removeEach(Iterator<?> it)
      Removes from this collection element-wise occurrences of elements given by the specified Iterator. Note that if a value is present more than once in this collection, only one of those occurrences will be removed for each time other yields that value. If other has the same contents as this collection or has additional items, then removing each of other will clear this.
      Parameters:
      it - an Iterator of any items to remove one-by-one, such as an ObjectList or ObjectSet
      Returns:
      true if this collection was modified.

    • removeEach

      default boolean removeEach(Object[] array)
      Removes from this collection element-wise occurrences of elements contained in the specified array. Note that if a value is present more than once in this collection, only one of those occurrences will be removed for each occurrence of that value in other. If other has the same contents as this collection or has additional items, then removing each of other will clear this.
      Parameters:
      array - an array of any items to remove one-by-one, such as an ObjectList or ObjectSet
      Returns:
      true if this collection was modified.

    • removeEach

      default boolean removeEach(Object[] array, int offset, int length)
      Removes from this collection element-wise occurrences of elements contained in the specified array. Note that if a value is present more than once in this collection, only one of those occurrences will be removed for each occurrence of that value in other. If other has the same contents as this collection or has additional items, then removing each of other will clear this.
      Parameters:
      array - an array of any items to remove one-by-one, such as an ObjectList or ObjectSet
      offset - the first index in array to use
      length - how many items from array should be used
      Returns:
      true if this collection was modified.

    • containsAllIterable

      default boolean containsAllIterable(Iterable<?> it)
      Returns true if this collection contains all the elements in the specified Iterable.
      Parameters:
      it - a non-null Collection or other Iterable to have items checked for containment in this collection
      Returns:
      true if this collection contains all the elements in the specified Iterable
      Throws:
      NullPointerException - if the specified Iterable is null.
      See Also:

    • containsAll

      default boolean containsAll(Iterator<?> it)
      Returns true if this collection contains all the elements remaining in the specified Iterator.
      Parameters:
      it - a non-null Iterator to have items checked for containment in this collection
      Returns:
      true if this collection contains all the elements in the specified Iterator
      Throws:
      NullPointerException - if the specified Iterator is null.
      See Also:

    • containsAll

      default boolean containsAll(Object[] array)
      Returns true if this collection contains all the elements in the specified array.
      Parameters:
      array - a non-null array to have items checked for containment in this collection
      Returns:
      true if this collection contains all the elements in the specified collection
      Throws:
      NullPointerException - if the specified collection is null.
      See Also:

    • containsAll

      default boolean containsAll(Object[] array, int offset, int length)
      Returns true if this collection contains all the elements in the specified array starting from offset and using length items from the array.
      Parameters:
      array - a non-null array to have items checked for containment in this collection
      offset - the first index in array to use
      length - how many items from array should be used
      Returns:
      true if this collection contains all the elements in the specified collection
      Throws:
      NullPointerException - if the specified collection is null.
      See Also:

    • containsAnyIterable

      default boolean containsAnyIterable(Iterable<?> other)
      Like Collection.containsAll(Collection), but returns true immediately if any item in the given Iterable other is present in this EnhancedCollection.
      Parameters:
      other - a Collection or other Iterable of any type to look through
      Returns:
      true if any items from the Iterable are present in this EnhancedCollection

    • containsAny

      default boolean containsAny(Iterator<?> it)
      Like Collection.containsAll(Collection), but returns true immediately if any item in the given Iterator it is present in this EnhancedCollection.
      Parameters:
      it - an Iterator of any type to look through
      Returns:
      true if any items from the Iterator are present in this EnhancedCollection

    • containsAny

      default boolean containsAny(Object[] array)

    • containsAny

      default boolean containsAny(Object[] array, int offset, int length)
      Like Collection.containsAll(Collection), but returns true immediately if any item in the given array is present in this EnhancedCollection.
      Parameters:
      array - an array to look through; will not be modified
      offset - the first index in array to check
      length - how many items in array to check
      Returns:
      true if any items from array are present in this EnhancedCollection

    • first

      default T first()
      Attempts to get the first item in this EnhancedCollection, where "first" is only defined meaningfully if this type is ordered. Many times, this applies to a class that is not ordered, and in those cases it can get an arbitrary item, and that item is permitted to be different for different calls to first().
      This is useful for cases where you would normally be able to call something like List.get(int) to get an item, any item, from a collection, but whatever class you're using doesn't necessarily provide a get(), first(), peek(), or similar method.
      The default implementation uses Collection.iterator(), tries to get the first item, or throws an IllegalStateException if this is empty.
      Returns:
      the first item in this EnhancedCollection, as produced by Collection.iterator()
      Throws:
      IllegalStateException - if this is empty

    • toString

      default String toString(String itemSeparator)
      Delegates to toString(String, boolean) with the given itemSeparator and without surrounding brackets.
      Parameters:
      itemSeparator - how to separate items, such as ", "
      Returns:
      a new String representing this map

    • toString

      default String toString(String itemSeparator, boolean brackets)
      Makes a String from the contents of this EnhancedCollection, using the Object.toString() method of each item, separating items with the given itemSeparator, and wrapping the result in square brackets if brackets is true.
      Delegates to appendTo(CharSequence, String, boolean).
      Parameters:
      itemSeparator - how to separate items, such as ", "
      brackets - true to wrap the result in square brackets, or false to leave the items unadorned
      Returns:
      a new String representing this EnhancedCollection

    • toString

      default String toString(String separator, boolean brackets, Appender<T> appender)
      Makes a String from the contents of this EnhancedCollection, but uses the given Appender to convert each item to a customizable representation and append them to a StringBuilder. To use the default String representation, you can use Appender::append as an appender.
      Be advised that Appender::append will allocate a method reference, each time this is called, on minimized Android builds due to R8 behavior. You can cache an Appender of the appropriate T type easily, however, as with this for when T is String: public static final Appender<String> STRING_APPENDER = Appender::append;
      Delegates to appendTo(CharSequence, String, boolean, Appender).
      Parameters:
      separator - how to separate items, such as ", "
      brackets - true to wrap the output in square brackets, or false to omit them
      appender - a function that takes a StringBuilder and a T, and returns the modified StringBuilder
      Returns:
      a new String representing this EnhancedCollection

    • appendTo

      default <S extends CharSequence & Appendable> S appendTo(S sb, String separator, boolean brackets)
      Appends to a StringBuilder from the contents of this EnhancedCollection, using Appender::append to append each item's String representation, separating items with separator, and optionally wrapping the output in square brackets if brackets is true.
      Be advised that Appender::append will allocate a method reference, each time this is called, on minimized Android builds due to R8 behavior. You can cache an Appender of the appropriate T type easily, however, as with this for when T is String: public static final Appender<String> STRING_APPENDER = Appender::append;
      Delegates to appendTo(CharSequence, String, boolean, Appender).
      Parameters:
      sb - a StringBuilder that this can append to
      separator - how to separate items, such as ", "
      brackets - true to wrap the output in square brackets, or false to omit them
      Returns:
      sb, with the appended items of this EnhancedCollection

    • appendTo

      default <S extends CharSequence & Appendable> S appendTo(S sb, String separator, boolean brackets, Appender<T> appender)
      Appends to a StringBuilder from the contents of this EnhancedCollection, but uses the given Appender to convert each item to a customizable representation and append them to a StringBuilder. To use the default String representation, you can use Appender::append, but be advised that it will allocate a method reference, each time this is called, on minimized Android builds due to R8 behavior. You can cache an Appender of the appropriate T type easily, however, as with this for when T is String: public static final Appender<String> STRING_APPENDER = Appender::append;
      Parameters:
      sb - a StringBuilder that this can append to
      separator - how to separate items, such as ", "
      brackets - true to wrap the output in square brackets, or false to omit them
      appender - a function that takes a StringBuilder and a T, and returns the modified StringBuilder
      Returns:
      sb, with the appended items of this EnhancedCollection

    • addLegible

      default void addLegible(String str, String delimiter, PartialParser<T> parser)
      Adds items to this EnhancedCollection drawn from the result of toString(String) or appendTo(CharSequence, String, boolean). A PartialParser will be used to parse items from sections of str. Any brackets inside the given range of characters will ruin the parsing, so increase offset by 1 and reduce length by 2 if the original String had brackets added to it.
      Parameters:
      str - a String containing string representations of items
      delimiter - the String separating every item in str
      parser - a PartialParser that returns a T item from a section of str

    • addLegible

      default void addLegible(String str, String delimiter, PartialParser<T> parser, int offset, int length)
      Adds items to this EnhancedCollection drawn from the result of toString(String) or appendTo(CharSequence, String, boolean). A PartialParser will be used to parse items from sections of str. Any brackets inside the given range of characters will ruin the parsing, so increase offset by 1 and reduce length by 2 if the original String had brackets added to it.
      Parameters:
      str - a String containing string representations of items
      delimiter - the String separating every item in str
      parser - a PartialParser that returns a T item from a section of str
      offset - the first position to read items from in str
      length - how many chars to read; -1 is treated as maximum length