< prev index next >

## src/java.base/share/classes/java/util/List.java

Print this page

    rev 47953 : 8177290: add copy factory methods for unmodifiable List, Set, Map
    8184690: add Collectors for collecting into unmodifiable List, Set, and Map
    Reviewed-by: alanb, briangoetz, dholmes, jrose, rriggs, scolebourne

      70  * remove multiple elements at an arbitrary point in the list.<p>
      71  *
      72  * Note: While it is permissible for lists to contain themselves as elements,
      73  * extreme caution is advised: the {@code equals} and {@code hashCode}
      74  * methods are no longer well defined on such a list.
      75  *
      76  * <p>Some list implementations have restrictions on the elements that
      77  * they may contain.  For example, some implementations prohibit null elements,
      78  * and some have restrictions on the types of their elements.  Attempting to
      79  * add an ineligible element throws an unchecked exception, typically
      80  * {@code NullPointerException} or {@code ClassCastException}.  Attempting
      81  * to query the presence of an ineligible element may throw an exception,
      82  * or it may simply return false; some implementations will exhibit the former
      83  * behavior and some will exhibit the latter.  More generally, attempting an
      84  * operation on an ineligible element whose completion would not result in
      85  * the insertion of an ineligible element into the list may throw an
      86  * exception or it may succeed, at the option of the implementation.
      87  * Such exceptions are marked as "optional" in the specification for this
      88  * interface.
      89  *
      90  * <h2><a id="immutable">Immutable List Static Factory Methods</a></h2>
      91  * <p>The {@link List#of(Object...) List.of()} static factory methods
      92  * provide a convenient way to create immutable lists. The {@code List}

      93  * instances created by these methods have the following characteristics:
      94  *
      95  * <ul>
      96  * <li>They are <em>structurally immutable</em>. Elements cannot be added, removed,
      97  * or replaced. Calling any mutator method will always cause
      98  * {@code UnsupportedOperationException} to be thrown.
      99  * However, if the contained elements are themselves mutable,
     100  * this may cause the List's contents to appear to change.
     101  * <li>They disallow {@code null} elements. Attempts to create them with
     102  * {@code null} elements result in {@code NullPointerException}.
     103  * <li>They are serializable if all elements are serializable.
     104  * <li>The order of elements in the list is the same as the order of the
     105  * provided arguments, or of the elements in the provided array.
     106  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
     107  * Callers should make no assumptions about the identity of the returned instances.
     108  * Factories are free to create new instances or reuse existing ones. Therefore,
     109  * identity-sensitive operations on these instances (reference equality ({@code ==}),
     110  * identity hash code, and synchronization) are unreliable and should be avoided.
     111  * <li>They are serialized as specified on the
     112  * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a>
     113  * page.
     114  * </ul>
     115  *
     116  * <p>This interface is a member of the
     117  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
     118  * Java Collections Framework</a>.
     760      *     <em>fail-fast</em> of the list's iterator.
     761      * </ul>
     762      *
     763      * @implNote
     764      * The created {@code Spliterator} additionally reports
     765      * {@link Spliterator#SUBSIZED}.
     766      *
     767      * @return a {@code Spliterator} over the elements in this list
     768      * @since 1.8
     769      */
     770     @Override
     771     default Spliterator<E> spliterator() {
     772         if (this instanceof RandomAccess) {
     773             return new AbstractList.RandomAccessSpliterator<>(this);
     774         } else {
     775             return Spliterators.spliterator(this, Spliterator.ORDERED);
     776         }
     777     }
     778
     779     /**
     780      * Returns an immutable list containing zero elements.
     781      *
     782      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     783      *
     784      * @param <E> the {@code List}'s element type
     785      * @return an empty {@code List}
     786      *
     787      * @since 9
     788      */
     789     static <E> List<E> of() {
     790         return ImmutableCollections.List0.instance();
     791     }
     792
     793     /**
     794      * Returns an immutable list containing one element.
     795      *
     796      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     797      *
     798      * @param <E> the {@code List}'s element type
     799      * @param e1 the single element
     800      * @return a {@code List} containing the specified element
     801      * @throws NullPointerException if the element is {@code null}
     802      *
     803      * @since 9
     804      */
     805     static <E> List<E> of(E e1) {
     806         return new ImmutableCollections.List1<>(e1);
     807     }
     808
     809     /**
     810      * Returns an immutable list containing two elements.
     811      *
     812      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     813      *
     814      * @param <E> the {@code List}'s element type
     815      * @param e1 the first element
     816      * @param e2 the second element
     817      * @return a {@code List} containing the specified elements
     818      * @throws NullPointerException if an element is {@code null}
     819      *
     820      * @since 9
     821      */
     822     static <E> List<E> of(E e1, E e2) {
     823         return new ImmutableCollections.List2<>(e1, e2);
     824     }
     825
     826     /**
     827      * Returns an immutable list containing three elements.
     828      *
     829      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     830      *
     831      * @param <E> the {@code List}'s element type
     832      * @param e1 the first element
     833      * @param e2 the second element
     834      * @param e3 the third element
     835      * @return a {@code List} containing the specified elements
     836      * @throws NullPointerException if an element is {@code null}
     837      *
     838      * @since 9
     839      */
     840     static <E> List<E> of(E e1, E e2, E e3) {
     841         return new ImmutableCollections.ListN<>(e1, e2, e3);
     842     }
     843
     844     /**
     845      * Returns an immutable list containing four elements.
     846      *
     847      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     848      *
     849      * @param <E> the {@code List}'s element type
     850      * @param e1 the first element
     851      * @param e2 the second element
     852      * @param e3 the third element
     853      * @param e4 the fourth element
     854      * @return a {@code List} containing the specified elements
     855      * @throws NullPointerException if an element is {@code null}
     856      *
     857      * @since 9
     858      */
     859     static <E> List<E> of(E e1, E e2, E e3, E e4) {
     860         return new ImmutableCollections.ListN<>(e1, e2, e3, e4);
     861     }
     862
     863     /**
     864      * Returns an immutable list containing five elements.
     865      *
     866      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     867      *
     868      * @param <E> the {@code List}'s element type
     869      * @param e1 the first element
     870      * @param e2 the second element
     871      * @param e3 the third element
     872      * @param e4 the fourth element
     873      * @param e5 the fifth element
     874      * @return a {@code List} containing the specified elements
     875      * @throws NullPointerException if an element is {@code null}
     876      *
     877      * @since 9
     878      */
     879     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
     880         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5);
     881     }
     882
     883     /**
     884      * Returns an immutable list containing six elements.
     885      *
     886      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     887      *
     888      * @param <E> the {@code List}'s element type
     889      * @param e1 the first element
     890      * @param e2 the second element
     891      * @param e3 the third element
     892      * @param e4 the fourth element
     893      * @param e5 the fifth element
     894      * @param e6 the sixth element
     895      * @return a {@code List} containing the specified elements
     896      * @throws NullPointerException if an element is {@code null}
     897      *
     898      * @since 9
     899      */
     900     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
     901         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     902                                                 e6);
     903     }
     904
     905     /**
     906      * Returns an immutable list containing seven elements.
     907      *
     908      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     909      *
     910      * @param <E> the {@code List}'s element type
     911      * @param e1 the first element
     912      * @param e2 the second element
     913      * @param e3 the third element
     914      * @param e4 the fourth element
     915      * @param e5 the fifth element
     916      * @param e6 the sixth element
     917      * @param e7 the seventh element
     918      * @return a {@code List} containing the specified elements
     919      * @throws NullPointerException if an element is {@code null}
     920      *
     921      * @since 9
     922      */
     923     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
     924         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     925                                                 e6, e7);
     926     }
     927
     928     /**
     929      * Returns an immutable list containing eight elements.
     930      *
     931      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     932      *
     933      * @param <E> the {@code List}'s element type
     934      * @param e1 the first element
     935      * @param e2 the second element
     936      * @param e3 the third element
     937      * @param e4 the fourth element
     938      * @param e5 the fifth element
     939      * @param e6 the sixth element
     940      * @param e7 the seventh element
     941      * @param e8 the eighth element
     942      * @return a {@code List} containing the specified elements
     943      * @throws NullPointerException if an element is {@code null}
     944      *
     945      * @since 9
     946      */
     947     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
     948         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     949                                                 e6, e7, e8);
     950     }
     951
     952     /**
     953      * Returns an immutable list containing nine elements.
     954      *
     955      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     956      *
     957      * @param <E> the {@code List}'s element type
     958      * @param e1 the first element
     959      * @param e2 the second element
     960      * @param e3 the third element
     961      * @param e4 the fourth element
     962      * @param e5 the fifth element
     963      * @param e6 the sixth element
     964      * @param e7 the seventh element
     965      * @param e8 the eighth element
     966      * @param e9 the ninth element
     967      * @return a {@code List} containing the specified elements
     968      * @throws NullPointerException if an element is {@code null}
     969      *
     970      * @since 9
     971      */
     972     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
     973         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     974                                                 e6, e7, e8, e9);
     975     }
     976
     977     /**
     978      * Returns an immutable list containing ten elements.
     979      *
     980      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
     981      *
     982      * @param <E> the {@code List}'s element type
     983      * @param e1 the first element
     984      * @param e2 the second element
     985      * @param e3 the third element
     986      * @param e4 the fourth element
     987      * @param e5 the fifth element
     988      * @param e6 the sixth element
     989      * @param e7 the seventh element
     990      * @param e8 the eighth element
     991      * @param e9 the ninth element
     992      * @param e10 the tenth element
     993      * @return a {@code List} containing the specified elements
     994      * @throws NullPointerException if an element is {@code null}
     995      *
     996      * @since 9
     997      */
     998     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
     999         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
    1000                                                 e6, e7, e8, e9, e10);
    1001     }
    1002
    1003     /**
    1004      * Returns an immutable list containing an arbitrary number of elements.
    1005      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
    1006      *
    1007      * @apiNote
    1008      * This method also accepts a single array as an argument. The element type of
    1009      * the resulting list will be the component type of the array, and the size of
    1010      * the list will be equal to the length of the array. To create a list with
    1011      * a single element that is an array, do the following:
    1012      *
    1013      * <pre>{@code
    1014      *     String[] array = ... ;
    1015      *     List<String[]> list = List.<String[]>of(array);
    1016      * }</pre>
    1017      *
    1018      * This will cause the {@link List#of(Object) List.of(E)} method
    1019      * to be invoked instead.
    1020      *
    1021      * @param <E> the {@code List}'s element type
    1022      * @param elements the elements to be contained in the list
    1023      * @return a {@code List} containing the specified elements
    1024      * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
    1025      *
    1026      * @since 9
    1027      */
    1028     @SafeVarargs
    1029     @SuppressWarnings("varargs")
    1030     static <E> List<E> of(E... elements) {
    1031         switch (elements.length) { // implicit null check of elements
    1032             case 0:
    1033                 return ImmutableCollections.List0.instance();
    1034             case 1:
    1035                 return new ImmutableCollections.List1<>(elements[0]);
    1036             case 2:
    1037                 return new ImmutableCollections.List2<>(elements[0], elements[1]);
    1038             default:
    1039                 return new ImmutableCollections.ListN<>(elements);
    1040         }
    1041     }

    1042 }
      70  * remove multiple elements at an arbitrary point in the list.<p>
      71  *
      72  * Note: While it is permissible for lists to contain themselves as elements,
      73  * extreme caution is advised: the {@code equals} and {@code hashCode}
      74  * methods are no longer well defined on such a list.
      75  *
      76  * <p>Some list implementations have restrictions on the elements that
      77  * they may contain.  For example, some implementations prohibit null elements,
      78  * and some have restrictions on the types of their elements.  Attempting to
      79  * add an ineligible element throws an unchecked exception, typically
      80  * {@code NullPointerException} or {@code ClassCastException}.  Attempting
      81  * to query the presence of an ineligible element may throw an exception,
      82  * or it may simply return false; some implementations will exhibit the former
      83  * behavior and some will exhibit the latter.  More generally, attempting an
      84  * operation on an ineligible element whose completion would not result in
      85  * the insertion of an ineligible element into the list may throw an
      86  * exception or it may succeed, at the option of the implementation.
      87  * Such exceptions are marked as "optional" in the specification for this
      88  * interface.
      89  *
      90  * <h2><a id="unmodifiable">Unmodifiable Lists</a></h2>
      91  * <p>The {@link List#of(Object...) List.of} and
      92  * {@link List#copyOf List.copyOf} static factory methods
      93  * provide a convenient way to create unmodifiable lists. The {@code List}
      94  * instances created by these methods have the following characteristics:
      95  *
      96  * <ul>
      97  * <li>They are <a href="Collection.html#unmodifiable"><i>unmodifiable</i></a>. Elements cannot
      98  * be added, removed, or replaced. Calling any mutator method on the List
      99  * will always cause {@code UnsupportedOperationException} to be thrown.
     100  * However, if the contained elements are themselves mutable,
     101  * this may cause the List's contents to appear to change.
     102  * <li>They disallow {@code null} elements. Attempts to create them with
     103  * {@code null} elements result in {@code NullPointerException}.
     104  * <li>They are serializable if all elements are serializable.
     105  * <li>The order of elements in the list is the same as the order of the
     106  * provided arguments, or of the elements in the provided array.
     107  * <li>They are <a href="../lang/doc-files/ValueBased.html">value-based</a>.
     108  * Callers should make no assumptions about the identity of the returned instances.
     109  * Factories are free to create new instances or reuse existing ones. Therefore,
     110  * identity-sensitive operations on these instances (reference equality ({@code ==}),
     111  * identity hash code, and synchronization) are unreliable and should be avoided.
     112  * <li>They are serialized as specified on the
     113  * <a href="{@docRoot}/serialized-form.html#java.util.CollSer">Serialized Form</a>
     114  * page.
     115  * </ul>
     116  *
     117  * <p>This interface is a member of the
     118  * <a href="{@docRoot}/java/util/package-summary.html#CollectionsFramework">
     119  * Java Collections Framework</a>.
     761      *     <em>fail-fast</em> of the list's iterator.
     762      * </ul>
     763      *
     764      * @implNote
     765      * The created {@code Spliterator} additionally reports
     766      * {@link Spliterator#SUBSIZED}.
     767      *
     768      * @return a {@code Spliterator} over the elements in this list
     769      * @since 1.8
     770      */
     771     @Override
     772     default Spliterator<E> spliterator() {
     773         if (this instanceof RandomAccess) {
     774             return new AbstractList.RandomAccessSpliterator<>(this);
     775         } else {
     776             return Spliterators.spliterator(this, Spliterator.ORDERED);
     777         }
     778     }
     779
     780     /**
     781      * Returns an unmodifiable list containing zero elements.
     782      *
     783      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     784      *
     785      * @param <E> the {@code List}'s element type
     786      * @return an empty {@code List}
     787      *
     788      * @since 9
     789      */
     790     static <E> List<E> of() {
     791         return ImmutableCollections.List0.instance();
     792     }
     793
     794     /**
     795      * Returns an unmodifiable list containing one element.
     796      *
     797      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     798      *
     799      * @param <E> the {@code List}'s element type
     800      * @param e1 the single element
     801      * @return a {@code List} containing the specified element
     802      * @throws NullPointerException if the element is {@code null}
     803      *
     804      * @since 9
     805      */
     806     static <E> List<E> of(E e1) {
     807         return new ImmutableCollections.List1<>(e1);
     808     }
     809
     810     /**
     811      * Returns an unmodifiable list containing two elements.
     812      *
     813      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     814      *
     815      * @param <E> the {@code List}'s element type
     816      * @param e1 the first element
     817      * @param e2 the second element
     818      * @return a {@code List} containing the specified elements
     819      * @throws NullPointerException if an element is {@code null}
     820      *
     821      * @since 9
     822      */
     823     static <E> List<E> of(E e1, E e2) {
     824         return new ImmutableCollections.List2<>(e1, e2);
     825     }
     826
     827     /**
     828      * Returns an unmodifiable list containing three elements.
     829      *
     830      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     831      *
     832      * @param <E> the {@code List}'s element type
     833      * @param e1 the first element
     834      * @param e2 the second element
     835      * @param e3 the third element
     836      * @return a {@code List} containing the specified elements
     837      * @throws NullPointerException if an element is {@code null}
     838      *
     839      * @since 9
     840      */
     841     static <E> List<E> of(E e1, E e2, E e3) {
     842         return new ImmutableCollections.ListN<>(e1, e2, e3);
     843     }
     844
     845     /**
     846      * Returns an unmodifiable list containing four elements.
     847      *
     848      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     849      *
     850      * @param <E> the {@code List}'s element type
     851      * @param e1 the first element
     852      * @param e2 the second element
     853      * @param e3 the third element
     854      * @param e4 the fourth element
     855      * @return a {@code List} containing the specified elements
     856      * @throws NullPointerException if an element is {@code null}
     857      *
     858      * @since 9
     859      */
     860     static <E> List<E> of(E e1, E e2, E e3, E e4) {
     861         return new ImmutableCollections.ListN<>(e1, e2, e3, e4);
     862     }
     863
     864     /**
     865      * Returns an unmodifiable list containing five elements.
     866      *
     867      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     868      *
     869      * @param <E> the {@code List}'s element type
     870      * @param e1 the first element
     871      * @param e2 the second element
     872      * @param e3 the third element
     873      * @param e4 the fourth element
     874      * @param e5 the fifth element
     875      * @return a {@code List} containing the specified elements
     876      * @throws NullPointerException if an element is {@code null}
     877      *
     878      * @since 9
     879      */
     880     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
     881         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5);
     882     }
     883
     884     /**
     885      * Returns an unmodifiable list containing six elements.
     886      *
     887      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     888      *
     889      * @param <E> the {@code List}'s element type
     890      * @param e1 the first element
     891      * @param e2 the second element
     892      * @param e3 the third element
     893      * @param e4 the fourth element
     894      * @param e5 the fifth element
     895      * @param e6 the sixth element
     896      * @return a {@code List} containing the specified elements
     897      * @throws NullPointerException if an element is {@code null}
     898      *
     899      * @since 9
     900      */
     901     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
     902         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     903                                                 e6);
     904     }
     905
     906     /**
     907      * Returns an unmodifiable list containing seven elements.
     908      *
     909      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     910      *
     911      * @param <E> the {@code List}'s element type
     912      * @param e1 the first element
     913      * @param e2 the second element
     914      * @param e3 the third element
     915      * @param e4 the fourth element
     916      * @param e5 the fifth element
     917      * @param e6 the sixth element
     918      * @param e7 the seventh element
     919      * @return a {@code List} containing the specified elements
     920      * @throws NullPointerException if an element is {@code null}
     921      *
     922      * @since 9
     923      */
     924     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
     925         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     926                                                 e6, e7);
     927     }
     928
     929     /**
     930      * Returns an unmodifiable list containing eight elements.
     931      *
     932      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     933      *
     934      * @param <E> the {@code List}'s element type
     935      * @param e1 the first element
     936      * @param e2 the second element
     937      * @param e3 the third element
     938      * @param e4 the fourth element
     939      * @param e5 the fifth element
     940      * @param e6 the sixth element
     941      * @param e7 the seventh element
     942      * @param e8 the eighth element
     943      * @return a {@code List} containing the specified elements
     944      * @throws NullPointerException if an element is {@code null}
     945      *
     946      * @since 9
     947      */
     948     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
     949         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     950                                                 e6, e7, e8);
     951     }
     952
     953     /**
     954      * Returns an unmodifiable list containing nine elements.
     955      *
     956      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     957      *
     958      * @param <E> the {@code List}'s element type
     959      * @param e1 the first element
     960      * @param e2 the second element
     961      * @param e3 the third element
     962      * @param e4 the fourth element
     963      * @param e5 the fifth element
     964      * @param e6 the sixth element
     965      * @param e7 the seventh element
     966      * @param e8 the eighth element
     967      * @param e9 the ninth element
     968      * @return a {@code List} containing the specified elements
     969      * @throws NullPointerException if an element is {@code null}
     970      *
     971      * @since 9
     972      */
     973     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
     974         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
     975                                                 e6, e7, e8, e9);
     976     }
     977
     978     /**
     979      * Returns an unmodifiable list containing ten elements.
     980      *
     981      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
     982      *
     983      * @param <E> the {@code List}'s element type
     984      * @param e1 the first element
     985      * @param e2 the second element
     986      * @param e3 the third element
     987      * @param e4 the fourth element
     988      * @param e5 the fifth element
     989      * @param e6 the sixth element
     990      * @param e7 the seventh element
     991      * @param e8 the eighth element
     992      * @param e9 the ninth element
     993      * @param e10 the tenth element
     994      * @return a {@code List} containing the specified elements
     995      * @throws NullPointerException if an element is {@code null}
     996      *
     997      * @since 9
     998      */
     999     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10) {
    1000         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
    1001                                                 e6, e7, e8, e9, e10);
    1002     }
    1003
    1004     /**
    1005      * Returns an unmodifiable list containing an arbitrary number of elements.
    1006      * See <a href="#unmodifiable">Unmodifiable Lists</a> for details.
    1007      *
    1008      * @apiNote
    1009      * This method also accepts a single array as an argument. The element type of
    1010      * the resulting list will be the component type of the array, and the size of
    1011      * the list will be equal to the length of the array. To create a list with
    1012      * a single element that is an array, do the following:
    1013      *
    1014      * <pre>{@code
    1015      *     String[] array = ... ;
    1016      *     List<String[]> list = List.<String[]>of(array);
    1017      * }</pre>
    1018      *
    1019      * This will cause the {@link List#of(Object) List.of(E)} method
    1020      * to be invoked instead.
    1021      *
    1022      * @param <E> the {@code List}'s element type
    1023      * @param elements the elements to be contained in the list
    1024      * @return a {@code List} containing the specified elements
    1025      * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
    1026      *
    1027      * @since 9
    1028      */
    1029     @SafeVarargs
    1030     @SuppressWarnings("varargs")
    1031     static <E> List<E> of(E... elements) {
    1032         switch (elements.length) { // implicit null check of elements
    1033             case 0:
    1034                 return ImmutableCollections.List0.instance();
    1035             case 1:
    1036                 return new ImmutableCollections.List1<>(elements[0]);
    1037             case 2:
    1038                 return new ImmutableCollections.List2<>(elements[0], elements[1]);
    1039             default:
    1040                 return new ImmutableCollections.ListN<>(elements);
    1041         }
    1042     }
    1043
    1044     /**
    1045      * Returns an <a href="#unmodifiable">unmodifiable List</a> containing the elements of
    1046      * the given Collection, in its iteration order. The given Collection must not be null,
    1047      * and it must not contain any null elements. If the given Collection is subsequently
    1048      * modified, the returned List will not reflect such modifications.
    1049      *
    1050      * @implNote
    1051      * If the given Collection is an <a href="#unmodifiable">unmodifiable List</a>,
    1052      * calling copyOf will generally not create a copy.
    1053      *
    1054      * @param <E> the {@code List}'s element type
    1055      * @param coll a {@code Collection} from which elements are drawn, must be non-null
    1056      * @return a {@code List} containing the elements of the given {@code Collection}
    1057      * @throws NullPointerException if coll is null, or if it contains any nulls
    1058      * @since 10
    1059      */
    1060     @SuppressWarnings("unchecked")
    1061     static <E> List<E> copyOf(Collection<? extends E> coll) {
    1062         if (coll instanceof ImmutableCollections.AbstractImmutableList) {
    1063             return (List<E>)coll;
    1064         } else {
    1065             return (List<E>)List.of(coll.toArray());
    1066         }
    1067     }
    1068 }

< prev index next >