< prev index next >

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

Print this page
rev 47476 : 8177290: add copy factory methods for unmodifiable List, Set, Map
8184690: add Collectors for collecting into unmodifiable List, Set, and Map
Reviewed-by: alanb, dholmes, 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>.


 759      *     <em>fail-fast</em> of the list's iterator.
 760      * </ul>
 761      *
 762      * @implNote
 763      * The created {@code Spliterator} additionally reports
 764      * {@link Spliterator#SUBSIZED}.
 765      *
 766      * @return a {@code Spliterator} over the elements in this list
 767      * @since 1.8
 768      */
 769     @Override
 770     default Spliterator<E> spliterator() {
 771         if (this instanceof RandomAccess) {
 772             return new AbstractList.RandomAccessSpliterator<>(this);
 773         } else {
 774             return Spliterators.spliterator(this, Spliterator.ORDERED);
 775         }
 776     }
 777 
 778     /**
 779      * Returns an immutable list containing zero elements.
 780      *
 781      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 782      *
 783      * @param <E> the {@code List}'s element type
 784      * @return an empty {@code List}
 785      *
 786      * @since 9
 787      */
 788     static <E> List<E> of() {
 789         return ImmutableCollections.List0.instance();
 790     }
 791 
 792     /**
 793      * Returns an immutable list containing one element.
 794      *
 795      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 796      *
 797      * @param <E> the {@code List}'s element type
 798      * @param e1 the single element
 799      * @return a {@code List} containing the specified element
 800      * @throws NullPointerException if the element is {@code null}
 801      *
 802      * @since 9
 803      */
 804     static <E> List<E> of(E e1) {
 805         return new ImmutableCollections.List1<>(e1);
 806     }
 807 
 808     /**
 809      * Returns an immutable list containing two elements.
 810      *
 811      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 812      *
 813      * @param <E> the {@code List}'s element type
 814      * @param e1 the first element
 815      * @param e2 the second element
 816      * @return a {@code List} containing the specified elements
 817      * @throws NullPointerException if an element is {@code null}
 818      *
 819      * @since 9
 820      */
 821     static <E> List<E> of(E e1, E e2) {
 822         return new ImmutableCollections.List2<>(e1, e2);
 823     }
 824 
 825     /**
 826      * Returns an immutable list containing three elements.
 827      *
 828      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 829      *
 830      * @param <E> the {@code List}'s element type
 831      * @param e1 the first element
 832      * @param e2 the second element
 833      * @param e3 the third element
 834      * @return a {@code List} containing the specified elements
 835      * @throws NullPointerException if an element is {@code null}
 836      *
 837      * @since 9
 838      */
 839     static <E> List<E> of(E e1, E e2, E e3) {
 840         return new ImmutableCollections.ListN<>(e1, e2, e3);
 841     }
 842 
 843     /**
 844      * Returns an immutable list containing four elements.
 845      *
 846      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 847      *
 848      * @param <E> the {@code List}'s element type
 849      * @param e1 the first element
 850      * @param e2 the second element
 851      * @param e3 the third element
 852      * @param e4 the fourth element
 853      * @return a {@code List} containing the specified elements
 854      * @throws NullPointerException if an element is {@code null}
 855      *
 856      * @since 9
 857      */
 858     static <E> List<E> of(E e1, E e2, E e3, E e4) {
 859         return new ImmutableCollections.ListN<>(e1, e2, e3, e4);
 860     }
 861 
 862     /**
 863      * Returns an immutable list containing five elements.
 864      *
 865      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 866      *
 867      * @param <E> the {@code List}'s element type
 868      * @param e1 the first element
 869      * @param e2 the second element
 870      * @param e3 the third element
 871      * @param e4 the fourth element
 872      * @param e5 the fifth element
 873      * @return a {@code List} containing the specified elements
 874      * @throws NullPointerException if an element is {@code null}
 875      *
 876      * @since 9
 877      */
 878     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
 879         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5);
 880     }
 881 
 882     /**
 883      * Returns an immutable list containing six elements.
 884      *
 885      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 886      *
 887      * @param <E> the {@code List}'s element type
 888      * @param e1 the first element
 889      * @param e2 the second element
 890      * @param e3 the third element
 891      * @param e4 the fourth element
 892      * @param e5 the fifth element
 893      * @param e6 the sixth element
 894      * @return a {@code List} containing the specified elements
 895      * @throws NullPointerException if an element is {@code null}
 896      *
 897      * @since 9
 898      */
 899     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
 900         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
 901                                                 e6);
 902     }
 903 
 904     /**
 905      * Returns an immutable list containing seven elements.
 906      *
 907      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 908      *
 909      * @param <E> the {@code List}'s element type
 910      * @param e1 the first element
 911      * @param e2 the second element
 912      * @param e3 the third element
 913      * @param e4 the fourth element
 914      * @param e5 the fifth element
 915      * @param e6 the sixth element
 916      * @param e7 the seventh element
 917      * @return a {@code List} containing the specified elements
 918      * @throws NullPointerException if an element is {@code null}
 919      *
 920      * @since 9
 921      */
 922     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
 923         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
 924                                                 e6, e7);
 925     }
 926 
 927     /**
 928      * Returns an immutable list containing eight elements.
 929      *
 930      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 931      *
 932      * @param <E> the {@code List}'s element type
 933      * @param e1 the first element
 934      * @param e2 the second element
 935      * @param e3 the third element
 936      * @param e4 the fourth element
 937      * @param e5 the fifth element
 938      * @param e6 the sixth element
 939      * @param e7 the seventh element
 940      * @param e8 the eighth element
 941      * @return a {@code List} containing the specified elements
 942      * @throws NullPointerException if an element is {@code null}
 943      *
 944      * @since 9
 945      */
 946     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
 947         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
 948                                                 e6, e7, e8);
 949     }
 950 
 951     /**
 952      * Returns an immutable list containing nine elements.
 953      *
 954      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 955      *
 956      * @param <E> the {@code List}'s element type
 957      * @param e1 the first element
 958      * @param e2 the second element
 959      * @param e3 the third element
 960      * @param e4 the fourth element
 961      * @param e5 the fifth element
 962      * @param e6 the sixth element
 963      * @param e7 the seventh element
 964      * @param e8 the eighth element
 965      * @param e9 the ninth element
 966      * @return a {@code List} containing the specified elements
 967      * @throws NullPointerException if an element is {@code null}
 968      *
 969      * @since 9
 970      */
 971     static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
 972         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
 973                                                 e6, e7, e8, e9);
 974     }
 975 
 976     /**
 977      * Returns an immutable list containing ten elements.
 978      *
 979      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
 980      *
 981      * @param <E> the {@code List}'s element type
 982      * @param e1 the first element
 983      * @param e2 the second element
 984      * @param e3 the third element
 985      * @param e4 the fourth element
 986      * @param e5 the fifth element
 987      * @param e6 the sixth element
 988      * @param e7 the seventh element
 989      * @param e8 the eighth element
 990      * @param e9 the ninth element
 991      * @param e10 the tenth element
 992      * @return a {@code List} containing the specified elements
 993      * @throws NullPointerException if an element is {@code null}
 994      *
 995      * @since 9
 996      */
 997     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) {
 998         return new ImmutableCollections.ListN<>(e1, e2, e3, e4, e5,
 999                                                 e6, e7, e8, e9, e10);
1000     }
1001 
1002     /**
1003      * Returns an immutable list containing an arbitrary number of elements.
1004      * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
1005      *
1006      * @apiNote
1007      * This method also accepts a single array as an argument. The element type of
1008      * the resulting list will be the component type of the array, and the size of
1009      * the list will be equal to the length of the array. To create a list with
1010      * a single element that is an array, do the following:
1011      *
1012      * <pre>{@code
1013      *     String[] array = ... ;
1014      *     List<String[]> list = List.<String[]>of(array);
1015      * }</pre>
1016      *
1017      * This will cause the {@link List#of(Object) List.of(E)} method
1018      * to be invoked instead.
1019      *
1020      * @param <E> the {@code List}'s element type
1021      * @param elements the elements to be contained in the list
1022      * @return a {@code List} containing the specified elements
1023      * @throws NullPointerException if an element is {@code null} or if the array is {@code null}
1024      *
1025      * @since 9
1026      */
1027     @SafeVarargs
1028     @SuppressWarnings("varargs")
1029     static <E> List<E> of(E... elements) {
1030         switch (elements.length) { // implicit null check of elements
1031             case 0:
1032                 return ImmutableCollections.List0.instance();
1033             case 1:
1034                 return new ImmutableCollections.List1<>(elements[0]);
1035             case 2:
1036                 return new ImmutableCollections.List2<>(elements[0], elements[1]);
1037             default:
1038                 return new ImmutableCollections.ListN<>(elements);
1039         }
1040     }





















1041 }


  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>.


 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 unmodifiable list containing zero elements.
 781      *
 782      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing one element.
 795      *
 796      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing two elements.
 811      *
 812      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing three elements.
 828      *
 829      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing four elements.
 846      *
 847      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing five elements.
 865      *
 866      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing six elements.
 885      *
 886      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing seven elements.
 907      *
 908      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing eight elements.
 930      *
 931      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing nine elements.
 954      *
 955      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing ten elements.
 979      *
 980      * See <a href="#unmodifiable">Unmodifiable Lists</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 unmodifiable list containing an arbitrary number of elements.
1005      * See <a href="#unmodifiable">Unmodifiable Lists</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 
1043     /**
1044      * Returns an <a href="#unmodifiable">unmodifiable List</a> containing the elements
1045      * of the given Collection, in iteration order. The given Collection must not be null,
1046      * and it must not contain any null elements. If the given Collection is subsequently
1047      * modified, the returned List will not reflect such modifications.
1048      *
1049      * @param <E> the {@code List}'s element type
1050      * @param coll the collection from which elements are drawn, must be non-null
1051      * @return the new {@code List}
1052      * @throws NullPointerException if coll is null, or if it contains any nulls
1053      * @since 10
1054      */
1055     @SuppressWarnings("unchecked")
1056     static <E> List<E> copyOf(Collection<? extends E> coll) {
1057         if (coll instanceof ImmutableCollections.AbstractImmutableList) {
1058             return (List<E>)coll;
1059         } else {
1060             return (List<E>)List.of(coll.toArray());
1061         }
1062     }
1063 }
< prev index next >