Class ReadOnlyHashSet<E>

  • Type Parameters:
    E - the type of elements maintained by this set
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Cloneable, java.lang.Iterable<E>, ReadOnlyCollection<E>, ReadOnlySet<E>
    public class ReadOnlyHashSet<E>
extends java.lang.Object
implements ReadOnlySet<E>, java.lang.Cloneable, 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.HashSet, 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 ReadOnlyHashSet's. The builder actually extends java.util.HashSet, and can therefore insert / accept / add data in just about any way that the original HashSet can.

    Immutable Wrapper Class:
    This data class contains all of the methods that the standard Java class 'HashSet' 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 HashSet remain constant and unchanged, this class retains an internal HashSet, 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 HashSet.

    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 HashSet 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 ReadOnlyHashSet's
    Though likely uncommon in most typical software projects, it is possible for a HashSet to actually contain a reference to itself. However, in the translation from a standard HashSet to a ReadOnlyHashSet, there is actually no direct and realizable way to preserve any self-referential pointers inside the ReadOnlyHashSet 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 ReadOnlyHashSet, 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 ReadOnlyHashSet 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
      ReadOnlyHashSet​(
         Integer quantityIfKnown,
         Float loadFactor,
         Supplier<E> s
      )
      Use a Supplier<E> to provide an arbitrary number of elements of type 'E' directly to this constructor.
      ReadOnlyHashSet​(Collection<E> c)
      Copies parameter 'c' (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
      ReadOnlyHashSet​(
         Iterable<E> i,
         Integer sizeIfKnown,
         Float loadFactor
      )
      If a Standard Java Iterable can be directly mapped into a HashSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyHashSet<E> with just this single invocation.
      ReadOnlyHashSet​(
         Iterable<T> i,
         Function<? super T,​? extends E> mapper,
         Integer sizeIfKnown,
         Float loadFactor
      )
      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 ReadOnlyHashSet, using a simple 'mapper'.
       
      Iterable<E> Source: Build Instance, but Filter some Elements
      Constructor
      ReadOnlyHashSet​(
         Iterable<E> i,
         Predicate<? super E> filter,
         Integer sizeIfKnown,
         Float loadFactor
      )
      If a Standard Java Iterable can be directly mapped into a HashSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyHashSet<E> with just this single invocation.
      ReadOnlyHashSet​(
         Iterable<T> i,
         Function<T,​E> mapper,
         Predicate<? super T> filter,
         Integer sizeIfKnown,
         Float loadFactor
      )
      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 ReadOnlyHashSet, using a simple 'mapper'.
       
      Varargs Object[]-Array Source: Build an Instance
      Constructor
      ReadOnlyHashSet​(
         Class<E> elementsType,
         Float loadFactor,
         Object... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyHashSet​(
         Function<Object,​? extends E> mapper,
         Float loadFactor,
         Object... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      Varargs Object[]-Array Source: Build Instance, but Filter some Elements
      Constructor
      ReadOnlyHashSet​(
         Class<E> elementsType,
         Predicate<? super E> filter,
         Float loadFactor,
         Object... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyHashSet​(
         Function<Object,​? extends E> mapper,
         Predicate<Object> filter,
         Float loadFactor,
         Object... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      @SafeVarargs Generic-Array Source: Build an Instance
      Constructor
      ReadOnlyHashSet​(
         Float loadFactor,
         E... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyHashSet​(
         Float loadFactor,
         Function<? super T,​? extends E> mapper,
         T... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      @SafeVarargs Generic-Array Source: Build & Filter some Elements
      Constructor
      ReadOnlyHashSet​(
         Predicate<? super E> filter,
         Float loadFactor,
         E... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
      ReadOnlyHashSet​(
         Predicate<? super T> filter,
         Function<? super T,​? extends E> mapper,
         Float loadFactor,
         T... elements
      )
      Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
       
      Primitive Array Source: Build an Instance of a Java Boxed-Type
      Constructor
      ReadOnlyHashSet​(
         Object primitiveArray,
         Float loadFactor
      )
      Converts a Java Primitive-Array to a ReadOnlyHashSet<E>, where 'E' is the Java Boxed-Type which corresponds to the Primitive-Array's Type.
      ReadOnlyHashSet​(
         Object primitiveArray,
         Float loadFactor,
         Predicate<?> filter
      )
      Converts a Java Primitive-Array to a ReadOnlyHashSet<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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(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.
        Parameters:
        c - The Collection to be copied and saved into this instance internal and private 'hashSet' field.
        Code:
        Exact Constructor Body:
         this.fromBuilderOrHashSet = false;
 this.hashSet = (c.size() == 0) ? ((HashSet<E>) EMPTY_HASH_SET) : new HashSet<>(c);

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Integer quantityIfKnown,
                       java.lang.Float loadFactor,
                       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.
        Parameters:
        quantityIfKnown - If the number of elements inside the Supplier is known, it may be provided so that the internal HashSet is adequately initialized at the beginning of the constructor, without any need for resizing during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashSet constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's Standard Default-Value for a new HashSet instance of '16' will be passed to the constructor's 'initialCapacity' parameter.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        s - Any Java Supplier<E>
        Throws:
        java.lang.IllegalArgumentException - if the specified quantity / capacity is negative
        Code:
        Exact Constructor Body:
         fromBuilderOrHashSet = false;

 HashSet<E> hashSet = new HashSet<E>(
     (quantityIfKnown != null)   ? quantityIfKnown   : 16,
     (loadFactor != null)        ? loadFactor        : 0.75f
 );

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​
            (java.lang.Iterable<T> i,
             java.util.function.Function<? super T,​? extends E> mapper,
             java.lang.Integer sizeIfKnown,
             java.lang.Float loadFactor)
        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 ReadOnlyHashSet, using a simple 'mapper'.
        Type Parameters:
        T - The type of the elements inside the User-Provided Iterable<T>. These elements will not actually be inserted into the internal HashSet, 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 ReadOnlyHashSet's actual Generic-Type, which is 'E'.

        If this parameter is passed null, this method will throw a NullPointerException.
        sizeIfKnown - If the number of elements inside the Iterable is known, it may be provided so that the internal HashSet is adequately initialized at the beginning of the constructor, without any need for resizing during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashSet constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's Standard Default-Value for a new HashSet instance of '16' will be passed to the constructor's 'initialCapacity' parameter.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        Throws:
        java.lang.NullPointerException - if either 'i' or 'mapper' are passed null.
        java.lang.IllegalArgumentException - if the initial capacity ('sizeIfKnown') is less than zero, or if the load factor is nonpositive
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrHashSet = false;

 HashSet<E> hashSet = new HashSet<E>(
     (sizeIfKnown != null)   ? sizeIfKnown   : 16,
     (loadFactor != null)    ? loadFactor    : 0.75f
 );

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Iterable<E> i,
                       java.lang.Integer sizeIfKnown,
                       java.lang.Float loadFactor)
        If a Standard Java Iterable can be directly mapped into a HashSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyHashSet<E> with just this single invocation.
        Parameters:
        i - Any Java Iterator<E>
        sizeIfKnown - If the number of elements inside the Iterable is known, it may be provided so that the internal HashSet is adequately initialized at the beginning of the constructor, without any need for resizing during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashSet constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's Standard Default-Value for a new HashSet instance of '16' will be passed to the constructor's 'initialCapacity' parameter.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        Throws:
        java.lang.NullPointerException - if 'i' is passed null.
        java.lang.IllegalArgumentException - if the initial capacity ('sizeIfKnown') is less than zero, or if the load factor is nonpositive
        Code:
        Exact Constructor Body:
         fromBuilderOrHashSet = false;

 HashSet<E> hashSet = new HashSet<E>(
     (sizeIfKnown != null)   ? sizeIfKnown   : 16,
     (loadFactor != null)    ? loadFactor    : 0.75f
 );

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Class<E> elementsType,
                       java.lang.Float loadFactor,
                       java.lang.Object... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        Parameters:
        elementsType - This parameter is used to specify the actual contents of the Var-Args Parameter 'elements'.

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

        If this cast fails, a ClassCastException will throw.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<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'");

 fromBuilderOrHashSet = false;

 if (elements.length == 0)
     this.hashSet = (HashSet<E>) EMPTY_HASH_SET;

 else
 {
     this.hashSet = (loadFactor != null)
         ? new HashSet<>(elements.length, loadFactor)
         : new HashSet<>(elements.length, 0.75f);

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​
            (java.util.function.Function<java.lang.Object,​? extends E> mapper,
             java.lang.Float loadFactor,
             java.lang.Object... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        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.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<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'");

 fromBuilderOrHashSet = false;

 if (elements.length == 0)
     this.hashSet = (HashSet<E>) EMPTY_HASH_SET;

 else
 {
     this.hashSet = (loadFactor != null)
         ? new HashSet<>(elements.length, loadFactor)
         : new HashSet<>(elements.length, 0.75f);

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Iterable<T> i,
                       java.util.function.Function<T,​E> mapper,
                       java.util.function.Predicate<? super T> filter,
                       java.lang.Integer sizeIfKnown,
                       java.lang.Float loadFactor)
        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 ReadOnlyHashSet, using a simple 'mapper'.
        Type Parameters:
        T - The type of the elements inside the User-Provided Iterable<T>. These elements will not actually be inserted into the internal HashSet, 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 ReadOnlyHashSet'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 ReadOnlyHashSet 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.
        sizeIfKnown - If the number of elements inside the Iterable is known, it may be provided so that the internal HashSet is adequately initialized at the beginning of the constructor, without any need for resizing during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashSet constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's Standard Default-Value for a new HashSet instance of '16' will be passed to the constructor's 'initialCapacity' parameter.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        Throws:
        java.lang.NullPointerException - if either 'mapper' or 'filter' are passed null
        java.lang.IllegalArgumentException - if the initial capacity ('sizeIfKnown') is less than zero, or if the load factor is nonpositive
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrHashSet = false;

 HashSet<E> hashSet = new HashSet<E>(
     (sizeIfKnown != null)   ? sizeIfKnown   : 16,
     (loadFactor != null)    ? loadFactor    : 0.75f
 );

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Iterable<E> i,
                       java.util.function.Predicate<? super E> filter,
                       java.lang.Integer sizeIfKnown,
                       java.lang.Float loadFactor)
        If a Standard Java Iterable can be directly mapped into a HashSet (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyHashSet<E> with just this single invocation.
        Parameters:
        i - Any Java Iterator<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 ReadOnlyHashSet 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.
        sizeIfKnown - If the number of elements inside the Iterable is known, it may be provided so that the internal HashSet is adequately initialized at the beginning of the constructor, without any need for resizing during this class' construction.

        It is not mandatory that the value provided be accurate, as ought be seen in the code below, this value is solely used for the 'initialCapacity' argument to the HashSet constructor. When it is more accurate, the Data-Structure operates more efficiently

        If this parameter is passed null, Java's Standard Default-Value for a new HashSet instance of '16' will be passed to the constructor's 'initialCapacity' parameter.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        Throws:
        java.lang.NullPointerException - if either 'i' or 'filter' are passed null
        java.lang.IllegalArgumentException - if the initial capacity ('sizeIfKnown') is less than zero, or if the load factor is nonpositive
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrHashSet = false;

 HashSet<E> hashSet = new HashSet<E>(
     (sizeIfKnown != null)   ? sizeIfKnown   : 16,
     (loadFactor != null)    ? loadFactor    : 0.75f
 );

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Class<E> elementsType,
                       java.util.function.Predicate<? super E> filter,
                       java.lang.Float loadFactor,
                       java.lang.Object... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        Parameters:
        elementsType - This parameter is used to specify the actual contents of the Var-Args Parameter 'elements'.

        When loading this ReadOnlyHashSet, 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 ReadOnlyHashSet 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.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<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' is passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");
 Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");

 fromBuilderOrHashSet = false;

 HashSet<E> hashSet = (loadFactor != null)
     ? new HashSet<>(elements.length, loadFactor)
     : new HashSet<>(elements.length, 0.75f);

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​
            (java.util.function.Function<java.lang.Object,​? extends E> mapper,
             java.util.function.Predicate<java.lang.Object> filter,
             java.lang.Float loadFactor,
             java.lang.Object... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        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 ReadOnlyHashSet 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.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<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' is passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");
 Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrHashSet = false;

 HashSet<E> hashSet = (loadFactor != null)
     ? new HashSet<>(elements.length, loadFactor)
     : new HashSet<>(elements.length, 0.75f);

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
public ReadOnlyHashSet​(java.lang.Float loadFactor,
                       E... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        Parameters:
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<E> is constructed.
        Code:
        Exact Constructor Body:
         fromBuilderOrHashSet = false;

 if (elements.length == 0)
     this.hashSet = (HashSet<E>) EMPTY_HASH_SET;

 else
 {
     this.hashSet = (loadFactor != null)
         ? new HashSet<>(elements.length, loadFactor)
         : new HashSet<>(elements.length, 0.75f);

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyHashSet​
            (java.lang.Float loadFactor,
             java.util.function.Function<? super T,​? extends E> mapper,
             T... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        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 HashSet, but rather will first be converted by the 'mapper' to chosen / destination type 'E'.
        Parameters:
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        mapper - A function used to map each element of array T... into the object instances used by the ReadOnlyHashSet'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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'mapper' is passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrHashSet = false;

 if (elements.length == 0)
     this.hashSet = (HashSet<E>) EMPTY_HASH_SET;

 else
 {
     this.hashSet = (loadFactor != null)
         ? new HashSet<>(elements.length, loadFactor)
         : new HashSet<>(elements.length, 0.75f);

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
public ReadOnlyHashSet​(java.util.function.Predicate<? super E> filter,
                       java.lang.Float loadFactor,
                       E... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        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 ReadOnlyHashSet 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.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'filter' is passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrHashSet = false;

 HashSet<E> hashSet = (loadFactor != null)
     ? new HashSet<>(elements.length, loadFactor)
     : new HashSet<>(elements.length, 0.75f);

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyHashSet​
            (java.util.function.Predicate<? super T> filter,
             java.util.function.Function<? super T,​? extends E> mapper,
             java.lang.Float loadFactor,
             T... elements)
        Builds ReadOnlyHashSet<E> instance having Generic-Type 'E', and contents 'elements'.
        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 HashSet, 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 ReadOnlyHashSet 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 ReadOnlyHashSet's actual Generic-Type, which is 'E'.

        If this parameter is passed null, this method will throw a NullPointerException.
        loadFactor - the load factor of the HashSet

        This parameter may be passed null, and if is, Java's Standard Default-Value Load-Factor of '0.75' will be assigned as the Data-Structure's Load-Factor.
        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 ReadOnlyHashSet. For the variant that accepts Generic-Array E..., a ReadOnlyHashSet<E> is constructed.
        Throws:
        java.lang.NullPointerException - If either 'mapper' or 'filter' is passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");
 Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrHashSet = false;

 HashSet<E> hashSet = (loadFactor != null)
     ? new HashSet<>(elements.length, loadFactor)
     : new HashSet<>(elements.length, 0.75f);

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

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

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Object primitiveArray,
                       java.lang.Float loadFactor)
        Converts a Java Primitive-Array to a ReadOnlyHashSet<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 ReadOnlyHashSet 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[] ReadOnlyHashSet<Integer>
        long[] ReadOnlyHashSet<Long>
        short[] ReadOnlyHashSet<Short>
        byte[] ReadOnlyHashSet<Byte>
        double[] ReadOnlyHashSet<Double>
        float[] ReadOnlyHashSet<Float>
        boolean[] ReadOnlyHashSet<Boolean>
        char[] ReadOnlyHashSet<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:
         fromBuilderOrHashSet = false;

 HashSet<E> hs = ROHelpers.buildROListOrSet(
     primitiveArray,
     (int arrayLen) -> new HashSet<E>(arrayLen, (loadFactor != null) ? loadFactor : 0.75f),
     null
 );

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashSet = (hs.size() == 0) ? ((HashSet<E>) EMPTY_HASH_SET) : hs;

      • ReadOnlyHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyHashSet​(java.lang.Object primitiveArray,
                       java.lang.Float loadFactor,
                       java.util.function.Predicate<?> filter)
        Converts a Java Primitive-Array to a ReadOnlyHashSet<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 ReadOnlyHashSet 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[] ReadOnlyHashSet<Integer>
        long[] ReadOnlyHashSet<Long>
        short[] ReadOnlyHashSet<Short>
        byte[] ReadOnlyHashSet<Byte>
        double[] ReadOnlyHashSet<Double>
        float[] ReadOnlyHashSet<Float>
        boolean[] ReadOnlyHashSet<Boolean>
        char[] ReadOnlyHashSet<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 ReadOnlyHashSet, 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'");

 fromBuilderOrHashSet = false;

 HashSet<E> hs = ROHelpers.buildROListOrSet(
     primitiveArray,
     (int arrayLen) -> new HashSet<E>(arrayLen, (loadFactor != null) ? loadFactor : 0.75f),
     filter
 );

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.hashSet = (hs.size() == 0) ? ((HashSet<E>) EMPTY_HASH_SET) : hs;

    • Method Detail

      • streamCollector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> java.util.stream.Collector<T,​ROHashSetBuilder<T>,​ReadOnlyHashSet<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 ReadOnlyHashSet (having whatever Generic-Type the Input-Stream actually is).

        Example:
        ReadOnlyHashSet<String> rohs = someJavaDataStructure
     .stream()
     .filter(someTestPredicate)
     .map((X x) -> x.toString())
     .collect(ReadOnlyHashSet.streamCollector());
        Type Parameters:
        T - This is the Generic-Type of the Input-Stream. It will also be the Generic-Type of the ReadOnlyHashSet 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(
     ROHashSetBuilder<T>::new,    // The "Supplier"    (builds a new ROHashSetBuilder)
     ROHashSetBuilder<T>::add,    // The "Accumulator" (adds elements to the builder)

     // Oracle Making Life Difficult - It should be the line below, but, alas, it is not!
     // ROHashSetBuilder<T>::addAll, // The "Combiner"    (combines multiple ROHashSetBuilders)
     //
     // 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>"
    
     (ROHashSetBuilder<T> rohsb1, ROHashSetBuilder<T> rohsb2) ->
     {
         rohsb1.addAll(rohsb2);
         return rohsb1;
     },

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

      • cloneToHashSet

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.HashSet<E> cloneToHashSet()
        Clone's 'this' instance internal HashSet<E> field, and returns it. This method generates a Read / Write Cloned Version of 'this' instance' internal ReadOnlyHashSet. 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 HashSet
        The returned object is a Standard JDK HashSet data-structure (the one from package java.util). It is mutable, but again because it is a clone of 'this' instance's internal HashSet, it is not actually 'linked' to the internal HashSet

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

      • wrapToImmutableSet

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

        Standard JDK Set:
        There may be situations where the Type ReadOnlyHashSet 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.hashSet);

      • iterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public RemoveUnsupportedIterator<E> iterator()
        Returns an iterator over the elements in this set. The elements are returned in no particular order.
        Specified by:
        iterator in interface java.lang.Iterable<E>
        Specified by:
        iterator in interface ReadOnlyCollection<E>
        Specified by:
        iterator in interface ReadOnlySet<E>
        Returns:
        an Iterator over the elements in this set
        See Also:
        ConcurrentModificationException
        Code:
        Exact Method Body:
         return fromBuilderOrHashSet
     ? ((ROHashSetBuilder<E>) this.hashSet).iterator()
     : new RemoveUnsupportedIterator<>(this.hashSet.iterator());

      • 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.hashSet.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 - element whose presence in this set is to be tested
        Returns:
        TRUE if this set contains the specified element
        Code:
        Exact Method Body:
         return this.hashSet.contains(o);

      • spliterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Spliterator<E> spliterator()
        Creates a late-binding and fail-fast Spliterator over the elements in this set.

        The Spliterator reports Spliterator.SIZED and Spliterator.DISTINCT. Overriding 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>
        Specified by:
        spliterator in interface ReadOnlySet<E>
        Returns:
        a Spliterator over the elements in this set
        Code:
        Exact Method Body:
         return this.hashSet.spliterator();

      • 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.hashSet.containsAll(c);

      • 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.hashSet.toArray();

      • 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.hashSet.toArray(a);

      • toString

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.String toString()
        Returns a String representation of this HashSet. 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 HashSet
        Code:
        Exact Method Body:
         return this.hashSet.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.HashSet.
        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 ReadOnlyHashSet.
        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.HashSet.
        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.hashSet.hashCode();