6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.util;
27
28 import java.util.function.UnaryOperator;
29
30 /**
31 * An ordered collection (also known as a <i>sequence</i>). The user of this
32 * interface has precise control over where in the list each element is
33 * inserted. The user can access elements by their integer index (position in
34 * the list), and search for elements in the list.<p>
35 *
36 * Unlike sets, lists typically allow duplicate elements. More formally,
37 * lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>
38 * such that <tt>e1.equals(e2)</tt>, and they typically allow multiple
39 * null elements if they allow null elements at all. It is not inconceivable
40 * that someone might wish to implement a list that prohibits duplicates, by
41 * throwing runtime exceptions when the user attempts to insert them, but we
42 * expect this usage to be rare.<p>
43 *
44 * The <tt>List</tt> interface places additional stipulations, beyond those
45 * specified in the <tt>Collection</tt> interface, on the contracts of the
46 * <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and
47 * <tt>hashCode</tt> methods. Declarations for other inherited methods are
48 * also included here for convenience.<p>
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 */
110
111 public interface List<E> extends Collection<E> {
112 // Query Operations
113
114 /**
115 * Returns the number of elements in this list. If this list contains
116 * more than <tt>Integer.MAX_VALUE</tt> elements, returns
117 * <tt>Integer.MAX_VALUE</tt>.
118 *
119 * @return the number of elements in this list
120 */
121 int size();
122
123 /**
124 * Returns <tt>true</tt> if this list contains no elements.
125 *
126 * @return <tt>true</tt> if this list contains no elements
127 */
128 boolean isEmpty();
129
130 /**
131 * Returns <tt>true</tt> if this list contains the specified element.
191 * <p>Suppose <tt>x</tt> is a list known to contain only strings.
192 * The following code can be used to dump the list into a newly
193 * allocated array of <tt>String</tt>:
194 *
195 * <pre>{@code
196 * String[] y = x.toArray(new String[0]);
197 * }</pre>
198 *
199 * Note that <tt>toArray(new Object[0])</tt> is identical in function to
200 * <tt>toArray()</tt>.
201 *
202 * @param a the array into which the elements of this list are to
203 * be stored, if it is big enough; otherwise, a new array of the
204 * same runtime type is allocated for this purpose.
205 * @return an array containing the elements of this list
206 * @throws ArrayStoreException if the runtime type of the specified array
207 * is not a supertype of the runtime type of every element in
208 * this list
209 * @throws NullPointerException if the specified array is null
210 */
211 <T> T[] toArray(T[] a);
212
213
214 // Modification Operations
215
216 /**
217 * Appends the specified element to the end of this list (optional
218 * operation).
219 *
220 * <p>Lists that support this operation may place limitations on what
221 * elements may be added to this list. In particular, some
222 * lists will refuse to add null elements, and others will impose
223 * restrictions on the type of elements that may be added. List
224 * classes should clearly specify in their documentation any restrictions
225 * on what elements may be added.
226 *
227 * @param e element to be appended to this list
228 * @return <tt>true</tt> (as specified by {@link Collection#add})
229 * @throws UnsupportedOperationException if the <tt>add</tt> operation
230 * is not supported by this list
231 * @throws ClassCastException if the class of the specified element
457 * TimSort</a>). It uses techniques from Peter McIlroy's "Optimistic
458 * Sorting and Information Theoretic Complexity", in Proceedings of the
459 * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
460 * January 1993.
461 *
462 * @param c the {@code Comparator} used to compare list elements.
463 * A {@code null} value indicates that the elements'
464 * {@linkplain Comparable natural ordering} should be used
465 * @throws ClassCastException if the list contains elements that are not
466 * <i>mutually comparable</i> using the specified comparator
467 * @throws UnsupportedOperationException if the list's list-iterator does
468 * not support the {@code set} operation
469 * @throws IllegalArgumentException
470 * (<a href="Collection.html#optional-restrictions">optional</a>)
471 * if the comparator is found to violate the {@link Comparator}
472 * contract
473 * @since 1.8
474 */
475 @SuppressWarnings({"unchecked", "rawtypes"})
476 default void sort(Comparator<? super E> c) {
477 Object[] a = this.toArray();
478 Arrays.sort(a, (Comparator) c);
479 ListIterator<E> i = this.listIterator();
480 for (Object e : a) {
481 i.next();
482 i.set((E) e);
483 }
484 }
485
486 /**
487 * Removes all of the elements from this list (optional operation).
488 * The list will be empty after this call returns.
489 *
490 * @throws UnsupportedOperationException if the <tt>clear</tt> operation
491 * is not supported by this list
492 */
493 void clear();
494
495
496 // Comparison and hashing
497
498 /**
499 * Compares the specified object with this list for equality. Returns
500 * <tt>true</tt> if and only if the specified object is also a list, both
501 * lists have the same size, and all corresponding pairs of elements in
502 * the two lists are <i>equal</i>. (Two elements <tt>e1</tt> and
604
605 /**
606 * Returns the index of the first occurrence of the specified element
607 * in this list, or -1 if this list does not contain the element.
608 * More formally, returns the lowest index <tt>i</tt> such that
609 * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
610 * or -1 if there is no such index.
611 *
612 * @param o element to search for
613 * @return the index of the first occurrence of the specified element in
614 * this list, or -1 if this list does not contain the element
615 * @throws ClassCastException if the type of the specified element
616 * is incompatible with this list
617 * (<a href="Collection.html#optional-restrictions">optional</a>)
618 * @throws NullPointerException if the specified element is null and this
619 * list does not permit null elements
620 * (<a href="Collection.html#optional-restrictions">optional</a>)
621 */
622 int indexOf(Object o);
623
624 /**
625 * Returns the index of the last occurrence of the specified element
626 * in this list, or -1 if this list does not contain the element.
627 * More formally, returns the highest index <tt>i</tt> such that
628 * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
629 * or -1 if there is no such index.
630 *
631 * @param o element to search for
632 * @return the index of the last occurrence of the specified element in
633 * this list, or -1 if this list does not contain the element
634 * @throws ClassCastException if the type of the specified element
635 * is incompatible with this list
636 * (<a href="Collection.html#optional-restrictions">optional</a>)
637 * @throws NullPointerException if the specified element is null and this
638 * list does not permit null elements
639 * (<a href="Collection.html#optional-restrictions">optional</a>)
640 */
641 int lastIndexOf(Object o);
642
643
644 // List Iterators
645
646 /**
647 * Returns a list iterator over the elements in this list (in proper
648 * sequence).
649 *
650 * @return a list iterator over the elements in this list (in proper
651 * sequence)
652 */
653 ListIterator<E> listIterator();
654
655 /**
656 * Returns a list iterator over the elements in this list (in proper
657 * sequence), starting at the specified position in the list.
658 * The specified index indicates the first element that would be
659 * returned by an initial call to {@link ListIterator#next next}.
660 * An initial call to {@link ListIterator#previous previous} would
661 * return the element with the specified index minus one.
662 *
710 /**
711 * Creates a {@link Spliterator} over the elements in this list.
712 *
713 * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and
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 }
|
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package javany.util;
27
28 import javany.util.function.UnaryOperator;
29
30 import java.util.Objects;
31
32 /**
33 * An ordered collection (also known as a <i>sequence</i>). The user of this
34 * interface has precise control over where in the list each element is
35 * inserted. The user can access elements by their integer index (position in
36 * the list), and search for elements in the list.<p>
37 *
38 * Unlike sets, lists typically allow duplicate elements. More formally,
39 * lists typically allow pairs of elements <tt>e1</tt> and <tt>e2</tt>
40 * such that <tt>e1.equals(e2)</tt>, and they typically allow multiple
41 * null elements if they allow null elements at all. It is not inconceivable
42 * that someone might wish to implement a list that prohibits duplicates, by
43 * throwing runtime exceptions when the user attempts to insert them, but we
44 * expect this usage to be rare.<p>
45 *
46 * The <tt>List</tt> interface places additional stipulations, beyond those
47 * specified in the <tt>Collection</tt> interface, on the contracts of the
48 * <tt>iterator</tt>, <tt>add</tt>, <tt>remove</tt>, <tt>equals</tt>, and
49 * <tt>hashCode</tt> methods. Declarations for other inherited methods are
50 * also included here for convenience.<p>
93 * <a href="{@docRoot}/../technotes/guides/collections/index.html">
94 * Java Collections Framework</a>.
95 *
96 * @param <E> the type of elements in this list
97 *
98 * @author Josh Bloch
99 * @author Neal Gafter
100 * @see Collection
101 * @see Set
102 * @see ArrayList
103 * @see LinkedList
104 * @see Vector
105 * @see Arrays#asList(Object[])
106 * @see Collections#nCopies(int, Object)
107 * @see Collections#EMPTY_LIST
108 * @see AbstractList
109 * @see AbstractSequentialList
110 * @since 1.2
111 */
112
113 public interface List<any E> extends Collection<E> {
114 // Query Operations
115
116 /**
117 * Returns the number of elements in this list. If this list contains
118 * more than <tt>Integer.MAX_VALUE</tt> elements, returns
119 * <tt>Integer.MAX_VALUE</tt>.
120 *
121 * @return the number of elements in this list
122 */
123 int size();
124
125 /**
126 * Returns <tt>true</tt> if this list contains no elements.
127 *
128 * @return <tt>true</tt> if this list contains no elements
129 */
130 boolean isEmpty();
131
132 /**
133 * Returns <tt>true</tt> if this list contains the specified element.
193 * <p>Suppose <tt>x</tt> is a list known to contain only strings.
194 * The following code can be used to dump the list into a newly
195 * allocated array of <tt>String</tt>:
196 *
197 * <pre>{@code
198 * String[] y = x.toArray(new String[0]);
199 * }</pre>
200 *
201 * Note that <tt>toArray(new Object[0])</tt> is identical in function to
202 * <tt>toArray()</tt>.
203 *
204 * @param a the array into which the elements of this list are to
205 * be stored, if it is big enough; otherwise, a new array of the
206 * same runtime type is allocated for this purpose.
207 * @return an array containing the elements of this list
208 * @throws ArrayStoreException if the runtime type of the specified array
209 * is not a supertype of the runtime type of every element in
210 * this list
211 * @throws NullPointerException if the specified array is null
212 */
213 <any T> T[] toArray(T[] a);
214
215
216 // Modification Operations
217
218 /**
219 * Appends the specified element to the end of this list (optional
220 * operation).
221 *
222 * <p>Lists that support this operation may place limitations on what
223 * elements may be added to this list. In particular, some
224 * lists will refuse to add null elements, and others will impose
225 * restrictions on the type of elements that may be added. List
226 * classes should clearly specify in their documentation any restrictions
227 * on what elements may be added.
228 *
229 * @param e element to be appended to this list
230 * @return <tt>true</tt> (as specified by {@link Collection#add})
231 * @throws UnsupportedOperationException if the <tt>add</tt> operation
232 * is not supported by this list
233 * @throws ClassCastException if the class of the specified element
459 * TimSort</a>). It uses techniques from Peter McIlroy's "Optimistic
460 * Sorting and Information Theoretic Complexity", in Proceedings of the
461 * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
462 * January 1993.
463 *
464 * @param c the {@code Comparator} used to compare list elements.
465 * A {@code null} value indicates that the elements'
466 * {@linkplain Comparable natural ordering} should be used
467 * @throws ClassCastException if the list contains elements that are not
468 * <i>mutually comparable</i> using the specified comparator
469 * @throws UnsupportedOperationException if the list's list-iterator does
470 * not support the {@code set} operation
471 * @throws IllegalArgumentException
472 * (<a href="Collection.html#optional-restrictions">optional</a>)
473 * if the comparator is found to violate the {@link Comparator}
474 * contract
475 * @since 1.8
476 */
477 @SuppressWarnings({"unchecked", "rawtypes"})
478 default void sort(Comparator<? super E> c) {
479 E[] a = this.toArray(new E[size()]);
480 Arrays.sort(a, c);
481 ListIterator<E> i = this.listIterator();
482 for (E e : a) {
483 i.next();
484 i.set(e);
485 }
486 }
487
488 /**
489 * Removes all of the elements from this list (optional operation).
490 * The list will be empty after this call returns.
491 *
492 * @throws UnsupportedOperationException if the <tt>clear</tt> operation
493 * is not supported by this list
494 */
495 void clear();
496
497
498 // Comparison and hashing
499
500 /**
501 * Compares the specified object with this list for equality. Returns
502 * <tt>true</tt> if and only if the specified object is also a list, both
503 * lists have the same size, and all corresponding pairs of elements in
504 * the two lists are <i>equal</i>. (Two elements <tt>e1</tt> and
606
607 /**
608 * Returns the index of the first occurrence of the specified element
609 * in this list, or -1 if this list does not contain the element.
610 * More formally, returns the lowest index <tt>i</tt> such that
611 * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
612 * or -1 if there is no such index.
613 *
614 * @param o element to search for
615 * @return the index of the first occurrence of the specified element in
616 * this list, or -1 if this list does not contain the element
617 * @throws ClassCastException if the type of the specified element
618 * is incompatible with this list
619 * (<a href="Collection.html#optional-restrictions">optional</a>)
620 * @throws NullPointerException if the specified element is null and this
621 * list does not permit null elements
622 * (<a href="Collection.html#optional-restrictions">optional</a>)
623 */
624 int indexOf(Object o);
625
626 default int indexOfElement(E e) {
627 ListIterator<E> it = listIterator();
628 while (it.hasNext())
629 if (Any.equals(e, it.next()))
630 return it.previousIndex();
631 return -1;
632 }
633
634 /**
635 * Returns the index of the last occurrence of the specified element
636 * in this list, or -1 if this list does not contain the element.
637 * More formally, returns the highest index <tt>i</tt> such that
638 * <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,
639 * or -1 if there is no such index.
640 *
641 * @param o element to search for
642 * @return the index of the last occurrence of the specified element in
643 * this list, or -1 if this list does not contain the element
644 * @throws ClassCastException if the type of the specified element
645 * is incompatible with this list
646 * (<a href="Collection.html#optional-restrictions">optional</a>)
647 * @throws NullPointerException if the specified element is null and this
648 * list does not permit null elements
649 * (<a href="Collection.html#optional-restrictions">optional</a>)
650 */
651 int lastIndexOf(Object o);
652
653 default int lastIndexOfElement(E e) {
654 ListIterator<E> it = listIterator(size());
655 while (it.hasPrevious())
656 if (Any.equals(e, it.previous()))
657 return it.nextIndex();
658 return -1;
659 }
660
661 // List Iterators
662
663 /**
664 * Returns a list iterator over the elements in this list (in proper
665 * sequence).
666 *
667 * @return a list iterator over the elements in this list (in proper
668 * sequence)
669 */
670 ListIterator<E> listIterator();
671
672 /**
673 * Returns a list iterator over the elements in this list (in proper
674 * sequence), starting at the specified position in the list.
675 * The specified index indicates the first element that would be
676 * returned by an initial call to {@link ListIterator#next next}.
677 * An initial call to {@link ListIterator#previous previous} would
678 * return the element with the specified index minus one.
679 *
727 /**
728 * Creates a {@link Spliterator} over the elements in this list.
729 *
730 * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and
731 * {@link Spliterator#ORDERED}. Implementations should document the
732 * reporting of additional characteristic values.
733 *
734 * @implSpec
735 * The default implementation creates a
736 * <em><a href="Spliterator.html#binding">late-binding</a></em> spliterator
737 * from the list's {@code Iterator}. The spliterator inherits the
738 * <em>fail-fast</em> properties of the list's iterator.
739 *
740 * @implNote
741 * The created {@code Spliterator} additionally reports
742 * {@link Spliterator#SUBSIZED}.
743 *
744 * @return a {@code Spliterator} over the elements in this list
745 * @since 1.8
746 */
747 // @Override
748 // default Spliterator<E> spliterator() {
749 // return Spliterators.spliterator(this, Spliterator.ORDERED);
750 // }
751 }
|