/*
 * Copyright (c) 1994, 2018, 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.RemoveUnsupportedIterator;
import Torello.Java.ReadOnly.ROVectorBuilder;

import java.io.IOException;
import java.io.ObjectInputStream;
import java.io.StreamCorruptedException;

import java.util.*;

import java.util.stream.Collector;

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

/**
 * Immutable Wrapper for <CODE>java&#46;util&#46;Vector</CODE>, found in the "Java Collections
 * Framework".
 * 
 * <EMBED CLASS=globalDefs DATA-JDK=Vector>
 * <EMBED CLASS='external-html' DATA-FILE-ID=MUCHOS_CONSTRUCTORS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=DATA_CLASS>
 * <EMBED CLASS='external-html' DATA-FILE-ID=RO_SYNCHRONIZED>
 *
 * @param <E> Type of component elements
 */
@Torello.JavaDoc.JDHeaderBackgroundImg(EmbedTagFileID="JDHBI_MAIN")
@SuppressWarnings("unchecked")
public class ReadOnlyVector<E>
    // extends AbstractReadOnlyList<E>
    implements ReadOnlyList<E>, RandomAccess, 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 Vector'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 Vector EMPTY_VECTOR = new Vector(0);

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

    // The actual Vector used by this instance.
    private final Vector<E> vector;

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

    private final boolean fromBuilderOrVector;

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

    public static <T> ReadOnlyVector<T> emptyROV()
    { return (ReadOnlyVector<T>) EMPTY_READONLY_VECTOR; }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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
    // ROVectorBuilder
    //
    // This is the Constructor used by the Builder.  It has a "Zero-Size" Optimization

    ReadOnlyVector(ROVectorBuilder<E> rovb, ROVectorBuilder.AccessBadge badge)
    {
        Objects.requireNonNull(badge, "Access Badge is null.  Requires Friend-Class Badge");

        this.fromBuilderOrVector = true;
        this.vector = rovb;
    }

    /**
     * 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 'vector'} field.
     */
    public ReadOnlyVector(Collection<E> c)
    {
        this.fromBuilderOrVector = false;

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (c.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : new Vector<>(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.
     *
     * @param quantityIfKnown If the number of elements to be supplied is known, that number may be
     * provided so that the internal {@code Vector} is adequately initialized at the beginning
     * of the constructor, without any need for resizing during construction.
     * 
     * <BR /><BR />If this parameter is passed null, it will be ignored.  When this happens, the
     * initialization of the internal {@code Vector} will be done by Java's default (Zero
     * Argument) {@code Vector}-Constructor.
     * 
     * <BR /><BR />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 {@code 'initialCapacity'} parameter to the
     * {@code Vector} constructor.
     * 
     * @param s Any Java {@code Supplier<E>}
     * 
     * @throws IllegalArgumentException if the specified quantity / capacity is negative
     */
    public ReadOnlyVector(Integer quantityIfKnown, Supplier<E> s)
    {
        fromBuilderOrVector = false;

        Vector<E>vector = (quantityIfKnown != null)
            ? new Vector<>(quantityIfKnown)
            : new Vector<>();

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

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }


    // ********************************************************************************************
    // ********************************************************************************************
    // 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 ReadOnlyVector}, 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=VECAL_INIT_CAPACITY>
     * 
     * @throws NullPointerException If either {@code 'i'} or {@code 'mapper'} are passed null.
     */
    public <T> ReadOnlyVector(
            Iterable<T>                         i,
            Function<? super T, ? extends E>    mapper,
            Integer                             sizeIfKnown
        )
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

        fromBuilderOrVector = false;

        Vector<E> vector = (sizeIfKnown != null)
            ? new Vector<>(sizeIfKnown)
            : new Vector<>();

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

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }

    /**
     * If a Standard Java {@code Iterable} can be directly mapped into a {@code Vector}
     * (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 ReadOnlyVector<E>}
     * with just this single invocation</I>.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param i             Any Java {@code Iteratable<E>}
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=VECAL_INIT_CAPACITY>
     * 
     * @throws IllegalArgumentException if the specified initial capacity is negative
     */
    public ReadOnlyVector(Iterable<E> i, Integer sizeIfKnown)
    {
        fromBuilderOrVector = false;

        Vector<E> vector = (sizeIfKnown != null)
            ? new Vector<>(sizeIfKnown)
            : new Vector<>();

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

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }

    /**
     * Builds {@code ReadOnlyVector<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param elementsType  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_TYPE>
     * @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 ReadOnlyVector(Class<E> elementsType, Object... elements)
    {
        Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");

        fromBuilderOrVector = false;

        if (elements.length == 0)
            this.vector = (Vector<E>) EMPTY_VECTOR;

        else 
        {
            this.vector = new Vector<>(elements.length);
            for (Object element : elements) this.vector.add(elementsType.cast(element));
        }
    }

    /**
     * Builds {@code ReadOnlyVector<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param mapper    <EMBED CLASS='external-html' DATA-FILE-ID=OBJ_E_MAPPER>
     * @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 ReadOnlyVector(Function<Object, ? extends E> mapper, Object... elements)
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

        fromBuilderOrVector = false;

        if (elements.length == 0)
            this.vector = (Vector<E>) EMPTY_VECTOR;

        else 
        {
            this.vector = new Vector<>(elements.length);
            for (Object element : elements) this.vector.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 ReadOnlyVector}, 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=VECAL_INIT_CAPACITY>
     * 
     * @throws NullPointerException If any of {@code 'i'}, {@code 'mapper'} or {@code 'filter'} are
     * passed null.
     */
    public <T> ReadOnlyVector(
            Iterable<T>                         i,
            Function<? super T, ? extends E>    mapper,
            Predicate<? super T>                filter,
            Integer                             sizeIfKnown
        )
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrVector = false;

        Vector<E> vector = (sizeIfKnown != null)
            ? new Vector<>(sizeIfKnown)
            : new Vector<>();

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

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }

    /**
     * If a Standard Java {@code Iterable} can be directly mapped into an {@code Vector}
     * (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 ReadOnlyVector<E>}
     * with just this single invocation</I>.
     *
     * <EMBED CLASS=defs DATA-SOURCE=Iterable>
     * 
     * @param i             Any Java {@code Iteratable<E>}
     * @param filter        <EMBED CLASS='external-html' DATA-FTP=E DATA-FILE-ID=PREDICATE_FILTER>
     * @param sizeIfKnown   <EMBED CLASS='external-html' DATA-FILE-ID=VECAL_INIT_CAPACITY>
     * 
     * @throws IllegalArgumentException if the specified initial capacity is negative
     * @throws NullPointerException     If either {@code 'i'} or {@code 'filter'} are passed null.
     */
    public ReadOnlyVector(Iterable<E> i, Predicate<? super E> filter, Integer sizeIfKnown)
    {
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrVector = false;

        Vector<E> vector = (sizeIfKnown != null)
            ? new Vector<>(sizeIfKnown)
            : new Vector<>();

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

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }

    /**
     * Builds {@code ReadOnlyVector<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 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'} are passed
     * null.
     */
    public ReadOnlyVector
        (Class<E> elementsType, Predicate<? super E> filter, Object... elements)
    {
        Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrVector = false;

        Vector<E> vector = new Vector<>(elements.length);

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

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }

    /**
     * Builds {@code ReadOnlyVector<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 elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If either {@code 'mapper'}  or {@code 'filter'} are passed null
     */
    public ReadOnlyVector(
            Function<Object, ? extends E>   mapper,
            Predicate<Object>               filter,
            Object...                       elements
        )
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrVector = false;

        Vector<E> vector = new Vector<>(elements.length);

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

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }


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


    /**
     * Builds {@code ReadOnlyVector<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param elements <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     */
    @SafeVarargs
    public ReadOnlyVector(E... elements)
    {
        fromBuilderOrVector = false;

        if (elements.length == 0)
            this.vector = (Vector<E>) EMPTY_VECTOR;

        else 
        {
            this.vector = new Vector<>(elements.length);
            for (E e : elements) this.vector.add(e);
        }
    }

    /**
     * Builds {@code ReadOnlyVector<E>} instance having Generic-Type {@code 'E'}, and contents
     * {@code 'elements'}.
     * 
     * @param <T>       <EMBED CLASS='external-html' DATA-FILE-ID=VARARGS_TYPE_PARAM>
     * @param dummy     <EMBED CLASS='external-html' DATA-FILE-ID=DUMMY_INT>
     * @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 null.
     */
    @SafeVarargs
    public <T> ReadOnlyVector
        (int dummy, Function<? super T, ? extends E> mapper, T... elements)
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

        fromBuilderOrVector = false;

        if (elements.length == 0)
            this.vector = (Vector<E>) EMPTY_VECTOR;

        else 
        {
            this.vector = new Vector<>(elements.length);
            for (T t : elements) this.vector.add(mapper.apply(t));
        }
    }

    /**
     * Builds {@code ReadOnlyVector<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 elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If {@code 'elementsType'} is null.
     */
    @SafeVarargs
    public ReadOnlyVector(Predicate<? super E> filter, E... elements)
    {
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrVector = false;

        Vector<E> vector = new Vector<>(elements.length);
        for (E e : elements) if (filter.test(e)) vector.add(e);

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }

    /**
     * Builds {@code ReadOnlyVector<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 elements  <EMBED CLASS='external-html' DATA-FILE-ID=ELEMENTS_VAR_ARGS>
     * 
     * @throws NullPointerException If {@code 'mapper'} or {@code 'filter'} is null.
     */
    @SafeVarargs
    public <T> ReadOnlyVector(
            Predicate<? super T> filter,
            Function<? super T, ? extends E> mapper,
            T... elements
        )
    {
        Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrVector = false;

        Vector<E> vector = new Vector<>(elements.length);
        for (T t : elements) if (filter.test(t)) vector.add(mapper.apply(t));

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (vector.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : vector;
    }


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


    /**
     * Converts a Java Primitive-Array to a {@code ReadOnlyVector<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 ReadOnlyVector(Object primitiveArray)
    {
        fromBuilderOrVector = false;

        Vector<E> v = ROHelpers.buildROListOrSet(
            primitiveArray,
            (int arrayLen) -> new Vector<E>(arrayLen),
            null
        );

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (v.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : v;
    }

    /**
     * Converts a Java Primitive-Array to a {@code ReadOnlyVector<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 ReadOnlyVector(
            Object          primitiveArray,
            Predicate<?>    filter
        )
    {
        Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

        fromBuilderOrVector = false;

        Vector<E> v = ROHelpers.buildROListOrSet(
            primitiveArray,
            (int arrayLen) -> new Vector<E>(arrayLen),
            filter
        );

        // Empty Optimization (throw away, completely, the reference, use static-constant)
        this.vector = (v.size() == 0) ? ((Vector<E>) EMPTY_VECTOR) : v;
    }


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


    /**
     * For use with a the Java Stream method {@code 'collect(Collector c)'}.
     * 
     * <EMBED CLASS='external-html' DATA-ABBREV=v 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 ReadOnlyVector} 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, ROVectorBuilder<T>, ReadOnlyVector<T>>
        streamCollector(Collector.Characteristics... characteristics)
    {
        return Collector.of(
            ROVectorBuilder<T>::new,    // The "Supplier"    (builds a new ROVectorBuilder)
            ROVectorBuilder<T>::add,    // The "Accumulator" (adds elements to the builder)

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

            ROVectorBuilder<T>::build,  // The "Finisher"    (Converts Builder to ReadOnlyVector)
            characteristics
        );
    }


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


    /**
     * Clone's {@code 'this'} instance internal {@code Vector<E>} field, and returns it. 
     * <EMBED CLASS='external-html' DATA-TYPE=Vector DATA-FILE-ID=CLONE_TO>
     * 
     * @return An independent, mutable copy of {@code 'this'} instance' internal {@code Vector<E>}
     * data-structure.
     */
    public Vector<E> cloneToVector()
    {
        return fromBuilderOrVector
            ? new Vector<E>(this.vector)
            : (Vector<E>) this.vector.clone(); 
    }

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


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


    /**
     * Copies the components of this {@code Vector} into the specified array.  The item at
     * index{@code k} in this {@code Vector} is copied into component {@code k} of {@code anArray}.
     *
     * @param  anArray the array into which the components get copied
     * 
     * @throws NullPointerException if the given array is null
     * 
     * @throws IndexOutOfBoundsException if the specified array is not large enough to hold all the
     * components of this {@code Vector}
     * 
     * @throws ArrayStoreException if a component of this {@code Vector} is not of a runtime type
     * that can be stored in the specified array
     * 
     * @see #toArray(Object[])
     */
    public void copyInto(Object[] anArray)
    { this.vector.copyInto(anArray); }

    /**
     * Returns the current capacity of this {@code Vector}.
     *
     * @return  the current capacity (the length of its internal data array, kept in the field
     * {@code elementData} of this {@code Vector})
     */
    public int capacity()
    { return this.vector.capacity(); }

    /**
     * Returns the number of components in this {@code Vector}.
     * 
     * @return  the number of components in this {@code Vector}
     */
    public int size()
    { return this.vector.size(); }

    /**
     * Tests if this {@code Vector} has no components.
     *
     * @return  {@code TRUE} if and only if this {@code Vector} has no components, that is, its
     * size is zero; {@code FALSE} otherwise.
     */
    public boolean isEmpty()
    { return this.vector.isEmpty(); }

    /**
     * Returns an enumeration of the components of this {@code Vector}. The returned
     * {@code Enumeration} object will generate all items in this {@code Vector}. The first item
     * generated is the item at index {@code 0}, then the item at index {@code 1}, and so on. If
     * the {@code Vector} is structurally modified while enumerating over the elements then the
     * results of enumerating are undefined.
     *
     * @return an enumeration of the components of this {@code Vector}
     */
    public Enumeration<E> elements()
    { return this.vector.elements(); }

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

    /**
     * Returns the index of the first occurrence of the specified element in this {@code Vector},
     * or {@code -1} if this {@code Vector} does not contain the element.  More formally, returns
     * the lowest index {@code i} such that {@code Objects.equals(o, get(i))}, or {@code -1} if
     * there is no such index.
     *
     * @param o element to search for
     * 
     * @return the index of the first occurrence of the specified element in this {@code Vector},
     * or {@code -1} if this {@code Vector} does not contain the element
     */
    public int indexOf(Object o)
    { return this.vector.indexOf(o); }

    /**
     * Returns the index of the first occurrence of the specified element in this {@code Vector},
     * searching forwards from {@code index}, or returns {@code -1} if the element is not found.
     * More formally, returns the lowest index {@code i} such that
     * {@code (i >= index && Objects.equals(o, get(i)))}, or {@code -1} if there is no such index.
     *
     * @param o element to search for
     * 
     * @param index index to start searching from
     * 
     * @return the index of the first occurrence of the element in this {@code Vector} at position
     * {@code index} or later in the {@code Vector}; {@code -1} if the element is not found.
     * 
     * @throws IndexOutOfBoundsException if the specified index is negative
     */
    public int indexOf(Object o, int index)
    { return this.vector.indexOf(o, index); }

    /**
     * Returns the index of the last occurrence of the specified element in this {@code Vector}, or
     * {@code -1} if this {@code Vector} does not contain the element.  More formally, returns the
     * highest index {@code i} such that {@code Objects.equals(o, get(i))}, or {@code -1} if there
     * is no such index.
     *
     * @param o element to search for
     * 
     * @return the index of the last occurrence of the specified element in this {@code Vector}, or
     * {@code -1} if this {@code Vector} does not contain the element
     */
    public int lastIndexOf(Object o)
    { return this.vector.lastIndexOf(o); }

    /**
     * Returns the index of the last occurrence of the specified element in this {@code Vector},
     * searching backwards from {@code index}, or returns {@code -1} if the element is not found.
     * More formally, returns the highest index {@code i} such that
     * {@code (i <= index && Objects.equals(o, get(i)))}, or {@code -1} if there is no such index.
     *
     * @param o element to search for
     * 
     * @param index index to start searching backwards from
     * 
     * @return the index of the last occurrence of the element at position less than or equal to
     * {@code index} in this {@code Vector}; {@code -1} if the element is not found.
     * 
     * @throws IndexOutOfBoundsException if the specified index is greater than or equal to the
     * current size of this {@code Vector}
     */
    public int lastIndexOf(Object o, int index)
    { return this.vector.lastIndexOf(index); }

    /**
     * Returns the component at the specified index.
     *
     * <BR /><BR />This method is identical in functionality to the {@link #get(int)}
     * method (which is part of the {@link ReadOnlyList} interface).
     *
     * @param index an index into this {@code Vector}
     * 
     * @return the component at the specified index
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index >= size()})
     */
    public E elementAt(int index)
    { return this.vector.elementAt(index); }

    /**
     * Returns the first component (the item at index {@code 0}) of this {@code Vector}.
     * 
     * @return the first component of this {@code Vector}
     * 
     * @throws NoSuchElementException if this {@code Vector} has no components
     */
    public E firstElement()
    { return this.vector.firstElement(); }

    /**
     * Returns the last component of the {@code Vector}.
     * 
     * @return  the last component of the {@code Vector}, i.e., the component at index
     * {@code size() - 1}
     * 
     * @throws NoSuchElementException if this {@code Vector} is empty
     */
    public E lastElement()
    { return this.vector.lastElement(); }

    /** Returns an array containing all of the elements in this {@code Vector} in the correct order. */
    public Object[] toArray()
    { return this.vector.toArray(); }

    /**
     * Returns an array containing all of the elements in this {@code Vector} in the correct order;
     * the runtime type of the returned array is that of the specified array.  If the
     * {@code Vector} 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
     * {@code Vector}.
     *
     * <BR /><BR />If the {@code Vector} fits in the specified array with room to spare (i.e., the
     * array has more elements than the {@code Vector}), the element in the array immediately
     * following the end of the {@code Vector} is set to null.  (This is useful in determining the
     * length of the {@code Vector} <em>only</em> if the caller knows that the {@code Vector} does
     * not contain any null elements.)
     *
     * @param <T> type of array elements. The same type as {@code <E>} or a supertype of
     * {@code <E>}.
     * 
     * @param a the array into which the elements of the {@code Vector} are to be stored, if it is
     * big enough; otherwise, a new array of the same runtime type is allocated for this purpose.
     * 
     * @return an array containing the elements of the {@code Vector}
     * 
     * @throws ArrayStoreException if the runtime type of a, {@code <T>}, is not a supertype of the
     * runtime type, {@code <E>}, of every element in this {@code Vector}
     * 
     * @throws NullPointerException if the given array is null
     */
    public <T> T[] toArray(T[] a)
    { return this.vector.toArray(a); }

    /**
     * Returns the element at the specified position in this {@code Vector}.
     *
     * @param index index of the element to return
     * 
     * @return object at the specified index
     * 
     * @throws ArrayIndexOutOfBoundsException if the index is out of range
     * ({@code index < 0 || index >= size()})
     */
    public E get(int index)
    { return this.vector.get(index); }

    /**
     * Returns {@code TRUE} if this {@code Vector} contains all of the elements in the specified
     * Collection
     * 
     * @param c a collection whose elements will be tested for containment in this {@code Vector}
     * 
     * @return {@code TRUE} if this {@code Vector} contains all of the elements in the specified
     * collection
     * 
     * @throws NullPointerException if the specified collection is null
     */
    public boolean containsAll(Collection<?> c)
    { return this.vector.containsAll(c); }

    /**
     * Returns a view of the portion of this List between {@code 'fromIndex'}, inclusive, and
     * {@code 'toIndex'}, exclusive.  (If {@code 'fromIndex'} and {@code 'toIndex'} are equal, the
     * returned List is empty.)  The returned List supports all of the optional
     * {@code ReadOnlyList} operations supported by this {@code ReadOnlyList}.
     *
     * <BR /><BR />This method eliminates the need for explicit range operations (of the sort that
     * commonly exist for arrays).  Any operation that expects a List can be used as a range
     * operation by operating on a subList view instead of a whole List.  Idioms may be constructed
     * for indexOf and lastIndexOf, and all of the algorithms in the Collections class can be
     * applied to a subList.
     *
     * @param fromIndex low endpoint (inclusive) of the subList
     * @param toIndex high endpoint (exclusive) of the subList
     * @return a view of the specified range within this List
     * 
     * @throws IndexOutOfBoundsException if an endpoint index value is out of range
     * {@code (fromIndex < 0 || toIndex > size)}
     * 
     * @throws IllegalArgumentException if the endpoint indices are out of order
     * {@code (fromIndex > toIndex)}
     */
    public ReadOnlyList<E> subList(int fromIndex, int toIndex)
    {
        return InterfaceBuilder.toReadOnlyList(
            fromBuilderOrVector
                ? ((ROVectorBuilder<E>) this.vector)._subList(fromIndex, toIndex, friendClassBadge)
                : this.vector.subList(fromIndex, toIndex)
        );
    }

    /**
     * Returns a list iterator over the elements in this list (in proper sequence), starting at the
     * specified position in the list. The specified index indicates the first element that would
     * be returned by an initial call to {@link ReadOnlyListIterator#next next}.  An initial call
     * to {@link ReadOnlyListIterator#previous previous} would return the element with the
     * specified index minus one.
     *
     * @throws IndexOutOfBoundsException if the index is out of range
     * {@code (index < 0 || index > size())}
     */
    public ReadOnlyListIterator<E> listIterator(int index)
    {
        return InterfaceBuilder.toReadOnlyListIterator(
            fromBuilderOrVector
                ? ((ROVectorBuilder<E>) this.vector)._listIterator(index, friendClassBadge)
                : this.vector.listIterator(index)
        );
    }

    /**
     * Returns a list iterator over the elements in this list (in proper sequence).
     * @see #listIterator(int)
     */
    public ReadOnlyListIterator<E> listIterator()
    {
        return InterfaceBuilder.toReadOnlyListIterator(
            fromBuilderOrVector
                ? ((ROVectorBuilder<E>) this.vector)._listIterator(friendClassBadge)
                : this.vector.listIterator()
        );
    }

    /**
     * Returns an iterator over the elements in this list in proper sequence.
     * 
     * @return an iterator over the elements in this list in proper sequence
     */
    public RemoveUnsupportedIterator<E> iterator()
    { return new RemoveUnsupportedIterator<>(this.vector.iterator()); }

    /** @throws NullPointerException {@inheritDoc} */
    @Override
    public void forEach(Consumer<? super E> action)
    { this.vector.forEach(action); }

    /**
     * Uses the private and internal {@code 'vector'} field to build a {@code 'Spliterator'}
     * @return a {@code Spliterator} over the elements in this list
     */
    @Override
    public Spliterator<E> spliterator()
    { return this.vector.spliterator(); }


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


    /**
     * Returns a {@code String} representation of this {@code Vector}. 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 Vector}
     */
    public String toString()
    { return this.vector.toString(); }

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

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