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 * <p>This interface is a member of the
91 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
92 * Java Collections Framework</a>.
93 *
94 * @param <E> the type of elements in this list
95 *
96 * @author Josh Bloch
97 * @author Neal Gafter
98 * @see Collection
99 * @see Set
100 * @see ArrayList
101 * @see LinkedList
102 * @see Vector
103 * @see Arrays#asList(Object[])
104 * @see Collections#nCopies(int, Object)
105 * @see Collections#EMPTY_LIST
106 * @see AbstractList
107 * @see AbstractSequentialList
108 * @since 1.2
109 */
714 * {@link Spliterator#ORDERED}. Implementations should document the
715 * reporting of additional characteristic values.
716 *
717 * @implSpec
718 * The default implementation creates a
719 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
720 * from the list's {@code Iterator}. The spliterator inherits the
721 * <em>fail-fast</em> properties of the list's iterator.
722 *
723 * @implNote
724 * The created {@code Spliterator} additionally reports
725 * {@link Spliterator#SUBSIZED}.
726 *
727 * @return a {@code Spliterator} over the elements in this list
728 * @since 1.8
729 */
730 @Override
731 default Spliterator<E> spliterator() {
732 return Spliterators.spliterator(this, Spliterator.ORDERED);
733 }
734 }
|
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 name="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 cannot be modified. Attempts to modify them result in
97 * an {@code UnsupportedOperationException}.
98 * <li>They are truly immutable only if the contained elements are themselves
99 * immutable. If an element is mutated, it will affect the result of the
100 * containing list's {@code equals()} and {@code hashCode()} methods.
101 * <li>They disallow null elements. Attempts to create them with
102 * null elements result in {@code NullPointerException}.
103 * <li>They are serializable if all elements are serializable.
104 * </ul>
105 *
106 * <p>This interface is a member of the
107 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
108 * Java Collections Framework</a>.
109 *
110 * @param <E> the type of elements in this list
111 *
112 * @author Josh Bloch
113 * @author Neal Gafter
114 * @see Collection
115 * @see Set
116 * @see ArrayList
117 * @see LinkedList
118 * @see Vector
119 * @see Arrays#asList(Object[])
120 * @see Collections#nCopies(int, Object)
121 * @see Collections#EMPTY_LIST
122 * @see AbstractList
123 * @see AbstractSequentialList
124 * @since 1.2
125 */
730 * {@link Spliterator#ORDERED}. Implementations should document the
731 * reporting of additional characteristic values.
732 *
733 * @implSpec
734 * The default implementation creates a
735 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
736 * from the list's {@code Iterator}. The spliterator inherits the
737 * <em>fail-fast</em> properties of the list's iterator.
738 *
739 * @implNote
740 * The created {@code Spliterator} additionally reports
741 * {@link Spliterator#SUBSIZED}.
742 *
743 * @return a {@code Spliterator} over the elements in this list
744 * @since 1.8
745 */
746 @Override
747 default Spliterator<E> spliterator() {
748 return Spliterators.spliterator(this, Spliterator.ORDERED);
749 }
750
751 /**
752 * Creates an immutable list containing zero elements.
753 *
754 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
755 *
756 * @param <E> the list's element type
757 * @return the newly created list
758 *
759 * @since 9
760 */
761 static <E> List<E> of() {
762 return Collections.emptyList();
763 }
764
765 /**
766 * Creates an immutable list containing one element.
767 *
768 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
769 *
770 * @param <E> the list's element type
771 * @param e1 the single list element
772 * @return the newly created list
773 * @throws NullPointerException if the element is null
774 *
775 * @since 9
776 */
777 static <E> List<E> of(E e1) {
778 return Collections.singletonList(Objects.requireNonNull(e1));
779 }
780
781 /**
782 * Creates an immutable list containing two elements.
783 *
784 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
785 *
786 * @param <E> the list's element type
787 * @param e1 the first list element
788 * @param e2 the second list element
789 * @return the newly created list
790 * @throws NullPointerException if an element is null
791 *
792 * @since 9
793 */
794 static <E> List<E> of(E e1, E e2) {
795 return Collections.unmodifiableList(
796 Arrays.asList(Objects.requireNonNull(e1),
797 Objects.requireNonNull(e2)));
798 }
799
800 /**
801 * Creates an immutable list containing three elements.
802 *
803 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
804 *
805 * @param <E> the list's element type
806 * @param e1 the first list element
807 * @param e2 the second list element
808 * @param e3 the third list element
809 * @return the newly created list
810 * @throws NullPointerException if an element is null
811 *
812 * @since 9
813 */
814 static <E> List<E> of(E e1, E e2, E e3) {
815 return Collections.unmodifiableList(
816 Arrays.asList(Objects.requireNonNull(e1),
817 Objects.requireNonNull(e2),
818 Objects.requireNonNull(e3)));
819 }
820
821 /**
822 * Creates an immutable list containing four elements.
823 *
824 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
825 *
826 * @param <E> the list's element type
827 * @param e1 the first list element
828 * @param e2 the second list element
829 * @param e3 the third list element
830 * @param e4 the fourth list element
831 * @return the newly created list
832 * @throws NullPointerException if an element is null
833 *
834 * @since 9
835 */
836 static <E> List<E> of(E e1, E e2, E e3, E e4) {
837 return Collections.unmodifiableList(
838 Arrays.asList(Objects.requireNonNull(e1),
839 Objects.requireNonNull(e2),
840 Objects.requireNonNull(e3),
841 Objects.requireNonNull(e4)));
842 }
843
844 /**
845 * Creates an immutable list containing five elements.
846 *
847 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
848 *
849 * @param <E> the list's element type
850 * @param e1 the first list element
851 * @param e2 the second list element
852 * @param e3 the third list element
853 * @param e4 the fourth list element
854 * @param e5 the fifth list element
855 * @return the newly created list
856 * @throws NullPointerException if an element is null
857 *
858 * @since 9
859 */
860 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5) {
861 return Collections.unmodifiableList(
862 Arrays.asList(Objects.requireNonNull(e1),
863 Objects.requireNonNull(e2),
864 Objects.requireNonNull(e3),
865 Objects.requireNonNull(e4),
866 Objects.requireNonNull(e5)));
867 }
868
869 /**
870 * Creates an immutable list containing six elements.
871 *
872 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
873 *
874 * @param <E> the list's element type
875 * @param e1 the first list element
876 * @param e2 the second list element
877 * @param e3 the third list element
878 * @param e4 the fourth list element
879 * @param e5 the fifth list element
880 * @param e6 the sixth list element
881 * @return the newly created list
882 * @throws NullPointerException if an element is null
883 *
884 * @since 9
885 */
886 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6) {
887 return Collections.unmodifiableList(
888 Arrays.asList(Objects.requireNonNull(e1),
889 Objects.requireNonNull(e2),
890 Objects.requireNonNull(e3),
891 Objects.requireNonNull(e4),
892 Objects.requireNonNull(e5),
893 Objects.requireNonNull(e6)));
894 }
895
896 /**
897 * Creates an immutable list containing seven elements.
898 *
899 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
900 *
901 * @param <E> the list's element type
902 * @param e1 the first list element
903 * @param e2 the second list element
904 * @param e3 the third list element
905 * @param e4 the fourth list element
906 * @param e5 the fifth list element
907 * @param e6 the sixth list element
908 * @param e7 the seventh list element
909 * @return the newly created list
910 * @throws NullPointerException if an element is null
911 *
912 * @since 9
913 */
914 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7) {
915 return Collections.unmodifiableList(
916 Arrays.asList(Objects.requireNonNull(e1),
917 Objects.requireNonNull(e2),
918 Objects.requireNonNull(e3),
919 Objects.requireNonNull(e4),
920 Objects.requireNonNull(e5),
921 Objects.requireNonNull(e6),
922 Objects.requireNonNull(e7)));
923 }
924
925 /**
926 * Creates an immutable list containing eight elements.
927 *
928 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
929 *
930 * @param <E> the list's element type
931 * @param e1 the first list element
932 * @param e2 the second list element
933 * @param e3 the third list element
934 * @param e4 the fourth list element
935 * @param e5 the fifth list element
936 * @param e6 the sixth list element
937 * @param e7 the seventh list element
938 * @param e8 the eighth list element
939 * @return the newly created list
940 * @throws NullPointerException if an element is null
941 *
942 * @since 9
943 */
944 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8) {
945 return Collections.unmodifiableList(
946 Arrays.asList(Objects.requireNonNull(e1),
947 Objects.requireNonNull(e2),
948 Objects.requireNonNull(e3),
949 Objects.requireNonNull(e4),
950 Objects.requireNonNull(e5),
951 Objects.requireNonNull(e6),
952 Objects.requireNonNull(e7),
953 Objects.requireNonNull(e8)));
954 }
955
956 /**
957 * Creates an immutable list containing nine elements.
958 *
959 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
960 *
961 * @param <E> the list's element type
962 * @param e1 the first list element
963 * @param e2 the second list element
964 * @param e3 the third list element
965 * @param e4 the fourth list element
966 * @param e5 the fifth list element
967 * @param e6 the sixth list element
968 * @param e7 the seventh list element
969 * @param e8 the eighth list element
970 * @param e9 the ninth list element
971 * @return the newly created list
972 * @throws NullPointerException if an element is null
973 *
974 * @since 9
975 */
976 static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9) {
977 return Collections.unmodifiableList(
978 Arrays.asList(Objects.requireNonNull(e1),
979 Objects.requireNonNull(e2),
980 Objects.requireNonNull(e3),
981 Objects.requireNonNull(e4),
982 Objects.requireNonNull(e5),
983 Objects.requireNonNull(e6),
984 Objects.requireNonNull(e7),
985 Objects.requireNonNull(e8),
986 Objects.requireNonNull(e9)));
987 }
988
989 /**
990 * Creates an immutable list containing ten elements.
991 *
992 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
993 *
994 * @param <E> the list's element type
995 * @param e1 the first list element
996 * @param e2 the second list element
997 * @param e3 the third list element
998 * @param e4 the fourth list element
999 * @param e5 the fifth list element
1000 * @param e6 the sixth list element
1001 * @param e7 the seventh list element
1002 * @param e8 the eighth list element
1003 * @param e9 the ninth list element
1004 * @param e10 the tenth list element
1005 * @return the newly created list
1006 * @throws NullPointerException if an element is null
1007 *
1008 * @since 9
1009 */
1010 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) {
1011 return Collections.unmodifiableList(
1012 Arrays.asList(Objects.requireNonNull(e1),
1013 Objects.requireNonNull(e2),
1014 Objects.requireNonNull(e3),
1015 Objects.requireNonNull(e4),
1016 Objects.requireNonNull(e5),
1017 Objects.requireNonNull(e6),
1018 Objects.requireNonNull(e7),
1019 Objects.requireNonNull(e8),
1020 Objects.requireNonNull(e9),
1021 Objects.requireNonNull(e10)));
1022 }
1023
1024 /**
1025 * Creates an immutable list containing an arbitrary number of elements.
1026 * See <a href="#immutable">Immutable List Static Factory Methods</a> for details.
1027 *
1028 * @apiNote
1029 * This method also accepts a single array as an argument. The element type of
1030 * the resulting list will be the component type of the array, and the size of
1031 * the list will be equal to the length of the array. To create a list with
1032 * a single element that is an array, do the following:
1033 *
1034 * <pre>{@code
1035 * String[] array = ... ;
1036 * List<String[]> list = List.<String[]>of(array);
1037 * }</pre>
1038 *
1039 * This will cause the {@link List#of(Object) List.of(E)} method
1040 * to be invoked instead.
1041 *
1042 * @param <E> the list's element type
1043 * @param es the elements to be contained in the list
1044 * @return the newly created list
1045 * @throws NullPointerException if an element is null or if the array is null
1046 *
1047 * @since 9
1048 */
1049 @SafeVarargs
1050 @SuppressWarnings("varargs")
1051 static <E> List<E> of(E... es) {
1052 es = es.clone(); // throws NPE if es is null
1053 for (E e : es) {
1054 Objects.requireNonNull(e);
1055 }
1056 return Collections.unmodifiableList(Arrays.asList(es));
1057 }
1058 }
|