|
Java example source code file (List.java)
The List.java Java example source code/* * Copyright (c) 1997, 2013, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code is distributed in the hope that it will be useful, but WITHOUT * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package java.util; import java.util.function.UnaryOperator; /** * An ordered collection (also known as a <i>sequence). The user of this * interface has precise control over where in the list each element is * inserted. The user can access elements by their integer index (position in * the list), and search for elements in the list.<p> * * Unlike sets, lists typically allow duplicate elements. More formally, * lists typically allow pairs of elements <tt>e1 and e2 * such that <tt>e1.equals(e2), and they typically allow multiple * null elements if they allow null elements at all. It is not inconceivable * that someone might wish to implement a list that prohibits duplicates, by * throwing runtime exceptions when the user attempts to insert them, but we * expect this usage to be rare.<p> * * The <tt>List interface places additional stipulations, beyond those * specified in the <tt>Collection interface, on the contracts of the * <tt>iterator, add, remove, equals, and * <tt>hashCode methods. Declarations for other inherited methods are * also included here for convenience.<p> * * The <tt>List interface provides four methods for positional (indexed) * access to list elements. Lists (like Java arrays) are zero based. Note * that these operations may execute in time proportional to the index value * for some implementations (the <tt>LinkedList class, for * example). Thus, iterating over the elements in a list is typically * preferable to indexing through it if the caller does not know the * implementation.<p> * * The <tt>List interface provides a special iterator, called a * <tt>ListIterator, that allows element insertion and replacement, and * bidirectional access in addition to the normal operations that the * <tt>Iterator interface provides. A method is provided to obtain a * list iterator that starts at a specified position in the list.<p> * * The <tt>List interface provides two methods to search for a specified * object. From a performance standpoint, these methods should be used with * caution. In many implementations they will perform costly linear * searches.<p> * * The <tt>List interface provides two methods to efficiently insert and * remove multiple elements at an arbitrary point in the list.<p> * * Note: While it is permissible for lists to contain themselves as elements, * extreme caution is advised: the <tt>equals and hashCode * methods are no longer well defined on such a list. * * <p>Some list implementations have restrictions on the elements that * they may contain. For example, some implementations prohibit null elements, * and some have restrictions on the types of their elements. Attempting to * add an ineligible element throws an unchecked exception, typically * <tt>NullPointerException or ClassCastException. Attempting * to query the presence of an ineligible element may throw an exception, * or it may simply return false; some implementations will exhibit the former * behavior and some will exhibit the latter. More generally, attempting an * operation on an ineligible element whose completion would not result in * the insertion of an ineligible element into the list may throw an * exception or it may succeed, at the option of the implementation. * Such exceptions are marked as "optional" in the specification for this * interface. * * <p>This interface is a member of the * <a href="{@docRoot}/../technotes/guides/collections/index.html"> * Java Collections Framework</a>. * * @param <E> the type of elements in this list * * @author Josh Bloch * @author Neal Gafter * @see Collection * @see Set * @see ArrayList * @see LinkedList * @see Vector * @see Arrays#asList(Object[]) * @see Collections#nCopies(int, Object) * @see Collections#EMPTY_LIST * @see AbstractList * @see AbstractSequentialList * @since 1.2 */ public interface List<E> extends Collection* * @param c the {@code Comparator} used to compare list elements. * A {@code null} value indicates that the elements' * {@linkplain Comparable natural ordering} should be used * @throws ClassCastException if the list contains elements that are not * <i>mutually comparable using the specified comparator * @throws UnsupportedOperationException if the list's list-iterator does * not support the {@code set} operation * @throws IllegalArgumentException * (<a href="Collection.html#optional-restrictions">optional) * if the comparator is found to violate the {@link Comparator} * contract * @since 1.8 */ default void sort(Comparator<? super E> c) { Collections.sort(this, c); } /** * Removes all of the elements from this list (optional operation). * The list will be empty after this call returns. * * @throws UnsupportedOperationException if the <tt>clear operation * is not supported by this list */ void clear(); // Comparison and hashing /** * Compares the specified object with this list for equality. Returns * <tt>true if and only if the specified object is also a list, both * lists have the same size, and all corresponding pairs of elements in * the two lists are <i>equal. (Two elements e1 and * <tt>e2 are equal if (e1==null ? e2==null : * e1.equals(e2))</tt>.) In other words, two lists are defined to be * equal if they contain the same elements in the same order. This * definition ensures that the equals method works properly across * different implementations of the <tt>List interface. * * @param o the object to be compared for equality with this list * @return <tt>true if the specified object is equal to this list */ boolean equals(Object o); /** * Returns the hash code value for this list. The hash code of a list * is defined to be the result of the following calculation: * <pre>{@code * int hashCode = 1; * for (E e : list) * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode()); * }</pre> * This ensures that <tt>list1.equals(list2) implies that * <tt>list1.hashCode()==list2.hashCode() for any two lists, * <tt>list1 and list2, as required by the general * contract of {@link Object#hashCode}. * * @return the hash code value for this list * @see Object#equals(Object) * @see #equals(Object) */ int hashCode(); // Positional Access Operations /** * Returns the element at the specified position in this list. * * @param index index of the element to return * @return the element at the specified position in this list * @throws IndexOutOfBoundsException if the index is out of range * (<tt>index < 0 || index >= size()) */ E get(int index); /** * Replaces the element at the specified position in this list with the * specified element (optional operation). * * @param index index of the element to replace * @param element element to be stored at the specified position * @return the element previously at the specified position * @throws UnsupportedOperationException if the <tt>set operation * is not supported by this list * @throws ClassCastException if the class of the specified element * prevents it from being added to this list * @throws NullPointerException if the specified element is null and * this list does not permit null elements * @throws IllegalArgumentException if some property of the specified * element prevents it from being added to this list * @throws IndexOutOfBoundsException if the index is out of range * (<tt>index < 0 || index >= size()) */ E set(int index, E element); /** * Inserts the specified element at the specified position in this list * (optional operation). Shifts the element currently at that position * (if any) and any subsequent elements to the right (adds one to their * indices). * * @param index index at which the specified element is to be inserted * @param element element to be inserted * @throws UnsupportedOperationException if the <tt>add operation * is not supported by this list * @throws ClassCastException if the class of the specified element * prevents it from being added to this list * @throws NullPointerException if the specified element is null and * this list does not permit null elements * @throws IllegalArgumentException if some property of the specified * element prevents it from being added to this list * @throws IndexOutOfBoundsException if the index is out of range * (<tt>index < 0 || index > size()) */ void add(int index, E element); /** * Removes the element at the specified position in this list (optional * operation). Shifts any subsequent elements to the left (subtracts one * from their indices). Returns the element that was removed from the * list. * * @param index the index of the element to be removed * @return the element previously at the specified position * @throws UnsupportedOperationException if the <tt>remove operation * is not supported by this list * @throws IndexOutOfBoundsException if the index is out of range * (<tt>index < 0 || index >= size()) */ E remove(int index); // Search Operations /** * Returns the index of the first occurrence of the specified element * in this list, or -1 if this list does not contain the element. * More formally, returns the lowest index <tt>i such that * <tt>(o==null ? get(i)==null : o.equals(get(i))), * or -1 if there is no such index. * * @param o element to search for * @return the index of the first occurrence of the specified element in * this list, or -1 if this list does not contain the element * @throws ClassCastException if the type of the specified element * is incompatible with this list * (<a href="Collection.html#optional-restrictions">optional) * @throws NullPointerException if the specified element is null and this * list does not permit null elements * (<a href="Collection.html#optional-restrictions">optional) */ int indexOf(Object o); /** * Returns the index of the last occurrence of the specified element * in this list, or -1 if this list does not contain the element. * More formally, returns the highest index <tt>i such that * <tt>(o==null ? get(i)==null : o.equals(get(i))), * or -1 if there is no such index. * * @param o element to search for * @return the index of the last occurrence of the specified element in * this list, or -1 if this list does not contain the element * @throws ClassCastException if the type of the specified element * is incompatible with this list * (<a href="Collection.html#optional-restrictions">optional) * @throws NullPointerException if the specified element is null and this * list does not permit null elements * (<a href="Collection.html#optional-restrictions">optional) */ int lastIndexOf(Object o); // List Iterators /** * Returns a list iterator over the elements in this list (in proper * sequence). * * @return a list iterator over the elements in this list (in proper * sequence) */ ListIterator<E> listIterator(); /** * Returns a list iterator over the elements in this list (in proper * sequence), starting at the specified position in the list. * The specified index indicates the first element that would be * returned by an initial call to {@link ListIterator#next next}. * An initial call to {@link ListIterator#previous previous} would * return the element with the specified index minus one. * * @param index index of the first element to be returned from the * list iterator (by a call to {@link ListIterator#next next}) * @return a list iterator over the elements in this list (in proper * sequence), starting at the specified position in the list * @throws IndexOutOfBoundsException if the index is out of range * ({@code index < 0 || index > size()}) */ ListIterator<E> listIterator(int index); // View /** * Returns a view of the portion of this list between the specified * <tt>fromIndex, inclusive, and toIndex, exclusive. (If * <tt>fromIndex and toIndex are equal, the returned list is * empty.) The returned list is backed by this list, so non-structural * changes in the returned list are reflected in this list, and vice-versa. * The returned list supports all of the optional list operations supported * by this list.<p> * * This method eliminates the need for explicit range operations (of * the sort that commonly exist for arrays). Any operation that expects * a list can be used as a range operation by passing a subList view * instead of a whole list. For example, the following idiom * removes a range of elements from a list: * <pre>{@code * list.subList(from, to).clear(); * }</pre> * Similar idioms may be constructed for <tt>indexOf and * <tt>lastIndexOf, and all of the algorithms in the * <tt>Collections class can be applied to a subList. * * The semantics of the list returned by this method become undefined if * the backing list (i.e., this list) is <i>structurally modified in * any way other than via the returned list. (Structural modifications are * those that change the size of this list, or otherwise perturb it in such * a fashion that iterations in progress may yield incorrect results.) * * @param fromIndex low endpoint (inclusive) of the subList * @param toIndex high endpoint (exclusive) of the subList * @return a view of the specified range within this list * @throws IndexOutOfBoundsException for an illegal endpoint index value * (<tt>fromIndex < 0 || toIndex > size || * fromIndex > toIndex</tt>) */ List<E> subList(int fromIndex, int toIndex); /** * Creates a {@link Spliterator} over the elements in this list. * * <p>The {@code Spliterator} reports {@link Spliterator#SIZED} and * {@link Spliterator#ORDERED}. Implementations should document the * reporting of additional characteristic values. * * @implSpec * The default implementation creates a * <em>late-binding spliterator * from the list's {@code Iterator}. The spliterator inherits the * <em>fail-fast properties of the list's iterator. * * @implNote * The created {@code Spliterator} additionally reports * {@link Spliterator#SUBSIZED}. * * @return a {@code Spliterator} over the elements in this list * @since 1.8 */ @Override default Spliterator<E> spliterator() { return Spliterators.spliterator(this, Spliterator.ORDERED); } } Other Java examples (source code examples)Here is a short list of links related to this Java List.java source code file: |
... this post is sponsored by my books ... | |
#1 New Release! |
FP Best Seller |
Copyright 1998-2021 Alvin Alexander, alvinalexander.com
All Rights Reserved.
A percentage of advertising revenue from
pages under the /java/jwarehouse
URI on this website is
paid back to open source projects.