Interface ReadOnlySet<E>

  • Type Parameters:
    E - the type of elements maintained by this set
    All Superinterfaces:
    java.lang.Iterable<E>, ReadOnlyCollection<E>
    All Known Subinterfaces:
    ReadOnlyNavigableSet<E>, ReadOnlySequencedSet<E>, ReadOnlySortedSet<E>
    All Known Implementing Classes:
    ReadOnlyHashSet, ReadOnlyTreeSet
    public interface ReadOnlySet<E>
extends ReadOnlyCollection<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.Set<E>. This interface contains all of the methods that the standard Java interface ReadOnlySet contains - except those which would directly or indirectly modify / mutate the internal data-structure.


    • Method Detail

      • size

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int size()
        Returns the number of elements in this set (its cardinality). If this set contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
        Specified by:
        size in interface ReadOnlyCollection<E>
        Returns:
        the number of elements in this set (its cardinality)

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean contains​(java.lang.Object o)
        Returns TRUE if this set contains the specified element. More formally, returns TRUE if and only if this set contains an element e such that Objects.equals(o, e).
        Specified by:
        contains in interface ReadOnlyCollection<E>
        Parameters:
        o - element whose presence in this set is to be tested
        Returns:
        TRUE if this set contains the specified element
        Throws:
        java.lang.ClassCastException - if the type of the specified element is incompatible with this set (optional)
        java.lang.NullPointerException - if the specified element is null and this set does not permit null elements (optional)

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.lang.Object[] toArray()
        Returns an array containing all of the elements in this set. If this set 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 will be "safe" in that no references to it are maintained by this set. (In other words, this method must allocate a new array even if this set is backed by an array). The caller is thus free to modify the returned array.

        This method acts as bridge between array-based and collection-based APIs.
        Specified by:
        toArray in interface ReadOnlyCollection<E>
        Returns:
        an array containing all the elements in this set

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        <T> T[] toArray​(T[] a)
        Returns an array containing all of the elements in this set; the runtime type of the returned array is that of the specified array. If the set 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 set.

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

        If this set makes any guarantees as to what order its elements are returned by its iterator, this method must return the elements in the same order.

        Like the toArray() method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs.

        Suppose x is a set known to contain only strings. The following code can be used to dump the set into a newly allocated array of String: 
             String[] y = x.toArray(new String[0]);
        Note that toArray(new Object[0]) is identical in function to toArray().
        Specified by:
        toArray in interface ReadOnlyCollection<E>
        Type Parameters:
        T - the component type of the array to contain the collection
        Parameters:
        a - the array into which the elements of this set 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 the elements in this set
        Throws:
        java.lang.ArrayStoreException - if the runtime type of the specified array is not a supertype of the runtime type of every element in this set
        java.lang.NullPointerException - if the specified array is null

      • containsAll

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

      • cloneToSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.Set<E> cloneToSet()
        Clones the internal java.util.Set representation, and returns it. This is the Top-Level Interface-Variant of this method. It returns the Interface-Implementation java.util.Set.

        Alternate Variant:
        The two classes which implement the interface ReadOnlySet (which are ReadOnlyHashSet and ReadOnlyTreeSet), for convenience, also implement an identical "Wrap To" Method which returns the exact type of the internal Set representation (which are java.util.HashSet and java.util.TreeSet) - rather than the Top-Level Interface-Type java.util.Set.
        Returns:
        • For the sub-class ReadOnlyHashSet, this will return a cloned instance of the internal java.util.HashSet.

        • For the sub-class ReadOnlyTreeSet, this will return a cloned instance of the internal java.util.TreeSet.

      • wrapToImmutableSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.Set<E> wrapToImmutableSet()
        Invokes java.util.Collections.unmodifiableSet on the internal Set

        Standard JDK Set:
        There may be situations where the Type ReadOnlySet is simply not usable with an API that can't be adapted to accept Type's from the Java-HTML ReadOnly Package. If such a case arises, this method can be used to generate an immutable instance of a JDK-Standard java.util Type, which does not inherit from Torello.Java.ReadOnly

        Class java.util.Collections offers a method that wraps a type into an Unmodifiable-Wrapper that implements the standard java.util.Set, but throws an exception if any attempts are made to invoke Mutator-Methods.

        Unmodifiable-Collections throw Exceptions instead:
        The returned java.util.Set instance will hopefully provide an acceptable substitute when ReadOnly Type's cannot match an API's requirements. Java's Immutable-Wrappers work on a different principle - these classes retain any / all Mutator-Methods amongst their Type-Members, but instead throw an UnsupportedOperationException if any of those methods are invoked!

        Also, if a Java Collections Framework Unmodifiable-Class has any Member-Methods that return a "View" into the underlying Data-Structure, the Sub-Lists and Sub-Maps returned by those methods are also, subsequently, wrapped in an Unmodifiable-Wrapper. These returned instances will also throw an UnsupportedOperationException if any of those methods are invoked!

        This does provide a shield or layer of protection against modification to guarantee the "Immutability-Contract" offered by these classes, all-the-while returning to native Java API Collection Types, rather than Torello.Java.ReadOnly Types, which may not always be compatible with a given API or Interface requirement!

        Remember, many of the Data-Classes inside java.util have methods whose documentation state very clearly that "any changes made the this [View] will be pushed back into the original type."
        Returns:
        A Set which adheres to the JDK interface java.util.Set, but throws an UnsupportedOperationException if a user attempts to invoke a Mutator-Method on the returned instance.

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean equals​(java.lang.Object o)
        Compares the specified object with this set for equality. Returns TRUE if the specified object is also a set, the two sets have the same size, and every member of the specified set is contained in this set (or equivalently, every member of this set is contained in the specified set). This definition ensures that the equals method works properly across different implementations of the set interface.
        Specified by:
        equals in interface ReadOnlyCollection<E>
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to be compared for equality with this set
        Returns:
        TRUE if the specified object is equal to this set
        See Also:
        Object.equals(Object), equals(Object), ReadOnlyList.equals(Object)

      • hashCode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int hashCode()
        Returns the hash code value for this set. The hash code of a set is defined to be the sum of the hash codes of the elements in the set, where the hash code of a null element is defined to be zero. This ensures that s1.equals(s2) implies that s1.hashCode()==s2.hashCode() for any two sets s1 and s2, as required by the general contract of Object.hashCode.
        Specified by:
        hashCode in interface ReadOnlyCollection<E>
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code value for this set
        See Also:
        Object.equals(Object), Set.equals(Object)

      • spliterator

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

        The Spliterator reports Spliterator.DISTINCT. Implementations should document the reporting of additional characteristic values.
        Specified by:
        spliterator in interface java.lang.Iterable<E>
        Specified by:
        spliterator in interface ReadOnlyCollection<E>
        Returns:
        a Spliterator over the elements in this set
        Code:
        Exact Method Body:
         return Spliterators.spliterator(this.iterator(), this.size(), Spliterator.DISTINCT);

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of()
        Returns an unmodifiable set containing zero elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Returns:
        an empty Set
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of());

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1)
        Returns an unmodifiable set containing one element. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the single element
        Returns:
        a Set containing the specified element
        Throws:
        java.lang.NullPointerException - if the element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2)
        Returns an unmodifiable set containing two elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if the elements are duplicates
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3)
        Returns an unmodifiable set containing three elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3,
                             E e4)
        Returns an unmodifiable set containing four elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3, e4));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5)
        Returns an unmodifiable set containing five elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3, e4, e5));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6)
        Returns an unmodifiable set containing six elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3, e4, e5, e6));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7)
        Returns an unmodifiable set containing seven elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3, e4, e5, e6, e7));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8)
        Returns an unmodifiable set containing eight elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        e8 - the eighth element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3, e4, e5, e6, e7, e8));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8,
                             E e9)
        Returns an unmodifiable set containing nine elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        e8 - the eighth element
        e9 - the ninth element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3, e4, e5, e6, e7, e8, e9));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> of​(E e1,
                             E e2,
                             E e3,
                             E e4,
                             E e5,
                             E e6,
                             E e7,
                             E e8,
                             E e9,
                             E e10)
        Returns an unmodifiable set containing ten elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        e8 - the eighth element
        e9 - the ninth element
        e10 - the tenth element
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
static <E> ReadOnlySet<E> of​(E... elements)
        Returns an unmodifiable set containing an arbitrary number of elements. See Unmodifiable Sets for details.
        Type Parameters:
        E - the Set's element type
        Parameters:
        elements - the elements to be contained in the set
        Returns:
        a Set containing the specified elements
        Throws:
        java.lang.IllegalArgumentException - if there are any duplicate elements
        java.lang.NullPointerException - if an element is null or if the array is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.of(elements));

      • copyOf

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlySet<E> copyOf​(java.util.Collection<? extends E> coll)
        Returns an unmodifiable Set containing the elements of the given Collection. The given Collection must not be null, and it must not contain any null elements. If the given Collection contains duplicate elements, an arbitrary element of the duplicates is preserved. If the given Collection is subsequently modified, the returned Set will not reflect such modifications.
        Type Parameters:
        E - the Set's element type
        Parameters:
        coll - a Collection from which elements are drawn, must be non-null
        Returns:
        a Set containing the elements of the given Collection
        Throws:
        java.lang.NullPointerException - if coll is null, or if it contains any nulls
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlySet<>(Set.copyOf(coll));