/*
 * Copyright (c) 1997, 2023, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
package Torello.Java.ReadOnly;

import Torello.Java.Additional.EffectivelyFinal;
import Torello.Java.Additional.RemoveUnsupportedIterator;

import java.util.*;

import java.util.stream.Collector;

import java.util.function.Function;
import java.util.function.Supplier;
import java.util.function.Predicate;
import java.util.function.Consumer;
import java.util.function.IntFunction;

/**
 * Immutable Wrapper for <CODE>java&#46;util&#46;HashSet</CODE>, found in the "Java Collections
 * Framework".
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=HashSet DATA-ENDING=Set>
 * <EMBED CLASS='external-html' DATA-FILE-ID=MUCHOS_CONSTRUCTORS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=DATA_CLASS>
 * 
 * @param <E> the type of elements maintained by this set
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_MAIN")
@SuppressWarnings("unchecked")
public class ReadOnlyHashSet<E>
    // extends AbstractSet<E>
    implements ReadOnlySet<E>, Cloneable, java.io.Serializable
{
    // ********************************************************************************************
    // ********************************************************************************************
    // Protected & Private Fields, Methods, Statics
    // ********************************************************************************************
    // ********************************************************************************************


    /** <EMBED CLASS='external-html' DATA-FILE-ID=SVUID> */
    protected static final long serialVersionUID = 1;

    // Minor Optimization where new HashSet's that have no contents always re-use this static
    // instance.  Since this instance is completely empty, the Raw-Types things is irrelevant.

    @SuppressWarnings("rawtypes")
    private static final HashSet EMPTY_HASH_SET = new HashSet(0, 0.75f);

    // Singleton & Empty ReadOnlyHashSet, Uses the "Supplier Constructor"
    @SuppressWarnings("rawtypes")
    private static final ReadOnlyHashSet EMPTY_READONLY_HASH_SET =
        new ReadOnlyHashSet(0, 0.75f, () -> null);

    // The actual HashSet used by this instance.
    private final HashSet<E> hashSet;

    // TRUE     => This was built using the class ROHashSetBuilder
    // FALSE    => This was built using the clone() of a standard java.util.HashSet constructor

    private final boolean fromBuilderOrHashSet;

    // Mimics the C++ Keyword/Concept of "Friend Class".   Is "Friends With" ROHashSetBuilder
    static class AccessBadge { private AccessBadge() { } }
    private static final AccessBadge friendClassBadge = new AccessBadge();

    public static <T> ReadOnlyHashSet<T> emptyROHS()
    { return (ReadOnlyHashSet<T>) EMPTY_READONLY_HASH_SET; }


    // ********************************************************************************************
    // ********************************************************************************************
    // Basic Constructors
    // ********************************************************************************************
    // ********************************************************************************************


    // To all the readers out there following along: The "AccessBadge" thing is just a slightly
    // wimpier substitute for the C++ keyword / concept 'friend' or "Friend Class".  It means this
    // constructor is (for all intents and purposes) a private-constructor, except for the class
    // ROHashSetBuilder
    //
    // This is the Constructor used by the Builder.  It has a "Zero-Size" Optimization

    ReadOnlyHashSet(ROHashSetBuilder<E> rohsb, ROHashSetBuilder.AccessBadge badge)
    {
        Objects.requireNonNull(badge, "Access Badge is null.  Requires Friend-Class Badge");

        this.fromBuilderOrHashSet = true;
        this.hashSet = rohsb;
    }

    /**
     * Copies parameter {@code 'c'} (and saves it) in order to guarantee that {@code 'this'}
     * instance is Read-Only, and shielded from outside modification.
     * 
     * @param c The {@code Collection} to be copied and saved into this instance internal
     * and private {@code 'hashSet'} field.
     */
    public ReadOnlyHashSet(Collection<E> c)
    {
        this.fromBuilderOrHashSet = false;
        this.hashSet = (c.size() == 0) ? ((HashSet<E>) EMPTY_HASH_SET) : new HashSet<>(c);
    }

    /**
     * Use a {@code Supplier<E>} to provide an arbitrary number of elements of type {@code 'E'} 
     * directly to this constructor.  This constructor will request elements from the
     * {@code Supplier} provided to parameter {@code 's'} until {@code 's'} returns null.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Supplier>
     * 
     * @param quantityIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=HASH_INIT_CAPACITY>
     * @param loadFactor        <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param s                 Any Java {@code Supplier<E>}
     * 
     * @throws IllegalArgumentException if the specified quantity / capacity is negative
     */
    public ReadOnlyHashSet(Integer quantityIfKnown, Float loadFactor, Supplier<E> s)
    {
        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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Iterable & Array Based Constructors - **NO FILTER**
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * 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 - <I>this
     * constructor can convert any Java {@code Iterable} into a {@code ReadOnlyHashSet}, using
     * a simple {@code 'mapper'}</I>.
     * 
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     *  
     * @param <T>           <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_TYPE_PARAM>
     * @param i             Any Java {@code Iterable<T>}
     * @param mapper        <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_MAPPER>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=HASH_INIT_CAPACITY>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * 
     * @throws NullPointerException if either {@code 'i'} or {@code 'mapper'} are passed null.
     * 
     * @throws IllegalArgumentException if the initial capacity ({@code 'sizeIfKnown'}) is less
     * than zero, or if the load factor is nonpositive
     */
    public <T> ReadOnlyHashSet(
            Iterable<T>                         i,
            Function<? super T, ? extends E>    mapper,
            Integer                             sizeIfKnown,
            Float                               loadFactor
        )
    {
        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;
    }

    /**
     * If a Standard Java {@code Iterable} can be directly mapped into a {@code HashSet}
     * (and, ergo, an entire Builder-Instance would be a bit excessive) - <I>this constructor will
     * seamlessly convert any Java {@code Iterable<E>} directly into a {@code ReadOnlyHashSet<E>}
     * with just this single invocation</I>.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param i             Any Java {@code Iterator<E>}
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=HASH_INIT_CAPACITY>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * 
     * @throws NullPointerException if {@code 'i'} is passed null.
     * 
     * @throws IllegalArgumentException if the initial capacity ({@code 'sizeIfKnown'}) is less
     * than zero, or if the load factor is nonpositive
     */
    public ReadOnlyHashSet(Iterable<E> i, Integer sizeIfKnown, Float loadFactor)
    {
        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;
    }

    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param elementsType  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_TYPE>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=CCEX>
     * @throws NullPointerException If {@code 'elementsType'} is passed null.
     */
    public ReadOnlyHashSet(Class<E> elementsType, Float loadFactor, Object... elements)
    {
        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));
        }
    }

    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param mapper        <EMBED CLASS='external-html' DATA-FILE-ID=OBJ_E_MAPPER>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=CCEX>
     * @throws NullPointerException If {@code 'mapper'} is passed null.
     */
    public ReadOnlyHashSet
        (Function<Object, ? extends E> mapper, Float loadFactor, Object... elements)
    {
        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));
        }
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Iterable & Array Based Constructors - **INCLUDES ELEMENT FILTER**
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * 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 - <I>this
     * constructor can convert any Java {@code Iterable} into a {@code ReadOnlyHashSet}, using
     * a simple {@code 'mapper'}</I>.
     * 
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param <T>           <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_TYPE_PARAM>
     * @param i             Any Java {@code Iterable<T>}
     * @param mapper        <EMBED CLASS='external-html' DATA-FILE-ID=ITERABLE_MAPPER>
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=T DATA-FILE-ID=PREDICATE_FILTER>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=HASH_INIT_CAPACITY>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * 
     * @throws NullPointerException if either {@code 'mapper'} or {@code 'filter'} are passed null
     * 
     * @throws IllegalArgumentException if the initial capacity ({@code 'sizeIfKnown'}) is less
     * than zero, or if the load factor is nonpositive
     */
    public <T> ReadOnlyHashSet(
            Iterable<T> i, Function<T, E>   mapper,
            Predicate<? super T>            filter,
            Integer                         sizeIfKnown,
            Float                           loadFactor
        )
    {
        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;
    }

    /**
     * If a Standard Java {@code Iterable} can be directly mapped into a {@code HashSet}
     * (and, ergo, an entire Builder-Instance would be a bit excessive) - <I>this constructor will
     * seamlessly convert any Java {@code Iterable<E>} directly into a {@code ReadOnlyHashSet<E>}
     * with just this single invocation</I>.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param i             Any Java {@code Iterator<E>}
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=E DATA-FILE-ID=PREDICATE_FILTER>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=HASH_INIT_CAPACITY>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * 
     * @throws NullPointerException if either {@code 'i'} or {@code 'filter'} are passed null
     * 
     * @throws IllegalArgumentException if the initial capacity ({@code 'sizeIfKnown'}) is less
     * than zero, or if the load factor is nonpositive
     */
    public ReadOnlyHashSet
        (Iterable<E> i, Predicate<? super E> filter, Integer sizeIfKnown, Float loadFactor)
    {
        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;
    }

    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param elementsType  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_TYPE>
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=E DATA-FILE-ID=PREDICATE_FILTER>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws ClassCastException <EMBED CLASS='external-html' DATA-FILE-ID=CCEX>
     * 
     * @throws NullPointerException If either {@code 'elementsType'} or {@code 'filter'} is passed
     * null
     */
    public ReadOnlyHashSet(
            Class<E>                elementsType,
            Predicate<? super E>    filter,
            Float                   loadFactor,
            Object...               elements
        )
    {
        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;
    }

    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param mapper <EMBED CLASS='external-html' DATA-FILE-ID=OBJ_E_MAPPER>
     * @param filter <EMBED CLASS='external-html' DATA-FTP=Object DATA-FILE-ID=PREDICATE_FILTER>
     * 
     * @param loadFactor <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements   <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws ClassCastException <EMBED CLASS='external-html' DATA-FILE-ID=CCEX>
     * @throws NullPointerException If either {@code 'mapper'} or {@code 'filter'} is passed null
     */
    public ReadOnlyHashSet(
            Function<Object, ? extends E>   mapper,
            Predicate<Object>               filter,
            Float                           loadFactor,
            Object...                       elements
        )
    {
        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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // @SafeVarargs / Variable-Arity / VarArgs: with Parameterized / Generic Type's
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param loadFactor <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements   <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     */
    @SafeVarargs
    public ReadOnlyHashSet(Float loadFactor, E... elements)
    {
        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);
        }
    }

    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param <T>           <EMBED CLASS='external-html' DATA-FILE-ID=VARARGS_TYPE_PARAM>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param mapper        <EMBED CLASS='external-html' DATA-FILE-ID=T_ARR_E_MAPPER>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If {@code 'mapper'} is passed null.
     */
    @SafeVarargs
    public <T> ReadOnlyHashSet(
            Float                               loadFactor,
            Function<? super T, ? extends E>    mapper,
            T...                                elements
        )
    {
        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));
        }
    }

    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=E DATA-FILE-ID=PREDICATE_FILTER>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If {@code 'filter'} is passed null
     */
    @SafeVarargs
    public ReadOnlyHashSet(
            Predicate<? super E>    filter,
            Float                   loadFactor,
            E...                    elements
        )
    {
        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;
    }

    /**
     * Builds {@code ReadOnlyHashSet<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param <T>           <EMBED CLASS='external-html' DATA-FILE-ID=VARARGS_TYPE_PARAM>
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=T DATA-FILE-ID=PREDICATE_FILTER>
     * @param mapper        <EMBED CLASS='external-html' DATA-FILE-ID=T_ARR_E_MAPPER>
     * @param loadFactor    <EMBED CLASS='external-html' DATA-FILE-ID=HASH_LOAD_FACTOR>
     * @param elements      <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If either {@code 'mapper'} or {@code 'filter'} is passed null
     */
    @SafeVarargs
    public <T> ReadOnlyHashSet(
            Predicate<? super T>                filter,
            Function<? super T, ? extends E>    mapper,
            Float                               loadFactor,
            T...                                elements
        )
    {
        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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // PRIMITIVE-ARRAY INPUT
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Converts a Java Primitive-Array to a {@code ReadOnlyHashSet<E>}, where {@code 'E'} is the
     * Java Boxed-Type which corresponds to the Primitive-Array's Type.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CTOR_DESC>
     * @param primitiveArray        <EMBED CLASS='external-html' DATA-FILE-ID=PRIMITIVE_ARRAY>
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * @throws NullPointerException If {@code 'primitiveArray'} is passed null;
     */
    public ReadOnlyHashSet(
            Object  primitiveArray,
            Float   loadFactor
        )
    {
        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;
    }

    /**
     * Converts a Java Primitive-Array to a {@code ReadOnlyHashSet<E>}, where {@code 'E'} is the
     * Java Boxed-Type which corresponds to the Primitive-Array's Type - <I>but also accepts a 
     * {@code 'filter'} that can remove any array-entries that need to be removed</I>.
     *
     * <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CTOR_DESC>
     * @param primitiveArray        <EMBED CLASS='external-html' DATA-FILE-ID=PRIMITIVE_ARRAY>
     * @param filter                <EMBED CLASS='external-html' DATA-FILE-ID=PRED_FILT_PRIM>
     * @throws ClassCastException   <EMBED CLASS='external-html' DATA-FILE-ID=PRIM_ARR_CCEX>
     * @throws NullPointerException If {@code 'primitiveArray'} is passed null;
     */
    public ReadOnlyHashSet(
            Object          primitiveArray,
            Float           loadFactor,
            Predicate<?>    filter
        )
    {
        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;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.util.stream.Stream HELPER
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * For use with a the Java Stream method {@code 'collect(Collector c)'}.
     * 
     * <EMBED CLASS='external-html' DATA-ABBREV=hs DATA-FILE-ID=STREAM_COLLECTOR>
     * 
     * @param <T> This is the Generic-Type of the Input-Stream.  It will also be the Generic-Type
     * of the {@code ReadOnlyHashSet} that's returned from the stream's {@code collect} method.
     * 
     * @param characteristics Optional Characteristics List.  See Java Stream-API Documentation on
     * {@code Collector.Characteristics} inner-class for more details.
     * 
     * @return This returns a collector that may be piped into a stream's {@code 'collect'} method,
     * as in the example, above.
     */
    public static <T> java.util.stream.Collector
        <T, ROHashSetBuilder<T>, ReadOnlyHashSet<T>>
        streamCollector(Collector.Characteristics... characteristics)
    {
        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
        );
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // Convert to java.util Types
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Clone's {@code 'this'} instance internal {@code HashSet<E>} field, and returns it. 
     * <EMBED CLASS='external-html' DATA-TYPE=HashSet DATA-FILE-ID=CLONE_TO>
     * 
     * @return An independent, mutable copy of {@code 'this'} instance' internal {@code HashSet<E>}
     * data-structure.
     */
    @SuppressWarnings("unchecked") // The clone() cast
    public HashSet<E> cloneToHashSet()
    { 
        return fromBuilderOrHashSet
            ? new HashSet<E>(this.hashSet)
            : (HashSet<E>) this.hashSet.clone();
    }

    /**
     * Invokes {@code java.util.Collections.unmodifiableSet} on the internal {@code HashSet}.
     * <EMBED CLASS='external-html' DATA-RET_TYPE=Set DATA-FILE-ID=WRAP_TO_IMMUTABLE>
     * 
     * @return A {@code Set} which adheres to the JDK interface {@code java.util.Set}, but throws
     * an {@code UnsupportedOperationException} if a user attempts to invoke a Mutator-Method on
     * the returned instance.
     */
    public Set<E> wrapToImmutableSet()
    { return Collections.unmodifiableSet(this.hashSet); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Original JDK Methods, java.util.HashSet
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns an iterator over the elements in this set.  The elements are returned in no
     * particular order.
     *
     * @return an {@code Iterator} over the elements in this set
     * @see ConcurrentModificationException
     */
    public RemoveUnsupportedIterator<E> iterator()
    {
        return fromBuilderOrHashSet
            ? ((ROHashSetBuilder<E>) this.hashSet).iterator()
            : new RemoveUnsupportedIterator<>(this.hashSet.iterator());
    }

    /**
     * Returns the number of elements in this set (its cardinality).
     * @return the number of elements in this set (its cardinality)
     */
    public int size()
    { return this.hashSet.size(); }

    /**
     * Returns {@code TRUE} if this set contains no elements.
     * @return {@code TRUE} if this set contains no elements
     */
    public boolean isEmpty()
    { return this.hashSet.isEmpty(); }

    /**
     * Returns {@code TRUE} if this set contains the specified element. More formally, returns
     * {@code TRUE} if and only if this set contains an element {@code e} such that
     * {@code Objects.equals(o, e)}.
     *
     * @param o element whose presence in this set is to be tested
     * @return {@code TRUE} if this set contains the specified element
     */
    public boolean contains(Object o)
    { return this.hashSet.contains(o); }

    /**
     * Creates a <em><a href="Spliterator.html#binding">late-binding</a></em> and
     * <em>fail-fast</em> {@code Spliterator} over the elements in this set.
     *
     * <BR /><BR />The {@code Spliterator} reports {@code Spliterator.SIZED} and
     * {@code Spliterator.DISTINCT}.  Overriding implementations should document the reporting of
     * additional characteristic values.
     *
     * @return a {@code Spliterator} over the elements in this set
     */
    public Spliterator<E> spliterator()
    { return this.hashSet.spliterator(); }


    // ********************************************************************************************
    // ********************************************************************************************
    // Misc Stuff that is defined in a super-class - for java.util, but not for Java.ReadOnly
    // ********************************************************************************************
    // ********************************************************************************************


    public boolean containsAll(Collection<?> c)
    { return this.hashSet.containsAll(c); }

    @Override
    public Object[] toArray()
    { return this.hashSet.toArray(); }

    @Override
    public <T> T[] toArray(T[] a)
    { return this.hashSet.toArray(a);  }


    // ********************************************************************************************
    // ********************************************************************************************
    // java.lang.Object
    // ********************************************************************************************
    // ********************************************************************************************


    /**
     * Returns a {@code String} representation of this {@code HashSet}. The {@code String}
     * representation consists of a list of the collection's elements in the order they are
     * returned by its iterator, enclosed in square brackets ({@code "[]"}). Adjacent elements are
     * separated by the characters {@code ", "} (comma and space). Elements are converted to
     * {@code String's} as by {@code String.valueOf(Object)}.
     * 
     * @return a {@code String} representation of this {@code HashSet}
     */
    public String toString()
    { return this.hashSet.toString(); }

    /**
     * Compares the specified Object with this Set for equality, as per the definition in the 
     * class {@code java.util.HashSet}.
     *
     * @param  o object to be compared for equality with this {@code ReadOnlyHashSet}.
     * @return {@code TRUE} if the specified Object is equal to this set
     */
    public boolean equals(Object o)
    { return ROHelpers.roSetEq(this, o); }

    /**
     * Returns the hash code value for this Set as per the definition in the class
     * {@code java.util.HashSet}.
     */
    public int hashCode() 
    { return this.hashSet.hashCode(); }
}