Interface ReadOnlyList<E>

  • Type Parameters:
    E - the type of elements in this list
    All Superinterfaces:
    java.lang.Iterable<E>, ReadOnlyCollection<E>
    All Known Implementing Classes:
    ReadOnlyArrayList, ReadOnlyVector
    public interface ReadOnlyList<E>
extends ReadOnlyCollection<E>
    This interface was originally copied from GitHub's Open-JDK Account. Though the original file has been modified, few changes have been applied to the Javadoc Commenting. Due to fact that that is a Java interface file, there were few method bodies with Source-Code to begin with - meaning this is largely a copy of Method-Signatures and Java-Doc Comments.

    Method and parameter names & types have not been modified whatsoever; but several methods had to be eliminated for not being Read-Only. This Source-File was copied from the original Open JDK-21 file of the same (or, rather, highly similar) Interface-Name. The original 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 variant of Java Collections Framework interface java.util.List<E>. This interface contains all of the methods that the standard Java interface ReadOnlyList contains - except those which would directly or indirectly modify / mutate the internal data-structure.


    • Method Detail

      • size

        🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int size()
        Returns the number of elements in this list. If this list contains more than Integer.MAX_VALUE elements, returns Integer.MAX_VALUE.
        Specified by:
        size in interface ReadOnlyCollection<E>
        Returns:
        the number of elements in this list

      • contains

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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>
        Parameters:
        o - element whose presence in this list is to be tested
        Returns:
        TRUE if this list contains the specified element
        Throws:
        java.lang.ClassCastException - if the type of the specified element is incompatible with this list (optional)
        java.lang.NullPointerException - if the specified element is null and this list does not permit null elements (optional)

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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 even if this list is backed by an array). The caller is thus free to modify the returned array.

        This method acts as bridge between array-based and collection-based APIs.
        Specified by:
        toArray in interface ReadOnlyCollection<E>
        Returns:
        an array containing all of the elements in this list in proper sequence

      • toArray

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        <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 list 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.)

        Like the toArray() method, this method acts as bridge between array-based and collection-based APIs. Further, this method allows precise control over the runtime type of the output array, and may, under certain circumstances, be used to save allocation costs.

        Suppose x is a list known to contain only strings. The following code can be used to dump the list into a newly allocated array of String: 

         String[] y = x.toArray(new String[0]);


        Note that toArray(new Object[0]) is identical in function to toArray().
        Specified by:
        toArray in interface ReadOnlyCollection<E>
        Type Parameters:
        T - the component type of the array to contain the collection
        Parameters:
        a - the array into which the elements of this 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 this 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

      • containsAll

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean containsAll​(java.util.Collection<?> c)
        Returns TRUE if this list contains all of the elements of the specified collection.
        Specified by:
        containsAll in interface ReadOnlyCollection<E>
        Parameters:
        c - collection to be checked for containment in this list
        Returns:
        TRUE if this list contains all of the elements of the specified collection
        Throws:
        java.lang.ClassCastException - if the types of one or more elements in the specified collection are incompatible with this list (optional)
        java.lang.NullPointerException - if the specified collection contains one or more null elements and this list does not permit null elements (optional), or if the specified collection is null
        See Also:
        contains(Object)

      • equals

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        boolean equals​(java.lang.Object o)
        Compares the specified object with this list for equality. Returns TRUE if and only if the specified object is also a list, both lists have the same size, and all corresponding pairs of elements in the two lists are equal. (Two elements e1 and e2 are equal if Objects.equals(e1, e2).) In other words, two lists are defined to be equal if they contain the same elements in the same order. This definition ensures that the equals method works properly across different implementations of the ReadOnlyList interface.
        Specified by:
        equals in interface ReadOnlyCollection<E>
        Overrides:
        equals in class java.lang.Object
        Parameters:
        o - the object to be compared for equality with this list
        Returns:
        TRUE if the specified object is equal to this list
        See Also:
        Object.equals(Object), ReadOnlySet.equals(Object), equals(Object)

      • hashCode

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        int hashCode()
        Returns the hash code value for this list. The hash code of a list is defined to be the result of the following calculation: 

         int hashCode = 1;
 for (E e : list) hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());


        This ensures that list1.equals(list2) implies that list1.hashCode()==list2.hashCode() for any two lists, list1 and list2, as required by the general contract of Object.hashCode.
        Specified by:
        hashCode in interface ReadOnlyCollection<E>
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hash code value for this list
        See Also:
        Object.equals(Object), equals(Object)

      • get

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        E get​(int index)
        Returns the element at the specified position in this list.
        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())

      • indexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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.
        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
        Throws:
        java.lang.ClassCastException - if the type of the specified element is incompatible with this list (optional)
        java.lang.NullPointerException - if the specified element is null and this list does not permit null elements (optional)

      • lastIndexOf

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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.
        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
        Throws:
        java.lang.ClassCastException - if the type of the specified element is incompatible with this list (optional)
        java.lang.NullPointerException - if the specified element is null and this list does not permit null elements (optional)

      • cloneToList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.List<E> cloneToList()
        Clones the internal java.util.List representation, and returns it. This is the Top-Level Interface-Variant of this method. It returns the Interface-Implementation java.util.List.

        Alternate Variant:
        The two classes which implement the interface ReadOnlyList (which are ReadOnlyVector and ReadOnlyArrayList), for convenience, also implement an identical "Wrap To" Method which returns the exact type of the internal List representation (which are java.util.ArrayList and java.util.Vector) - rather than the Top-Leval Interface-Type java.util.List.
        Returns:
        • For the sub-class ReadOnlyArrayList, this will return a cloned instance of the internal java.util.ArrayList.

        • For the sub-class ReadOnlyVector, this will return a cloned instance of the internal java.util.Vector.

      • wrapToImmutableList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        java.util.List<E> wrapToImmutableList()
        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."
        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.

      • listIterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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 ReadOnlyListIterator.next(). An initial call to ReadOnlyListIterator.previous() would return the element with the specified index minus one.
        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())

      • subList

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        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.) The returned list is backed by this list, so non-structural changes in the returned list are reflected in this list, and vice-versa. The returned list supports all of the optional list operations supported by this list.

        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 passing a subList view instead of a whole list. For example, the following idiom removes a range of elements from a list: 

         list.subList(from, to).clear();


        Similar idioms may be constructed for indexOf and lastIndexOf, and all of the algorithms in the Collections class can be applied to a subList.

        The semantics of the list returned by this method become undefined if the backing list (i.e., this list) is structurally modified in any way other than via the returned list. (Structural modifications are those that change the size of this list, or otherwise perturb it in such a fashion that iterations in progress may yield incorrect results.)
        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)

      • spliterator

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        default java.util.Spliterator<E> spliterator()
        Description copied from interface: ReadOnlyCollection
        Creates a Spliterator over the elements in this collection.

        Implementations should document characteristic values reported by the spliterator. Such characteristic values are not required to be reported if the spliterator reports Spliterator.SIZED and this collection contains no elements.

        The default implementation should be overridden by subclasses that can return a more efficient spliterator. In order to preserve expected laziness behavior for the ReadOnlyCollection.stream() and ReadOnlyCollection.parallelStream() methods, spliterators should either have the characteristic of IMMUTABLE or CONCURRENT, or be late-binding. If none of these is practical, the overriding class should describe the spliterator's documented policy of binding and structural interference, and should override the ReadOnlyCollection.stream() and ReadOnlyCollection.parallelStream() methods to create streams using a Supplier of the spliterator, as in: 

         Stream<E> s = StreamSupport.stream(() -> spliterator(), spliteratorCharacteristics)


        These requirements ensure that streams produced by the ReadOnlyCollection.stream() and ReadOnlyCollection.parallelStream() methods will reflect the contents of the collection as of initiation of the terminal stream operation.

        The default implementation creates a late-binding spliterator from the collection's Iterator.

        The created Spliterator reports Spliterator.SIZED.
        Specified by:
        spliterator in interface java.lang.Iterable<E>
        Specified by:
        spliterator in interface ReadOnlyCollection<E>
        Returns:
        a Spliterator over the elements in this collection
        Code:
        Exact Method Body:
         return (this instanceof RandomAccess)
     ? new RandomAccessSpliterator<>(this)
     : Spliterators.spliterator(this.iterator(), this.size(), Spliterator.ORDERED);

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of()
        Returns an unmodifiable list containing zero elements.
        Type Parameters:
        E - the List's element type
        Returns:
        an empty List
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of());

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1)
        Returns an unmodifiable list containing one element.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the single element
        Returns:
        a List containing the specified element
        Throws:
        java.lang.NullPointerException - if the element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2)
        Returns an unmodifiable list containing two elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3)
        Returns an unmodifiable list containing three elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3,
                              E e4)
        Returns an unmodifiable list containing four elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3,
                              E e4,
                              E e5)
        Returns an unmodifiable list containing five elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3,
                              E e4,
                              E e5,
                              E e6)
        Returns an unmodifiable list containing six elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5, e6));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3,
                              E e4,
                              E e5,
                              E e6,
                              E e7)
        Returns an unmodifiable list containing seven elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5, e6, e7));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3,
                              E e4,
                              E e5,
                              E e6,
                              E e7,
                              E e8)
        Returns an unmodifiable list containing eight elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        e8 - the eighth element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3,
                              E e4,
                              E e5,
                              E e6,
                              E e7,
                              E e8,
                              E e9)
        Returns an unmodifiable list containing nine elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        e8 - the eighth element
        e9 - the ninth element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>
     (java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8, e9));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> of​(E e1,
                              E e2,
                              E e3,
                              E e4,
                              E e5,
                              E e6,
                              E e7,
                              E e8,
                              E e9,
                              E e10)
        Returns an unmodifiable list containing ten elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        e1 - the first element
        e2 - the second element
        e3 - the third element
        e4 - the fourth element
        e5 - the fifth element
        e6 - the sixth element
        e7 - the seventh element
        e8 - the eighth element
        e9 - the ninth element
        e10 - the tenth element
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>
     (java.util.List.of(e1, e2, e3, e4, e5, e6, e7, e8, e9, e10));

      • of

        🡅  🡇  ⇈  ⮫ 🗕  🗗  🗖 
        @SafeVarargs
static <E> ReadOnlyList<E> of​(E... elements)
        Returns an unmodifiable list containing an arbitrary number of elements.
        Type Parameters:
        E - the List's element type
        Parameters:
        elements - the elements to be contained in the list
        Returns:
        a List containing the specified elements
        Throws:
        java.lang.NullPointerException - if an element is null or if the array is null
        Code:
        Exact Method Body:
         return new JavaHTMLReadOnlyList<>(java.util.List.of(elements));

      • copyOf

        🡅  ⇈  ⮫ 🗕  🗗  🗖 
        static <E> ReadOnlyList<E> copyOf​(ReadOnlyCollection<? extends E> coll)
        Returns a ReadOnlyList containing the elements of the given ReadOnlyCollection, in its iteration order. The given Collection must not be null, and it must not contain any null elements. If the given Collection is subsequently modified, the returned ReadOnlyList will not reflect such modifications
        Type Parameters:
        E - the ReadOnlyList's element type
        Parameters:
        coll - a ReadOnlyCollection from which elements are drawn, must be non-null
        Returns:
        a ReadOnlyList containing the elements of the given Collection
        Throws:
        java.lang.NullPointerException - if coll is null, or if it contains any nulls
        Code:
        Exact Method Body:
         return (ReadOnlyList.class.isAssignableFrom(coll.getClass()))
     ? (ReadOnlyList<E>) coll
     : new ReadOnlyArrayList<E>((ReadOnlyCollection<E>) coll, coll.size());