Interface ReadOnlyCollection<E>

  • Type Parameters:
    E - the type of elements in this collection
    All Superinterfaces:
    java.lang.Iterable<E>
    All Known Subinterfaces:
    ReadOnlyList<E>, ReadOnlyNavigableSet<E>, ReadOnlySequencedCollection<E>, ReadOnlySequencedSet<E>, ReadOnlySet<E>, ReadOnlySortedSet<E>
    All Known Implementing Classes:
    ReadOnlyArrayList, ReadOnlyHashSet, ReadOnlyTreeSet, ReadOnlyVector
    public interface ReadOnlyCollection<E>
extends java.lang.Iterable<E>
    This interface was originally copied from GitHub's Open-JDK Account. Though the original file has been modified, few changes have been applied to the Javadoc Commenting. Due to fact that that is a Java interface file, there were few method bodies with Source-Code to begin with - meaning this is largely a copy of Method-Signatures and Java-Doc Comments.

    Method and parameter names & types have not been modified whatsoever; but several methods had to be eliminated for not being Read-Only. This Source-File was copied from the original Open JDK-21 file of the same (or, rather, highly similar) Interface-Name. The original file may be viewed on the JDK-21 GitHub public (and, coincidentally, Read-Only) Source-Release archive for Java Package java.util.*

    The Original '.java' Source-File's Header-Copyright Information is included here: File Copyright. Within that Copyright Notice, it is suggested that a copy of the GNU Public License V2 also be included alongside.
    Immutable variant of Java Collections Framework interface java.util.Collection<E>. This interface contains all of the methods that the standard Java interface ReadOnlyCollection contains - except those which would directly or indirectly modify / mutate the internal data-structure.


    • Method Summary

       
      Check this Collection's Contents
      Modifier and Type Method
      boolean contains​(Object o)
      boolean containsAll​(Collection<?> c)
      boolean isEmpty()
      int size()
       
      Convert this Collection to an Array
      Modifier and Type Method
      Object[] toArray()
      <T> T[] toArray​(T[] a)
       
      Default Methods: Copy this Read-Only Collection into another Data-Structure
      Modifier and Type Method
      default void copyIntoCollection​(Collection<? super E> collection)
      default <T> T[] toArray​(IntFunction<T[]> generator)
       
      Default Methods (Interface Methods with a Concrete, Default Implementation)
      Modifier and Type Method
      default Stream<E> parallelStream()
      default Spliterator<E> spliterator()
      default Stream<E> stream()
       
      Default Methods: VarArgs Input - AND, NAND, OR & XOR
      Modifier and Type Method
      default boolean containsAND​(Object... elements)
      default boolean containsNAND​(Object... elements)
      default boolean containsOR​(Object... elements)
      default boolean containsXOR​(Object... elements)
       
      Default Methods: Iterable Input - AND, NAND, OR & XOR
      Modifier and Type Method
      default boolean containsAND​(Iterable<?> i)
      default boolean containsNAND​(Iterable<?> i)
      default boolean containsOR​(Iterable<?> i)
      default boolean containsXOR​(Iterable<?> i)
       
      Methods: class java.lang.Object
      Modifier and Type Method
      boolean equals​(Object o)
      int hashCode()
       
      Methods: interface java.lang.Iterable
      Modifier and Type Method
      RemoveUnsupportedIterator<E> iterator()

      • Methods inherited from interface java.lang.Iterable

        forEach

    • Method Detail

      • size

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int size()
        Returns the number of elements in this collection. If this collection contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
        Returns:
        the number of elements in this collection

      • isEmpty

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean isEmpty()
        Returns TRUE if this collection contains no elements.
        Returns:
        TRUE if this collection contains no elements

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean contains​(java.lang.Object o)
        Returns TRUE if this collection contains the specified element. More formally, returns TRUE if and only if this collection contains at least one element e such that Objects.equals(o, e).
        Parameters:
        o - element whose presence in this collection is to be tested
        Returns:
        TRUE if this collection contains the specifiedelement
        Throws:
        java.lang.ClassCastException - if the type of the specified element is incompatible with this collection (optional-restrictions)
        java.lang.NullPointerException - if the specified element is null and this collection does not permit null elements (optional-restrictions)

      • iterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        RemoveUnsupportedIterator<E> iterator()
        Returns an iterator over the elements in this collection. There are no guarantees concerning the order in which the elements are returned (unless this collection is an instance of some class that provides a guarantee).
        Specified by:
        iterator in interface java.lang.Iterable<E>
        Returns:
        an Iterator over the elements in this collection

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.lang.Object[] toArray()
        Returns an array containing all of the elements in this collection. If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order. The returned array's Class.getComponentType (runtime component type) is Object.

        The returned array will be "safe" in that no references to it are maintained by this collection. (In other words, this method must allocate a new array even if this collection is backed by an array). The caller is thus free to modify the returned array.
        Returns:
        an array, whose runtime component type is Object, containing all of the elements in this collection

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        <T> T[] toArray​(T[] a)
        Returns an array containing all of the elements in this collection; the runtime type of the returned array is that of the specified array. If the collection fits in the specified array, it is returned therein. Otherwise, a new array is allocated with the runtime type of the specified array and the size of this collection.

        If this collection fits in the specified array with room to spare (i.e., the array has more elements than this collection), the element in the array immediately following the end of the collection is set to null. (This is useful in determining the length of this collection only if the caller knows that this collection does not contain any null elements.)

        If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.
        Type Parameters:
        T - the component type of the array to contain the collection
        Parameters:
        a - the array into which the elements of this collection are to be stored, if it is big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
        Returns:
        an array containing all of the elements in this collection
        Throws:
        java.lang.ArrayStoreException - if the runtime type of any element in this collection is not assignable to the runtime component type of the specified array
        java.lang.NullPointerException - if the specified array is null

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default <T> T[] toArray​(java.util.function.IntFunction<T[]> generator)
        Returns an array containing all of the elements in this collection, using the provided generator function to allocate the returned array.

        If this collection makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.
        Type Parameters:
        T - the component type of the array to contain the collection
        Parameters:
        generator - a function which produces a new array of the desired type and the provided length
        Returns:
        an array containing all of the elements in this collection
        Throws:
        java.lang.ArrayStoreException - if the runtime type of any element in this collection is not assignable to the runtime component type of the generated array
        java.lang.NullPointerException - if the generator function is null
        Code:
        Exact Method Body:
         return toArray(generator.apply(0));

      • copyIntoCollection

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default void copyIntoCollection​
            (java.util.Collection<? super E> collection)
        Simply copies the contents of 'this' instance of ReadOnlyCollection into the user-provided 'collection' data-structure.
        Parameters:
        collection - Any Java Collection instance. This collection's 'add(E e)' method will be utilized for performing the coying.
        Code:
        Exact Method Body:
         for (E e : this) collection.add(e);

      • containsAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean containsAll​(java.util.Collection<?> c)
        Returns TRUE if this collection contains all of the elements in the specified collection.
        Parameters:
        c - collection to be checked for containment in this collection
        Returns:
        TRUE if this collection contains all of the elements in the specified collection
        Throws:
        java.lang.ClassCastException - if the types of one or more elements in the specified collection are incompatible with this collection (optional-restrictions)
        java.lang.NullPointerException - if the specified collection contains one or more null elements and this collection does not permit null elements (optional-restrictions), or if the specified collection is null.
        See Also:
        contains(Object)

      • containsAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsAND​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyCollection contains every one of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance contains every element in 'elements'
        Code:
        Exact Method Body:
         for (Object elem : elements) if (! this.contains(elem)) return false;
 return true;

      • containsNAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsNAND​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyCollection does not contain any of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance contains none of the elements in 'elements'
        Code:
        Exact Method Body:
         for (Object elem : elements) if (this.contains(elem)) return false;
 return true;

      • containsOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsOR​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyCollection contains at least one of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance contains one or more of the elements in 'elements'
        Code:
        Exact Method Body:
         for (Object elem : elements) if (this.contains(elem)) return true;
 return false;

      • containsXOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsXOR​(java.lang.Object... elements)
        Checks to ensure that 'this' instance of ReadOnlyCollection contains precisely one of the elements in Var-Args Parameter 'elements'
        Parameters:
        elements - a list of elements
        Returns:
        TRUE If and only if 'this' instance has exactly one element that is also in 'elements'
        Code:
        Exact Method Body:
         boolean found = false;

 for (Object elem : elements)

     if (this.contains(elem))
     {
         if (found) return false;
         else found = true;
     }

 return found;

      • containsAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsAND​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyCollection contains every one of the elements in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance contains every element in 'i'
        Code:
        Exact Method Body:
         for (Object o: i) if (! this.contains(o)) return false;
 return true;

      • containsNAND

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsNAND​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyCollection does not contain any of the elements in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance contains none of the elements in 'i'
        Code:
        Exact Method Body:
         for (Object o: i) if (this.contains(o)) return false;
 return true;

      • containsOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsOR​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyCollection contains at least one of the elements in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance contains one or more of the elements in 'i'
        Code:
        Exact Method Body:
         for (Object o: i) if (this.contains(o)) return true;
 return false;

      • containsXOR

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default boolean containsXOR​(java.lang.Iterable<?> i)
        Checks to ensure that 'this' instance of ReadOnlyCollection contains precisely one of the elements in Iterable parameter 'i'
        Parameters:
        i - any Java Iterable
        Returns:
        TRUE If and only if 'this' instance has exactly one element that is also in 'i'
        Code:
        Exact Method Body:
         boolean found = false;

 for (Object o: i)

     if (this.contains(o))
     {
         if (found) return false;
         else found = true;
     }

 return found;

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean equals​(java.lang.Object o)
        Compares the specified object with this collection for equality.

        While the ReadOnlyCollection interface adds no stipulations to the general contract for the Object.equals, programmers who implement the ReadOnlyCollection interface "directly" (in other words, create a class that is a ReadOnlyCollection but is not a ReadOnlySet or a ReadOnlyList) must exercise care if they choose to override the Object.equals. It is not necessary to do so, and the simplest course of action is to rely on Object's implementation, but the implementor may wish to implement a "value comparison" in place of the default "reference comparison." (The ReadOnlyList and ReadOnlySet interfaces mandate such value comparisons.)

        The general contract for the Object.equals method states that equals must be symmetric (in other words, a.equals(b) if and only if b.equals(a)). The contracts for ReadOnlyList.equals and ReadOnlySet.equals state that lists are only equal to other lists, and sets to other sets. Thus, a custom equals method for a collection class that implements neither the ReadOnlyList nor ReadOnlySet interface must return FALSE when this collection is compared to any list or set. (By the same logic, it is not possible to write a class that correctly implements both the ReadOnlySet and ReadOnlyList interfaces.)
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to be compared for equality with this collection
        Returns:
        TRUE if the specified object is equal to this collection
        See Also:
        Object.equals(Object), ReadOnlySet.equals(Object), ReadOnlyList.equals(Object)

      • hashCode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int hashCode()
        Returns the hash code value for this collection. While the Collection interface adds no stipulations to the general contract for the Object.hashCode method, programmers should take note that any class that overrides the Object.equals method must also override the Object.hashCode method in order to satisfy the general contract for the Object.hashCode method. In particular, c1.equals(c2) implies that c1.hashCode()==c2.hashCode().
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code value for this collection
        See Also:
        Object.hashCode(), Object.equals(Object)

      • spliterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default java.util.Spliterator<E> spliterator()
        Creates a Spliterator over the elements in this collection.

        Implementations should document characteristic values reported by the spliterator. Such characteristic values are not required to be reported if the spliterator reports Spliterator.SIZED and this collection contains no elements.

        The default implementation should be overridden by subclasses that can return a more efficient spliterator. In order to preserve expected laziness behavior for the stream() and parallelStream() methods, spliterators should either have the characteristic of IMMUTABLE or CONCURRENT, or be late-binding. If none of these is practical, the overriding class should describe the spliterator's documented policy of binding and structural interference, and should override the stream() and parallelStream() methods to create streams using a Supplier of the spliterator, as in: 

         Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)


        These requirements ensure that streams produced by the stream() and parallelStream() methods will reflect the contents of the collection as of initiation of the terminal stream operation.

        The default implementation creates a late-binding spliterator from the collection's Iterator.

        The created Spliterator reports Spliterator.SIZED.
        Specified by:
        spliterator in interface java.lang.Iterable<E>
        Returns:
        a Spliterator over the elements in this collection
        Code:
        Exact Method Body:
         return Spliterators.spliterator(this.iterator(), this.size(), 0);

      • stream

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default java.util.stream.Stream<E> stream()
        Returns a sequential Stream with this collection as its source.

        This method should be overridden when the spliterator() method cannot return a spliterator that is IMMUTABLE, CONCURRENT, or late-binding. (See spliterator() for details.)

        The default implementation creates a sequential Stream from the collection's Spliterator.
        Returns:
        a sequential Stream over the elements in this collection
        Code:
        Exact Method Body:
         return StreamSupport.stream(spliterator(), false);

      • parallelStream

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        default java.util.stream.Stream<E> parallelStream()
        Returns a possibly parallel Stream with this collection as its source. It is allowable for this method to return a sequential stream.

        This method should be overridden when the spliterator() method cannot return a spliterator that is IMMUTABLE, CONCURRENT, or late-binding. (See spliterator() for details.)
        Returns:
        a possibly parallel Stream over the elements in this collection
        Code:
        Exact Method Body:
         return StreamSupport.stream(spliterator(), true);