Class ReadOnlyArrayList<E>

  • Type Parameters:
    E - the type of elements in this list
    All Implemented Interfaces:
    java.io.Serializable, java.lang.Iterable<E>, java.util.RandomAccess, ReadOnlyCollection<E>, ReadOnlyList<E>
    public class ReadOnlyArrayList<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 nothing more than Wrapper-Code which has been placed around the code from the original Open JDK-21 Source-File of the same (or, rather, highly similar) Class-Name. The original JDK Source-File may be viewed on the JDK-21 GitHub public (and, coincidentally, Read-Only) Source-Release archive for Java Package java.util.*

    The Original '.java' Source-File's Header-Copyright Information is included here: File Copyright. Within that Copyright Notice, it is suggested that a copy of the GNU Public License V2 also be included alongside.
    Immutable Wrapper for java.util.ArrayList, 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 ReadOnlyArrayList's. The builder actually extends java.util.ArrayList, and can therefore insert / accept / add data in just about any way that the original ArrayList can.

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

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


    • Field Summary

       
      Serializable ID
      Modifier and Type Field
      protected static long serialVersionUID

    • Constructor Summary

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

    • Field Detail

      • serialVersionUID

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

    • Constructor Detail

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​(java.util.Collection<E> c)
        Copies parameter 'c' (and saves it) in order to guarantee that 'this' instance is Read-Only, and shielded from outside modification.
        Parameters:
        c - The Collection to be copied and saved into this instance internal and private 'arrayList' field.
        Code:
        Exact Constructor Body:
         fromBuilderOrArrayList = false;

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.arrayList = (c.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : new ArrayList<>(c);

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​(java.lang.Integer quantityIfKnown,
                         java.util.function.Supplier<E> s)
        Use a Supplier<E> to provide an arbitrary number of elements of type 'E' directly to this constructor. This constructor will request elements from the Supplier provided to parameter 's' until 's' returns null.
        Parameters:
        quantityIfKnown - If the number of elements inside the Supplier is known, it may be provided so that the internal ArrayList 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 ArrayList will be done by Java's default (Zero Argument) ArrayList-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 ArrayList constructor.
        s - Any Java Supplier<E>
        Throws:
        java.lang.IllegalArgumentException - if the specified quantity / capacity is negative
        Code:
        Exact Constructor Body:
         fromBuilderOrArrayList = false;

 ArrayList<E> arrayList = (quantityIfKnown != null)
     ? new ArrayList<>(quantityIfKnown)
     : new ArrayList<>();

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

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​
            (java.lang.Iterable<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 ReadOnlyArrayList, using a simple 'mapper'.
        Type Parameters:
        T - The type of the elements inside the User-Provided Iterable<T>. These elements will not actually be inserted into the internal ArrayList, 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 ReadOnlyArrayList'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 ArrayList 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 ArrayList will be done by Java's default (Zero Argument) ArrayList-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 ArrayList constructor.
        Throws:
        java.lang.NullPointerException - if either 'i' or 'mapper' are passed null
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrArrayList = false;

 ArrayList<E> arrayList = (sizeIfKnown != null)
     ? new ArrayList<>(sizeIfKnown)
     : new ArrayList<>();

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

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​(java.lang.Iterable<E> i,
                         java.lang.Integer sizeIfKnown)
        If a Standard Java Iterable can be directly mapped into an ArrayList (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyArrayList<E> with just this single invocation.
        Parameters:
        i - Any Java Iterable<E>
        sizeIfKnown - If the number of elements inside the Iterable is known, it may be provided so that the internal ArrayList 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 ArrayList will be done by Java's default (Zero Argument) ArrayList-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 ArrayList constructor.
        Throws:
        java.lang.IllegalArgumentException - if the specified initial capacity is negative
        Code:
        Exact Constructor Body:
         fromBuilderOrArrayList = false;

 ArrayList<E> arrayList = (sizeIfKnown != null)
     ? new ArrayList<>(sizeIfKnown)
     : new ArrayList<>();

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

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​(java.lang.Class<E> elementsType,
                         java.lang.Object... elements)
        Builds ReadOnlyArrayList<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 ReadOnlyArrayList, 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 ReadOnlyArrayList. For the variant that accepts Generic-Array E..., a ReadOnlyArrayList<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'");

 fromBuilderOrArrayList = false;

 if (elements.length == 0)
     this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

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

      • ReadOnlyArrayList

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

 fromBuilderOrArrayList = false;

 if (elements.length == 0)
     this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

 else 
 {
     this.arrayList = new ArrayList<>(elements.length);
     for (Object element : elements) this.arrayList.add(mapper.apply(element));
 }

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​
            (java.lang.Iterable<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 ReadOnlyArrayList, using a simple 'mapper'.
        Type Parameters:
        T - The type of the elements inside the User-Provided Iterable<T>. These elements will not actually be inserted into the internal ArrayList, 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 ReadOnlyArrayList'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 ReadOnlyArrayList 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 ArrayList 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 ArrayList will be done by Java's default (Zero Argument) ArrayList-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 ArrayList 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'");

 fromBuilderOrArrayList = false;

 ArrayList<E> arrayList = (sizeIfKnown != null)
     ? new ArrayList<>(sizeIfKnown)
     : new ArrayList<>();

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

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​(java.lang.Iterable<E> i,
                         java.util.function.Predicate<? super E> filter,
                         java.lang.Integer sizeIfKnown)
        If a Standard Java Iterable can be directly mapped into an ArrayList (and, ergo, an entire Builder-Instance would be a bit excessive) - this constructor will seamlessly convert any Java Iterable<E> directly into a ReadOnlyArrayList<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 ReadOnlyArrayList 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 ArrayList 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 ArrayList will be done by Java's default (Zero Argument) ArrayList-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 ArrayList 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'");

 fromBuilderOrArrayList = false;

 ArrayList<E> arrayList = (sizeIfKnown != null)
     ? new ArrayList<>(sizeIfKnown)
     : new ArrayList<>();

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

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyArrayList​(java.lang.Class<E> elementsType,
                         java.util.function.Predicate<? super E> filter,
                         java.lang.Object... elements)
        Builds ReadOnlyArrayList<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 ReadOnlyArrayList, 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 ReadOnlyArrayList 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 ReadOnlyArrayList. For the variant that accepts Generic-Array E..., a ReadOnlyArrayList<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 passsed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(elementsType, ROHelpers.NULL_MSG + "'elementsType'");
 Objects.requireNonNull(filter, ROHelpers.NULL_MSG + "'filter'");

 fromBuilderOrArrayList = false;

 ArrayList<E> arrayList = new ArrayList<>(elements.length);

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

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

      • ReadOnlyArrayList

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

 fromBuilderOrArrayList = false;

 ArrayList<E> arrayList = new ArrayList<>(elements.length);

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

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
public ReadOnlyArrayList​(E... elements)
        Builds ReadOnlyArrayList<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 ReadOnlyArrayList. For the variant that accepts Generic-Array E..., a ReadOnlyArrayList<E> is constructed.
        Code:
        Exact Constructor Body:
         fromBuilderOrArrayList = false;

 if (elements.length == 0)
     this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyArrayList​
            (int dummy,
             java.util.function.Function<? super T,​? extends E> mapper,
             T... elements)
        Builds ReadOnlyArrayList<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 ArrayList, 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 ReadOnlyArrayList'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 ReadOnlyArrayList. For the variant that accepts Generic-Array E..., a ReadOnlyArrayList<E> is constructed.
        Throws:
        java.lang.NullPointerException - If 'mapper' is passed null.
        Code:
        Exact Constructor Body:
         Objects.requireNonNull(mapper, ROHelpers.NULL_MSG + "'mapper'");

 fromBuilderOrArrayList = false;

 if (elements.length == 0)
     this.arrayList = (ArrayList<E>) EMPTY_ARRAY_LIST;

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

      • ReadOnlyArrayList

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

 fromBuilderOrArrayList = false;

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

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

      • ReadOnlyArrayList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
ublic ReadOnlyArrayList​
            (java.util.function.Predicate<? super T> filter,
             java.util.function.Function<? super T,​? extends E> mapper,
             T... elements)
        Builds ReadOnlyArrayList<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 ArrayList, 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 ReadOnlyArrayList 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 ReadOnlyArrayList'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 ReadOnlyArrayList. For the variant that accepts Generic-Array E..., a ReadOnlyArrayList<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'");

 fromBuilderOrArrayList = false;

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

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

      • ReadOnlyArrayList

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

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

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.arrayList = (al.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : al;

      • ReadOnlyArrayList

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

 fromBuilderOrArrayList = false;

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

 // Empty Optimization (throw away, completely, the reference, use static-constant)
 this.arrayList = (al.size() == 0) ? ((ArrayList<E>) EMPTY_ARRAY_LIST) : al;

    • Method Detail

      • streamCollector

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

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

     // Oracle Making Life Difficult - It should be the line below, but, alas, it is not!
     // ROArrayListBuilder<T>::addAll, // The "Combiner" (combines two  ROArrayListBuilders)
     //
     // 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>"

     (ROArrayListBuilder<T> roalb1, ROArrayListBuilder<T> roalb2) ->
     {
         roalb1.addAll(roalb2);
         return roalb1;
     },

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

      • cloneToArrayList

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

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

      • wrapToImmutableList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.List<E> wrapToImmutableList()
        Invokes java.util.Collections.unmodifiableList on the internal ArrayList.

        Standard JDK List:
        There may be situations where the Type ReadOnlyArrayList 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."
        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.arrayList);

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public boolean contains​(java.lang.Object o)
        Returns TRUE if this list contains the specified element. More formally, returns TRUE if and only if this list 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 list is to be tested
        Returns:
        TRUE if this list contains the specified element
        Code:
        Exact Method Body:
         return this.arrayList.contains(o);

      • indexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int indexOf​(java.lang.Object o)
        Returns the index of the first occurrence of the specified element in this list, or -1 if this list 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 list, or -1 if this list does not contain the element
        Code:
        Exact Method Body:
         return this.arrayList.indexOf(o);

      • lastIndexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public int lastIndexOf​(java.lang.Object o)
        Returns the index of the last occurrence of the specified element in this list, or -1 if this list 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 list, or -1 if this list does not contain the element
        Code:
        Exact Method Body:
         return this.arrayList.lastIndexOf(o);

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.lang.Object[] toArray()
        Returns an array containing all of the elements in this list in proper sequence (from first to last element).

        The returned array will be "safe" in that no references to it are maintained by this list. (In other words, this method must allocate a new array). The caller is thus free to modify the returned array.

        This method acts as bridge between array-based and collection-based APIs.
        Specified by:
        toArray in interface ReadOnlyCollection<E>
        Specified by:
        toArray in interface ReadOnlyList<E>
        Returns:
        an array containing all of the elements in this list in proper sequence
        Code:
        Exact Method Body:
         return this.arrayList.toArray();

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public <T> T[] toArray​(T[] a)
        Returns an array containing all of the elements in this list in proper sequence (from first to last element); the runtime type of the returned array is that of the specified array. If the list 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 list.

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

      • get

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

      • 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.arrayList.forEach(action);

      • spliterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public java.util.Spliterator<E> spliterator()
        Utilizes this class private, internal 'arrayList' field to generate 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.arrayList.spliterator();

      • listIterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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 InterfaceBuilder.toReadOnlyListIterator(
     fromBuilderOrArrayList 
         ? ((ROArrayListBuilder<E>) this.arrayList)._listIterator(index, friendClassBadge)
         : this.arrayList.listIterator(index)
 );

      • listIterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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 InterfaceBuilder.toReadOnlyListIterator(
     fromBuilderOrArrayList 
         ? ((ROArrayListBuilder<E>) this.arrayList)._listIterator(friendClassBadge)
         : this.arrayList.listIterator()
 );

      • iterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public RemoveUnsupportedIterator<E> iterator()
        Returns an iterator over the elements in this list in proper sequence.
        Specified by:
        iterator in interface java.lang.Iterable<E>
        Specified by:
        iterator in interface ReadOnlyCollection<E>
        Specified by:
        iterator in interface ReadOnlyList<E>
        Returns:
        an iterator over the elements in this list in proper sequence
        Code:
        Exact Method Body:
         return fromBuilderOrArrayList
     ? (RemoveUnsupportedIterator<E>) this.arrayList.iterator()
     : new RemoveUnsupportedIterator<E>(this.arrayList.iterator());

      • subList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        public ReadOnlyList<E> subList​(int fromIndex,
                               int toIndex)
        Returns a view of the portion of this list between the specified 'fromIndex', inclusive, and toIndex, exclusive. (If 'fromIndex' and 'toIndex' are equal, the returned list is empty.)
        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 - for an illegal endpoint index value (fromIndex < 0 || toIndex > size || fromIndex > toIndex)
        java.lang.IllegalArgumentException
        Code:
        Exact Method Body:
         return InterfaceBuilder.toReadOnlyList(
     fromBuilderOrArrayList 
         ? ((ROArrayListBuilder<E>) this.arrayList).
             _subList(fromIndex, toIndex, friendClassBadge)
         : this.arrayList.subList(fromIndex, toIndex)
 );

      • toString

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

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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.ArrayList.
        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 ReadOnlyArrayList
        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 ROHelpers.roListEq(this, o);