Class ReadOnlyTreeSet<E>

  • Type Parameters:
    E - the type of elements maintained by this set
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<E>, ReadOnlyCollection<E>, ReadOnlyNavigableSet<E>, ReadOnlySequencedCollection<E>, ReadOnlySequencedSet<E>, ReadOnlySet<E>, ReadOnlySortedSet<E>
    public class ReadOnlyTreeSet<E>
extends java.lang.Object
implements ReadOnlyNavigableSet<E>, java.io.Serializable
    This class was originally copied from GitHub's Open-JDK Account. It has been heavily modified as all method bodies have been removed; although few changes were applied to the file's Javadoc Commenting. Method and parameter names & types have not been modified whatsoever - although several methods have been eliminated.

    This file contains nothing more than Wrapper-Code which has been placed around the code from the original Open JDK-21 Source-File of the same (or, rather, highly similar) Class-Name. The original JDK Source-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 Wrapper for java.util.TreeSet, found in the "Java Collections Framework".

    Plethora of Constructors:
    How can data actually be inserted into a class that asserts it is a Read-Only, and therefore un-modifiable, class? Well, there are numerous constructors offered by this class for precisely this purpose. A wide variety of Data-Container, Mapping-Function and Filter input-parameters facilitate getting data into this Read-Only class, via a constructor. This class offers a very strong guarantee which is that once constructed, the instance simply cannot be modified because this class simply doesn't have any Data-Modification Methods.

    In addition to the list of constructors offered, there is also a builder class that builds ReadOnlyTreeSet's. The builder actually extends java.util.TreeSet, and can therefore insert / accept / add data in just about any way that the original TreeSet can.

    Immutable Wrapper Class:
    This data class contains all of the methods that the standard Java class 'TreeSet' contains - except those which would directly or indirectly modify / mutate the internal data-structure.

    In order to guarantee that the contents and values of this TreeSet remain constant and unchanged, this class retains an internal TreeSet, and assigns it the Java modifier 'private' to prevent any outside, unwanted modification. This class' own methods are all trivial, single-line wrappers that invoke the original java.util methods, but leave out any & all wrappers for methods that have the ability to modify, update, remove or insert values into the internal and private TreeSet.

    Finally, this class offers a Read Only Guarantee, which is enforced by preventing any instantiation of this class from occuring that would allow outside references of its internal, private TreeSet field

    Immutable interface Inheritance-Tree:
    This class implements a variant of the JDK's java.util.* Interface-Stack, all of which have been slightly modified (and renamed to add the prefix 'ReadOnly' to their names). This decision was necessary because many of the support functions inside Java Collection Framework classes have utility / helper methods that retrieve & generate Sub-Maps and Sub-Sets that are linked to the original Collection's, Set's and Map's from whence they were produced.

    These Sub-Map / Sub-Set retrieval methods all sing the same refrain - changes to the returned Map / Set will be reflected into 'this' instance, and vice-versa.

    These Sub-Map's and Sub-Set's would easily (even though 'accidentally') provide a dangerous back-door means for modifying and updating a Collection that is claiming to be Read-Only & Immutable.

    As a result, the decision was made to also port all of the java.util.* interfaces, such as Set, Map, List & Collection, into the Read-Only Collections Framework by renaming them to ReadOnlySet, ReadOnlyMap, & ReadOnlyCollection - and of course to remove / eliminate all Mutator-Methods from those interfaces. This extra step further guarantees the provision that this Data-Class is, truly, Read-Only and un-modifiable.

    Self-Referential ReadOnlyTreeSet's
    Though likely uncommon in most typical software projects, it is possible for a TreeSet to actually contain a reference to itself. However, in the translation from a standard TreeSet to a ReadOnlyTreeSet, there is actually no direct and realizable way to preserve any self-referential pointers inside the ReadOnlyTreeSet which is being constructed.

    Java's Generic Type-System, generally, makes such references nearly (but not completely) impossible. Unless you have assigned java.lang.Object to the Data-Class' Generic-Type, there is likely no common Ancestor-Type that would inherit both a ReadOnlyTreeSet, and the other objects in your data-set.

    As a result, if you happen to pass an instance of data that contains references or pointers to itself, those pointers will not be updated to reference the Read-Only variant of your Data-Structure when that Data-Structure is created. The ReadOnlyTreeSet that you get back will simply contain pointers to the original Data-Structure you passed to the constructor of this class!
    See Also:
    Serialized Form


    • Field Summary

       
      Serializable ID
      Modifier and Type Field
      protected static long serialVersionUID

    • Constructor Summary

       
      Construct a ReadOnly Instance
      Constructor
      ReadOnlyTreeSet​(Collection<E> c)
      Copies parameter 'c' (and saves it) in order to guarantee that 'this' instance is Read-Only, and shielded from outside modification.
      ReadOnlyTreeSet​(
         Comparator<? super E> comparator,
         Supplier<E> s
      )
      Use a Supplier<E> to provide an arbitrary number of elements of type 'E' directly to this constructor.
      ReadOnlyTreeSet​(SortedSet<E> s)
      Copies parameter 's' (and saves it) in order to guarantee that 'this' instance is Read-Only, and shielded from outside modification.
       
      Iterable<E> Source: Build an Instance
      Constructor
      ReadOnlyTreeSet​(
         Iterable<E> i,
         Comparator<? super E> comparator
      )
      If a Standard Java Iterable can be directly mapped into a TreeSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyTreeSet<E> with just this single invocation.
      ReadOnlyTreeSet​(
         Iterable<T> i,
         Function<? super T,​? extends E> mapper,
         Comparator<? super E> comparator
      )
      If only a small amount of processing needs to be done on the contents of some Java Data-Type, and using an entire Builder-Class seems disproportionately complex - this constructor can convert any Java Iterable into a ReadOnlyTreeSet, using a simple 'mapper'.
       
      Iterable<E> Source: Build Instance, but Filter some Elements
      Constructor
      ReadOnlyTreeSet​(
         Iterable<E> i,
         Predicate<? super E> filter,
         Comparator<? super E> comparator
      )
      If a Standard Java Iterable can be directly mapped into a TreeSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyTreeSet<E> with just this single invocation.
      ReadOnlyTreeSet​(
         Iterable<T> i,
         Function<? super T,​? extends E> mapper,
         Predicate<? super T> filter,
         Comparator<? super E> comparator
      )
      If only a small amount of processing needs to be done on the contents of some Java Data-Type, and using an entire Builder-Class seems disproportionately complex - this constructor can convert any Java Iterable into a ReadOnlyTreeSet, using a simple 'mapper'.
       
      Varargs Object[]-Array Source: Build an Instance
      Constructor
      ReadOnlyTreeSet​(
         Class<E> elementsType,
         Comparator<? super E> comparator,
         Object... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyTreeSet​(
         Function<Object,​? extends E> mapper,
         Comparator<? super E> comparator,
         Object... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      Varargs Object[]-Array Source: Build Instance, but Filter some Elements
      Constructor
      ReadOnlyTreeSet​(
         Class<E> elementsType,
         Predicate<? super E> filter,
         Comparator<? super E> comparator,
         Object... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyTreeSet​(
         Function<Object,​? extends E> mapper,
         Predicate<Object> filter,
         Comparator<? super E> comparator,
         Object... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      @SafeVarargs Generic-Array Source: Build an Instance
      Constructor
      ReadOnlyTreeSet​(
         Comparator<? super E> comparator,
         E... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyTreeSet​(
         Comparator<? super E> comparator,
         Function<? super T,​? extends E> mapper,
         T... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      @SafeVarargs Generic-Array Source: Build & Filter some Elements
      Constructor
      ReadOnlyTreeSet​(
         Predicate<? super E> filter,
         Comparator<? super E> comparator,
         E... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyTreeSet​(
         Predicate<? super T> filter,
         Function<? super T,​? extends E> mapper,
         Comparator<? super E> comparator,
         T... elements
      )
      Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      Primitive Array Source: Build an Instance of a Java Boxed-Type
      Constructor
      ReadOnlyTreeSet​(
         Object primitiveArray,
         Comparator<? super E> comparator
      )
      Converts a Java Primitive-Array to a ReadOnlyTreeSet<E>, where 'E' is the Java Boxed-Type which corresponds to the Primitive-Array's Type.
      ReadOnlyTreeSet​(
         Object primitiveArray,
         Comparator<? super E> comparator,
         Predicate<?> filter
      )
      Converts a Java Primitive-Array to a ReadOnlyTreeSet<E>, where 'E' is the Java Boxed-Type which corresponds to the Primitive-Array's Type - but also accepts a 'filter' that can remove any array-entries that need to be removed.

    • Field Detail

      • serialVersionUID

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        protected static final long serialVersionUID
        This fulfils the SerialVersion UID requirement for all classes that implement Java's interface java.io.Serializable. Using the Serializable Implementation offered by java is very easy, and can make saving program state when debugging a lot easier. It can also be used in place of more complicated systems like "hibernate" to store data as well.
        See Also:
        Constant Field Values
        Code:
        Exact Field Declaration Expression:
         protected static final long serialVersionUID = 1;

    • Constructor Detail

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.util.Collection<E> c)
        Copies parameter 'c' (and saves it) in order to guarantee that 'this' instance is Read-Only, and shielded from outside modification.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        c - The TreeSet to be copied and saved into this instance internal and private 'treeSet' field.
        Code:
        Exact Constructor Body:
         fromBuilderOrTreeSet = false;
 this.treeSet = (c.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : new TreeSet<>(c);

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.util.SortedSet<E> s)
        Copies parameter 's' (and saves it) in order to guarantee that 'this' instance is Read-Only, and shielded from outside modification.
        Parameters:
        s - The TreeSet to be copied and saved into this instance internal and private 'treeSet' field.
        Code:
        Exact Constructor Body:
         fromBuilderOrTreeSet = false;
 this.treeSet = (s.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : new TreeSet<>(s);

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.util.Comparator<? super E> comparator,
                       java.util.function.Supplier<E> s)
        Use a Supplier<E> to provide an arbitrary number of elements of type 'E' directly to this constructor. This constructor will request elements from the Supplier provided to parameter 's' until 's' returns null.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        s - Any Java Supplier<E>
        Code:
        Exact Constructor Body:
         fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 E e;
 while ((e = s.get()) != null) treeSet.add(e);

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​
            (java.lang.Iterable<T> i,
             java.util.function.Function<? super T,​? extends E> mapper,
             java.util.Comparator<? super E> comparator)
        If only a small amount of processing needs to be done on the contents of some Java Data-Type, and using an entire Builder-Class seems disproportionately complex - this constructor can convert any Java Iterable into a ReadOnlyTreeSet, using a simple 'mapper'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Type Parameters:
        T - The type of the elements inside the User-Provided Iterable<T>. These elements will not actually be inserted into the internal TreeSet, but rather will first be converted by the 'mapper' to chosen / destination type 'E'.
        Parameters:
        i - Any Java Iterable
        mapper - A function for mapping the iterated elements - which have Parameterized-Type 'T' - into the object instances used by the ReadOnlyTreeSet's actual Generic-Type, which is 'E'.

        If this parameter is passed null, this method will throw a NullPointerException.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Throws:
        java.lang.NullPointerException - if either 'i' or 'mapper' are passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 for (T t : i) treeSet.add(mapper.apply(t));

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.lang.Iterable<E> i,
                       java.util.Comparator<? super E> comparator)
        If a Standard Java Iterable can be directly mapped into a TreeSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyTreeSet<E> with just this single invocation.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        i - Any Java Iterable<E>
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Code:
        Exact Constructor Body:
         fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 for (E element : i) treeSet.add(element);

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.lang.Class<E> elementsType,
                       java.util.Comparator<? super E> comparator,
                       java.lang.Object... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        elementsType - This parameter is used to specify the actual contents of the Var-Args Parameter 'elements'.

        When loading this ReadOnlyTreeSet, each element inserted will first be cast to the type 'elementsType', before insertion.

        If this cast fails, a ClassCastException will throw.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Throws:
        java.lang.ClassCastException - if any of the 'elements' cannot be assigned to the type / class 'E'.
        java.lang.NullPointerException - If 'elementsType' is passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");

 fromBuilderOrTreeSet = false;

 if (elements.length == 0)
     this.treeSet = (TreeSet<E>) EMPTY_TREE_SET;

 else 
 {
     this.treeSet = (comparator != null)
         ? new TreeSet<>(comparator)
         : new TreeSet<>();

     for (Object element : elements) this.treeSet.add(elementsType.cast(element));
 }

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​
            (java.util.function.Function<java.lang.Object,​? extends E> mapper,
             java.util.Comparator<? super E> comparator,
             java.lang.Object... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        mapper - This may be any mapping function that accepts a Java 'Object' class / type instance, and in-return provides an instance of Type 'E'.

        This 'mapper' parameter is mandatory and may not be null. If it is, a NullPointerException will throw.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Throws:
        java.lang.ClassCastException - if any of the 'elements' cannot be assigned to the type / class 'E'.
        java.lang.NullPointerException - If 'mapper' is passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrTreeSet = false;

 if (elements.length == 0)
     this.treeSet = (TreeSet<E>) EMPTY_TREE_SET;

 else 
 {
     this.treeSet = (comparator != null)
         ? new TreeSet<>(comparator)
         : new TreeSet<>();

     for (Object element : elements) this.treeSet.add(mapper.apply(element));
 }

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​
            (java.lang.Iterable<T> i,
             java.util.function.Function<? super T,​? extends E> mapper,
             java.util.function.Predicate<? super T> filter,
             java.util.Comparator<? super E> comparator)
        If only a small amount of processing needs to be done on the contents of some Java Data-Type, and using an entire Builder-Class seems disproportionately complex - this constructor can convert any Java Iterable into a ReadOnlyTreeSet, using a simple 'mapper'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Type Parameters:
        T - The type of the elements inside the User-Provided Iterable<T>. These elements will not actually be inserted into the internal TreeSet, but rather will first be converted by the 'mapper' to chosen / destination type 'E'.
        Parameters:
        i - Any Java Iterable<T>
        mapper - A function for mapping the iterated elements - which have Parameterized-Type 'T' - into the object instances used by the ReadOnlyTreeSet's actual Generic-Type, which is 'E'.

        If this parameter is passed null, this method will throw a NullPointerException.
        filter - This Java Predicate (with Generic-Type 'T') can be used to filter the input Data-Structure content, such that elements which do not pass this filter's 'test' method are eliminated from the final ReadOnlyTreeSet instance.

        This parameter may not be null, or a NullPointerException will throw. If filtering the input data isn't necessary, this class also provides another constructor that is identical to this, but has one fewer parameter - leaving out this 'filter' Predicate.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Throws:
        java.lang.NullPointerException - if any of 'i', 'mapper' or 'filter' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 for (T t : i) if (filter.test(t)) treeSet.add(mapper.apply(t));

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.lang.Iterable<E> i,
                       java.util.function.Predicate<? super E> filter,
                       java.util.Comparator<? super E> comparator)
        If a Standard Java Iterable can be directly mapped into a TreeSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyTreeSet<E> with just this single invocation.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        i - Any Java Iterabler<E>
        filter - This Java Predicate (with Generic-Type 'E') can be used to filter the input Data-Structure content, such that elements which do not pass this filter's 'test' method are eliminated from the final ReadOnlyTreeSet instance.

        This parameter may not be null, or a NullPointerException will throw. If filtering the input data isn't necessary, this class also provides another constructor that is identical to this, but has one fewer parameter - leaving out this 'filter' Predicate.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        Throws:
        java.lang.NullPointerException - if either 'i' or 'filter' are passed null
        Code:
        Exact Constructor Body:
         fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 for (E element : i) if (filter.test(element)) treeSet.add(element);

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.lang.Class<E> elementsType,
                       java.util.function.Predicate<? super E> filter,
                       java.util.Comparator<? super E> comparator,
                       java.lang.Object... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        elementsType - This parameter is used to specify the actual contents of the Var-Args Parameter 'elements'.

        When loading this ReadOnlyTreeSet, each element inserted will first be cast to the type 'elementsType', before insertion.

        If this cast fails, a ClassCastException will throw.
        filter - This Java Predicate (with Generic-Type 'E') can be used to filter the input Data-Structure content, such that elements which do not pass this filter's 'test' method are eliminated from the final ReadOnlyTreeSet instance.

        This parameter may not be null, or a NullPointerException will throw. If filtering the input data isn't necessary, this class also provides another constructor that is identical to this, but has one fewer parameter - leaving out this 'filter' Predicate.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Throws:
        java.lang.ClassCastException - if any of the 'elements' cannot be assigned to the type / class 'E'.
        java.lang.NullPointerException - If either 'elementsType' or 'filter' are passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 E e;
 for (Object element : elements)
     if (filter.test(e = elementsType.cast(element)))
         treeSet.add(e);

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​
            (java.util.function.Function<java.lang.Object,​? extends E> mapper,
             java.util.function.Predicate<java.lang.Object> filter,
             java.util.Comparator<? super E> comparator,
             java.lang.Object... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        mapper - This may be any mapping function that accepts a Java 'Object' class / type instance, and in-return provides an instance of Type 'E'.

        This 'mapper' parameter is mandatory and may not be null. If it is, a NullPointerException will throw.
        filter - This Java Predicate (with Generic-Type 'Object') can be used to filter the input Data-Structure content, such that elements which do not pass this filter's 'test' method are eliminated from the final ReadOnlyTreeSet instance.

        This parameter may not be null, or a NullPointerException will throw. If filtering the input data isn't necessary, this class also provides another constructor that is identical to this, but has one fewer parameter - leaving out this 'filter' Predicate.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Throws:
        java.lang.ClassCastException - if any of the 'elements' cannot be assigned to the type / class 'E'.
        java.lang.NullPointerException - If either 'mapper' or 'filter' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 for (Object element : elements)
     if (filter.test(element))
         treeSet.add(mapper.apply(element));

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
public ReadOnlyTreeSet​(java.util.Comparator<? super E> comparator,
                       E... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Code:
        Exact Constructor Body:
         fromBuilderOrTreeSet = false;

 if (elements.length == 0)
     this.treeSet = (TreeSet<E>) EMPTY_TREE_SET;

 else 
 {
     this.treeSet = (comparator != null)
         ? new TreeSet<>(comparator)
         : new TreeSet<>();

     for (E e : elements) this.treeSet.add(e);
 }

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyTreeSet​
            (java.util.Comparator<? super E> comparator,
             java.util.function.Function<? super T,​? extends E> mapper,
             T... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Type Parameters:
        T - The type of the elements inside the User-Provided Var-Args ArrayT... These elements will not actually be inserted into the internal TreeSet, but rather will first be converted by the 'mapper' to chosen / destination type 'E'.
        Parameters:
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        mapper - A function used to map each element of array T... into the object instances used by the ReadOnlyTreeSet's actual Generic-Type, which is 'E'.

        If this parameter is passed null, this method will throw a NullPointerException.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'mapper' is passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrTreeSet = false;

 if (elements.length == 0)
     this.treeSet = (TreeSet<E>) EMPTY_TREE_SET;

 else 
 {
     this.treeSet = (comparator != null)
         ? new TreeSet<>(comparator)
         : new TreeSet<>();

     for (T t : elements) this.treeSet.add(mapper.apply(t));
 }

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
public ReadOnlyTreeSet​(java.util.function.Predicate<? super E> filter,
                       java.util.Comparator<? super E> comparator,
                       E... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Parameters:
        filter - This Java Predicate (with Generic-Type 'E') can be used to filter the input Data-Structure content, such that elements which do not pass this filter's 'test' method are eliminated from the final ReadOnlyTreeSet instance.

        This parameter may not be null, or a NullPointerException will throw. If filtering the input data isn't necessary, this class also provides another constructor that is identical to this, but has one fewer parameter - leaving out this 'filter' Predicate.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'filter' is passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 for (E e : elements) if (filter.test(e)) treeSet.add(e);

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyTreeSet​
            (java.util.function.Predicate<? super T> filter,
             java.util.function.Function<? super T,​? extends E> mapper,
             java.util.Comparator<? super E> comparator,
             T... elements)
        Builds ReadOnlyTreeSet<E> instance having Generic-Type 'E', and contents 'elements'.

        All elements inserted into the set must implement the Comparable interface. Furthermore, all such elements must be mutually comparable: e1.compareTo(e2) must not throw a ClassCastException for any elements e1 and e2 in the set.
        Type Parameters:
        T - The type of the elements inside the User-Provided Var-Args ArrayT... These elements will not actually be inserted into the internal TreeSet, but rather will first be converted by the 'mapper' to chosen / destination type 'E'.
        Parameters:
        filter - This Java Predicate (with Generic-Type 'T') can be used to filter the input Data-Structure content, such that elements which do not pass this filter's 'test' method are eliminated from the final ReadOnlyTreeSet instance.

        This parameter may not be null, or a NullPointerException will throw. If filtering the input data isn't necessary, this class also provides another constructor that is identical to this, but has one fewer parameter - leaving out this 'filter' Predicate.
        mapper - A function used to map each element of array T... into the object instances used by the ReadOnlyTreeSet's actual Generic-Type, which is 'E'.

        If this parameter is passed null, this method will throw a NullPointerException.
        comparator - the comparator that will be used to order this set. If null, the natural ordering of the elements will be used.
        elements - A Var-Args list, or an actual array, of elements all of which are instances of type 'E' (or a sub-class of 'E').

        Due to the occasional difficulties in using Generic-Type Parameters with arrays, there are two variants of this method, one which accepts a Var-Args Array of type java.lang.Object, and one which accepts a Var-Args Array of Generic / Parameterized Type type 'E'.

        For the method-variant that accepts an array of Object, it is obligatory to provide some common super-type, of your own choosing, in order to specify the final type of the ReadOnlyTreeSet. For the variant that accepts Generic-Array E..., a ReadOnlyTreeSet<E> is constructed.
        Throws:
        java.lang.NullPointerException - If either 'mapper' or 'filter' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrTreeSet = false;

 TreeSet<E> treeSet = (comparator != null)
     ? new TreeSet<>(comparator)
     : new TreeSet<>();

 for (T t : elements) if (filter.test(t)) treeSet.add(mapper.apply(t));

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (treeSet.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : treeSet;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.lang.Object primitiveArray,
                       java.util.Comparator<? super E> comparator)
        Converts a Java Primitive-Array to a ReadOnlyTreeSet<E>, where 'E' is the Java Boxed-Type which corresponds to the Primitive-Array's Type.

        Return-Type Heuristic:
        The heuristic for the kind of ReadOnlyTreeSet returned is directly analgous to Java's Auto-Boxing and Unboxing logic. Please review the table below - this is (hopefully) extremely simple to understand.
        Primitive-ArrayReturn-Type
        int[] ReadOnlyTreeSet<Integer>
        long[] ReadOnlyTreeSet<Long>
        short[] ReadOnlyTreeSet<Short>
        byte[] ReadOnlyTreeSet<Byte>
        double[] ReadOnlyTreeSet<Double>
        float[] ReadOnlyTreeSet<Float>
        boolean[] ReadOnlyTreeSet<Boolean>
        char[] ReadOnlyTreeSet<Character>
        Parameters:
        primitiveArray - This must be a One-Dimensional Java Primitive-Array.

        This parameter, essentially, is limited to one of the 8 following types: int[], long[], short[], byte[], double[], float[], boolean[] and char[].

        If an Object-Instance whose type is not one of the above 8 listed possibilities is passed to this parameter, this constructor will immediately throw a ClassCastException. This Class Generic-Type Parameter 'E' is chosen by the inner-helper method, listed in the source-code below, 'ROHelpers.buildROListOrSet'.
        Throws:
        java.lang.ClassCastException - If 'primitiveArray' cannot be cast to a One-Dimensional, Java Primitive-Array.
        java.lang.NullPointerException - If 'primitiveArray' is passed null;
        Code:
        Exact Constructor Body:
         fromBuilderOrTreeSet = false;

 TreeSet<E> ts = ROHelpers.buildROListOrSet(
     primitiveArray,
     (int arrayLen) -> (comparator != null) ? new TreeSet<E>(comparator) : new TreeSet<E>(),
     null
 );

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (ts.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : ts;

      • ReadOnlyTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyTreeSet​(java.lang.Object primitiveArray,
                       java.util.Comparator<? super E> comparator,
                       java.util.function.Predicate<?> filter)
        Converts a Java Primitive-Array to a ReadOnlyTreeSet<E>, where 'E' is the Java Boxed-Type which corresponds to the Primitive-Array's Type - but also accepts a 'filter' that can remove any array-entries that need to be removed.

        Return-Type Heuristic:
        The heuristic for the kind of ReadOnlyTreeSet returned is directly analgous to Java's Auto-Boxing and Unboxing logic. Please review the table below - this is (hopefully) extremely simple to understand.
        Primitive-ArrayReturn-Type
        int[] ReadOnlyTreeSet<Integer>
        long[] ReadOnlyTreeSet<Long>
        short[] ReadOnlyTreeSet<Short>
        byte[] ReadOnlyTreeSet<Byte>
        double[] ReadOnlyTreeSet<Double>
        float[] ReadOnlyTreeSet<Float>
        boolean[] ReadOnlyTreeSet<Boolean>
        char[] ReadOnlyTreeSet<Character>
        Parameters:
        primitiveArray - This must be a One-Dimensional Java Primitive-Array.

        This parameter, essentially, is limited to one of the 8 following types: int[], long[], short[], byte[], double[], float[], boolean[] and char[].

        If an Object-Instance whose type is not one of the above 8 listed possibilities is passed to this parameter, this constructor will immediately throw a ClassCastException. This Class Generic-Type Parameter 'E' is chosen by the inner-helper method, listed in the source-code below, 'ROHelpers.buildROListOrSet'.
        filter - The Java Predicate passed to this parameter must have a test(...) method that can handle input-references of the Java Boxed-Type that corresponds to the Java-Primitive Type used in parameter 'primitiveArray'.

        In English this means, If you have pased an int[]-Array to 'primitiveArray', and would like to filter some of the elements out of your ReadOnlyTreeSet, then you should pass a Predicate<java.lang.Integer> to this parameter.

        If you have passed a char[]-Array, then this parameter should be a Predicate<java.lang.Character> - and so on and so forth...

        NOTE: This is, indeed, a Run-Time rather than a Compile-Time Type-Solution. If you would like to know what that means (in plain English), it is as follows: There isn't a way to request that the Java-Compiler ensure, and print error-messages on error, that you have passed a Predicate<Integer> for an int[]-Array and a Predicate<Float> for a float[]-Array.

        If an erroneous Predicate is passed to parameter 'filter', then, during Run-Time, a ClassCastException will throw - rather than having a Compile-Time Error generated.
        Throws:
        java.lang.ClassCastException - If 'primitiveArray' cannot be cast to a One-Dimensional, Java Primitive-Array.
        java.lang.NullPointerException - If 'primitiveArray' is passed null;
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrTreeSet = false;

 TreeSet<E> ts = ROHelpers.buildROListOrSet(
     primitiveArray,
     (int arrayLen) -> (comparator != null) ? new TreeSet<E>(comparator) : new TreeSet<E>(),
     filter
 );

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.treeSet = (ts.size() == 0) ? ((TreeSet<E>) EMPTY_TREE_SET) : ts;

    • Method Detail

      • streamCollector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> java.util.stream.Collector<T,​ROTreeSetBuilder<T>,​ReadOnlyTreeSet<T>> streamCollector​
            (java.util.stream.Collector.Characteristics... characteristics)
        For use with a the Java Stream method 'collect(Collector c)'. When used to collect a stream, this collector's 'finisher' method will return an instance of ReadOnlyTreeSet (having whatever Generic-Type the Input-Stream actually is).

        Example:
        ReadOnlyTreeSet<String> rots = someJavaDataStructure
     .stream()
     .filter(someTestPredicate)
     .map((X x) -> x.toString())
     .collect(ReadOnlyTreeSet.streamCollector());
        Type Parameters:
        T - This is the Generic-Type of the Input-Stream. It will also be the Generic-Type of the ReadOnlyTreeSet that's returned from the stream's collect method.
        Parameters:
        characteristics - Optional Characteristics List. See Java Stream-API Documentation on Collector.Characteristics inner-class for more details.
        Returns:
        This returns a collector that may be piped into a stream's 'collect' method, as in the example, above.
        Code:
        Exact Method Body:
         return Collector.of(
     ROTreeSetBuilder<T>::new,    // The "Supplier"    (builds a new ROTreeSetBuilder)
     ROTreeSetBuilder<T>::add,    // The "Accumulator" (adds elements to the builder)

     // Oracle Making Life Difficult - It should be the line below, but, alas, it is not!
     // ROTreeSetBuilder<T>::addAll, // The "Combiner"    (combines multiple ROTreeSetBuilders)
     //
     // In Stream.collect(), the 3rd parameter - the "combiner" - is a "BiConsumer<R, R>"
     // NOTE: A "BiConsumer" is a FunctionalInterface that does not return anything - it is
     // (obviously) a "void" return method!
     //
     // **BUT**
     //
     // In Collector.of, the 3rd parameter - the "combiner" - is a "BinaryOperation<R>"
    
     (ROTreeSetBuilder<T> rotsb1, ROTreeSetBuilder<T> rotsb2) ->
     {
         rotsb1.addAll(rotsb2);
         return rotsb1;
     },

     ROTreeSetBuilder<T>::build,  // The "Finisher"    (Converts Builder to ReadOnlyTreeSet)
     characteristics
 );

      • cloneToTreeSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.TreeSet<E> cloneToTreeSet()
        Clone's 'this' instance internal TreeSet<E> field, and returns it. This method generates a Read / Write Cloned Version of 'this' instance' internal ReadOnlyTreeSet. The instance that's returned by this method is a clone, and this decision preserves the immutable (Read-Only) protection offered by this class.

        Standard JDK TreeSet
        The returned object is a Standard JDK TreeSet data-structure (the one from package java.util). It is mutable, but again because it is a clone of 'this' instance's internal TreeSet, it is not actually 'linked' to the internal TreeSet

        This does mean that changes to the returned TreeSet instance will not be reflected to the 'this' ReadOnlyTreeSet. They are, in fact, two independent and unlinked copies of the internal data.
        Returns:
        An independent, mutable copy of 'this' instance' internal TreeSet<E> data-structure.
        Code:
        Exact Method Body:
         return fromBuilderOrTreeSet
     ? new TreeSet<E>(this.treeSet)
     : (TreeSet<E>) this.treeSet.clone();

      • wrapToImmutableSet

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

        Standard JDK Set:
        There may be situations where the Type ReadOnlyTreeSet 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.
        Code:
        Exact Method Body:
         return Collections.unmodifiableSet(this.treeSet);

      • descendingSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyNavigableSet<E> descendingSet()
        Description copied from interface: ReadOnlyNavigableSet
        Returns a reverse order view of the elements contained in this set.

        The expression s.descendingSet().descendingSet() returns a view of s essentially equivalent to s.
        Specified by:
        descendingSet in interface ReadOnlyNavigableSet<E>
        Returns:
        a reverse order view of this set
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlyNavigableSet(
     fromBuilderOrTreeSet
         ? ((ROTreeSetBuilder<E>) this.treeSet)._descendingSet(friendClassBadge)
         : this.treeSet.descendingSet()
 );

      • size

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int size()
        Returns the number of elements in this set (its cardinality).
        Specified by:
        size in interface ReadOnlyCollection<E>
        Specified by:
        size in interface ReadOnlySet<E>
        Returns:
        the number of elements in this set (its cardinality)
        Code:
        Exact Method Body:
         return this.treeSet.size();

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public 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>
        Specified by:
        contains in interface ReadOnlySet<E>
        Parameters:
        o - object to be checked for containment in this set
        Returns:
        TRUE if this set contains the specified element
        Throws:
        java.lang.ClassCastException - if the specified object cannot be compared with the elements currently in the set
        java.lang.NullPointerException - if the specified element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         return this.treeSet.contains(o);

      • subSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyNavigableSet<E> subSet​(E fromElement,
                                      boolean fromInclusive,
                                      E toElement,
                                      boolean toInclusive)
        Description copied from interface: ReadOnlyNavigableSet
        Returns a view of the portion of this set whose elements range from fromElement to toElement. If fromElement and toElement are equal, the returned set is empty unless fromInclusive and toInclusive are both true. The returned set supports all optional set operations that this set supports.
        Specified by:
        subSet in interface ReadOnlyNavigableSet<E>
        Parameters:
        fromElement - low endpoint of the returned set
        fromInclusive - TRUE if the low endpoint is to be included in the returned view
        toElement - high endpoint of the returned set
        toInclusive - TRUE if the high endpoint is to be included in the returned view
        Returns:
        a view of the portion of this set whose elements range from fromElement, inclusive, to toElement, exclusive
        Throws:
        java.lang.ClassCastException - if fromElement and toElement cannot be compared to one another using this set's comparator (or, if the set has no comparator, using natural ordering). Implementations may, but are not required to, throw this exception if fromElement or toElement cannot be compared to elements currently in the set.
        java.lang.NullPointerException - if fromElement or toElement is null and this set uses natural ordering, or its comparator does not permit null elements
        java.lang.IllegalArgumentException - if fromElement is greater than toElement; or if this set itself has a restricted range, and fromElement or toElement lies outside the bounds of the range.
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlyNavigableSet(
     fromBuilderOrTreeSet
         ? ((ROTreeSetBuilder<E>) this.treeSet)._subSet
             (fromElement, fromInclusive, toElement, toInclusive, friendClassBadge)
         : this.treeSet.subSet(fromElement, fromInclusive, toElement, toInclusive)
 );

      • headSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyNavigableSet<E> headSet​(E toElement,
                                       boolean inclusive)
        Description copied from interface: ReadOnlyNavigableSet
        Returns a view of the portion of this set whose elements are less than (or equal to, if inclusive is true) toElement.
        Specified by:
        headSet in interface ReadOnlyNavigableSet<E>
        Parameters:
        toElement - high endpoint of the returned set
        inclusive - TRUE if the high endpoint is to be included in the returned view
        Returns:
        a view of the portion of this set whose elements are less than (or equal to, if inclusive is true) toElement
        Throws:
        java.lang.ClassCastException - if toElement is not compatible with this set's comparator (or, if the set has no comparator, if toElement does not implement Comparable). Implementations may, but are not required to, throw this exception if toElement cannot be compared to elements currently in the set.
        java.lang.NullPointerException - if toElement is null and this set uses natural ordering, or its comparator does not permit null elements
        java.lang.IllegalArgumentException - if this set itself has a restricted range, and toElement lies outside the bounds of the range
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlyNavigableSet(
     fromBuilderOrTreeSet
         ? ((ROTreeSetBuilder<E>) this.treeSet)._headSet
             (toElement, inclusive, friendClassBadge)
         : this.treeSet.headSet(toElement, inclusive)
 );

      • tailSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyNavigableSet<E> tailSet​(E fromElement,
                                       boolean inclusive)
        Description copied from interface: ReadOnlyNavigableSet
        Returns a view of the portion of this set whose elements are greater than (or equal to, if inclusive is true) fromElement.
        Specified by:
        tailSet in interface ReadOnlyNavigableSet<E>
        Parameters:
        fromElement - low endpoint of the returned set
        inclusive - TRUE if the low endpoint is to be included in the returned view
        Returns:
        a view of the portion of this set whose elements are greater than or equal to fromElement
        Throws:
        java.lang.ClassCastException - if fromElement is not compatible with this set's comparator (or, if the set has no comparator, if fromElement does not implement Comparable). Implementations may, but are not required to, throw this exception if fromElement cannot be compared to elements currently in the set.
        java.lang.NullPointerException - if fromElement is null and this set uses natural ordering, or its comparator does not permit null elements
        java.lang.IllegalArgumentException - if this set itself has a restricted range, and fromElement lies outside the bounds of the range
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlyNavigableSet(
     fromBuilderOrTreeSet
         ? ((ROTreeSetBuilder<E>) this.treeSet)._tailSet
             (fromElement, inclusive, friendClassBadge)
         : this.treeSet.tailSet(fromElement, inclusive)
 );

      • subSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlySortedSet<E> subSet​(E fromElement,
                                   E toElement)
        Description copied from interface: ReadOnlyNavigableSet
        Returns a view of the portion of this set whose elements range from fromElement, inclusive, to toElement, exclusive. (If fromElement and toElement are equal, the returned set is empty.) The returned set supports all optional set operations that this set supports.

        Equivalent to subSet(fromElement, true, toElement, false).
        Specified by:
        subSet in interface ReadOnlyNavigableSet<E>
        Specified by:
        subSet in interface ReadOnlySortedSet<E>
        Parameters:
        fromElement - low endpoint (inclusive) of the returned set
        toElement - high endpoint (exclusive) of the returned set
        Returns:
        a view of the portion of this set whose elements range from fromElement, inclusive, to toElement, exclusive
        Throws:
        java.lang.ClassCastException - if fromElement and toElement cannot be compared to one another using this set's comparator (or, if the set has no comparator, using natural ordering). Implementations may, but are not required to, throw this exception if fromElement or toElement cannot be compared to elements currently in the set.
        java.lang.NullPointerException - if fromElement or toElement is null and this set uses natural ordering, or its comparator does not permit null elements
        java.lang.IllegalArgumentException - if fromElement is greater than toElement; or if this set itself has a restricted range, and fromElement or toElement lies outside the bounds of the range
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlySortedSet(
     fromBuilderOrTreeSet
         ? ((ROTreeSetBuilder<E>) this.treeSet)._subSet
             (fromElement, toElement, friendClassBadge)
         : this.treeSet.subSet(fromElement, toElement)
 );

      • headSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlySortedSet<E> headSet​(E toElement)
        Description copied from interface: ReadOnlyNavigableSet
        Returns a view of the portion of this set whose elements are strictly less than toElement. The returned set supports all optional set operations that this set supports.

        Equivalent to headSet(toElement, false).
        Specified by:
        headSet in interface ReadOnlyNavigableSet<E>
        Specified by:
        headSet in interface ReadOnlySortedSet<E>
        Parameters:
        toElement - high endpoint (exclusive) of the returned set
        Returns:
        a view of the portion of this set whose elements are strictly less than toElement
        Throws:
        java.lang.ClassCastException - if toElement is not compatible with this set's comparator (or, if the set has no comparator, if toElement does not implement Comparable). Implementations may, but are not required to, throw this exception if toElement cannot be compared to elements currently in the set.
        java.lang.NullPointerException - if toElement is null and this set uses natural ordering, or its comparator does not permit null elements
        java.lang.IllegalArgumentException - if this set itself has a restricted range, and toElement lies outside the bounds of the range
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlySortedSet(
     fromBuilderOrTreeSet
         ? ((ROTreeSetBuilder<E>) this.treeSet)._headSet(toElement, friendClassBadge)
         : this.treeSet.headSet(toElement)
 );

      • tailSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlySortedSet<E> tailSet​(E fromElement)
        Description copied from interface: ReadOnlyNavigableSet
        Returns a view of the portion of this set whose elements are greater than or equal to fromElement. The returned set supports all optional set operations that this set supports.

        Equivalent to tailSet(fromElement, true).
        Specified by:
        tailSet in interface ReadOnlyNavigableSet<E>
        Specified by:
        tailSet in interface ReadOnlySortedSet<E>
        Parameters:
        fromElement - low endpoint (inclusive) of the returned set
        Returns:
        a view of the portion of this set whose elements are greater than or equal to fromElement
        Throws:
        java.lang.ClassCastException - if fromElement is not compatible with this set's comparator (or, if the set has no comparator, if fromElement does not implement Comparable). Implementations may, but are not required to, throw this exception if fromElement cannot be compared to elements currently in the set.
        java.lang.NullPointerException - if fromElement is null and this set uses natural ordering, or its comparator does not permit null elements
        java.lang.IllegalArgumentException - if this set itself has a restricted range, and fromElement lies outside the bounds of the range
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlySortedSet(
     fromBuilderOrTreeSet
         ? ((ROTreeSetBuilder<E>) this.treeSet)._tailSet(fromElement, friendClassBadge)
         : this.treeSet.tailSet(fromElement)
 );

      • comparator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Comparator<? super E> comparator()
        Description copied from interface: ReadOnlySortedSet
        Returns the comparator used to order the elements in this set, or null if this set uses the natural ordering of its elements.
        Specified by:
        comparator in interface ReadOnlySortedSet<E>
        Returns:
        the comparator used to order the elements in this set, or null if this set uses the natural ordering of its elements
        Code:
        Exact Method Body:
         return this.treeSet.comparator();

      • first

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E first()
        Description copied from interface: ReadOnlySortedSet
        Returns the first (lowest) element currently in this set.
        Specified by:
        first in interface ReadOnlySortedSet<E>
        Returns:
        the first (lowest) element currently in this set
        Throws:
        java.util.NoSuchElementException
        Code:
        Exact Method Body:
         return this.treeSet.first();

      • last

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E last()
        Description copied from interface: ReadOnlySortedSet
        Returns the last (highest) element currently in this set.
        Specified by:
        last in interface ReadOnlySortedSet<E>
        Returns:
        the last (highest) element currently in this set
        Throws:
        java.util.NoSuchElementException
        Code:
        Exact Method Body:
         return this.treeSet.last();

      • lower

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E lower​(E e)
        Description copied from interface: ReadOnlyNavigableSet
        Returns the greatest element in this set strictly less than the given element, or null if there is no such element.
        Specified by:
        lower in interface ReadOnlyNavigableSet<E>
        Parameters:
        e - the value to match
        Returns:
        the greatest element less than e, or null if there is no such element
        Throws:
        java.lang.ClassCastException - if the specified element cannot be compared with the elements currently in the set
        java.lang.NullPointerException - if the specified element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         return this.treeSet.lower(e);

      • floor

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E floor​(E e)
        Description copied from interface: ReadOnlyNavigableSet
        Returns the greatest element in this set less than or equal to the given element, or null if there is no such element.
        Specified by:
        floor in interface ReadOnlyNavigableSet<E>
        Parameters:
        e - the value to match
        Returns:
        the greatest element less than or equal to e, or null if there is no such element
        Throws:
        java.lang.ClassCastException - if the specified element cannot be compared with the elements currently in the set
        java.lang.NullPointerException - if the specified element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         return this.treeSet.floor(e);

      • ceiling

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E ceiling​(E e)
        Description copied from interface: ReadOnlyNavigableSet
        Returns the least element in this set greater than or equal to the given element, or null if there is no such element.
        Specified by:
        ceiling in interface ReadOnlyNavigableSet<E>
        Parameters:
        e - the value to match
        Returns:
        the least element greater than or equal to e, or null if there is no such element
        Throws:
        java.lang.ClassCastException - if the specified element cannot be compared with the elements currently in the set
        java.lang.NullPointerException - if the specified element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         return this.treeSet.ceiling(e);

      • higher

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E higher​(E e)
        Description copied from interface: ReadOnlyNavigableSet
        Returns the least element in this set strictly greater than the given element, or null if there is no such element.
        Specified by:
        higher in interface ReadOnlyNavigableSet<E>
        Parameters:
        e - the value to match
        Returns:
        the least element greater than e, or null if there is no such element
        Throws:
        java.lang.ClassCastException - if the specified element cannot be compared with the elements currently in the set
        java.lang.NullPointerException - if the specified element is null and this set uses natural ordering, or its comparator does not permit null elements
        Code:
        Exact Method Body:
         return this.treeSet.higher(e);

      • containsAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsAll​(java.util.Collection<?> c)
        Description copied from interface: ReadOnlySet
        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>
        Specified by:
        containsAll in interface ReadOnlySet<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
        See Also:
        ReadOnlySet.contains(Object)
        Code:
        Exact Method Body:
         return this.treeSet.containsAll(c);

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <T> T[] toArray​(T[] a)
        Description copied from interface: ReadOnlySet
        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 ReadOnlySet.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>
        Specified by:
        toArray in interface ReadOnlySet<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
        Code:
        Exact Method Body:
         return this.treeSet.toArray(a);

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Object[] toArray()
        Description copied from interface: ReadOnlySet
        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>
        Specified by:
        toArray in interface ReadOnlySet<E>
        Returns:
        an array containing all the elements in this set
        Code:
        Exact Method Body:
         return this.treeSet.toArray();

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Returns a String representation of this TreeSet. The String representation consists of a list of the collection's elements in the order they are returned by its iterator, enclosed in square brackets ("[]"). Adjacent elements are separated by the characters ", " (comma and space). Elements are converted to String's as by String.valueOf(Object).
        Overrides:
        toString in class java.lang.Object
        Returns:
        a String representation of this TreeSet
        Code:
        Exact Method Body:
         return this.treeSet.toString();

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean equals​(java.lang.Object o)
        Compares the specified Object with this Set for equality, as per the definition in the class java.util.TreeSet.
        Specified by:
        equals in interface ReadOnlyCollection<E>
        Specified by:
        equals in interface ReadOnlySet<E>
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - object to be compared for equality with this ReadOnlyTreeSet.
        Returns:
        TRUE if the specified Object is equal to this set
        See Also:
        Object.equals(Object), ReadOnlySet.equals(Object), ReadOnlyList.equals(Object)
        Code:
        Exact Method Body:
         return ROHelpers.roSetEq(this, o);

      • hashCode

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        public int hashCode()
        Returns the hash code value for this Set as per the definition in the class java.util.TreeSet.
        Specified by:
        hashCode in interface ReadOnlyCollection<E>
        Specified by:
        hashCode in interface ReadOnlySet<E>
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code value for this set
        See Also:
        Object.equals(Object), Set.equals(Object)
        Code:
        Exact Method Body:
         return this.treeSet.hashCode();