Class ReadOnlyVector<E>

  • Type Parameters:
    E - Type of component elements
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<E>, java.util.RandomAccess, ReadOnlyCollection<E>, ReadOnlyList<E>
    public class ReadOnlyVector<E>
extends java.lang.Object
implements ReadOnlyList<E>, java.util.RandomAccess, 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 quite a bit of 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.Vector, 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 ReadOnlyVector's. The builder actually extends java.util.Vector, and can therefore insert / accept / add data in just about any way that the original Vector can.

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

    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 Vector 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 ReadOnlyVector's
    Though likely uncommon in most typical software projects, it is possible for a Vector to actually contain a reference to itself. However, in the translation from a standard Vector to a ReadOnlyVector, there is actually no direct and realizable way to preserve any self-referential pointers inside the ReadOnlyVector 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 ReadOnlyVector, 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 ReadOnlyVector that you get back will simply contain pointers to the original Data-Structure you passed to the constructor of this class!

    Synchronized Class Wrapper:
    This class is a Wrapper-Class for an internal, private Vector Field. Since this internal field is of a type that is a Thread-Safe Class, all of this internal class' methods are declared with the Java 'synchronized' keyword. You may look at the Oracle Java-Doc Pages for java.util.Vector to see it is a Multi-Threaded-Friendly Type.

    Because this Wrapper-Class is simply incapable of data-writes itself, Thread-Safe Synchronization is therefore totally irrelevant. As a result, none of the methods in this class are declared 'synchronized', and the concept is completely ignored.

    Do we need Vector & Hashtable at all?
    The Java Collections Framework provides one Thread-Safe List in java.util.Vector, and one Map through java.util.Hashtable. Each of the methods in both of these classes are adorned with the 'synchronized' keyword, meaning their functions are atomic with respect to invocations, by other threads, on the same instance of a class.

    Given that this package is about creating Read-Only Classes, and since such a class is, by definition, Thread-Safe - why should we even need a ReadOnlyVector or a ReadOnlyHashtable? Well, since the Builder's for both of these classes also 'synchronized', it was decided that these two should stick around. The other reason is simply that some people (like me, for instance) are so used to typing 'Vector' that switching to 'ArrayList' would sort of be unthinkable!

    Remember that the builder's for all of these Read-Only Collections cannot be immutable / Read-Only (otherwise how would data be inserted into them?), so it seems to be important enough to retain these two 'synchronized' variants after all - even though Read-Only classes are, by definition, Thread-Safe.
    See Also:
    Serialized Form


    • Field Summary

       
      Serializable ID
      Modifier and Type Field
      protected static long serialVersionUID

    • Constructor Summary

       
      Construct a ReadOnly Instance
      Constructor
      ReadOnlyVector​(
         Integer quantityIfKnown,
         Supplier<? extends E> s
      )
      ReadOnlyVector​(Collection<? extends E> c)
       
      Iterable<E> Source: Build an Instance
      Constructor
      ReadOnlyVector​(
         Iterable<? extends E> i,
         Integer sizeIfKnown
      )
      ReadOnlyVector​(
         Iterable<? extends T> i,
         Function<? super T,​? extends E> mapper,
         Integer sizeIfKnown
      )
       
      Iterable<E> Source: Build Instance, but Filter some Elements
      Constructor
      ReadOnlyVector​(
         Iterable<? extends E> i,
         Predicate<? super E> filter,
         Integer sizeIfKnown
      )
      ReadOnlyVector​(
         Iterable<? extends T> i,
         Function<? super T,​? extends E> mapper,
         Predicate<? super T> filter,
         Integer sizeIfKnown
      )
       
      Varargs Object[]-Array Source: Build an Instance
      Constructor
      ReadOnlyVector​(
         Class<E> elementsType,
         Object... elements
      )
      ReadOnlyVector​(
         Function<Object,​? extends E> mapper,
         Object... elements
      )
       
      Varargs Object[]-Array Source: Build Instance, but Filter some Elements
      Constructor
      ReadOnlyVector​(
         Class<E> elementsType,
         Predicate<? super E> filter,
         Object... elements
      )
      ReadOnlyVector​(
         Function<Object,​? extends E> mapper,
         Predicate<Object> filter,
         Object... elements
      )
       
      @SafeVarargs Generic-Array Source: Build an Instance
      Constructor
      ReadOnlyVector​(
         int dummy,
         Function<? super T,​? extends E> mapper,
         T... elements
      )
      ReadOnlyVector​(E... elements)
       
      @SafeVarargs Generic-Array Source: Build & Filter some Elements
      Constructor
      ReadOnlyVector​(
         Predicate<? super E> filter,
         E... elements
      )
      ReadOnlyVector​(
         Predicate<? super T> filter,
         Function<? super T,​? extends E> mapper,
         T... elements
      )
       
      Primitive Array Source: Build an Instance of a Java Boxed-Type
      Constructor
      ReadOnlyVector​(Object primitiveArray)
      ReadOnlyVector​(
         Object primitiveArray,
         Predicate<?> filter
      )

    • 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

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyVector​(java.util.Collection<? extends 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 'vector' field.
        Code:
        Exact Constructor Body:
         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);

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyVector​(java.lang.Integer quantityIfKnown,
                      java.util.function.Supplier<? extends 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 to be supplied is known, that number may be provided so that the internal Vector is adequately initialized at the beginning of the constructor, without any need for resizing during construction.

        If this parameter is passed null, it will be ignored. When this happens, the initialization of the internal Vector will be done by Java's default (Zero Argument) Vector-Constructor.

        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' parameter to the Vector constructor.
        s - Any Java Supplier<? extends E>
        Throws:
        java.lang.IllegalArgumentException - if the specified quantity / capacity is negative
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyVector

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

        If this parameter is passed null, it will be ignored. If this happens, the initialization of the internal Vector will be done by Java's default (Zero Argument) Vector-Constructor.

        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' parameter to the Vector constructor.
        Throws:
        java.lang.NullPointerException - If either 'i' or 'mapper' are passed null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyVector

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

        If this parameter is passed null, it will be ignored. If this happens, the initialization of the internal Vector will be done by Java's default (Zero Argument) Vector-Constructor.

        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' parameter to the Vector constructor.
        Throws:
        java.lang.IllegalArgumentException - if the specified initial capacity is negative
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyVector​(java.lang.Class<E> elementsType,
                      java.lang.Object... elements)
        Builds ReadOnlyVector<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 ReadOnlyVector, each element inserted will first be cast to the type 'elementsType', before insertion.

        If this cast fails, a ClassCastException will throw.
        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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<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'");

 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));
 }

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyVector​
            (java.util.function.Function<java.lang.Object,​? extends E> mapper,
             java.lang.Object... elements)
        Builds ReadOnlyVector<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.
        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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<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'");

 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));
 }

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyVector​
            (java.lang.Iterable<? extends T> i,
             java.util.function.Function<? super T,​? extends E> mapper,
             java.util.function.Predicate<? super T> filter,
             java.lang.Integer sizeIfKnown)
        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 ReadOnlyVector, using a simple 'mapper'.
        Type Parameters:
        T - The type of the elements inside the User-Provided Iterable<? extends T>. These elements will not actually be inserted into the internal Vector, but rather will first be converted by the 'mapper' to chosen / destination type 'E'.
        Parameters:
        i - Any Java Iterable<? extends T>
        mapper - A function for mapping the iterated elements - which have Parameterized-Type 'T' - into the object instances used by the ReadOnlyVector'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 ReadOnlyVector 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 Vector is adequately initialized at the beginning of the constructor, without any need for resizing during this class' construction.

        If this parameter is passed null, it will be ignored. If this happens, the initialization of the internal Vector will be done by Java's default (Zero Argument) Vector-Constructor.

        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' parameter to the Vector constructor.
        Throws:
        java.lang.NullPointerException - If any of 'i', 'mapper' or 'filter' are passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 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;

      • ReadOnlyVector

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

        If this parameter is passed null, it will be ignored. If this happens, the initialization of the internal Vector will be done by Java's default (Zero Argument) Vector-Constructor.

        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' parameter to the Vector constructor.
        Throws:
        java.lang.IllegalArgumentException - if the specified initial capacity is negative
        java.lang.NullPointerException - If either 'i' or 'filter' are passed null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyVector​(java.lang.Class<E> elementsType,
                      java.util.function.Predicate<? super E> filter,
                      java.lang.Object... elements)
        Builds ReadOnlyVector<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 ReadOnlyVector, 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 ReadOnlyVector 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.
        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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<E> is constructed.
        Throws:
        java.lang.ClassCastException - if any of the 'elements' cannot be assigned to the type / class 'E'.
        java.lang.NullPointerException - If either 'elementsType' or 'filter' are passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 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;

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyVector​
            (java.util.function.Function<java.lang.Object,​? extends E> mapper,
             java.util.function.Predicate<java.lang.Object> filter,
             java.lang.Object... elements)
        Builds ReadOnlyVector<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 ReadOnlyVector 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.
        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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<E> is constructed.
        Throws:
        java.lang.NullPointerException - If either 'mapper' or 'filter' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 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;

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
public ReadOnlyVector​(E... elements)
        Builds ReadOnlyVector<E> instance having Generic-Type 'E', and contents 'elements'.
        Parameters:
        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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<E> is constructed.
        Code:
        Exact Constructor Body:
         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);
 }

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyVector​
            (int dummy,
             java.util.function.Function<? super T,​? extends E> mapper,
             T... elements)
        Builds ReadOnlyVector<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 Vector, but rather will first be converted by the 'mapper' to chosen / destination type 'E'.
        Parameters:
        dummy - To escape the clutches of Compiler-Messages about Generic-Erasure and Name-Clashes - this integer parameter is needed. Any value at all may passed here; it's always ignored!
        mapper - A function used to map each element of array T... into the object instances used by the ReadOnlyVector'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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'mapper' is null.
        Code:
        Exact Constructor Body:
         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));
 }

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
public ReadOnlyVector​(java.util.function.Predicate<? super E> filter,
                      E... elements)
        Builds ReadOnlyVector<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 ReadOnlyVector 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.
        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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'elementsType' is null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyVector

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyVector​
            (java.util.function.Predicate<? super T> filter,
             java.util.function.Function<? super T,​? extends E> mapper,
             T... elements)
        Builds ReadOnlyVector<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 Vector, 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 ReadOnlyVector 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 ReadOnlyVector'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 ReadOnlyVector. For the variant that accepts Generic-Array E..., a ReadOnlyVector<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'mapper' or 'filter' is null.
        Code:
        Exact Constructor Body:
         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;

      • ReadOnlyVector

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

 Vector<E> v = ROHelperPrimitiveArrays.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;

      • ReadOnlyVector

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

 fromBuilderOrVector = false;

 Vector<E> v = ROHelperPrimitiveArrays.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;

    • Method Detail

      • emptyROV

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public static <T> ReadOnlyVector<T> emptyROV()
        Returns an empty, singleton, instance of ReadOnlyVector.
        Type Parameters:
        T - Returned ReadOnlyList's Data-Type.
        Returns:
        An empty list. Since this list is both empty & read-only, a raw-type singleton will suffice for all operations offered by this clas.

        NOTE: The instance that is returned is a static, final constant which is constructed during the loading of this class by the Class-Loader. It is fully Thread-Safe, unless it is going to be used as an Object-Monitor to help lock a Synchronized Code-Block!
        Code:
        Exact Method Body:
         return (ReadOnlyVector<T>) EMPTY_READONLY_VECTOR;

      • streamCollector

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

        Example:
        ReadOnlyVector<String> rov = someJavaDataStructure
     .stream()
     .filter(someTestPredicate)
     .map((X x) -> x.toString())
     .collect(ReadOnlyVector.streamCollector());
        Type Parameters:
        T - This is the Generic-Type of the Input-Stream. It will also be the Generic-Type of the ReadOnlyVector 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(
     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
 );

      • cloneToVector

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

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

      • wrapToImmutableList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.List<E> wrapToImmutableList()
        Description copied from interface: ReadOnlyList
        Invokes java.util.Collections.unmodifiableList on the internal List.

        Standard JDK List:
        There may be situations where the Type ReadOnlyList 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.List, but throws an exception if any attempts are made to invoke Mutator-Methods.

        Unmodifiable-Collections throw Exceptions instead:
        The returned java.util.List 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."
        Specified by:
        wrapToImmutableList in interface ReadOnlyList<E>
        Returns:
        A List which adheres to the JDK interface java.util.List, but throws an UnsupportedOperationException if a user attempts to invoke a Mutator-Method on the returned instance.
        Code:
        Exact Method Body:
         return Collections.unmodifiableList(this.vector);

      • copyInto

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void copyInto​(java.lang.Object[] anArray)
        Copies the components of this Vector into the specified array. The item at indexk in this Vector is copied into component k of anArray.
        Parameters:
        anArray - the array into which the components get copied
        Throws:
        java.lang.NullPointerException - if the given array is null
        java.lang.IndexOutOfBoundsException - if the specified array is not large enough to hold all the components of this Vector
        java.lang.ArrayStoreException - if a component of this Vector is not of a runtime type that can be stored in the specified array
        See Also:
        toArray(Object[])
        Code:
        Exact Method Body:
         this.vector.copyInto(anArray);

      • capacity

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int capacity()
        Returns the current capacity of this Vector.
        Returns:
        the current capacity (the length of its internal data array, kept in the field elementData of this Vector)
        Code:
        Exact Method Body:
         return this.vector.capacity();

      • elements

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Enumeration<E> elements()
        Returns an enumeration of the components of this Vector. The returned Enumeration object will generate all items in this Vector. The first item generated is the item at index 0, then the item at index 1, and so on. If the Vector is structurally modified while enumerating over the elements then the results of enumerating are undefined.
        Returns:
        an enumeration of the components of this Vector
        Code:
        Exact Method Body:
         return this.vector.elements();

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean contains​(java.lang.Object o)
        Returns TRUE if this Vector contains the specified element. More formally, returns TRUE if and only if this Vector contains at least one element e such that Objects.equals(o, e).
        Specified by:
        contains in interface ReadOnlyCollection<E>
        Specified by:
        contains in interface ReadOnlyList<E>
        Parameters:
        o - element whose presence in this Vector is to be tested
        Returns:
        TRUE if this Vector contains the specified element
        Code:
        Exact Method Body:
         return this.vector.contains(o);

      • indexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int indexOf​(java.lang.Object o)
        Returns the index of the first occurrence of the specified element in this Vector, or -1 if this Vector does not contain the element. More formally, returns the lowest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.
        Specified by:
        indexOf in interface ReadOnlyList<E>
        Parameters:
        o - element to search for
        Returns:
        the index of the first occurrence of the specified element in this Vector, or -1 if this Vector does not contain the element
        Code:
        Exact Method Body:
         return this.vector.indexOf(o);

      • indexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int indexOf​(java.lang.Object o,
                   int index)
        Returns the index of the first occurrence of the specified element in this Vector, searching forwards from index, or returns -1 if the element is not found. More formally, returns the lowest index i such that (i >= index && Objects.equals(o, get(i))), or -1 if there is no such index.
        Parameters:
        o - element to search for
        index - index to start searching from
        Returns:
        the index of the first occurrence of the element in this Vector at position index or later in the Vector; -1 if the element is not found.
        Throws:
        java.lang.IndexOutOfBoundsException - if the specified index is negative
        Code:
        Exact Method Body:
         return this.vector.indexOf(o, index);

      • lastIndexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int lastIndexOf​(java.lang.Object o)
        Returns the index of the last occurrence of the specified element in this Vector, or -1 if this Vector does not contain the element. More formally, returns the highest index i such that Objects.equals(o, get(i)), or -1 if there is no such index.
        Specified by:
        lastIndexOf in interface ReadOnlyList<E>
        Parameters:
        o - element to search for
        Returns:
        the index of the last occurrence of the specified element in this Vector, or -1 if this Vector does not contain the element
        Code:
        Exact Method Body:
         return this.vector.lastIndexOf(o);

      • lastIndexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int lastIndexOf​(java.lang.Object o,
                       int index)
        Returns the index of the last occurrence of the specified element in this Vector, searching backwards from index, or returns -1 if the element is not found. More formally, returns the highest index i such that (i <= index && Objects.equals(o, get(i))), or -1 if there is no such index.
        Parameters:
        o - element to search for
        index - index to start searching backwards from
        Returns:
        the index of the last occurrence of the element at position less than or equal to index in this Vector; -1 if the element is not found.
        Throws:
        java.lang.IndexOutOfBoundsException - if the specified index is greater than or equal to the current size of this Vector
        Code:
        Exact Method Body:
         return this.vector.lastIndexOf(index);

      • elementAt

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E elementAt​(int index)
        Returns the component at the specified index.

        This method is identical in functionality to the get(int) method (which is part of the ReadOnlyList interface).
        Parameters:
        index - an index into this Vector
        Returns:
        the component at the specified index
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         return this.vector.elementAt(index);

      • firstElement

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E firstElement()
        Returns the first component (the item at index 0) of this Vector.
        Returns:
        the first component of this Vector
        Throws:
        java.util.NoSuchElementException - if this Vector has no components
        Code:
        Exact Method Body:
         return this.vector.firstElement();

      • lastElement

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E lastElement()
        Returns the last component of the Vector.
        Returns:
        the last component of the Vector, i.e., the component at index size() - 1
        Throws:
        java.util.NoSuchElementException - if this Vector is empty
        Code:
        Exact Method Body:
         return this.vector.lastElement();

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Object[] toArray()
        Returns an array containing all of the elements in this Vector in the correct order.
        Specified by:
        toArray in interface ReadOnlyCollection<E>
        Specified by:
        toArray in interface ReadOnlyList<E>
        Returns:
        an array containing all of the elements in this list in proper sequence
        Code:
        Exact Method Body:
         return this.vector.toArray();

      • toArray

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

        If the Vector fits in the specified array with room to spare (i.e., the array has more elements than the Vector), the element in the array immediately following the end of the Vector is set to null. (This is useful in determining the length of the Vector only if the caller knows that the Vector does not contain any null elements.)
        Specified by:
        toArray in interface ReadOnlyCollection<E>
        Specified by:
        toArray in interface ReadOnlyList<E>
        Type Parameters:
        T - type of array elements. The same type as <E> or a supertype of <E>.
        Parameters:
        a - the array into which the elements of the Vector 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 the elements of the Vector
        Throws:
        java.lang.ArrayStoreException - if the runtime type of a, <T>, is not a supertype of the runtime type, <E>, of every element in this Vector
        java.lang.NullPointerException - if the given array is null
        Code:
        Exact Method Body:
         return this.vector.toArray(a);

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public E get​(int index)
        Returns the element at the specified position in this Vector.
        Specified by:
        get in interface ReadOnlyList<E>
        Parameters:
        index - index of the element to return
        Returns:
        object at the specified index
        Throws:
        java.lang.ArrayIndexOutOfBoundsException - if the index is out of range (index < 0 || index >= size())
        Code:
        Exact Method Body:
         return this.vector.get(index);

      • containsAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean containsAll​(java.util.Collection<?> c)
        Returns TRUE if this Vector contains all of the elements in the specified Collection
        Specified by:
        containsAll in interface ReadOnlyCollection<E>
        Specified by:
        containsAll in interface ReadOnlyList<E>
        Parameters:
        c - a collection whose elements will be tested for containment in this Vector
        Returns:
        TRUE if this Vector contains all of the elements in the specified collection
        Throws:
        java.lang.NullPointerException - if the specified collection is null
        See Also:
        ReadOnlyList.contains(Object)
        Code:
        Exact Method Body:
         return this.vector.containsAll(c);

      • subList

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyList<E> subList​(int fromIndex,
                               int toIndex)
        Returns a view of the portion of this List between 'fromIndex', inclusive, and 'toIndex', exclusive. (If 'fromIndex' and 'toIndex' are equal, the returned List is empty.) The returned List supports all of the optional ReadOnlyList operations supported by this ReadOnlyList.

        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.
        Specified by:
        subList in interface ReadOnlyList<E>
        Parameters:
        fromIndex - low endpoint (inclusive) of the subList
        toIndex - high endpoint (exclusive) of the subList
        Returns:
        a view of the specified range within this List
        Throws:
        java.lang.IndexOutOfBoundsException - if an endpoint index value is out of range (fromIndex < 0 || toIndex > size)
        java.lang.IllegalArgumentException - if the endpoint indices are out of order (fromIndex > toIndex)
        Code:
        Exact Method Body:
         // return new ReadOnlyVector<>(
 return new JavaHTMLReadOnlyList<>(
     fromBuilderOrVector
         ? ((ROVectorBuilder<E>) this.vector)._subList(fromIndex, toIndex, friendClassBadge)
         : this.vector.subList(fromIndex, toIndex)
 );

      • listIterator

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyListIterator<E> listIterator​(int index)
        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 next. An initial call to previous would return the element with the specified index minus one.
        Specified by:
        listIterator in interface ReadOnlyList<E>
        Parameters:
        index - index of the first element to be returned from the list iterator (by a call to next)
        Returns:
        a list iterator over the elements in this list (in proper sequence), starting at the specified position in the list
        Throws:
        java.lang.IndexOutOfBoundsException - if the index is out of range (index < 0 || index > size())
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyListIterator<>(
     fromBuilderOrVector
         ? ((ROVectorBuilder<E>) this.vector)._listIterator(index, friendClassBadge)
         : this.vector.listIterator(index)
 );

      • listIterator

        🡅  🡇  ⇈  ⮫     External-Java:   ⮫ 🗕  🗗  🗖 
        public ReadOnlyListIterator<E> listIterator()
        Returns a list iterator over the elements in this list (in proper sequence).
        Specified by:
        listIterator in interface ReadOnlyList<E>
        Returns:
        a list iterator over the elements in this list (in proper sequence)
        See Also:
        listIterator(int)
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyListIterator<>(
     fromBuilderOrVector
         ? ((ROVectorBuilder<E>) this.vector)._listIterator(friendClassBadge)
         : this.vector.listIterator()
 );

      • forEach

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public void forEach​(java.util.function.Consumer<? super E> action)
        Specified by:
        forEach in interface java.lang.Iterable<E>
        Throws:
        java.lang.NullPointerException
        Code:
        Exact Method Body:
         this.vector.forEach(action);

      • spliterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Spliterator<E> spliterator()
        Uses the private and internal 'vector' field to build a 'Spliterator'
        Specified by:
        spliterator in interface java.lang.Iterable<E>
        Specified by:
        spliterator in interface ReadOnlyCollection<E>
        Specified by:
        spliterator in interface ReadOnlyList<E>
        Returns:
        a Spliterator over the elements in this list
        Code:
        Exact Method Body:
         return this.vector.spliterator();

      • toString

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

      • equals

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