61.83/19.54 YES
61.83/19.56 proof of /export/starexec/sandbox/benchmark/theBenchmark.jar
61.83/19.56 # AProVE Commit ID: 48fb2092695e11cc9f56e44b17a92a5f88ffb256 marcel 20180622 unpublished dirty
61.83/19.56
61.83/19.56
61.83/19.56 termination of the given Bare JBC problem could be proven:
61.83/19.56
61.83/19.56 (0) Bare JBC problem
61.83/19.56 (1) BareJBCToJBCProof [EQUIVALENT, 95 ms]
61.83/19.56 (2) JBC problem
61.83/19.56 (3) JBCToGraph [EQUIVALENT, 11.8 s]
61.83/19.56 (4) JBCTerminationGraph
61.83/19.56 (5) TerminationGraphToSCCProof [SOUND, 0 ms]
61.83/19.56 (6) AND
61.83/19.56 (7) JBCTerminationSCC
61.83/19.56 (8) SCCToIRSProof [SOUND, 411 ms]
61.83/19.56 (9) IRSwT
61.83/19.56 (10) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (11) IRSwT
61.83/19.56 (12) IRSwTTerminationDigraphProof [EQUIVALENT, 122 ms]
61.83/19.56 (13) IRSwT
61.83/19.56 (14) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (15) IRSwT
61.83/19.56 (16) TempFilterProof [SOUND, 56 ms]
61.83/19.56 (17) IntTRS
61.83/19.56 (18) RankingReductionPairProof [EQUIVALENT, 0 ms]
61.83/19.56 (19) YES
61.83/19.56 (20) JBCTerminationSCC
61.83/19.56 (21) SCCToIRSProof [SOUND, 1236 ms]
61.83/19.56 (22) IRSwT
61.83/19.56 (23) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (24) IRSwT
61.83/19.56 (25) IRSwTTerminationDigraphProof [EQUIVALENT, 1343 ms]
61.83/19.56 (26) IRSwT
61.83/19.56 (27) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (28) IRSwT
61.83/19.56 (29) TempFilterProof [SOUND, 52 ms]
61.83/19.56 (30) IntTRS
61.83/19.56 (31) RankingReductionPairProof [EQUIVALENT, 15 ms]
61.83/19.56 (32) YES
61.83/19.56 (33) JBCTerminationSCC
61.83/19.56 (34) SCCToIRSProof [SOUND, 142 ms]
61.83/19.56 (35) IRSwT
61.83/19.56 (36) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (37) IRSwT
61.83/19.56 (38) IRSwTTerminationDigraphProof [EQUIVALENT, 294 ms]
61.83/19.56 (39) IRSwT
61.83/19.56 (40) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (41) IRSwT
61.83/19.56 (42) TempFilterProof [SOUND, 75 ms]
61.83/19.56 (43) IntTRS
61.83/19.56 (44) PolynomialOrderProcessor [EQUIVALENT, 0 ms]
61.83/19.56 (45) IntTRS
61.83/19.56 (46) PolynomialOrderProcessor [EQUIVALENT, 8 ms]
61.83/19.56 (47) YES
61.83/19.56 (48) JBCTerminationSCC
61.83/19.56 (49) SCCToIRSProof [SOUND, 118 ms]
61.83/19.56 (50) IRSwT
61.83/19.56 (51) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (52) IRSwT
61.83/19.56 (53) IRSwTTerminationDigraphProof [EQUIVALENT, 39 ms]
61.83/19.56 (54) IRSwT
61.83/19.56 (55) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (56) IRSwT
61.83/19.56 (57) TempFilterProof [SOUND, 25 ms]
61.83/19.56 (58) IntTRS
61.83/19.56 (59) RankingReductionPairProof [EQUIVALENT, 0 ms]
61.83/19.56 (60) YES
61.83/19.56 (61) JBCTerminationSCC
61.83/19.56 (62) SCCToIRSProof [SOUND, 118 ms]
61.83/19.56 (63) IRSwT
61.83/19.56 (64) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (65) IRSwT
61.83/19.56 (66) IRSwTTerminationDigraphProof [EQUIVALENT, 39 ms]
61.83/19.56 (67) IRSwT
61.83/19.56 (68) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (69) IRSwT
61.83/19.56 (70) TempFilterProof [SOUND, 13 ms]
61.83/19.56 (71) IntTRS
61.83/19.56 (72) RankingReductionPairProof [EQUIVALENT, 0 ms]
61.83/19.56 (73) YES
61.83/19.56 (74) JBCTerminationSCC
61.83/19.56 (75) SCCToIRSProof [SOUND, 26 ms]
61.83/19.56 (76) IRSwT
61.83/19.56 (77) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (78) IRSwT
61.83/19.56 (79) IRSwTTerminationDigraphProof [EQUIVALENT, 13 ms]
61.83/19.56 (80) IRSwT
61.83/19.56 (81) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (82) IRSwT
61.83/19.56 (83) TempFilterProof [SOUND, 40 ms]
61.83/19.56 (84) IntTRS
61.83/19.56 (85) RankingReductionPairProof [EQUIVALENT, 0 ms]
61.83/19.56 (86) YES
61.83/19.56 (87) JBCTerminationSCC
61.83/19.56 (88) SCCToIRSProof [SOUND, 46 ms]
61.83/19.56 (89) IRSwT
61.83/19.56 (90) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (91) IRSwT
61.83/19.56 (92) IRSwTTerminationDigraphProof [EQUIVALENT, 15 ms]
61.83/19.56 (93) IRSwT
61.83/19.56 (94) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (95) IRSwT
61.83/19.56 (96) TempFilterProof [SOUND, 13 ms]
61.83/19.56 (97) IntTRS
61.83/19.56 (98) RankingReductionPairProof [EQUIVALENT, 0 ms]
61.83/19.56 (99) YES
61.83/19.56 (100) JBCTerminationSCC
61.83/19.56 (101) SCCToIRSProof [SOUND, 231 ms]
61.83/19.56 (102) IRSwT
61.83/19.56 (103) IRSFormatTransformerProof [EQUIVALENT, 0 ms]
61.83/19.56 (104) IRSwT
61.83/19.56 (105) IRSwTTerminationDigraphProof [EQUIVALENT, 352 ms]
61.83/19.56 (106) IRSwT
61.83/19.56 (107) IntTRSCompressionProof [EQUIVALENT, 0 ms]
61.83/19.56 (108) IRSwT
61.83/19.56 (109) TempFilterProof [SOUND, 87 ms]
61.83/19.56 (110) IntTRS
61.83/19.56 (111) PolynomialOrderProcessor [EQUIVALENT, 21 ms]
61.83/19.56 (112) IntTRS
61.83/19.56 (113) PolynomialOrderProcessor [EQUIVALENT, 9 ms]
61.83/19.56 (114) YES
61.83/19.56
61.83/19.56
61.83/19.56 ----------------------------------------
61.83/19.56
61.83/19.56 (0)
61.83/19.56 Obligation:
61.83/19.56 need to prove termination of the following program:
61.83/19.56 /*
61.83/19.56 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
61.83/19.56 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
61.83/19.56 *
61.83/19.56 * This code is free software; you can redistribute it and/or modify it
61.83/19.56 * under the terms of the GNU General Public License version 2 only, as
61.83/19.56 * published by the Free Software Foundation. Sun designates this
61.83/19.56 * particular file as subject to the "Classpath" exception as provided
61.83/19.56 * by Sun in the LICENSE file that accompanied this code.
61.83/19.56 *
61.83/19.56 * This code is distributed in the hope that it will be useful, but WITHOUT
61.83/19.56 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
61.83/19.56 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
61.83/19.56 * version 2 for more details (a copy is included in the LICENSE file that
61.83/19.56 * accompanied this code).
61.83/19.56 *
61.83/19.56 * You should have received a copy of the GNU General Public License version
61.83/19.56 * 2 along with this work; if not, write to the Free Software Foundation,
61.83/19.56 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
61.83/19.56 *
61.83/19.56 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
61.83/19.56 * CA 95054 USA or visit www.sun.com if you need additional information or
61.83/19.56 * have any questions.
61.83/19.56 */
61.83/19.56
61.83/19.56 package javaUtilEx;
61.83/19.56
61.83/19.56 /**
61.83/19.56 * This class provides a skeletal implementation of the Collection
61.83/19.56 * interface, to minimize the effort required to implement this interface.
61.83/19.56 *
61.83/19.56 * To implement an unmodifiable collection, the programmer needs only to
61.83/19.56 * extend this class and provide implementations for the iterator and
61.83/19.56 * size methods. (The iterator returned by the iterator
61.83/19.56 * method must implement hasNext and next.)
61.83/19.56 *
61.83/19.56 * To implement a modifiable collection, the programmer must additionally
61.83/19.56 * override this class's add method (which otherwise throws an
61.83/19.56 * UnsupportedOperationException), and the iterator returned by the
61.83/19.56 * iterator method must additionally implement its remove
61.83/19.56 * method.
61.83/19.56 *
61.83/19.56 * The programmer should generally provide a void (no argument) and
61.83/19.56 * Collection constructor, as per the recommendation in the
61.83/19.56 * Collection interface specification.
61.83/19.56 *
61.83/19.56 * The documentation for each non-abstract method in this class describes its
61.83/19.56 * implementation in detail. Each of these methods may be overridden if
61.83/19.56 * the collection being implemented admits a more efficient implementation.
61.83/19.56 *
61.83/19.56 * This class is a member of the
61.83/19.56 *
61.83/19.56 * Java Collections Framework.
61.83/19.56 *
61.83/19.56 * @author Josh Bloch
61.83/19.56 * @author Neal Gafter
61.83/19.56 * @see Collection
61.83/19.56 * @since 1.2
61.83/19.56 */
61.83/19.56
61.83/19.56 public abstract class AbstractCollection implements Collection {
61.83/19.56 /**
61.83/19.56 * Sole constructor. (For invocation by subclass constructors, typically
61.83/19.56 * implicit.)
61.83/19.56 */
61.83/19.56 protected AbstractCollection() {
61.83/19.56 }
61.83/19.56
61.83/19.56 // Query Operations
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Returns an iterator over the elements contained in this collection.
61.83/19.56 *
61.83/19.56 * @return an iterator over the elements contained in this collection
61.83/19.56 */
61.83/19.56 public abstract Iterator iterator();
61.83/19.56
61.83/19.56 public abstract int size();
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation returns size() == 0.
61.83/19.56 */
61.83/19.56 public boolean isEmpty() {
61.83/19.56 return size() == 0;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation iterates over the elements in the collection,
61.83/19.56 * checking each element in turn for equality with the specified element.
61.83/19.56 *
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public boolean contains(Object o) {
61.83/19.56 Iterator e = iterator();
61.83/19.56 if (o==null) {
61.83/19.56 while (e.hasNext())
61.83/19.56 if (e.next()==null)
61.83/19.56 return true;
61.83/19.56 } else {
61.83/19.56 while (e.hasNext())
61.83/19.56 if (o.equals(e.next()))
61.83/19.56 return true;
61.83/19.56 }
61.83/19.56 return false;
61.83/19.56 }
61.83/19.56
61.83/19.56 // Modification Operations
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation always throws an
61.83/19.56 * UnsupportedOperationException.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.56 * @throws IllegalStateException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public boolean add(E e) {
61.83/19.56 throw new UnsupportedOperationException();
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation iterates over the collection looking for the
61.83/19.56 * specified element. If it finds the element, it removes the element
61.83/19.56 * from the collection using the iterator's remove method.
61.83/19.56 *
61.83/19.56 *
Note that this implementation throws an
61.83/19.56 * UnsupportedOperationException if the iterator returned by this
61.83/19.56 * collection's iterator method does not implement the remove
61.83/19.56 * method and this collection contains the specified object.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public boolean remove(Object o) {
61.83/19.56 Iterator e = iterator();
61.83/19.56 if (o==null) {
61.83/19.56 while (e.hasNext()) {
61.83/19.56 if (e.next()==null) {
61.83/19.56 e.remove();
61.83/19.56 return true;
61.83/19.56 }
61.83/19.56 }
61.83/19.56 } else {
61.83/19.56 while (e.hasNext()) {
61.83/19.56 if (o.equals(e.next())) {
61.83/19.56 e.remove();
61.83/19.56 return true;
61.83/19.56 }
61.83/19.56 }
61.83/19.56 }
61.83/19.56 return false;
61.83/19.56 }
61.83/19.56
61.83/19.56
61.83/19.56 // Bulk Operations
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation iterates over the specified collection,
61.83/19.56 * checking each element returned by the iterator in turn to see
61.83/19.56 * if it's contained in this collection. If all elements are so
61.83/19.56 * contained true is returned, otherwise false.
61.83/19.56 *
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 * @see #contains(Object)
61.83/19.56 */
61.83/19.56 public boolean containsAll(Collection c) {
61.83/19.56 Iterator e = c.iterator();
61.83/19.56 while (e.hasNext())
61.83/19.56 if (!contains(e.next()))
61.83/19.56 return false;
61.83/19.56 return true;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation iterates over the specified collection, and adds
61.83/19.56 * each object returned by the iterator to this collection, in turn.
61.83/19.56 *
61.83/19.56 *
Note that this implementation will throw an
61.83/19.56 * UnsupportedOperationException unless add is
61.83/19.56 * overridden (assuming the specified collection is non-empty).
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.56 * @throws IllegalStateException {@inheritDoc}
61.83/19.56 *
61.83/19.56 * @see #add(Object)
61.83/19.56 */
61.83/19.56 public boolean addAll(Collection c) {
61.83/19.56 boolean modified = false;
61.83/19.56 Iterator e = c.iterator();
61.83/19.56 while (e.hasNext()) {
61.83/19.56 if (add(e.next()))
61.83/19.56 modified = true;
61.83/19.56 }
61.83/19.56 return modified;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation iterates over this collection, checking each
61.83/19.56 * element returned by the iterator in turn to see if it's contained
61.83/19.56 * in the specified collection. If it's so contained, it's removed from
61.83/19.56 * this collection with the iterator's remove method.
61.83/19.56 *
61.83/19.56 *
Note that this implementation will throw an
61.83/19.56 * UnsupportedOperationException if the iterator returned by the
61.83/19.56 * iterator method does not implement the remove method
61.83/19.56 * and this collection contains one or more elements in common with the
61.83/19.56 * specified collection.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 *
61.83/19.56 * @see #remove(Object)
61.83/19.56 * @see #contains(Object)
61.83/19.56 */
61.83/19.56 public boolean removeAll(Collection c) {
61.83/19.56 boolean modified = false;
61.83/19.56 Iterator e = iterator();
61.83/19.56 while (e.hasNext()) {
61.83/19.56 if (c.contains(e.next())) {
61.83/19.56 e.remove();
61.83/19.56 modified = true;
61.83/19.56 }
61.83/19.56 }
61.83/19.56 return modified;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation iterates over this collection, checking each
61.83/19.56 * element returned by the iterator in turn to see if it's contained
61.83/19.56 * in the specified collection. If it's not so contained, it's removed
61.83/19.56 * from this collection with the iterator's remove method.
61.83/19.56 *
61.83/19.56 *
Note that this implementation will throw an
61.83/19.56 * UnsupportedOperationException if the iterator returned by the
61.83/19.56 * iterator method does not implement the remove method
61.83/19.56 * and this collection contains one or more elements not present in the
61.83/19.56 * specified collection.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 *
61.83/19.56 * @see #remove(Object)
61.83/19.56 * @see #contains(Object)
61.83/19.56 */
61.83/19.56 public boolean retainAll(Collection c) {
61.83/19.56 boolean modified = false;
61.83/19.56 Iterator e = iterator();
61.83/19.56 while (e.hasNext()) {
61.83/19.56 if (!c.contains(e.next())) {
61.83/19.56 e.remove();
61.83/19.56 modified = true;
61.83/19.56 }
61.83/19.56 }
61.83/19.56 return modified;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation iterates over this collection, removing each
61.83/19.56 * element using the Iterator.remove operation. Most
61.83/19.56 * implementations will probably choose to override this method for
61.83/19.56 * efficiency.
61.83/19.56 *
61.83/19.56 *
Note that this implementation will throw an
61.83/19.56 * UnsupportedOperationException if the iterator returned by this
61.83/19.56 * collection's iterator method does not implement the
61.83/19.56 * remove method and this collection is non-empty.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public void clear() {
61.83/19.56 Iterator e = iterator();
61.83/19.56 while (e.hasNext()) {
61.83/19.56 e.next();
61.83/19.56 e.remove();
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56
61.83/19.56 // String conversion
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Returns a string representation of this collection. The string
61.83/19.56 * representation consists of a list of the collection's elements in the
61.83/19.56 * order they are returned by its iterator, enclosed in square brackets
61.83/19.56 * ("[]"). Adjacent elements are separated by the characters
61.83/19.56 * ", " (comma and space). Elements are converted to strings as
61.83/19.56 * by {@link String#valueOf(Object)}.
61.83/19.56 *
61.83/19.56 * @return a string representation of this collection
61.83/19.56 */
61.83/19.56 public String toString() {
61.83/19.56 Iterator i = iterator();
61.83/19.56 if (! i.hasNext())
61.83/19.56 return "[]";
61.83/19.56
61.83/19.56 String sb = "";
61.83/19.56 sb = sb + "[";
61.83/19.56 for (;;) {
61.83/19.56 E e = i.next();
61.83/19.56 sb = sb + (e == this ? "(this Collection)" : e);
61.83/19.56 if (! i.hasNext()) {
61.83/19.56 sb = sb + "]";
61.83/19.56 return sb;
61.83/19.56 }
61.83/19.56 sb = sb + ", ";
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 }
61.83/19.56
61.83/19.56
61.83/19.56 /*
61.83/19.56 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
61.83/19.56 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
61.83/19.56 *
61.83/19.56 * This code is free software; you can redistribute it and/or modify it
61.83/19.56 * under the terms of the GNU General Public License version 2 only, as
61.83/19.56 * published by the Free Software Foundation. Sun designates this
61.83/19.56 * particular file as subject to the "Classpath" exception as provided
61.83/19.56 * by Sun in the LICENSE file that accompanied this code.
61.83/19.56 *
61.83/19.56 * This code is distributed in the hope that it will be useful, but WITHOUT
61.83/19.56 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
61.83/19.56 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
61.83/19.56 * version 2 for more details (a copy is included in the LICENSE file that
61.83/19.56 * accompanied this code).
61.83/19.56 *
61.83/19.56 * You should have received a copy of the GNU General Public License version
61.83/19.56 * 2 along with this work; if not, write to the Free Software Foundation,
61.83/19.56 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
61.83/19.56 *
61.83/19.56 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
61.83/19.56 * CA 95054 USA or visit www.sun.com if you need additional information or
61.83/19.56 * have any questions.
61.83/19.56 */
61.83/19.56
61.83/19.56 package javaUtilEx;
61.83/19.56
61.83/19.56 /**
61.83/19.56 * This class provides a skeletal implementation of the {@link List}
61.83/19.56 * interface to minimize the effort required to implement this interface
61.83/19.56 * backed by a "random access" data store (such as an array). For sequential
61.83/19.56 * access data (such as a linked list), {@link AbstractSequentialList} should
61.83/19.56 * be used in preference to this class.
61.83/19.56 *
61.83/19.56 * To implement an unmodifiable list, the programmer needs only to extend
61.83/19.56 * this class and provide implementations for the {@link #get(int)} and
61.83/19.56 * {@link List#size() size()} methods.
61.83/19.56 *
61.83/19.56 *
To implement a modifiable list, the programmer must additionally
61.83/19.56 * override the {@link #set(int, Object) set(int, E)} method (which otherwise
61.83/19.56 * throws an {@code UnsupportedOperationException}). If the list is
61.83/19.56 * variable-size the programmer must additionally override the
61.83/19.56 * {@link #add(int, Object) add(int, E)} and {@link #remove(int)} methods.
61.83/19.56 *
61.83/19.56 *
The programmer should generally provide a void (no argument) and collection
61.83/19.56 * constructor, as per the recommendation in the {@link Collection} interface
61.83/19.56 * specification.
61.83/19.56 *
61.83/19.56 *
Unlike the other abstract collection implementations, the programmer does
61.83/19.56 * not have to provide an iterator implementation; the iterator and
61.83/19.56 * list iterator are implemented by this class, on top of the "random access"
61.83/19.56 * methods:
61.83/19.56 * {@link #get(int)},
61.83/19.56 * {@link #set(int, Object) set(int, E)},
61.83/19.56 * {@link #add(int, Object) add(int, E)} and
61.83/19.56 * {@link #remove(int)}.
61.83/19.56 *
61.83/19.56 *
The documentation for each non-abstract method in this class describes its
61.83/19.56 * implementation in detail. Each of these methods may be overridden if the
61.83/19.56 * collection being implemented admits a more efficient implementation.
61.83/19.56 *
61.83/19.56 *
This class is a member of the
61.83/19.56 *
61.83/19.56 * Java Collections Framework.
61.83/19.56 *
61.83/19.56 * @author Josh Bloch
61.83/19.56 * @author Neal Gafter
61.83/19.56 * @since 1.2
61.83/19.56 */
61.83/19.56
61.83/19.56 public abstract class AbstractList extends AbstractCollection implements List {
61.83/19.56 /**
61.83/19.56 * Sole constructor. (For invocation by subclass constructors, typically
61.83/19.56 * implicit.)
61.83/19.56 */
61.83/19.56 protected AbstractList() {
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Appends the specified element to the end of this list (optional
61.83/19.56 * operation).
61.83/19.56 *
61.83/19.56 * Lists that support this operation may place limitations on what
61.83/19.56 * elements may be added to this list. In particular, some
61.83/19.56 * lists will refuse to add null elements, and others will impose
61.83/19.56 * restrictions on the type of elements that may be added. List
61.83/19.56 * classes should clearly specify in their documentation any restrictions
61.83/19.56 * on what elements may be added.
61.83/19.56 *
61.83/19.56 *
This implementation calls {@code add(size(), e)}.
61.83/19.56 *
61.83/19.56 *
Note that this implementation throws an
61.83/19.56 * {@code UnsupportedOperationException} unless
61.83/19.56 * {@link #add(int, Object) add(int, E)} is overridden.
61.83/19.56 *
61.83/19.56 * @param e element to be appended to this list
61.83/19.56 * @return {@code true} (as specified by {@link Collection#add})
61.83/19.56 * @throws UnsupportedOperationException if the {@code add} operation
61.83/19.56 * is not supported by this list
61.83/19.56 * @throws ClassCastException if the class of the specified element
61.83/19.56 * prevents it from being added to this list
61.83/19.56 * @throws NullPointerException if the specified element is null and this
61.83/19.56 * list does not permit null elements
61.83/19.56 * @throws IllegalArgumentException if some property of this element
61.83/19.56 * prevents it from being added to this list
61.83/19.56 */
61.83/19.56 public boolean add(E e) {
61.83/19.56 add(size(), e);
61.83/19.56 return true;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.56 */
61.83/19.56 abstract public E get(int index);
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation always throws an
61.83/19.56 * {@code UnsupportedOperationException}.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.56 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public E set(int index, E element) {
61.83/19.56 throw new UnsupportedOperationException();
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation always throws an
61.83/19.56 * {@code UnsupportedOperationException}.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.56 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public void add(int index, E element) {
61.83/19.56 throw new UnsupportedOperationException();
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation always throws an
61.83/19.56 * {@code UnsupportedOperationException}.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public E remove(int index) {
61.83/19.56 throw new UnsupportedOperationException();
61.83/19.56 }
61.83/19.56
61.83/19.56
61.83/19.56 // Search Operations
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation first gets a list iterator (with
61.83/19.56 * {@code listIterator()}). Then, it iterates over the list until the
61.83/19.56 * specified element is found or the end of the list is reached.
61.83/19.56 *
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public int indexOf(Object o) {
61.83/19.56 ListIterator e = listIterator();
61.83/19.56 if (o==null) {
61.83/19.56 while (e.hasNext())
61.83/19.56 if (e.next()==null)
61.83/19.56 return e.previousIndex();
61.83/19.56 } else {
61.83/19.56 while (e.hasNext())
61.83/19.56 if (o.equals(e.next()))
61.83/19.56 return e.previousIndex();
61.83/19.56 }
61.83/19.56 return -1;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation first gets a list iterator that points to the end
61.83/19.56 * of the list (with {@code listIterator(size())}). Then, it iterates
61.83/19.56 * backwards over the list until the specified element is found, or the
61.83/19.56 * beginning of the list is reached.
61.83/19.56 *
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public int lastIndexOf(Object o) {
61.83/19.56 ListIterator e = listIterator(size());
61.83/19.56 if (o==null) {
61.83/19.56 while (e.hasPrevious())
61.83/19.56 if (e.previous()==null)
61.83/19.56 return e.nextIndex();
61.83/19.56 } else {
61.83/19.56 while (e.hasPrevious())
61.83/19.56 if (o.equals(e.previous()))
61.83/19.56 return e.nextIndex();
61.83/19.56 }
61.83/19.56 return -1;
61.83/19.56 }
61.83/19.56
61.83/19.56
61.83/19.56 // Bulk Operations
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Removes all of the elements from this list (optional operation).
61.83/19.56 * The list will be empty after this call returns.
61.83/19.56 *
61.83/19.56 * This implementation calls {@code removeRange(0, size())}.
61.83/19.56 *
61.83/19.56 *
Note that this implementation throws an
61.83/19.56 * {@code UnsupportedOperationException} unless {@code remove(int
61.83/19.56 * index)} or {@code removeRange(int fromIndex, int toIndex)} is
61.83/19.56 * overridden.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException if the {@code clear} operation
61.83/19.56 * is not supported by this list
61.83/19.56 */
61.83/19.56 public void clear() {
61.83/19.56 removeRange(0, size());
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 *
This implementation gets an iterator over the specified collection
61.83/19.56 * and iterates over it, inserting the elements obtained from the
61.83/19.56 * iterator into this list at the appropriate position, one at a time,
61.83/19.56 * using {@code add(int, E)}.
61.83/19.56 * Many implementations will override this method for efficiency.
61.83/19.56 *
61.83/19.56 *
Note that this implementation throws an
61.83/19.56 * {@code UnsupportedOperationException} unless
61.83/19.56 * {@link #add(int, Object) add(int, E)} is overridden.
61.83/19.56 *
61.83/19.56 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.56 * @throws ClassCastException {@inheritDoc}
61.83/19.56 * @throws NullPointerException {@inheritDoc}
61.83/19.56 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.56 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public boolean addAll(int index, Collection c) {
61.83/19.56 rangeCheckForAdd(index);
61.83/19.56 boolean modified = false;
61.83/19.56 Iterator e = c.iterator();
61.83/19.56 while (e.hasNext()) {
61.83/19.56 add(index++, e.next());
61.83/19.56 modified = true;
61.83/19.56 }
61.83/19.56 return modified;
61.83/19.56 }
61.83/19.56
61.83/19.56
61.83/19.56 // Iterators
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Returns an iterator over the elements in this list in proper sequence.
61.83/19.56 *
61.83/19.56 *
This implementation returns a straightforward implementation of the
61.83/19.56 * iterator interface, relying on the backing list's {@code size()},
61.83/19.56 * {@code get(int)}, and {@code remove(int)} methods.
61.83/19.56 *
61.83/19.56 *
Note that the iterator returned by this method will throw an
61.83/19.56 * {@link UnsupportedOperationException} in response to its
61.83/19.56 * {@code remove} method unless the list's {@code remove(int)} method is
61.83/19.56 * overridden.
61.83/19.56 *
61.83/19.56 *
This implementation can be made to throw runtime exceptions in the
61.83/19.56 * face of concurrent modification, as described in the specification
61.83/19.56 * for the (protected) {@link #modCount} field.
61.83/19.56 *
61.83/19.56 * @return an iterator over the elements in this list in proper sequence
61.83/19.56 */
61.83/19.56 public Iterator iterator() {
61.83/19.56 return new Itr();
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation returns {@code listIterator(0)}.
61.83/19.56 *
61.83/19.56 * @see #listIterator(int)
61.83/19.56 */
61.83/19.56 public ListIterator listIterator() {
61.83/19.56 return listIterator(0);
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation returns a straightforward implementation of the
61.83/19.56 * {@code ListIterator} interface that extends the implementation of the
61.83/19.56 * {@code Iterator} interface returned by the {@code iterator()} method.
61.83/19.56 * The {@code ListIterator} implementation relies on the backing list's
61.83/19.56 * {@code get(int)}, {@code set(int, E)}, {@code add(int, E)}
61.83/19.56 * and {@code remove(int)} methods.
61.83/19.56 *
61.83/19.56 *
Note that the list iterator returned by this implementation will
61.83/19.56 * throw an {@link UnsupportedOperationException} in response to its
61.83/19.56 * {@code remove}, {@code set} and {@code add} methods unless the
61.83/19.56 * list's {@code remove(int)}, {@code set(int, E)}, and
61.83/19.56 * {@code add(int, E)} methods are overridden.
61.83/19.56 *
61.83/19.56 *
This implementation can be made to throw runtime exceptions in the
61.83/19.56 * face of concurrent modification, as described in the specification for
61.83/19.56 * the (protected) {@link #modCount} field.
61.83/19.56 *
61.83/19.56 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.56 */
61.83/19.56 public ListIterator listIterator(final int index) {
61.83/19.56 rangeCheckForAdd(index);
61.83/19.56
61.83/19.56 return new ListItr(index);
61.83/19.56 }
61.83/19.56
61.83/19.56 private class Itr implements Iterator {
61.83/19.56 /**
61.83/19.56 * Index of element to be returned by subsequent call to next.
61.83/19.56 */
61.83/19.56 int cursor = 0;
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Index of element returned by most recent call to next or
61.83/19.56 * previous. Reset to -1 if this element is deleted by a call
61.83/19.56 * to remove.
61.83/19.56 */
61.83/19.56 int lastRet = -1;
61.83/19.56
61.83/19.56 /**
61.83/19.56 * The modCount value that the iterator believes that the backing
61.83/19.56 * List should have. If this expectation is violated, the iterator
61.83/19.56 * has detected concurrent modification.
61.83/19.56 */
61.83/19.56 int expectedModCount = modCount;
61.83/19.56
61.83/19.56 public boolean hasNext() {
61.83/19.56 return cursor != size();
61.83/19.56 }
61.83/19.56
61.83/19.56 public E next() {
61.83/19.56 checkForComodification();
61.83/19.56 try {
61.83/19.56 int i = cursor;
61.83/19.56 E next = get(i);
61.83/19.56 lastRet = i;
61.83/19.56 cursor = i + 1;
61.83/19.56 return next;
61.83/19.56 } catch (IndexOutOfBoundsException e) {
61.83/19.56 checkForComodification();
61.83/19.56 throw new NoSuchElementException();
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 public void remove() {
61.83/19.56 if (lastRet < 0)
61.83/19.56 throw new IllegalStateException();
61.83/19.56 checkForComodification();
61.83/19.56
61.83/19.56 try {
61.83/19.56 AbstractList.this.remove(lastRet);
61.83/19.56 if (lastRet < cursor)
61.83/19.56 cursor--;
61.83/19.56 lastRet = -1;
61.83/19.56 expectedModCount = modCount;
61.83/19.56 } catch (IndexOutOfBoundsException e) {
61.83/19.56 throw new ConcurrentModificationException();
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 final void checkForComodification() {
61.83/19.56 if (modCount != expectedModCount)
61.83/19.56 throw new ConcurrentModificationException();
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 private class ListItr extends Itr implements ListIterator {
61.83/19.56 ListItr(int index) {
61.83/19.56 cursor = index;
61.83/19.56 }
61.83/19.56
61.83/19.56 public boolean hasPrevious() {
61.83/19.56 return cursor != 0;
61.83/19.56 }
61.83/19.56
61.83/19.56 public E previous() {
61.83/19.56 checkForComodification();
61.83/19.56 try {
61.83/19.56 int i = cursor - 1;
61.83/19.56 E previous = get(i);
61.83/19.56 lastRet = cursor = i;
61.83/19.56 return previous;
61.83/19.56 } catch (IndexOutOfBoundsException e) {
61.83/19.56 checkForComodification();
61.83/19.56 throw new NoSuchElementException();
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 public int nextIndex() {
61.83/19.56 return cursor;
61.83/19.56 }
61.83/19.56
61.83/19.56 public int previousIndex() {
61.83/19.56 return cursor-1;
61.83/19.56 }
61.83/19.56
61.83/19.56 public void set(E e) {
61.83/19.56 if (lastRet < 0)
61.83/19.56 throw new IllegalStateException();
61.83/19.56 checkForComodification();
61.83/19.56
61.83/19.56 try {
61.83/19.56 AbstractList.this.set(lastRet, e);
61.83/19.56 expectedModCount = modCount;
61.83/19.56 } catch (IndexOutOfBoundsException ex) {
61.83/19.56 throw new ConcurrentModificationException();
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 public void add(E e) {
61.83/19.56 checkForComodification();
61.83/19.56
61.83/19.56 try {
61.83/19.56 int i = cursor;
61.83/19.56 AbstractList.this.add(i, e);
61.83/19.56 lastRet = -1;
61.83/19.56 cursor = i + 1;
61.83/19.56 expectedModCount = modCount;
61.83/19.56 } catch (IndexOutOfBoundsException ex) {
61.83/19.56 throw new ConcurrentModificationException();
61.83/19.56 }
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * {@inheritDoc}
61.83/19.56 *
61.83/19.56 * This implementation returns a list that subclasses
61.83/19.56 * {@code AbstractList}. The subclass stores, in private fields, the
61.83/19.56 * offset of the subList within the backing list, the size of the subList
61.83/19.56 * (which can change over its lifetime), and the expected
61.83/19.56 * {@code modCount} value of the backing list. There are two variants
61.83/19.56 * of the subclass, one of which implements {@code RandomAccess}.
61.83/19.56 * If this list implements {@code RandomAccess} the returned list will
61.83/19.56 * be an instance of the subclass that implements {@code RandomAccess}.
61.83/19.56 *
61.83/19.56 *
The subclass's {@code set(int, E)}, {@code get(int)},
61.83/19.56 * {@code add(int, E)}, {@code remove(int)}, {@code addAll(int,
61.83/19.56 * Collection)} and {@code removeRange(int, int)} methods all
61.83/19.56 * delegate to the corresponding methods on the backing abstract list,
61.83/19.56 * after bounds-checking the index and adjusting for the offset. The
61.83/19.56 * {@code addAll(Collection c)} method merely returns {@code addAll(size,
61.83/19.56 * c)}.
61.83/19.56 *
61.83/19.56 *
The {@code listIterator(int)} method returns a "wrapper object"
61.83/19.56 * over a list iterator on the backing list, which is created with the
61.83/19.56 * corresponding method on the backing list. The {@code iterator} method
61.83/19.56 * merely returns {@code listIterator()}, and the {@code size} method
61.83/19.56 * merely returns the subclass's {@code size} field.
61.83/19.56 *
61.83/19.56 *
All methods first check to see if the actual {@code modCount} of
61.83/19.56 * the backing list is equal to its expected value, and throw a
61.83/19.56 * {@code ConcurrentModificationException} if it is not.
61.83/19.56 *
61.83/19.56 * @throws IndexOutOfBoundsException if an endpoint index value is out of range
61.83/19.56 * {@code (fromIndex < 0 || toIndex > size)}
61.83/19.56 * @throws IllegalArgumentException if the endpoint indices are out of order
61.83/19.56 * {@code (fromIndex > toIndex)}
61.83/19.56 */
61.83/19.56 public List subList(int fromIndex, int toIndex) {
61.83/19.56 return (this instanceof RandomAccess ?
61.83/19.56 new RandomAccessSubList(this, fromIndex, toIndex) :
61.83/19.56 new SubList(this, fromIndex, toIndex));
61.83/19.56 }
61.83/19.56
61.83/19.56 // Comparison and hashing
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Compares the specified object with this list for equality. Returns
61.83/19.56 * {@code true} if and only if the specified object is also a list, both
61.83/19.56 * lists have the same size, and all corresponding pairs of elements in
61.83/19.56 * the two lists are equal. (Two elements {@code e1} and
61.83/19.56 * {@code e2} are equal if {@code (e1==null ? e2==null :
61.83/19.56 * e1.equals(e2))}.) In other words, two lists are defined to be
61.83/19.56 * equal if they contain the same elements in the same order.
61.83/19.56 *
61.83/19.56 * This implementation first checks if the specified object is this
61.83/19.56 * list. If so, it returns {@code true}; if not, it checks if the
61.83/19.56 * specified object is a list. If not, it returns {@code false}; if so,
61.83/19.56 * it iterates over both lists, comparing corresponding pairs of elements.
61.83/19.56 * If any comparison returns {@code false}, this method returns
61.83/19.56 * {@code false}. If either iterator runs out of elements before the
61.83/19.56 * other it returns {@code false} (as the lists are of unequal length);
61.83/19.56 * otherwise it returns {@code true} when the iterations complete.
61.83/19.56 *
61.83/19.56 * @param o the object to be compared for equality with this list
61.83/19.56 * @return {@code true} if the specified object is equal to this list
61.83/19.56 */
61.83/19.56 public boolean equals(Object o) {
61.83/19.56 if (o == this)
61.83/19.56 return true;
61.83/19.56 if (!(o instanceof List))
61.83/19.56 return false;
61.83/19.56
61.83/19.56 ListIterator e1 = listIterator();
61.83/19.56 ListIterator e2 = ((List) o).listIterator();
61.83/19.56 while(e1.hasNext() && e2.hasNext()) {
61.83/19.56 E o1 = e1.next();
61.83/19.56 Object o2 = e2.next();
61.83/19.56 if (!(o1==null ? o2==null : o1.equals(o2)))
61.83/19.56 return false;
61.83/19.56 }
61.83/19.56 return !(e1.hasNext() || e2.hasNext());
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Returns the hash code value for this list.
61.83/19.56 *
61.83/19.56 * This implementation uses exactly the code that is used to define the
61.83/19.56 * list hash function in the documentation for the {@link List#hashCode}
61.83/19.56 * method.
61.83/19.56 *
61.83/19.56 * @return the hash code value for this list
61.83/19.56 */
61.83/19.56 public int hashCode() {
61.83/19.56 int hashCode = 1;
61.83/19.56 Iterator it = this.iterator();
61.83/19.56 while (it.hasNext()) {
61.83/19.56 E e = it.next();
61.83/19.56 hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
61.83/19.56 }
61.83/19.56 return hashCode;
61.83/19.56 }
61.83/19.56
61.83/19.56 /**
61.83/19.56 * Removes from this list all of the elements whose index is between
61.83/19.56 * {@code fromIndex}, inclusive, and {@code toIndex}, exclusive.
61.83/19.56 * Shifts any succeeding elements to the left (reduces their index).
61.83/19.56 * This call shortens the list by {@code (toIndex - fromIndex)} elements.
61.83/19.56 * (If {@code toIndex==fromIndex}, this operation has no effect.)
61.83/19.56 *
61.83/19.56 * This method is called by the {@code clear} operation on this list
61.83/19.56 * and its subLists. Overriding this method to take advantage of
61.83/19.56 * the internals of the list implementation can substantially
61.83/19.56 * improve the performance of the {@code clear} operation on this list
61.83/19.56 * and its subLists.
61.83/19.56 *
61.83/19.56 *
This implementation gets a list iterator positioned before
61.83/19.56 * {@code fromIndex}, and repeatedly calls {@code ListIterator.next}
61.83/19.56 * followed by {@code ListIterator.remove} until the entire range has
61.83/19.56 * been removed. Note: if {@code ListIterator.remove} requires linear
61.83/19.56 * time, this implementation requires quadratic time.
61.83/19.56 *
61.83/19.56 * @param fromIndex index of first element to be removed
61.83/19.56 * @param toIndex index after last element to be removed
61.83/19.56 */
61.83/19.56 protected void removeRange(int fromIndex, int toIndex) {
61.83/19.56 ListIterator it = listIterator(fromIndex);
61.83/19.56 for (int i=0, n=toIndex-fromIndex; istructurally modified.
61.83/19.56 * Structural modifications are those that change the size of the
61.83/19.56 * list, or otherwise perturb it in such a fashion that iterations in
61.83/19.56 * progress may yield incorrect results.
61.83/19.56 *
61.83/19.56 * This field is used by the iterator and list iterator implementation
61.83/19.56 * returned by the {@code iterator} and {@code listIterator} methods.
61.83/19.56 * If the value of this field changes unexpectedly, the iterator (or list
61.83/19.56 * iterator) will throw a {@code ConcurrentModificationException} in
61.83/19.56 * response to the {@code next}, {@code remove}, {@code previous},
61.83/19.56 * {@code set} or {@code add} operations. This provides
61.83/19.56 * fail-fast behavior, rather than non-deterministic behavior in
61.83/19.56 * the face of concurrent modification during iteration.
61.83/19.56 *
61.83/19.56 *
Use of this field by subclasses is optional. If a subclass
61.83/19.56 * wishes to provide fail-fast iterators (and list iterators), then it
61.83/19.56 * merely has to increment this field in its {@code add(int, E)} and
61.83/19.56 * {@code remove(int)} methods (and any other methods that it overrides
61.83/19.56 * that result in structural modifications to the list). A single call to
61.83/19.56 * {@code add(int, E)} or {@code remove(int)} must add no more than
61.83/19.56 * one to this field, or the iterators (and list iterators) will throw
61.83/19.56 * bogus {@code ConcurrentModificationExceptions}. If an implementation
61.83/19.56 * does not wish to provide fail-fast iterators, this field may be
61.83/19.56 * ignored.
61.83/19.56 */
61.83/19.56 protected transient int modCount = 0;
61.83/19.56
61.83/19.56 private void rangeCheckForAdd(int index) {
61.83/19.56 if (index < 0 || index > size())
61.83/19.56 throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
61.83/19.56 }
61.83/19.56
61.83/19.56 private String outOfBoundsMsg(int index) {
61.83/19.56 return "";
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 class SubList extends AbstractList {
61.83/19.56 private final AbstractList l;
61.83/19.56 private final int offset;
61.83/19.56 private int size;
61.83/19.56
61.83/19.56 SubList(AbstractList list, int fromIndex, int toIndex) {
61.83/19.56 if (fromIndex < 0)
61.83/19.56 throw new IndexOutOfBoundsException();
61.83/19.56 if (toIndex > list.size())
61.83/19.56 throw new IndexOutOfBoundsException();
61.83/19.56 if (fromIndex > toIndex)
61.83/19.56 throw new IllegalArgumentException();
61.83/19.56 l = list;
61.83/19.56 offset = fromIndex;
61.83/19.56 size = toIndex - fromIndex;
61.83/19.56 this.modCount = l.modCount;
61.83/19.56 }
61.83/19.56
61.83/19.56 public E set(int index, E element) {
61.83/19.56 rangeCheck(index);
61.83/19.56 checkForComodification();
61.83/19.56 return l.set(index+offset, element);
61.83/19.56 }
61.83/19.56
61.83/19.56 public E get(int index) {
61.83/19.56 rangeCheck(index);
61.83/19.56 checkForComodification();
61.83/19.56 return l.get(index+offset);
61.83/19.56 }
61.83/19.56
61.83/19.56 public int size() {
61.83/19.56 checkForComodification();
61.83/19.56 return size;
61.83/19.56 }
61.83/19.56
61.83/19.56 public void add(int index, E element) {
61.83/19.56 rangeCheckForAdd(index);
61.83/19.56 checkForComodification();
61.83/19.56 l.add(index+offset, element);
61.83/19.56 this.modCount = l.modCount;
61.83/19.56 size++;
61.83/19.56 }
61.83/19.56
61.83/19.56 public E remove(int index) {
61.83/19.56 rangeCheck(index);
61.83/19.56 checkForComodification();
61.83/19.56 E result = l.remove(index+offset);
61.83/19.56 this.modCount = l.modCount;
61.83/19.56 size--;
61.83/19.56 return result;
61.83/19.56 }
61.83/19.56
61.83/19.56 protected void removeRange(int fromIndex, int toIndex) {
61.83/19.56 checkForComodification();
61.83/19.56 l.removeRange(fromIndex+offset, toIndex+offset);
61.83/19.56 this.modCount = l.modCount;
61.83/19.56 size -= (toIndex-fromIndex);
61.83/19.56 }
61.83/19.56
61.83/19.56 public boolean addAll(Collection c) {
61.83/19.56 return addAll(size, c);
61.83/19.56 }
61.83/19.56
61.83/19.56 public boolean addAll(int index, Collection c) {
61.83/19.56 rangeCheckForAdd(index);
61.83/19.56 int cSize = c.size();
61.83/19.56 if (cSize==0)
61.83/19.56 return false;
61.83/19.56
61.83/19.56 checkForComodification();
61.83/19.56 l.addAll(offset+index, c);
61.83/19.56 this.modCount = l.modCount;
61.83/19.56 size += cSize;
61.83/19.56 return true;
61.83/19.56 }
61.83/19.56
61.83/19.56 public Iterator iterator() {
61.83/19.56 return listIterator();
61.83/19.56 }
61.83/19.56
61.83/19.56 public ListIterator listIterator(final int index) {
61.83/19.56 checkForComodification();
61.83/19.56 rangeCheckForAdd(index);
61.83/19.56
61.83/19.56 return new ListIterator() {
61.83/19.56 private final ListIterator i = l.listIterator(index+offset);
61.83/19.56
61.83/19.56 public boolean hasNext() {
61.83/19.56 return nextIndex() < size;
61.83/19.56 }
61.83/19.56
61.83/19.56 public E next() {
61.83/19.56 if (hasNext())
61.83/19.56 return i.next();
61.83/19.56 else
61.83/19.56 throw new NoSuchElementException();
61.83/19.56 }
61.83/19.56
61.83/19.56 public boolean hasPrevious() {
61.83/19.56 return previousIndex() >= 0;
61.83/19.56 }
61.83/19.56
61.83/19.56 public E previous() {
61.83/19.56 if (hasPrevious())
61.83/19.56 return i.previous();
61.83/19.56 else
61.83/19.56 throw new NoSuchElementException();
61.83/19.56 }
61.83/19.56
61.83/19.56 public int nextIndex() {
61.83/19.56 return i.nextIndex() - offset;
61.83/19.56 }
61.83/19.56
61.83/19.56 public int previousIndex() {
61.83/19.56 return i.previousIndex() - offset;
61.83/19.56 }
61.83/19.56
61.83/19.56 public void remove() {
61.83/19.56 i.remove();
61.83/19.56 SubList.this.modCount = l.modCount;
61.83/19.56 size--;
61.83/19.56 }
61.83/19.56
61.83/19.56 public void set(E e) {
61.83/19.56 i.set(e);
61.83/19.56 }
61.83/19.56
61.83/19.56 public void add(E e) {
61.83/19.56 i.add(e);
61.83/19.56 SubList.this.modCount = l.modCount;
61.83/19.56 size++;
61.83/19.56 }
61.83/19.56 };
61.83/19.56 }
61.83/19.56
61.83/19.56 public List subList(int fromIndex, int toIndex) {
61.83/19.56 return new SubList(this, fromIndex, toIndex);
61.83/19.56 }
61.83/19.56
61.83/19.56 private void rangeCheck(int index) {
61.83/19.56 if (index < 0 || index >= size)
61.83/19.56 throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
61.83/19.56 }
61.83/19.56
61.83/19.56 private void rangeCheckForAdd(int index) {
61.83/19.56 if (index < 0 || index > size)
61.83/19.56 throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
61.83/19.56 }
61.83/19.56
61.83/19.56 private String outOfBoundsMsg(int index) {
61.83/19.56 return "";
61.83/19.56 }
61.83/19.56
61.83/19.56 private void checkForComodification() {
61.83/19.56 if (this.modCount != l.modCount)
61.83/19.56 throw new ConcurrentModificationException();
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56 class RandomAccessSubList extends SubList implements RandomAccess {
61.83/19.56 RandomAccessSubList(AbstractList list, int fromIndex, int toIndex) {
61.83/19.56 super(list, fromIndex, toIndex);
61.83/19.56 }
61.83/19.56
61.83/19.56 public List subList(int fromIndex, int toIndex) {
61.83/19.56 return new RandomAccessSubList(this, fromIndex, toIndex);
61.83/19.56 }
61.83/19.56 }
61.83/19.56
61.83/19.56
61.83/19.56 /*
61.83/19.56 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
61.83/19.56 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
61.83/19.56 *
61.83/19.56 * This code is free software; you can redistribute it and/or modify it
61.83/19.56 * under the terms of the GNU General Public License version 2 only, as
61.83/19.56 * published by the Free Software Foundation. Sun designates this
61.83/19.56 * particular file as subject to the "Classpath" exception as provided
61.83/19.56 * by Sun in the LICENSE file that accompanied this code.
61.83/19.56 *
61.83/19.56 * This code is distributed in the hope that it will be useful, but WITHOUT
61.83/19.56 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
61.83/19.56 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
61.83/19.56 * version 2 for more details (a copy is included in the LICENSE file that
61.83/19.56 * accompanied this code).
61.83/19.56 *
61.83/19.56 * You should have received a copy of the GNU General Public License version
61.83/19.56 * 2 along with this work; if not, write to the Free Software Foundation,
61.83/19.56 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
61.83/19.56 *
61.83/19.56 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
61.83/19.56 * CA 95054 USA or visit www.sun.com if you need additional information or
61.83/19.56 * have any questions.
61.83/19.56 */
61.83/19.56
61.83/19.56 package javaUtilEx;
61.83/19.56
61.83/19.56 /**
61.83/19.56 * This class provides a skeletal implementation of the List
61.83/19.56 * interface to minimize the effort required to implement this interface
61.83/19.56 * backed by a "sequential access" data store (such as a linked list). For
61.83/19.56 * random access data (such as an array), AbstractList should be used
61.83/19.56 * in preference to this class.
61.83/19.56 *
61.83/19.56 * This class is the opposite of the AbstractList class in the sense
61.83/19.56 * that it implements the "random access" methods (get(int index),
61.83/19.56 * set(int index, E element), add(int index, E element) and
61.83/19.56 * remove(int index)) on top of the list's list iterator, instead of
61.83/19.56 * the other way around.
61.83/19.56 *
61.83/19.56 * To implement a list the programmer needs only to extend this class and
61.83/19.56 * provide implementations for the listIterator and size
61.83/19.56 * methods. For an unmodifiable list, the programmer need only implement the
61.83/19.56 * list iterator's hasNext, next, hasPrevious,
61.83/19.57 * previous and index methods.
61.83/19.57 *
61.83/19.57 * For a modifiable list the programmer should additionally implement the list
61.83/19.57 * iterator's set method. For a variable-size list the programmer
61.83/19.57 * should additionally implement the list iterator's remove and
61.83/19.57 * add methods.
61.83/19.57 *
61.83/19.57 * The programmer should generally provide a void (no argument) and collection
61.83/19.57 * constructor, as per the recommendation in the Collection interface
61.83/19.57 * specification.
61.83/19.57 *
61.83/19.57 * This class is a member of the
61.83/19.57 *
61.83/19.57 * Java Collections Framework.
61.83/19.57 *
61.83/19.57 * @author Josh Bloch
61.83/19.57 * @author Neal Gafter
61.83/19.57 * @see Collection
61.83/19.57 * @see List
61.83/19.57 * @see AbstractList
61.83/19.57 * @see AbstractCollection
61.83/19.57 * @since 1.2
61.83/19.57 */
61.83/19.57
61.83/19.57 public abstract class AbstractSequentialList extends AbstractList {
61.83/19.57 /**
61.83/19.57 * Sole constructor. (For invocation by subclass constructors, typically
61.83/19.57 * implicit.)
61.83/19.57 */
61.83/19.57 protected AbstractSequentialList() {
61.83/19.57 }
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns the element at the specified position in this list.
61.83/19.57 *
61.83/19.57 * This implementation first gets a list iterator pointing to the
61.83/19.57 * indexed element (with listIterator(index)). Then, it gets
61.83/19.57 * the element using ListIterator.next and returns it.
61.83/19.57 *
61.83/19.57 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.57 */
61.83/19.57 public E get(int index) {
61.83/19.57 try {
61.83/19.57 return listIterator(index).next();
61.83/19.57 } catch (NoSuchElementException exc) {
61.83/19.57 throw new IndexOutOfBoundsException();
61.83/19.57 }
61.83/19.57 }
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Replaces the element at the specified position in this list with the
61.83/19.57 * specified element (optional operation).
61.83/19.57 *
61.83/19.57 *
This implementation first gets a list iterator pointing to the
61.83/19.57 * indexed element (with listIterator(index)). Then, it gets
61.83/19.57 * the current element using ListIterator.next and replaces it
61.83/19.57 * with ListIterator.set.
61.83/19.57 *
61.83/19.57 *
Note that this implementation will throw an
61.83/19.57 * UnsupportedOperationException if the list iterator does not
61.83/19.57 * implement the set operation.
61.83/19.57 *
61.83/19.57 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.57 * @throws ClassCastException {@inheritDoc}
61.83/19.57 * @throws NullPointerException {@inheritDoc}
61.83/19.57 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.57 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.57 */
61.83/19.57 public E set(int index, E element) {
61.83/19.57 try {
61.83/19.57 ListIterator e = listIterator(index);
61.83/19.57 E oldVal = e.next();
61.83/19.57 e.set(element);
61.83/19.57 return oldVal;
61.83/19.57 } catch (NoSuchElementException exc) {
61.83/19.57 throw new IndexOutOfBoundsException();
61.83/19.57 }
61.83/19.57 }
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Inserts the specified element at the specified position in this list
61.83/19.57 * (optional operation). Shifts the element currently at that position
61.83/19.57 * (if any) and any subsequent elements to the right (adds one to their
61.83/19.57 * indices).
61.83/19.57 *
61.83/19.57 * This implementation first gets a list iterator pointing to the
61.83/19.57 * indexed element (with listIterator(index)). Then, it
61.83/19.57 * inserts the specified element with ListIterator.add.
61.83/19.57 *
61.83/19.57 *
Note that this implementation will throw an
61.83/19.57 * UnsupportedOperationException if the list iterator does not
61.83/19.57 * implement the add operation.
61.83/19.57 *
61.83/19.57 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.57 * @throws ClassCastException {@inheritDoc}
61.83/19.57 * @throws NullPointerException {@inheritDoc}
61.83/19.57 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.57 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.57 */
61.83/19.57 public void add(int index, E element) {
61.83/19.57 try {
61.83/19.57 listIterator(index).add(element);
61.83/19.57 } catch (NoSuchElementException exc) {
61.83/19.57 throw new IndexOutOfBoundsException();
61.83/19.57 }
61.83/19.57 }
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Removes the element at the specified position in this list (optional
61.83/19.57 * operation). Shifts any subsequent elements to the left (subtracts one
61.83/19.57 * from their indices). Returns the element that was removed from the
61.83/19.57 * list.
61.83/19.57 *
61.83/19.57 *
This implementation first gets a list iterator pointing to the
61.83/19.57 * indexed element (with listIterator(index)). Then, it removes
61.83/19.57 * the element with ListIterator.remove.
61.83/19.57 *
61.83/19.57 *
Note that this implementation will throw an
61.83/19.57 * UnsupportedOperationException if the list iterator does not
61.83/19.57 * implement the remove operation.
61.83/19.57 *
61.83/19.57 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.57 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.57 */
61.83/19.57 public E remove(int index) {
61.83/19.57 try {
61.83/19.57 ListIterator e = listIterator(index);
61.83/19.57 E outCast = e.next();
61.83/19.57 e.remove();
61.83/19.57 return outCast;
61.83/19.57 } catch (NoSuchElementException exc) {
61.83/19.57 throw new IndexOutOfBoundsException();
61.83/19.57 }
61.83/19.57 }
61.83/19.57
61.83/19.57
61.83/19.57 // Bulk Operations
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Inserts all of the elements in the specified collection into this
61.83/19.57 * list at the specified position (optional operation). Shifts the
61.83/19.57 * element currently at that position (if any) and any subsequent
61.83/19.57 * elements to the right (increases their indices). The new elements
61.83/19.57 * will appear in this list in the order that they are returned by the
61.83/19.57 * specified collection's iterator. The behavior of this operation is
61.83/19.57 * undefined if the specified collection is modified while the
61.83/19.57 * operation is in progress. (Note that this will occur if the specified
61.83/19.57 * collection is this list, and it's nonempty.)
61.83/19.57 *
61.83/19.57 * This implementation gets an iterator over the specified collection and
61.83/19.57 * a list iterator over this list pointing to the indexed element (with
61.83/19.57 * listIterator(index)). Then, it iterates over the specified
61.83/19.57 * collection, inserting the elements obtained from the iterator into this
61.83/19.57 * list, one at a time, using ListIterator.add followed by
61.83/19.57 * ListIterator.next (to skip over the added element).
61.83/19.57 *
61.83/19.57 *
Note that this implementation will throw an
61.83/19.57 * UnsupportedOperationException if the list iterator returned by
61.83/19.57 * the listIterator method does not implement the add
61.83/19.57 * operation.
61.83/19.57 *
61.83/19.57 * @throws UnsupportedOperationException {@inheritDoc}
61.83/19.57 * @throws ClassCastException {@inheritDoc}
61.83/19.57 * @throws NullPointerException {@inheritDoc}
61.83/19.57 * @throws IllegalArgumentException {@inheritDoc}
61.83/19.57 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.57 */
61.83/19.57 public boolean addAll(int index, Collection c) {
61.83/19.57 try {
61.83/19.57 boolean modified = false;
61.83/19.57 ListIterator e1 = listIterator(index);
61.83/19.57 Iterator e2 = c.iterator();
61.83/19.57 while (e2.hasNext()) {
61.83/19.57 e1.add(e2.next());
61.83/19.57 modified = true;
61.83/19.57 }
61.83/19.57 return modified;
61.83/19.57 } catch (NoSuchElementException exc) {
61.83/19.57 throw new IndexOutOfBoundsException();
61.83/19.57 }
61.83/19.57 }
61.83/19.57
61.83/19.57
61.83/19.57 // Iterators
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns an iterator over the elements in this list (in proper
61.83/19.57 * sequence).
61.83/19.57 *
61.83/19.57 * This implementation merely returns a list iterator over the list.
61.83/19.57 *
61.83/19.57 * @return an iterator over the elements in this list (in proper sequence)
61.83/19.57 */
61.83/19.57 public Iterator iterator() {
61.83/19.57 return listIterator();
61.83/19.57 }
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns a list iterator over the elements in this list (in proper
61.83/19.57 * sequence).
61.83/19.57 *
61.83/19.57 * @param index index of first element to be returned from the list
61.83/19.57 * iterator (by a call to the next method)
61.83/19.57 * @return a list iterator over the elements in this list (in proper
61.83/19.57 * sequence)
61.83/19.57 * @throws IndexOutOfBoundsException {@inheritDoc}
61.83/19.57 */
61.83/19.57 public abstract ListIterator listIterator(int index);
61.83/19.57 }
61.83/19.57
61.83/19.57
61.83/19.57 /*
61.83/19.57 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
61.83/19.57 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
61.83/19.57 *
61.83/19.57 * This code is free software; you can redistribute it and/or modify it
61.83/19.57 * under the terms of the GNU General Public License version 2 only, as
61.83/19.57 * published by the Free Software Foundation. Sun designates this
61.83/19.57 * particular file as subject to the "Classpath" exception as provided
61.83/19.57 * by Sun in the LICENSE file that accompanied this code.
61.83/19.57 *
61.83/19.57 * This code is distributed in the hope that it will be useful, but WITHOUT
61.83/19.57 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
61.83/19.57 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
61.83/19.57 * version 2 for more details (a copy is included in the LICENSE file that
61.83/19.57 * accompanied this code).
61.83/19.57 *
61.83/19.57 * You should have received a copy of the GNU General Public License version
61.83/19.57 * 2 along with this work; if not, write to the Free Software Foundation,
61.83/19.57 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
61.83/19.57 *
61.83/19.57 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
61.83/19.57 * CA 95054 USA or visit www.sun.com if you need additional information or
61.83/19.57 * have any questions.
61.83/19.57 */
61.83/19.57
61.83/19.57 package javaUtilEx;
61.83/19.57
61.83/19.57 /**
61.83/19.57 * The root interface in the collection hierarchy. A collection
61.83/19.57 * represents a group of objects, known as its elements. Some
61.83/19.57 * collections allow duplicate elements and others do not. Some are ordered
61.83/19.57 * and others unordered. The JDK does not provide any direct
61.83/19.57 * implementations of this interface: it provides implementations of more
61.83/19.57 * specific subinterfaces like Set and List. This interface
61.83/19.57 * is typically used to pass collections around and manipulate them where
61.83/19.57 * maximum generality is desired.
61.83/19.57 *
61.83/19.57 * Bags or multisets (unordered collections that may contain
61.83/19.57 * duplicate elements) should implement this interface directly.
61.83/19.57 *
61.83/19.57 *
All general-purpose Collection implementation classes (which
61.83/19.57 * typically implement Collection indirectly through one of its
61.83/19.57 * subinterfaces) should provide two "standard" constructors: a void (no
61.83/19.57 * arguments) constructor, which creates an empty collection, and a
61.83/19.57 * constructor with a single argument of type Collection, which
61.83/19.57 * creates a new collection with the same elements as its argument. In
61.83/19.57 * effect, the latter constructor allows the user to copy any collection,
61.83/19.57 * producing an equivalent collection of the desired implementation type.
61.83/19.57 * There is no way to enforce this convention (as interfaces cannot contain
61.83/19.57 * constructors) but all of the general-purpose Collection
61.83/19.57 * implementations in the Java platform libraries comply.
61.83/19.57 *
61.83/19.57 *
The "destructive" methods contained in this interface, that is, the
61.83/19.57 * methods that modify the collection on which they operate, are specified to
61.83/19.57 * throw UnsupportedOperationException if this collection does not
61.83/19.57 * support the operation. If this is the case, these methods may, but are not
61.83/19.57 * required to, throw an UnsupportedOperationException if the
61.83/19.57 * invocation would have no effect on the collection. For example, invoking
61.83/19.57 * the {@link #addAll(Collection)} method on an unmodifiable collection may,
61.83/19.57 * but is not required to, throw the exception if the collection to be added
61.83/19.57 * is empty.
61.83/19.57 *
61.83/19.57 *
Some collection implementations have restrictions on the elements that
61.83/19.57 * they may contain. For example, some implementations prohibit null elements,
61.83/19.57 * and some have restrictions on the types of their elements. Attempting to
61.83/19.57 * add an ineligible element throws an unchecked exception, typically
61.83/19.57 * NullPointerException or ClassCastException. Attempting
61.83/19.57 * to query the presence of an ineligible element may throw an exception,
61.83/19.57 * or it may simply return false; some implementations will exhibit the former
61.83/19.57 * behavior and some will exhibit the latter. More generally, attempting an
61.83/19.57 * operation on an ineligible element whose completion would not result in
61.83/19.57 * the insertion of an ineligible element into the collection may throw an
61.83/19.57 * exception or it may succeed, at the option of the implementation.
61.83/19.57 * Such exceptions are marked as "optional" in the specification for this
61.83/19.57 * interface.
61.83/19.57 *
61.83/19.57 *
It is up to each collection to determine its own synchronization
61.83/19.57 * policy. In the absence of a stronger guarantee by the
61.83/19.57 * implementation, undefined behavior may result from the invocation
61.83/19.57 * of any method on a collection that is being mutated by another
61.83/19.57 * thread; this includes direct invocations, passing the collection to
61.83/19.57 * a method that might perform invocations, and using an existing
61.83/19.57 * iterator to examine the collection.
61.83/19.57 *
61.83/19.57 *
Many methods in Collections Framework interfaces are defined in
61.83/19.57 * terms of the {@link Object#equals(Object) equals} method. For example,
61.83/19.57 * the specification for the {@link #contains(Object) contains(Object o)}
61.83/19.57 * method says: "returns true if and only if this collection
61.83/19.57 * contains at least one element e such that
61.83/19.57 * (o==null ? e==null : o.equals(e))." This specification should
61.83/19.57 * not be construed to imply that invoking Collection.contains
61.83/19.57 * with a non-null argument o will cause o.equals(e) to be
61.83/19.57 * invoked for any element e. Implementations are free to implement
61.83/19.57 * optimizations whereby the equals invocation is avoided, for
61.83/19.57 * example, by first comparing the hash codes of the two elements. (The
61.83/19.57 * {@link Object#hashCode()} specification guarantees that two objects with
61.83/19.57 * unequal hash codes cannot be equal.) More generally, implementations of
61.83/19.57 * the various Collections Framework interfaces are free to take advantage of
61.83/19.57 * the specified behavior of underlying {@link Object} methods wherever the
61.83/19.57 * implementor deems it appropriate.
61.83/19.57 *
61.83/19.57 *
This interface is a member of the
61.83/19.57 *
61.83/19.57 * Java Collections Framework.
61.83/19.57 *
61.83/19.57 * @author Josh Bloch
61.83/19.57 * @author Neal Gafter
61.83/19.57 * @see Set
61.83/19.57 * @see List
61.83/19.57 * @see Map
61.83/19.57 * @see SortedSet
61.83/19.57 * @see SortedMap
61.83/19.57 * @see HashSet
61.83/19.57 * @see TreeSet
61.83/19.57 * @see ArrayList
61.83/19.57 * @see LinkedList
61.83/19.57 * @see Vector
61.83/19.57 * @see Collections
61.83/19.57 * @see Arrays
61.83/19.57 * @see AbstractCollection
61.83/19.57 * @since 1.2
61.83/19.57 */
61.83/19.57
61.83/19.57 public interface Collection {
61.83/19.57 // Query Operations
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns the number of elements in this collection. If this collection
61.83/19.57 * contains more than Integer.MAX_VALUE elements, returns
61.83/19.57 * Integer.MAX_VALUE.
61.83/19.57 *
61.83/19.57 * @return the number of elements in this collection
61.83/19.57 */
61.83/19.57 int size();
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns true if this collection contains no elements.
61.83/19.57 *
61.83/19.57 * @return true if this collection contains no elements
61.83/19.57 */
61.83/19.57 boolean isEmpty();
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns true if this collection contains the specified element.
61.83/19.57 * More formally, returns true if and only if this collection
61.83/19.57 * contains at least one element e such that
61.83/19.57 * (o==null ? e==null : o.equals(e)).
61.83/19.57 *
61.83/19.57 * @param o element whose presence in this collection is to be tested
61.83/19.57 * @return true if this collection contains the specified
61.83/19.57 * element
61.83/19.57 * @throws ClassCastException if the type of the specified element
61.83/19.57 * is incompatible with this collection (optional)
61.83/19.57 * @throws NullPointerException if the specified element is null and this
61.83/19.57 * collection does not permit null elements (optional)
61.83/19.57 */
61.83/19.57 boolean contains(Object o);
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns an iterator over the elements in this collection. There are no
61.83/19.57 * guarantees concerning the order in which the elements are returned
61.83/19.57 * (unless this collection is an instance of some class that provides a
61.83/19.57 * guarantee).
61.83/19.57 *
61.83/19.57 * @return an Iterator over the elements in this collection
61.83/19.57 */
61.83/19.57 Iterator iterator();
61.83/19.57
61.83/19.57 // Modification Operations
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Ensures that this collection contains the specified element (optional
61.83/19.57 * operation). Returns true if this collection changed as a
61.83/19.57 * result of the call. (Returns false if this collection does
61.83/19.57 * not permit duplicates and already contains the specified element.)
61.83/19.57 *
61.83/19.57 * Collections that support this operation may place limitations on what
61.83/19.57 * elements may be added to this collection. In particular, some
61.83/19.57 * collections will refuse to add null elements, and others will
61.83/19.57 * impose restrictions on the type of elements that may be added.
61.83/19.57 * Collection classes should clearly specify in their documentation any
61.83/19.57 * restrictions on what elements may be added.
61.83/19.57 *
61.83/19.57 * If a collection refuses to add a particular element for any reason
61.83/19.57 * other than that it already contains the element, it must throw
61.83/19.57 * an exception (rather than returning false). This preserves
61.83/19.57 * the invariant that a collection always contains the specified element
61.83/19.57 * after this call returns.
61.83/19.57 *
61.83/19.57 * @param e element whose presence in this collection is to be ensured
61.83/19.57 * @return true if this collection changed as a result of the
61.83/19.57 * call
61.83/19.57 * @throws UnsupportedOperationException if the add operation
61.83/19.57 * is not supported by this collection
61.83/19.57 * @throws ClassCastException if the class of the specified element
61.83/19.57 * prevents it from being added to this collection
61.83/19.57 * @throws NullPointerException if the specified element is null and this
61.83/19.57 * collection does not permit null elements
61.83/19.57 * @throws IllegalArgumentException if some property of the element
61.83/19.57 * prevents it from being added to this collection
61.83/19.57 * @throws IllegalStateException if the element cannot be added at this
61.83/19.57 * time due to insertion restrictions
61.83/19.57 */
61.83/19.57 boolean add(E e);
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Removes a single instance of the specified element from this
61.83/19.57 * collection, if it is present (optional operation). More formally,
61.83/19.57 * removes an element e such that
61.83/19.57 * (o==null ? e==null : o.equals(e)), if
61.83/19.57 * this collection contains one or more such elements. Returns
61.83/19.57 * true if this collection contained the specified element (or
61.83/19.57 * equivalently, if this collection changed as a result of the call).
61.83/19.57 *
61.83/19.57 * @param o element to be removed from this collection, if present
61.83/19.57 * @return true if an element was removed as a result of this call
61.83/19.57 * @throws ClassCastException if the type of the specified element
61.83/19.57 * is incompatible with this collection (optional)
61.83/19.57 * @throws NullPointerException if the specified element is null and this
61.83/19.57 * collection does not permit null elements (optional)
61.83/19.57 * @throws UnsupportedOperationException if the remove operation
61.83/19.57 * is not supported by this collection
61.83/19.57 */
61.83/19.57 boolean remove(Object o);
61.83/19.57
61.83/19.57
61.83/19.57 // Bulk Operations
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns true if this collection contains all of the elements
61.83/19.57 * in the specified collection.
61.83/19.57 *
61.83/19.57 * @param c collection to be checked for containment in this collection
61.83/19.57 * @return true if this collection contains all of the elements
61.83/19.57 * in the specified collection
61.83/19.57 * @throws ClassCastException if the types of one or more elements
61.83/19.57 * in the specified collection are incompatible with this
61.83/19.57 * collection (optional)
61.83/19.57 * @throws NullPointerException if the specified collection contains one
61.83/19.57 * or more null elements and this collection does not permit null
61.83/19.57 * elements (optional), or if the specified collection is null
61.83/19.57 * @see #contains(Object)
61.83/19.57 */
61.83/19.57 boolean containsAll(Collection c);
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Adds all of the elements in the specified collection to this collection
61.83/19.57 * (optional operation). The behavior of this operation is undefined if
61.83/19.57 * the specified collection is modified while the operation is in progress.
61.83/19.57 * (This implies that the behavior of this call is undefined if the
61.83/19.57 * specified collection is this collection, and this collection is
61.83/19.57 * nonempty.)
61.83/19.57 *
61.83/19.57 * @param c collection containing elements to be added to this collection
61.83/19.57 * @return true if this collection changed as a result of the call
61.83/19.57 * @throws UnsupportedOperationException if the addAll operation
61.83/19.57 * is not supported by this collection
61.83/19.57 * @throws ClassCastException if the class of an element of the specified
61.83/19.57 * collection prevents it from being added to this collection
61.83/19.57 * @throws NullPointerException if the specified collection contains a
61.83/19.57 * null element and this collection does not permit null elements,
61.83/19.57 * or if the specified collection is null
61.83/19.57 * @throws IllegalArgumentException if some property of an element of the
61.83/19.57 * specified collection prevents it from being added to this
61.83/19.57 * collection
61.83/19.57 * @throws IllegalStateException if not all the elements can be added at
61.83/19.57 * this time due to insertion restrictions
61.83/19.57 * @see #add(Object)
61.83/19.57 */
61.83/19.57 boolean addAll(Collection c);
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Removes all of this collection's elements that are also contained in the
61.83/19.57 * specified collection (optional operation). After this call returns,
61.83/19.57 * this collection will contain no elements in common with the specified
61.83/19.57 * collection.
61.83/19.57 *
61.83/19.57 * @param c collection containing elements to be removed from this collection
61.83/19.57 * @return true if this collection changed as a result of the
61.83/19.57 * call
61.83/19.57 * @throws UnsupportedOperationException if the removeAll method
61.83/19.57 * is not supported by this collection
61.83/19.57 * @throws ClassCastException if the types of one or more elements
61.83/19.57 * in this collection are incompatible with the specified
61.83/19.57 * collection (optional)
61.83/19.57 * @throws NullPointerException if this collection contains one or more
61.83/19.57 * null elements and the specified collection does not support
61.83/19.57 * null elements (optional), or if the specified collection is null
61.83/19.57 * @see #remove(Object)
61.83/19.57 * @see #contains(Object)
61.83/19.57 */
61.83/19.57 boolean removeAll(Collection c);
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Retains only the elements in this collection that are contained in the
61.83/19.57 * specified collection (optional operation). In other words, removes from
61.83/19.57 * this collection all of its elements that are not contained in the
61.83/19.57 * specified collection.
61.83/19.57 *
61.83/19.57 * @param c collection containing elements to be retained in this collection
61.83/19.57 * @return true if this collection changed as a result of the call
61.83/19.57 * @throws UnsupportedOperationException if the retainAll operation
61.83/19.57 * is not supported by this collection
61.83/19.57 * @throws ClassCastException if the types of one or more elements
61.83/19.57 * in this collection are incompatible with the specified
61.83/19.57 * collection (optional)
61.83/19.57 * @throws NullPointerException if this collection contains one or more
61.83/19.57 * null elements and the specified collection does not permit null
61.83/19.57 * elements (optional), or if the specified collection is null
61.83/19.57 * @see #remove(Object)
61.83/19.57 * @see #contains(Object)
61.83/19.57 */
61.83/19.57 boolean retainAll(Collection c);
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Removes all of the elements from this collection (optional operation).
61.83/19.57 * The collection will be empty after this method returns.
61.83/19.57 *
61.83/19.57 * @throws UnsupportedOperationException if the clear operation
61.83/19.57 * is not supported by this collection
61.83/19.57 */
61.83/19.57 void clear();
61.83/19.57
61.83/19.57
61.83/19.57 // Comparison and hashing
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Compares the specified object with this collection for equality.
61.83/19.57 *
61.83/19.57 * While the Collection interface adds no stipulations to the
61.83/19.57 * general contract for the Object.equals, programmers who
61.83/19.57 * implement the Collection interface "directly" (in other words,
61.83/19.57 * create a class that is a Collection but is not a Set
61.83/19.57 * or a List) must exercise care if they choose to override the
61.83/19.57 * Object.equals. It is not necessary to do so, and the simplest
61.83/19.57 * course of action is to rely on Object's implementation, but
61.83/19.57 * the implementor may wish to implement a "value comparison" in place of
61.83/19.57 * the default "reference comparison." (The List and
61.83/19.57 * Set interfaces mandate such value comparisons.)
61.83/19.57 *
61.83/19.57 * The general contract for the Object.equals method states that
61.83/19.57 * equals must be symmetric (in other words, a.equals(b) if and
61.83/19.57 * only if b.equals(a)). The contracts for List.equals
61.83/19.57 * and Set.equals state that lists are only equal to other lists,
61.83/19.57 * and sets to other sets. Thus, a custom equals method for a
61.83/19.57 * collection class that implements neither the List nor
61.83/19.57 * Set interface must return false when this collection
61.83/19.57 * is compared to any list or set. (By the same logic, it is not possible
61.83/19.57 * to write a class that correctly implements both the Set and
61.83/19.57 * List interfaces.)
61.83/19.57 *
61.83/19.57 * @param o object to be compared for equality with this collection
61.83/19.57 * @return true if the specified object is equal to this
61.83/19.57 * collection
61.83/19.57 *
61.83/19.57 * @see Object#equals(Object)
61.83/19.57 * @see Set#equals(Object)
61.83/19.57 * @see List#equals(Object)
61.83/19.57 */
61.83/19.57 boolean equals(Object o);
61.83/19.57
61.83/19.57 /**
61.83/19.57 * Returns the hash code value for this collection. While the
61.83/19.57 * Collection interface adds no stipulations to the general
61.83/19.57 * contract for the Object.hashCode method, programmers should
61.83/19.57 * take note that any class that overrides the Object.equals
61.83/19.57 * method must also override the Object.hashCode method in order
61.83/19.57 * to satisfy the general contract for the Object.hashCodemethod.
61.83/19.57 * In particular, c1.equals(c2) implies that
61.83/19.57 * c1.hashCode()==c2.hashCode().
61.83/19.57 *
61.83/19.57 * @return the hash code value for this collection
61.83/19.57 *
61.83/19.57 * @see Object#hashCode()
61.83/19.57 * @see Object#equals(Object)
61.83/19.57 */
61.83/19.57 int hashCode();
61.83/19.57 }
61.83/19.57
61.83/19.57
61.83/19.57 /*
61.83/19.57 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
61.83/19.57 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
61.83/19.57 *
61.83/19.57 * This code is free software; you can redistribute it and/or modify it
61.83/19.57 * under the terms of the GNU General Public License version 2 only, as
61.83/19.57 * published by the Free Software Foundation. Sun designates this
61.83/19.57 * particular file as subject to the "Classpath" exception as provided
61.83/19.57 * by Sun in the LICENSE file that accompanied this code.
61.83/19.57 *
61.83/19.57 * This code is distributed in the hope that it will be useful, but WITHOUT
61.83/19.57 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
61.83/19.57 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
61.83/19.57 * version 2 for more details (a copy is included in the LICENSE file that
61.83/19.57 * accompanied this code).
61.83/19.57 *
61.83/19.57 * You should have received a copy of the GNU General Public License version
61.83/19.57 * 2 along with this work; if not, write to the Free Software Foundation,
61.83/19.57 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
61.83/19.57 *
61.83/19.57 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.12/19.58 * CA 95054 USA or visit www.sun.com if you need additional information or
62.12/19.58 * have any questions.
62.12/19.58 */
62.12/19.58
62.12/19.58 package javaUtilEx;
62.12/19.58
62.12/19.58 /**
62.12/19.58 * This exception may be thrown by methods that have detected concurrent
62.12/19.58 * modification of an object when such modification is not permissible.
62.12/19.58 *
62.12/19.58 * For example, it is not generally permissible for one thread to modify a Collection
62.12/19.58 * while another thread is iterating over it. In general, the results of the
62.12/19.58 * iteration are undefined under these circumstances. Some Iterator
62.12/19.58 * implementations (including those of all the general purpose collection implementations
62.12/19.58 * provided by the JRE) may choose to throw this exception if this behavior is
62.12/19.58 * detected. Iterators that do this are known as fail-fast iterators,
62.12/19.58 * as they fail quickly and cleanly, rather that risking arbitrary,
62.12/19.58 * non-deterministic behavior at an undetermined time in the future.
62.12/19.58 *
62.12/19.58 * Note that this exception does not always indicate that an object has
62.12/19.58 * been concurrently modified by a different thread. If a single
62.12/19.58 * thread issues a sequence of method invocations that violates the
62.12/19.58 * contract of an object, the object may throw this exception. For
62.12/19.58 * example, if a thread modifies a collection directly while it is
62.12/19.58 * iterating over the collection with a fail-fast iterator, the iterator
62.12/19.58 * will throw this exception.
62.12/19.58 *
62.12/19.58 *
Note that fail-fast behavior cannot be guaranteed as it is, generally
62.12/19.58 * speaking, impossible to make any hard guarantees in the presence of
62.12/19.58 * unsynchronized concurrent modification. Fail-fast operations
62.12/19.58 * throw ConcurrentModificationException on a best-effort basis.
62.12/19.58 * Therefore, it would be wrong to write a program that depended on this
62.12/19.58 * exception for its correctness: ConcurrentModificationException
62.12/19.58 * should be used only to detect bugs.
62.12/19.58 *
62.12/19.58 * @author Josh Bloch
62.12/19.58 * @see Collection
62.12/19.58 * @see Iterator
62.12/19.58 * @see ListIterator
62.12/19.58 * @see Vector
62.12/19.58 * @see LinkedList
62.12/19.58 * @see HashSet
62.12/19.58 * @see Hashtable
62.12/19.58 * @see TreeMap
62.12/19.58 * @see AbstractList
62.12/19.58 * @since 1.2
62.12/19.58 */
62.12/19.58 public class ConcurrentModificationException extends RuntimeException {
62.12/19.58 /**
62.12/19.58 * Constructs a ConcurrentModificationException with no
62.12/19.58 * detail message.
62.12/19.58 */
62.12/19.58 public ConcurrentModificationException() {
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs a ConcurrentModificationException with the
62.12/19.58 * specified detail message.
62.12/19.58 *
62.12/19.58 * @param message the detail message pertaining to this exception.
62.12/19.58 */
62.12/19.58 public ConcurrentModificationException(String message) {
62.12/19.58 super(message);
62.12/19.58 }
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 /*
62.12/19.58 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.12/19.58 *
62.12/19.58 * This code is free software; you can redistribute it and/or modify it
62.12/19.58 * under the terms of the GNU General Public License version 2 only, as
62.12/19.58 * published by the Free Software Foundation. Sun designates this
62.12/19.58 * particular file as subject to the "Classpath" exception as provided
62.12/19.58 * by Sun in the LICENSE file that accompanied this code.
62.12/19.58 *
62.12/19.58 * This code is distributed in the hope that it will be useful, but WITHOUT
62.12/19.58 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.12/19.58 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.12/19.58 * version 2 for more details (a copy is included in the LICENSE file that
62.12/19.58 * accompanied this code).
62.12/19.58 *
62.12/19.58 * You should have received a copy of the GNU General Public License version
62.12/19.58 * 2 along with this work; if not, write to the Free Software Foundation,
62.12/19.58 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.12/19.58 *
62.12/19.58 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.12/19.58 * CA 95054 USA or visit www.sun.com if you need additional information or
62.12/19.58 * have any questions.
62.12/19.58 */
62.12/19.58
62.12/19.58 /*
62.12/19.58 * This file is available under and governed by the GNU General Public
62.12/19.58 * License version 2 only, as published by the Free Software Foundation.
62.12/19.58 * However, the following notice accompanied the original version of this
62.12/19.58 * file:
62.12/19.58 *
62.12/19.58 * Written by Doug Lea and Josh Bloch with assistance from members of
62.12/19.58 * JCP JSR-166 Expert Group and released to the public domain, as explained
62.12/19.58 * at http://creativecommons.org/licenses/publicdomain
62.12/19.58 */
62.12/19.58
62.12/19.58 package javaUtilEx;
62.12/19.58
62.12/19.58 /**
62.12/19.58 * A linear collection that supports element insertion and removal at
62.12/19.58 * both ends. The name deque is short for "double ended queue"
62.12/19.58 * and is usually pronounced "deck". Most Deque
62.12/19.58 * implementations place no fixed limits on the number of elements
62.12/19.58 * they may contain, but this interface supports capacity-restricted
62.12/19.58 * deques as well as those with no fixed size limit.
62.12/19.58 *
62.12/19.58 *
This interface defines methods to access the elements at both
62.12/19.58 * ends of the deque. Methods are provided to insert, remove, and
62.12/19.58 * examine the element. Each of these methods exists in two forms:
62.12/19.58 * one throws an exception if the operation fails, the other returns a
62.12/19.58 * special value (either null or false, depending on
62.12/19.58 * the operation). The latter form of the insert operation is
62.12/19.58 * designed specifically for use with capacity-restricted
62.12/19.58 * Deque implementations; in most implementations, insert
62.12/19.58 * operations cannot fail.
62.12/19.58 *
62.12/19.58 *
The twelve methods described above are summarized in the
62.12/19.58 * following table:
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * |
62.12/19.58 * First Element (Head) |
62.12/19.58 * Last Element (Tail) |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * |
62.12/19.58 * Throws exception |
62.12/19.58 * Special value |
62.12/19.58 * Throws exception |
62.12/19.58 * Special value |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | Insert |
62.12/19.58 * {@link #addFirst addFirst(e)} |
62.12/19.58 * {@link #offerFirst offerFirst(e)} |
62.12/19.58 * {@link #addLast addLast(e)} |
62.12/19.58 * {@link #offerLast offerLast(e)} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | Remove |
62.12/19.58 * {@link #removeFirst removeFirst()} |
62.12/19.58 * {@link #pollFirst pollFirst()} |
62.12/19.58 * {@link #removeLast removeLast()} |
62.12/19.58 * {@link #pollLast pollLast()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | Examine |
62.12/19.58 * {@link #getFirst getFirst()} |
62.12/19.58 * {@link #peekFirst peekFirst()} |
62.12/19.58 * {@link #getLast getLast()} |
62.12/19.58 * {@link #peekLast peekLast()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * This interface extends the {@link Queue} interface. When a deque is
62.12/19.58 * used as a queue, FIFO (First-In-First-Out) behavior results. Elements are
62.12/19.58 * added at the end of the deque and removed from the beginning. The methods
62.12/19.58 * inherited from the Queue interface are precisely equivalent to
62.12/19.58 * Deque methods as indicated in the following table:
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | Queue Method |
62.12/19.58 * Equivalent Deque Method |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link java.util.Queue#add add(e)} |
62.12/19.58 * {@link #addLast addLast(e)} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link java.util.Queue#offer offer(e)} |
62.12/19.58 * {@link #offerLast offerLast(e)} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link java.util.Queue#remove remove()} |
62.12/19.58 * {@link #removeFirst removeFirst()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link java.util.Queue#poll poll()} |
62.12/19.58 * {@link #pollFirst pollFirst()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link java.util.Queue#element element()} |
62.12/19.58 * {@link #getFirst getFirst()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link java.util.Queue#peek peek()} |
62.12/19.58 * {@link #peek peekFirst()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * Deques can also be used as LIFO (Last-In-First-Out) stacks. This
62.12/19.58 * interface should be used in preference to the legacy {@link Stack} class.
62.12/19.58 * When a deque is used as a stack, elements are pushed and popped from the
62.12/19.58 * beginning of the deque. Stack methods are precisely equivalent to
62.12/19.58 * Deque methods as indicated in the table below:
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | Stack Method |
62.12/19.58 * Equivalent Deque Method |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link #push push(e)} |
62.12/19.58 * {@link #addFirst addFirst(e)} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link #pop pop()} |
62.12/19.58 * {@link #removeFirst removeFirst()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * | {@link #peek peek()} |
62.12/19.58 * {@link #peekFirst peekFirst()} |
62.12/19.58 *
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * Note that the {@link #peek peek} method works equally well when
62.12/19.58 * a deque is used as a queue or a stack; in either case, elements are
62.12/19.58 * drawn from the beginning of the deque.
62.12/19.58 *
62.12/19.58 *
This interface provides two methods to remove interior
62.12/19.58 * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
62.12/19.58 * {@link #removeLastOccurrence removeLastOccurrence}.
62.12/19.58 *
62.12/19.58 *
Unlike the {@link List} interface, this interface does not
62.12/19.58 * provide support for indexed access to elements.
62.12/19.58 *
62.12/19.58 *
While Deque implementations are not strictly required
62.12/19.58 * to prohibit the insertion of null elements, they are strongly
62.12/19.58 * encouraged to do so. Users of any Deque implementations
62.12/19.58 * that do allow null elements are strongly encouraged not to
62.12/19.58 * take advantage of the ability to insert nulls. This is so because
62.12/19.58 * null is used as a special return value by various methods
62.12/19.58 * to indicated that the deque is empty.
62.12/19.58 *
62.12/19.58 *
Deque implementations generally do not define
62.12/19.58 * element-based versions of the equals and hashCode
62.12/19.58 * methods, but instead inherit the identity-based versions from class
62.12/19.58 * Object.
62.12/19.58 *
62.12/19.58 *
This interface is a member of the Java Collections
62.12/19.58 * Framework.
62.12/19.58 *
62.12/19.58 * @author Doug Lea
62.12/19.58 * @author Josh Bloch
62.12/19.58 * @since 1.6
62.12/19.58 * @param the type of elements held in this collection
62.12/19.58 */
62.12/19.58
62.12/19.58 public interface Deque extends Queue {
62.12/19.58 /**
62.12/19.58 * Inserts the specified element at the front of this deque if it is
62.12/19.58 * possible to do so immediately without violating capacity restrictions.
62.12/19.58 * When using a capacity-restricted deque, it is generally preferable to
62.12/19.58 * use method {@link #offerFirst}.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 * @throws IllegalStateException if the element cannot be added at this
62.12/19.58 * time due to capacity restrictions
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * prevents it from being added to this deque
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements
62.12/19.58 * @throws IllegalArgumentException if some property of the specified
62.12/19.58 * element prevents it from being added to this deque
62.12/19.58 */
62.12/19.58 void addFirst(E e);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Inserts the specified element at the end of this deque if it is
62.12/19.58 * possible to do so immediately without violating capacity restrictions.
62.12/19.58 * When using a capacity-restricted deque, it is generally preferable to
62.12/19.58 * use method {@link #offerLast}.
62.12/19.58 *
62.12/19.58 * This method is equivalent to {@link #add}.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 * @throws IllegalStateException if the element cannot be added at this
62.12/19.58 * time due to capacity restrictions
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * prevents it from being added to this deque
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements
62.12/19.58 * @throws IllegalArgumentException if some property of the specified
62.12/19.58 * element prevents it from being added to this deque
62.12/19.58 */
62.12/19.58 void addLast(E e);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Inserts the specified element at the front of this deque unless it would
62.12/19.58 * violate capacity restrictions. When using a capacity-restricted deque,
62.12/19.58 * this method is generally preferable to the {@link #addFirst} method,
62.12/19.58 * which can fail to insert an element only by throwing an exception.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 * @return true if the element was added to this deque, else
62.12/19.58 * false
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * prevents it from being added to this deque
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements
62.12/19.58 * @throws IllegalArgumentException if some property of the specified
62.12/19.58 * element prevents it from being added to this deque
62.12/19.58 */
62.12/19.58 boolean offerFirst(E e);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Inserts the specified element at the end of this deque unless it would
62.12/19.58 * violate capacity restrictions. When using a capacity-restricted deque,
62.12/19.58 * this method is generally preferable to the {@link #addLast} method,
62.12/19.58 * which can fail to insert an element only by throwing an exception.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 * @return true if the element was added to this deque, else
62.12/19.58 * false
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * prevents it from being added to this deque
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements
62.12/19.58 * @throws IllegalArgumentException if some property of the specified
62.12/19.58 * element prevents it from being added to this deque
62.12/19.58 */
62.12/19.58 boolean offerLast(E e);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves and removes the first element of this deque. This method
62.12/19.58 * differs from {@link #pollFirst pollFirst} only in that it throws an
62.12/19.58 * exception if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the head of this deque
62.12/19.58 * @throws NoSuchElementException if this deque is empty
62.12/19.58 */
62.12/19.58 E removeFirst();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves and removes the last element of this deque. This method
62.12/19.58 * differs from {@link #pollLast pollLast} only in that it throws an
62.12/19.58 * exception if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the tail of this deque
62.12/19.58 * @throws NoSuchElementException if this deque is empty
62.12/19.58 */
62.12/19.58 E removeLast();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves and removes the first element of this deque,
62.12/19.58 * or returns null if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the head of this deque, or null if this deque is empty
62.12/19.58 */
62.12/19.58 E pollFirst();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves and removes the last element of this deque,
62.12/19.58 * or returns null if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the tail of this deque, or null if this deque is empty
62.12/19.58 */
62.12/19.58 E pollLast();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves, but does not remove, the first element of this deque.
62.12/19.58 *
62.12/19.58 * This method differs from {@link #peekFirst peekFirst} only in that it
62.12/19.58 * throws an exception if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the head of this deque
62.12/19.58 * @throws NoSuchElementException if this deque is empty
62.12/19.58 */
62.12/19.58 E getFirst();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves, but does not remove, the last element of this deque.
62.12/19.58 * This method differs from {@link #peekLast peekLast} only in that it
62.12/19.58 * throws an exception if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the tail of this deque
62.12/19.58 * @throws NoSuchElementException if this deque is empty
62.12/19.58 */
62.12/19.58 E getLast();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves, but does not remove, the first element of this deque,
62.12/19.58 * or returns null if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the head of this deque, or null if this deque is empty
62.12/19.58 */
62.12/19.58 E peekFirst();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves, but does not remove, the last element of this deque,
62.12/19.58 * or returns null if this deque is empty.
62.12/19.58 *
62.12/19.58 * @return the tail of this deque, or null if this deque is empty
62.12/19.58 */
62.12/19.58 E peekLast();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes the first occurrence of the specified element from this deque.
62.12/19.58 * If the deque does not contain the element, it is unchanged.
62.12/19.58 * More formally, removes the first element e such that
62.12/19.58 * (o==null ? e==null : o.equals(e))
62.12/19.58 * (if such an element exists).
62.12/19.58 * Returns true if this deque contained the specified element
62.12/19.58 * (or equivalently, if this deque changed as a result of the call).
62.12/19.58 *
62.12/19.58 * @param o element to be removed from this deque, if present
62.12/19.58 * @return true if an element was removed as a result of this call
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * is incompatible with this deque (optional)
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements (optional)
62.12/19.58 */
62.12/19.58 boolean removeFirstOccurrence(Object o);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes the last occurrence of the specified element from this deque.
62.12/19.58 * If the deque does not contain the element, it is unchanged.
62.12/19.58 * More formally, removes the last element e such that
62.12/19.58 * (o==null ? e==null : o.equals(e))
62.12/19.58 * (if such an element exists).
62.12/19.58 * Returns true if this deque contained the specified element
62.12/19.58 * (or equivalently, if this deque changed as a result of the call).
62.12/19.58 *
62.12/19.58 * @param o element to be removed from this deque, if present
62.12/19.58 * @return true if an element was removed as a result of this call
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * is incompatible with this deque (optional)
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements (optional)
62.12/19.58 */
62.12/19.58 boolean removeLastOccurrence(Object o);
62.12/19.58
62.12/19.58 // *** Queue methods ***
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Inserts the specified element into the queue represented by this deque
62.12/19.58 * (in other words, at the tail of this deque) if it is possible to do so
62.12/19.58 * immediately without violating capacity restrictions, returning
62.12/19.58 * true upon success and throwing an
62.12/19.58 * IllegalStateException if no space is currently available.
62.12/19.58 * When using a capacity-restricted deque, it is generally preferable to
62.12/19.58 * use {@link #offer(Object) offer}.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #addLast}.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 * @return true (as specified by {@link Collection#add})
62.12/19.58 * @throws IllegalStateException if the element cannot be added at this
62.12/19.58 * time due to capacity restrictions
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * prevents it from being added to this deque
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements
62.12/19.58 * @throws IllegalArgumentException if some property of the specified
62.12/19.58 * element prevents it from being added to this deque
62.12/19.58 */
62.12/19.58 boolean add(E e);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Inserts the specified element into the queue represented by this deque
62.12/19.58 * (in other words, at the tail of this deque) if it is possible to do so
62.12/19.58 * immediately without violating capacity restrictions, returning
62.12/19.58 * true upon success and false if no space is currently
62.12/19.58 * available. When using a capacity-restricted deque, this method is
62.12/19.58 * generally preferable to the {@link #add} method, which can fail to
62.12/19.58 * insert an element only by throwing an exception.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #offerLast}.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 * @return true if the element was added to this deque, else
62.12/19.58 * false
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * prevents it from being added to this deque
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements
62.12/19.58 * @throws IllegalArgumentException if some property of the specified
62.12/19.58 * element prevents it from being added to this deque
62.12/19.58 */
62.12/19.58 boolean offer(E e);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves and removes the head of the queue represented by this deque
62.12/19.58 * (in other words, the first element of this deque).
62.12/19.58 * This method differs from {@link #poll poll} only in that it throws an
62.12/19.58 * exception if this deque is empty.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #removeFirst()}.
62.12/19.58 *
62.12/19.58 * @return the head of the queue represented by this deque
62.12/19.58 * @throws NoSuchElementException if this deque is empty
62.12/19.58 */
62.12/19.58 E remove();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves and removes the head of the queue represented by this deque
62.12/19.58 * (in other words, the first element of this deque), or returns
62.12/19.58 * null if this deque is empty.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #pollFirst()}.
62.12/19.58 *
62.12/19.58 * @return the first element of this deque, or null if
62.12/19.58 * this deque is empty
62.12/19.58 */
62.12/19.58 E poll();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves, but does not remove, the head of the queue represented by
62.12/19.58 * this deque (in other words, the first element of this deque).
62.12/19.58 * This method differs from {@link #peek peek} only in that it throws an
62.12/19.58 * exception if this deque is empty.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #getFirst()}.
62.12/19.58 *
62.12/19.58 * @return the head of the queue represented by this deque
62.12/19.58 * @throws NoSuchElementException if this deque is empty
62.12/19.58 */
62.12/19.58 E element();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Retrieves, but does not remove, the head of the queue represented by
62.12/19.58 * this deque (in other words, the first element of this deque), or
62.12/19.58 * returns null if this deque is empty.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #peekFirst()}.
62.12/19.58 *
62.12/19.58 * @return the head of the queue represented by this deque, or
62.12/19.58 * null if this deque is empty
62.12/19.58 */
62.12/19.58 E peek();
62.12/19.58
62.12/19.58
62.12/19.58 // *** Stack methods ***
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Pushes an element onto the stack represented by this deque (in other
62.12/19.58 * words, at the head of this deque) if it is possible to do so
62.12/19.58 * immediately without violating capacity restrictions, returning
62.12/19.58 * true upon success and throwing an
62.12/19.58 * IllegalStateException if no space is currently available.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #addFirst}.
62.12/19.58 *
62.12/19.58 * @param e the element to push
62.12/19.58 * @throws IllegalStateException if the element cannot be added at this
62.12/19.58 * time due to capacity restrictions
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * prevents it from being added to this deque
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements
62.12/19.58 * @throws IllegalArgumentException if some property of the specified
62.12/19.58 * element prevents it from being added to this deque
62.12/19.58 */
62.12/19.58 void push(E e);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Pops an element from the stack represented by this deque. In other
62.12/19.58 * words, removes and returns the first element of this deque.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #removeFirst()}.
62.12/19.58 *
62.12/19.58 * @return the element at the front of this deque (which is the top
62.12/19.58 * of the stack represented by this deque)
62.12/19.58 * @throws NoSuchElementException if this deque is empty
62.12/19.58 */
62.12/19.58 E pop();
62.12/19.58
62.12/19.58
62.12/19.58 // *** Collection methods ***
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes the first occurrence of the specified element from this deque.
62.12/19.58 * If the deque does not contain the element, it is unchanged.
62.12/19.58 * More formally, removes the first element e such that
62.12/19.58 * (o==null ? e==null : o.equals(e))
62.12/19.58 * (if such an element exists).
62.12/19.58 * Returns true if this deque contained the specified element
62.12/19.58 * (or equivalently, if this deque changed as a result of the call).
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #removeFirstOccurrence}.
62.12/19.58 *
62.12/19.58 * @param o element to be removed from this deque, if present
62.12/19.58 * @return true if an element was removed as a result of this call
62.12/19.58 * @throws ClassCastException if the class of the specified element
62.12/19.58 * is incompatible with this deque (optional)
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements (optional)
62.12/19.58 */
62.12/19.58 boolean remove(Object o);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns true if this deque contains the specified element.
62.12/19.58 * More formally, returns true if and only if this deque contains
62.12/19.58 * at least one element e such that
62.12/19.58 * (o==null ? e==null : o.equals(e)).
62.12/19.58 *
62.12/19.58 * @param o element whose presence in this deque is to be tested
62.12/19.58 * @return true if this deque contains the specified element
62.12/19.58 * @throws ClassCastException if the type of the specified element
62.12/19.58 * is incompatible with this deque (optional)
62.12/19.58 * @throws NullPointerException if the specified element is null and this
62.12/19.58 * deque does not permit null elements (optional)
62.12/19.58 */
62.12/19.58 boolean contains(Object o);
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the number of elements in this deque.
62.12/19.58 *
62.12/19.58 * @return the number of elements in this deque
62.12/19.58 */
62.12/19.58 public int size();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns an iterator over the elements in this deque in proper sequence.
62.12/19.58 * The elements will be returned in order from first (head) to last (tail).
62.12/19.58 *
62.12/19.58 * @return an iterator over the elements in this deque in proper sequence
62.12/19.58 */
62.12/19.58 Iterator iterator();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns an iterator over the elements in this deque in reverse
62.12/19.58 * sequential order. The elements will be returned in order from
62.12/19.58 * last (tail) to first (head).
62.12/19.58 *
62.12/19.58 * @return an iterator over the elements in this deque in reverse
62.12/19.58 * sequence
62.12/19.58 */
62.12/19.58 Iterator descendingIterator();
62.12/19.58
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 /*
62.12/19.58 * Copyright 1994-2003 Sun Microsystems, Inc. All Rights Reserved.
62.12/19.58 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.12/19.58 *
62.12/19.58 * This code is free software; you can redistribute it and/or modify it
62.12/19.58 * under the terms of the GNU General Public License version 2 only, as
62.12/19.58 * published by the Free Software Foundation. Sun designates this
62.12/19.58 * particular file as subject to the "Classpath" exception as provided
62.12/19.58 * by Sun in the LICENSE file that accompanied this code.
62.12/19.58 *
62.12/19.58 * This code is distributed in the hope that it will be useful, but WITHOUT
62.12/19.58 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.12/19.58 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.12/19.58 * version 2 for more details (a copy is included in the LICENSE file that
62.12/19.58 * accompanied this code).
62.12/19.58 *
62.12/19.58 * You should have received a copy of the GNU General Public License version
62.12/19.58 * 2 along with this work; if not, write to the Free Software Foundation,
62.12/19.58 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.12/19.58 *
62.12/19.58 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.12/19.58 * CA 95054 USA or visit www.sun.com if you need additional information or
62.12/19.58 * have any questions.
62.12/19.58 */
62.12/19.58
62.12/19.58 package javaUtilEx;
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Thrown to indicate that a method has been passed an illegal or
62.12/19.58 * inappropriate argument.
62.12/19.58 *
62.12/19.58 * @author unascribed
62.12/19.58 * @see java.lang.Thread#setPriority(int)
62.12/19.58 * @since JDK1.0
62.12/19.58 */
62.12/19.58 public
62.12/19.58 class IllegalArgumentException extends RuntimeException {
62.12/19.58 /**
62.12/19.58 * Constructs an IllegalArgumentException with no
62.12/19.58 * detail message.
62.12/19.58 */
62.12/19.58 public IllegalArgumentException() {
62.12/19.58 super();
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs an IllegalArgumentException with the
62.12/19.58 * specified detail message.
62.12/19.58 *
62.12/19.58 * @param s the detail message.
62.12/19.58 */
62.12/19.58 public IllegalArgumentException(String s) {
62.12/19.58 super(s);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs a new exception with the specified detail message and
62.12/19.58 * cause.
62.12/19.58 *
62.12/19.58 * Note that the detail message associated with cause is
62.12/19.58 * not automatically incorporated in this exception's detail
62.12/19.58 * message.
62.12/19.58 *
62.12/19.58 * @param message the detail message (which is saved for later retrieval
62.12/19.58 * by the {@link Throwable#getMessage()} method).
62.12/19.58 * @param cause the cause (which is saved for later retrieval by the
62.12/19.58 * {@link Throwable#getCause()} method). (A null value
62.12/19.58 * is permitted, and indicates that the cause is nonexistent or
62.12/19.58 * unknown.)
62.12/19.58 * @since 1.5
62.12/19.58 */
62.12/19.58 public IllegalArgumentException(String message, Throwable cause) {
62.12/19.58 super(message, cause);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs a new exception with the specified cause and a detail
62.12/19.58 * message of (cause==null ? null : cause.toString()) (which
62.12/19.58 * typically contains the class and detail message of cause).
62.12/19.58 * This constructor is useful for exceptions that are little more than
62.12/19.58 * wrappers for other throwables (for example, {@link
62.12/19.58 * java.security.PrivilegedActionException}).
62.12/19.58 *
62.12/19.58 * @param cause the cause (which is saved for later retrieval by the
62.12/19.58 * {@link Throwable#getCause()} method). (A null value is
62.12/19.58 * permitted, and indicates that the cause is nonexistent or
62.12/19.58 * unknown.)
62.12/19.58 * @since 1.5
62.12/19.58 */
62.12/19.58 public IllegalArgumentException(Throwable cause) {
62.12/19.58 super(cause);
62.12/19.58 }
62.12/19.58
62.12/19.58 private static final long serialVersionUID = -5365630128856068164L;
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 /*
62.12/19.58 * Copyright 1996-2003 Sun Microsystems, Inc. All Rights Reserved.
62.12/19.58 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.12/19.58 *
62.12/19.58 * This code is free software; you can redistribute it and/or modify it
62.12/19.58 * under the terms of the GNU General Public License version 2 only, as
62.12/19.58 * published by the Free Software Foundation. Sun designates this
62.12/19.58 * particular file as subject to the "Classpath" exception as provided
62.12/19.58 * by Sun in the LICENSE file that accompanied this code.
62.12/19.58 *
62.12/19.58 * This code is distributed in the hope that it will be useful, but WITHOUT
62.12/19.58 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.12/19.58 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.12/19.58 * version 2 for more details (a copy is included in the LICENSE file that
62.12/19.58 * accompanied this code).
62.12/19.58 *
62.12/19.58 * You should have received a copy of the GNU General Public License version
62.12/19.58 * 2 along with this work; if not, write to the Free Software Foundation,
62.12/19.58 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.12/19.58 *
62.12/19.58 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.12/19.58 * CA 95054 USA or visit www.sun.com if you need additional information or
62.12/19.58 * have any questions.
62.12/19.58 */
62.12/19.58
62.12/19.58 package javaUtilEx;
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Signals that a method has been invoked at an illegal or
62.12/19.58 * inappropriate time. In other words, the Java environment or
62.12/19.58 * Java application is not in an appropriate state for the requested
62.12/19.58 * operation.
62.12/19.58 *
62.12/19.58 * @author Jonni Kanerva
62.12/19.58 * @since JDK1.1
62.12/19.58 */
62.12/19.58 public
62.12/19.58 class IllegalStateException extends RuntimeException {
62.12/19.58 /**
62.12/19.58 * Constructs an IllegalStateException with no detail message.
62.12/19.58 * A detail message is a String that describes this particular exception.
62.12/19.58 */
62.12/19.58 public IllegalStateException() {
62.12/19.58 super();
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs an IllegalStateException with the specified detail
62.12/19.58 * message. A detail message is a String that describes this particular
62.12/19.58 * exception.
62.12/19.58 *
62.12/19.58 * @param s the String that contains a detailed message
62.12/19.58 */
62.12/19.58 public IllegalStateException(String s) {
62.12/19.58 super(s);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs a new exception with the specified detail message and
62.12/19.58 * cause.
62.12/19.58 *
62.12/19.58 *
Note that the detail message associated with cause is
62.12/19.58 * not automatically incorporated in this exception's detail
62.12/19.58 * message.
62.12/19.58 *
62.12/19.58 * @param message the detail message (which is saved for later retrieval
62.12/19.58 * by the {@link Throwable#getMessage()} method).
62.12/19.58 * @param cause the cause (which is saved for later retrieval by the
62.12/19.58 * {@link Throwable#getCause()} method). (A null value
62.12/19.58 * is permitted, and indicates that the cause is nonexistent or
62.12/19.58 * unknown.)
62.12/19.58 * @since 1.5
62.12/19.58 */
62.12/19.58 public IllegalStateException(String message, Throwable cause) {
62.12/19.58 super(message, cause);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs a new exception with the specified cause and a detail
62.12/19.58 * message of (cause==null ? null : cause.toString()) (which
62.12/19.58 * typically contains the class and detail message of cause).
62.12/19.58 * This constructor is useful for exceptions that are little more than
62.12/19.58 * wrappers for other throwables (for example, {@link
62.12/19.58 * java.security.PrivilegedActionException}).
62.12/19.58 *
62.12/19.58 * @param cause the cause (which is saved for later retrieval by the
62.12/19.58 * {@link Throwable#getCause()} method). (A null value is
62.12/19.58 * permitted, and indicates that the cause is nonexistent or
62.12/19.58 * unknown.)
62.12/19.58 * @since 1.5
62.12/19.58 */
62.12/19.58 public IllegalStateException(Throwable cause) {
62.12/19.58 super(cause);
62.12/19.58 }
62.12/19.58
62.12/19.58 static final long serialVersionUID = -1848914673093119416L;
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 /*
62.12/19.58 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.12/19.58 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.12/19.58 *
62.12/19.58 * This code is free software; you can redistribute it and/or modify it
62.12/19.58 * under the terms of the GNU General Public License version 2 only, as
62.12/19.58 * published by the Free Software Foundation. Sun designates this
62.12/19.58 * particular file as subject to the "Classpath" exception as provided
62.12/19.58 * by Sun in the LICENSE file that accompanied this code.
62.12/19.58 *
62.12/19.58 * This code is distributed in the hope that it will be useful, but WITHOUT
62.12/19.58 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.12/19.58 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.12/19.58 * version 2 for more details (a copy is included in the LICENSE file that
62.12/19.58 * accompanied this code).
62.12/19.58 *
62.12/19.58 * You should have received a copy of the GNU General Public License version
62.12/19.58 * 2 along with this work; if not, write to the Free Software Foundation,
62.12/19.58 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.12/19.58 *
62.12/19.58 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.12/19.58 * CA 95054 USA or visit www.sun.com if you need additional information or
62.12/19.58 * have any questions.
62.12/19.58 */
62.12/19.58
62.12/19.58 package javaUtilEx;
62.12/19.58
62.12/19.58 /**
62.12/19.58 * An iterator over a collection. {@code Iterator} takes the place of
62.12/19.58 * {@link Enumeration} in the Java Collections Framework. Iterators
62.12/19.58 * differ from enumerations in two ways:
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * - Iterators allow the caller to remove elements from the
62.12/19.58 * underlying collection during the iteration with well-defined
62.12/19.58 * semantics.
62.12/19.58 *
- Method names have been improved.
62.12/19.58 *
62.12/19.58 *
62.12/19.58 * This interface is a member of the
62.12/19.58 *
62.12/19.58 * Java Collections Framework.
62.12/19.58 *
62.12/19.58 * @author Josh Bloch
62.12/19.58 * @see Collection
62.12/19.58 * @see ListIterator
62.12/19.58 * @see Iterable
62.12/19.58 * @since 1.2
62.12/19.58 */
62.12/19.58 public interface Iterator {
62.12/19.58 /**
62.12/19.58 * Returns {@code true} if the iteration has more elements.
62.12/19.58 * (In other words, returns {@code true} if {@link #next} would
62.12/19.58 * return an element rather than throwing an exception.)
62.12/19.58 *
62.12/19.58 * @return {@code true} if the iteration has more elements
62.12/19.58 */
62.12/19.58 boolean hasNext();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the next element in the iteration.
62.12/19.58 *
62.12/19.58 * @return the next element in the iteration
62.12/19.58 * @throws NoSuchElementException if the iteration has no more elements
62.12/19.58 */
62.12/19.58 E next();
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes from the underlying collection the last element returned
62.12/19.58 * by this iterator (optional operation). This method can be called
62.12/19.58 * only once per call to {@link #next}. The behavior of an iterator
62.12/19.58 * is unspecified if the underlying collection is modified while the
62.12/19.58 * iteration is in progress in any way other than by calling this
62.12/19.58 * method.
62.12/19.58 *
62.12/19.58 * @throws UnsupportedOperationException if the {@code remove}
62.12/19.58 * operation is not supported by this iterator
62.12/19.58 *
62.12/19.58 * @throws IllegalStateException if the {@code next} method has not
62.12/19.58 * yet been called, or the {@code remove} method has already
62.12/19.58 * been called after the last call to the {@code next}
62.12/19.58 * method
62.12/19.58 */
62.12/19.58 void remove();
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 package javaUtilEx;
62.12/19.58
62.12/19.58 public class juLinkedListCreateAddAllAt {
62.12/19.58 public static void main(String[] args) {
62.12/19.58 Random.args = args;
62.12/19.58
62.12/19.58 LinkedList l1 = createList(Random.random());
62.12/19.58 LinkedList l2 = createList(Random.random());
62.12/19.58 l1.addAll(Random.random(), l2);
62.12/19.58 }
62.12/19.58
62.12/19.58 public static LinkedList createList(int n) {
62.12/19.58 LinkedList l = new LinkedList();
62.12/19.58 while (n > 0) {
62.12/19.58 l.addLast(new Content(Random.random()));
62.12/19.58 n--;
62.12/19.58 }
62.12/19.58 return l;
62.12/19.58 }
62.12/19.58 }
62.12/19.58
62.12/19.58 final class Content {
62.12/19.58 int val;
62.12/19.58
62.12/19.58 public Content(int v) {
62.12/19.58 this.val = v;
62.12/19.58 }
62.12/19.58
62.12/19.58 public int hashCode() {
62.12/19.58 return val^31;
62.12/19.58 }
62.12/19.58
62.12/19.58 public boolean equals(Object o) {
62.12/19.58 if (o instanceof Content) {
62.12/19.58 return this.val == ((Content) o).val;
62.12/19.58 }
62.12/19.58 return false;
62.12/19.58 }
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 /*
62.12/19.58 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.12/19.58 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.12/19.58 *
62.12/19.58 * This code is free software; you can redistribute it and/or modify it
62.12/19.58 * under the terms of the GNU General Public License version 2 only, as
62.12/19.58 * published by the Free Software Foundation. Sun designates this
62.12/19.58 * particular file as subject to the "Classpath" exception as provided
62.12/19.58 * by Sun in the LICENSE file that accompanied this code.
62.12/19.58 *
62.12/19.58 * This code is distributed in the hope that it will be useful, but WITHOUT
62.12/19.58 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.12/19.58 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.12/19.58 * version 2 for more details (a copy is included in the LICENSE file that
62.12/19.58 * accompanied this code).
62.12/19.58 *
62.12/19.58 * You should have received a copy of the GNU General Public License version
62.12/19.58 * 2 along with this work; if not, write to the Free Software Foundation,
62.12/19.58 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.12/19.58 *
62.12/19.58 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.12/19.58 * CA 95054 USA or visit www.sun.com if you need additional information or
62.12/19.58 * have any questions.
62.12/19.58 */
62.12/19.58
62.12/19.58 package javaUtilEx;
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Linked list implementation of the List interface. Implements all
62.12/19.58 * optional list operations, and permits all elements (including
62.12/19.58 * null). In addition to implementing the List interface,
62.12/19.58 * the LinkedList class provides uniformly named methods to
62.12/19.58 * get, remove and insert an element at the
62.12/19.58 * beginning and end of the list. These operations allow linked lists to be
62.12/19.58 * used as a stack, {@linkplain Queue queue}, or {@linkplain Deque
62.12/19.58 * double-ended queue}.
62.12/19.58 *
62.12/19.58 * The class implements the Deque interface, providing
62.12/19.58 * first-in-first-out queue operations for add,
62.12/19.58 * poll, along with other stack and deque operations.
62.12/19.58 *
62.12/19.58 * All of the operations perform as could be expected for a doubly-linked
62.12/19.58 * list. Operations that index into the list will traverse the list from
62.12/19.58 * the beginning or the end, whichever is closer to the specified index.
62.12/19.58 *
62.12/19.58 *
Note that this implementation is not synchronized.
62.12/19.58 * If multiple threads access a linked list concurrently, and at least
62.12/19.58 * one of the threads modifies the list structurally, it must be
62.12/19.58 * synchronized externally. (A structural modification is any operation
62.12/19.58 * that adds or deletes one or more elements; merely setting the value of
62.12/19.58 * an element is not a structural modification.) This is typically
62.12/19.58 * accomplished by synchronizing on some object that naturally
62.12/19.58 * encapsulates the list.
62.12/19.58 *
62.12/19.58 * If no such object exists, the list should be "wrapped" using the
62.12/19.58 * {@link Collections#synchronizedList Collections.synchronizedList}
62.12/19.58 * method. This is best done at creation time, to prevent accidental
62.12/19.58 * unsynchronized access to the list:
62.12/19.58 * List list = Collections.synchronizedList(new LinkedList(...));
62.12/19.58 *
62.12/19.58 * The iterators returned by this class's iterator and
62.12/19.58 * listIterator methods are fail-fast: if the list is
62.12/19.58 * structurally modified at any time after the iterator is created, in
62.12/19.58 * any way except through the Iterator's own remove or
62.12/19.58 * add methods, the iterator will throw a {@link
62.12/19.58 * ConcurrentModificationException}. Thus, in the face of concurrent
62.12/19.58 * modification, the iterator fails quickly and cleanly, rather than
62.12/19.58 * risking arbitrary, non-deterministic behavior at an undetermined
62.12/19.58 * time in the future.
62.12/19.58 *
62.12/19.58 *
Note that the fail-fast behavior of an iterator cannot be guaranteed
62.12/19.58 * as it is, generally speaking, impossible to make any hard guarantees in the
62.12/19.58 * presence of unsynchronized concurrent modification. Fail-fast iterators
62.12/19.58 * throw ConcurrentModificationException on a best-effort basis.
62.12/19.58 * Therefore, it would be wrong to write a program that depended on this
62.12/19.58 * exception for its correctness: the fail-fast behavior of iterators
62.12/19.58 * should be used only to detect bugs.
62.12/19.58 *
62.12/19.58 *
This class is a member of the
62.12/19.58 *
62.12/19.58 * Java Collections Framework.
62.12/19.58 *
62.12/19.58 * @author Josh Bloch
62.12/19.58 * @see List
62.12/19.58 * @see ArrayList
62.12/19.58 * @see Vector
62.12/19.58 * @since 1.2
62.12/19.58 * @param the type of elements held in this collection
62.12/19.58 */
62.12/19.58
62.12/19.58 public class LinkedList
62.12/19.58 extends AbstractSequentialList
62.12/19.58 implements List, Deque
62.12/19.58 {
62.12/19.58 private transient Entry header = new Entry(null, null, null);
62.12/19.58 private transient int size = 0;
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs an empty list.
62.12/19.58 */
62.12/19.58 public LinkedList() {
62.12/19.58 header.next = header.previous = header;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Constructs a list containing the elements of the specified
62.12/19.58 * collection, in the order they are returned by the collection's
62.12/19.58 * iterator.
62.12/19.58 *
62.12/19.58 * @param c the collection whose elements are to be placed into this list
62.12/19.58 * @throws NullPointerException if the specified collection is null
62.12/19.58 */
62.12/19.58 public LinkedList(Collection c) {
62.12/19.58 this();
62.12/19.58 addAll(c);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the first element in this list.
62.12/19.58 *
62.12/19.58 * @return the first element in this list
62.12/19.58 * @throws NoSuchElementException if this list is empty
62.12/19.58 */
62.12/19.58 public E getFirst() {
62.12/19.58 if (size==0)
62.12/19.58 throw new NoSuchElementException();
62.12/19.58
62.12/19.58 return header.next.element;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the last element in this list.
62.12/19.58 *
62.12/19.58 * @return the last element in this list
62.12/19.58 * @throws NoSuchElementException if this list is empty
62.12/19.58 */
62.12/19.58 public E getLast() {
62.12/19.58 if (size==0)
62.12/19.58 throw new NoSuchElementException();
62.12/19.58
62.12/19.58 return header.previous.element;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes and returns the first element from this list.
62.12/19.58 *
62.12/19.58 * @return the first element from this list
62.12/19.58 * @throws NoSuchElementException if this list is empty
62.12/19.58 */
62.12/19.58 public E removeFirst() {
62.12/19.58 return remove(header.next);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes and returns the last element from this list.
62.12/19.58 *
62.12/19.58 * @return the last element from this list
62.12/19.58 * @throws NoSuchElementException if this list is empty
62.12/19.58 */
62.12/19.58 public E removeLast() {
62.12/19.58 return remove(header.previous);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Inserts the specified element at the beginning of this list.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 */
62.12/19.58 public void addFirst(E e) {
62.12/19.58 addBefore(e, header.next);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Appends the specified element to the end of this list.
62.12/19.58 *
62.12/19.58 * This method is equivalent to {@link #add}.
62.12/19.58 *
62.12/19.58 * @param e the element to add
62.12/19.58 */
62.12/19.58 public void addLast(E e) {
62.12/19.58 addBefore(e, header);
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns true if this list contains the specified element.
62.12/19.58 * More formally, returns true if and only if this list contains
62.12/19.58 * at least one element e such that
62.12/19.58 * (o==null ? e==null : o.equals(e)).
62.12/19.58 *
62.12/19.58 * @param o element whose presence in this list is to be tested
62.12/19.58 * @return true if this list contains the specified element
62.12/19.58 */
62.12/19.58 public boolean contains(Object o) {
62.12/19.58 return indexOf(o) != -1;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the number of elements in this list.
62.12/19.58 *
62.12/19.58 * @return the number of elements in this list
62.12/19.58 */
62.12/19.58 public int size() {
62.12/19.58 return size;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Appends the specified element to the end of this list.
62.12/19.58 *
62.12/19.58 *
This method is equivalent to {@link #addLast}.
62.12/19.58 *
62.12/19.58 * @param e element to be appended to this list
62.12/19.58 * @return true (as specified by {@link Collection#add})
62.12/19.58 */
62.12/19.58 public boolean add(E e) {
62.12/19.58 addBefore(e, header);
62.12/19.58 return true;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes the first occurrence of the specified element from this list,
62.12/19.58 * if it is present. If this list does not contain the element, it is
62.12/19.58 * unchanged. More formally, removes the element with the lowest index
62.12/19.58 * i such that
62.12/19.58 * (o==null ? get(i)==null : o.equals(get(i)))
62.12/19.58 * (if such an element exists). Returns true if this list
62.12/19.58 * contained the specified element (or equivalently, if this list
62.12/19.58 * changed as a result of the call).
62.12/19.58 *
62.12/19.58 * @param o element to be removed from this list, if present
62.12/19.58 * @return true if this list contained the specified element
62.12/19.58 */
62.12/19.58 public boolean remove(Object o) {
62.12/19.58 if (o==null) {
62.12/19.58 for (Entry e = header.next; e != header; e = e.next) {
62.12/19.58 if (e.element==null) {
62.12/19.58 remove(e);
62.12/19.58 return true;
62.12/19.58 }
62.12/19.58 }
62.12/19.58 } else {
62.12/19.58 for (Entry e = header.next; e != header; e = e.next) {
62.12/19.58 if (o.equals(e.element)) {
62.12/19.58 remove(e);
62.12/19.58 return true;
62.12/19.58 }
62.12/19.58 }
62.12/19.58 }
62.12/19.58 return false;
62.12/19.58 }
62.12/19.58 /**
62.12/19.58 * Removes all of the elements from this list.
62.12/19.58 */
62.12/19.58 public void clear() {
62.12/19.58 Entry e = header.next;
62.12/19.58 while (e != header) {
62.12/19.58 Entry next = e.next;
62.12/19.58 e.next = e.previous = null;
62.12/19.58 e.element = null;
62.12/19.58 e = next;
62.12/19.58 }
62.12/19.58 header.next = header.previous = header;
62.12/19.58 size = 0;
62.12/19.58 modCount++;
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 // Positional Access Operations
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the element at the specified position in this list.
62.12/19.58 *
62.12/19.58 * @param index index of the element to return
62.12/19.58 * @return the element at the specified position in this list
62.12/19.58 * @throws IndexOutOfBoundsException {@inheritDoc}
62.12/19.58 */
62.12/19.58 public E get(int index) {
62.12/19.58 return entry(index).element;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Replaces the element at the specified position in this list with the
62.12/19.58 * specified element.
62.12/19.58 *
62.12/19.58 * @param index index of the element to replace
62.12/19.58 * @param element element to be stored at the specified position
62.12/19.58 * @return the element previously at the specified position
62.12/19.58 * @throws IndexOutOfBoundsException {@inheritDoc}
62.12/19.58 */
62.12/19.58 public E set(int index, E element) {
62.12/19.58 Entry e = entry(index);
62.12/19.58 E oldVal = e.element;
62.12/19.58 e.element = element;
62.12/19.58 return oldVal;
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Inserts the specified element at the specified position in this list.
62.12/19.58 * Shifts the element currently at that position (if any) and any
62.12/19.58 * subsequent elements to the right (adds one to their indices).
62.12/19.58 *
62.12/19.58 * @param index index at which the specified element is to be inserted
62.12/19.58 * @param element element to be inserted
62.12/19.58 * @throws IndexOutOfBoundsException {@inheritDoc}
62.12/19.58 */
62.12/19.58 public void add(int index, E element) {
62.12/19.58 addBefore(element, (index==size ? header : entry(index)));
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Removes the element at the specified position in this list. Shifts any
62.12/19.58 * subsequent elements to the left (subtracts one from their indices).
62.12/19.58 * Returns the element that was removed from the list.
62.12/19.58 *
62.12/19.58 * @param index the index of the element to be removed
62.12/19.58 * @return the element previously at the specified position
62.12/19.58 * @throws IndexOutOfBoundsException {@inheritDoc}
62.12/19.58 */
62.12/19.58 public E remove(int index) {
62.12/19.58 return remove(entry(index));
62.12/19.58 }
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the indexed entry.
62.12/19.58 */
62.12/19.58 private Entry entry(int index) {
62.12/19.58 if (index < 0 || index >= size)
62.12/19.58 throw new IndexOutOfBoundsException();
62.12/19.58 Entry e = header;
62.12/19.58 if (index < (size >> 1)) {
62.12/19.58 for (int i = 0; i <= index; i++)
62.12/19.58 e = e.next;
62.12/19.58 } else {
62.12/19.58 for (int i = size; i > index; i--)
62.12/19.58 e = e.previous;
62.12/19.58 }
62.12/19.58 return e;
62.12/19.58 }
62.12/19.58
62.12/19.58
62.12/19.58 // Search Operations
62.12/19.58
62.12/19.58 /**
62.12/19.58 * Returns the index of the first occurrence of the specified element
62.12/19.58 * in this list, or -1 if this list does not contain the element.
62.12/19.58 * More formally, returns the lowest index i such that
62.12/19.58 * (o==null ? get(i)==null : o.equals(get(i))),
62.12/19.58 * or -1 if there is no such index.
62.12/19.58 *
62.12/19.58 * @param o element to search for
62.12/19.58 * @return the index of the first occurrence of the specified element in
62.12/19.58 * this list, or -1 if this list does not contain the element
62.12/19.58 */
62.12/19.58 public int indexOf(Object o) {
62.12/19.58 int index = 0;
62.12/19.58 if (o==null) {
62.12/19.58 for (Entry e = header.next; e != header; e = e.next) {
62.12/19.58 if (e.element==null)
62.12/19.58 return index;
62.12/19.58 index++;
62.12/19.58 }
62.12/19.58 } else {
62.12/19.58 for (Entry e = header.next; e != header; e = e.next) {
62.12/19.58 if (o.equals(e.element))
62.12/19.58 return index;
62.12/19.59 index++;
62.12/19.59 }
62.12/19.59 }
62.12/19.59 return -1;
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Returns the index of the last occurrence of the specified element
62.12/19.59 * in this list, or -1 if this list does not contain the element.
62.12/19.59 * More formally, returns the highest index i such that
62.12/19.59 * (o==null ? get(i)==null : o.equals(get(i))),
62.12/19.59 * or -1 if there is no such index.
62.12/19.59 *
62.12/19.59 * @param o element to search for
62.12/19.59 * @return the index of the last occurrence of the specified element in
62.12/19.59 * this list, or -1 if this list does not contain the element
62.12/19.59 */
62.12/19.59 public int lastIndexOf(Object o) {
62.12/19.59 int index = size;
62.12/19.59 if (o==null) {
62.12/19.59 for (Entry e = header.previous; e != header; e = e.previous) {
62.12/19.59 index--;
62.12/19.59 if (e.element==null)
62.12/19.59 return index;
62.12/19.59 }
62.12/19.59 } else {
62.12/19.59 for (Entry e = header.previous; e != header; e = e.previous) {
62.12/19.59 index--;
62.12/19.59 if (o.equals(e.element))
62.12/19.59 return index;
62.12/19.59 }
62.12/19.59 }
62.12/19.59 return -1;
62.12/19.59 }
62.12/19.59
62.12/19.59 // Queue operations.
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves, but does not remove, the head (first element) of this list.
62.12/19.59 * @return the head of this list, or null if this list is empty
62.12/19.59 * @since 1.5
62.12/19.59 */
62.12/19.59 public E peek() {
62.12/19.59 if (size==0)
62.12/19.59 return null;
62.12/19.59 return getFirst();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves, but does not remove, the head (first element) of this list.
62.12/19.59 * @return the head of this list
62.12/19.59 * @throws NoSuchElementException if this list is empty
62.12/19.59 * @since 1.5
62.12/19.59 */
62.12/19.59 public E element() {
62.12/19.59 return getFirst();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves and removes the head (first element) of this list
62.12/19.59 * @return the head of this list, or null if this list is empty
62.12/19.59 * @since 1.5
62.12/19.59 */
62.12/19.59 public E poll() {
62.12/19.59 if (size==0)
62.12/19.59 return null;
62.12/19.59 return removeFirst();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves and removes the head (first element) of this list.
62.12/19.59 *
62.12/19.59 * @return the head of this list
62.12/19.59 * @throws NoSuchElementException if this list is empty
62.12/19.59 * @since 1.5
62.12/19.59 */
62.12/19.59 public E remove() {
62.12/19.59 return removeFirst();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Adds the specified element as the tail (last element) of this list.
62.12/19.59 *
62.12/19.59 * @param e the element to add
62.12/19.59 * @return true (as specified by {@link Queue#offer})
62.12/19.59 * @since 1.5
62.12/19.59 */
62.12/19.59 public boolean offer(E e) {
62.12/19.59 return add(e);
62.12/19.59 }
62.12/19.59
62.12/19.59 // Deque operations
62.12/19.59 /**
62.12/19.59 * Inserts the specified element at the front of this list.
62.12/19.59 *
62.12/19.59 * @param e the element to insert
62.12/19.59 * @return true (as specified by {@link Deque#offerFirst})
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public boolean offerFirst(E e) {
62.12/19.59 addFirst(e);
62.12/19.59 return true;
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Inserts the specified element at the end of this list.
62.12/19.59 *
62.12/19.59 * @param e the element to insert
62.12/19.59 * @return true (as specified by {@link Deque#offerLast})
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public boolean offerLast(E e) {
62.12/19.59 addLast(e);
62.12/19.59 return true;
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves, but does not remove, the first element of this list,
62.12/19.59 * or returns null if this list is empty.
62.12/19.59 *
62.12/19.59 * @return the first element of this list, or null
62.12/19.59 * if this list is empty
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public E peekFirst() {
62.12/19.59 if (size==0)
62.12/19.59 return null;
62.12/19.59 return getFirst();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves, but does not remove, the last element of this list,
62.12/19.59 * or returns null if this list is empty.
62.12/19.59 *
62.12/19.59 * @return the last element of this list, or null
62.12/19.59 * if this list is empty
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public E peekLast() {
62.12/19.59 if (size==0)
62.12/19.59 return null;
62.12/19.59 return getLast();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves and removes the first element of this list,
62.12/19.59 * or returns null if this list is empty.
62.12/19.59 *
62.12/19.59 * @return the first element of this list, or null if
62.12/19.59 * this list is empty
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public E pollFirst() {
62.12/19.59 if (size==0)
62.12/19.59 return null;
62.12/19.59 return removeFirst();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Retrieves and removes the last element of this list,
62.12/19.59 * or returns null if this list is empty.
62.12/19.59 *
62.12/19.59 * @return the last element of this list, or null if
62.12/19.59 * this list is empty
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public E pollLast() {
62.12/19.59 if (size==0)
62.12/19.59 return null;
62.12/19.59 return removeLast();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Pushes an element onto the stack represented by this list. In other
62.12/19.59 * words, inserts the element at the front of this list.
62.12/19.59 *
62.12/19.59 * This method is equivalent to {@link #addFirst}.
62.12/19.59 *
62.12/19.59 * @param e the element to push
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public void push(E e) {
62.12/19.59 addFirst(e);
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Pops an element from the stack represented by this list. In other
62.12/19.59 * words, removes and returns the first element of this list.
62.12/19.59 *
62.12/19.59 *
This method is equivalent to {@link #removeFirst()}.
62.12/19.59 *
62.12/19.59 * @return the element at the front of this list (which is the top
62.12/19.59 * of the stack represented by this list)
62.12/19.59 * @throws NoSuchElementException if this list is empty
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public E pop() {
62.12/19.59 return removeFirst();
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Removes the first occurrence of the specified element in this
62.12/19.59 * list (when traversing the list from head to tail). If the list
62.12/19.59 * does not contain the element, it is unchanged.
62.12/19.59 *
62.12/19.59 * @param o element to be removed from this list, if present
62.12/19.59 * @return true if the list contained the specified element
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public boolean removeFirstOccurrence(Object o) {
62.12/19.59 return remove(o);
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Removes the last occurrence of the specified element in this
62.12/19.59 * list (when traversing the list from head to tail). If the list
62.12/19.59 * does not contain the element, it is unchanged.
62.12/19.59 *
62.12/19.59 * @param o element to be removed from this list, if present
62.12/19.59 * @return true if the list contained the specified element
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public boolean removeLastOccurrence(Object o) {
62.12/19.59 if (o==null) {
62.12/19.59 for (Entry e = header.previous; e != header; e = e.previous) {
62.12/19.59 if (e.element==null) {
62.12/19.59 remove(e);
62.12/19.59 return true;
62.12/19.59 }
62.12/19.59 }
62.12/19.59 } else {
62.12/19.59 for (Entry e = header.previous; e != header; e = e.previous) {
62.12/19.59 if (o.equals(e.element)) {
62.12/19.59 remove(e);
62.12/19.59 return true;
62.12/19.59 }
62.12/19.59 }
62.12/19.59 }
62.12/19.59 return false;
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Returns a list-iterator of the elements in this list (in proper
62.12/19.59 * sequence), starting at the specified position in the list.
62.12/19.59 * Obeys the general contract of List.listIterator(int).
62.12/19.59 *
62.12/19.59 * The list-iterator is fail-fast: if the list is structurally
62.12/19.59 * modified at any time after the Iterator is created, in any way except
62.12/19.59 * through the list-iterator's own remove or add
62.12/19.59 * methods, the list-iterator will throw a
62.12/19.59 * ConcurrentModificationException. Thus, in the face of
62.12/19.59 * concurrent modification, the iterator fails quickly and cleanly, rather
62.12/19.59 * than risking arbitrary, non-deterministic behavior at an undetermined
62.12/19.59 * time in the future.
62.12/19.59 *
62.12/19.59 * @param index index of the first element to be returned from the
62.12/19.59 * list-iterator (by a call to next)
62.12/19.59 * @return a ListIterator of the elements in this list (in proper
62.12/19.59 * sequence), starting at the specified position in the list
62.12/19.59 * @throws IndexOutOfBoundsException {@inheritDoc}
62.12/19.59 * @see List#listIterator(int)
62.12/19.59 */
62.12/19.59 public ListIterator listIterator(int index) {
62.12/19.59 return new ListItr(index);
62.12/19.59 }
62.12/19.59
62.12/19.59 private class ListItr implements ListIterator {
62.12/19.59 private Entry lastReturned = header;
62.12/19.59 private Entry next;
62.12/19.59 private int nextIndex;
62.12/19.59 private int expectedModCount = modCount;
62.12/19.59
62.12/19.59 ListItr(int index) {
62.12/19.59 if (index < 0 || index > size)
62.12/19.59 throw new IndexOutOfBoundsException();
62.12/19.59 if (index < (size >> 1)) {
62.12/19.59 next = header.next;
62.12/19.59 for (nextIndex=0; nextIndexindex; nextIndex--)
62.12/19.59 next = next.previous;
62.12/19.59 }
62.12/19.59 }
62.12/19.59
62.12/19.59 public boolean hasNext() {
62.12/19.59 return nextIndex != size;
62.12/19.59 }
62.12/19.59
62.12/19.59 public E next() {
62.12/19.59 checkForComodification();
62.12/19.59 if (nextIndex == size)
62.12/19.59 throw new NoSuchElementException();
62.12/19.59
62.12/19.59 lastReturned = next;
62.12/19.59 next = next.next;
62.12/19.59 nextIndex++;
62.12/19.59 return lastReturned.element;
62.12/19.59 }
62.12/19.59
62.12/19.59 public boolean hasPrevious() {
62.12/19.59 return nextIndex != 0;
62.12/19.59 }
62.12/19.59
62.12/19.59 public E previous() {
62.12/19.59 if (nextIndex == 0)
62.12/19.59 throw new NoSuchElementException();
62.12/19.59
62.12/19.59 lastReturned = next = next.previous;
62.12/19.59 nextIndex--;
62.12/19.59 checkForComodification();
62.12/19.59 return lastReturned.element;
62.12/19.59 }
62.12/19.59
62.12/19.59 public int nextIndex() {
62.12/19.59 return nextIndex;
62.12/19.59 }
62.12/19.59
62.12/19.59 public int previousIndex() {
62.12/19.59 return nextIndex-1;
62.12/19.59 }
62.12/19.59
62.12/19.59 public void remove() {
62.12/19.59 checkForComodification();
62.12/19.59 Entry lastNext = lastReturned.next;
62.12/19.59 try {
62.12/19.59 LinkedList.this.remove(lastReturned);
62.12/19.59 } catch (NoSuchElementException e) {
62.12/19.59 throw new IllegalStateException();
62.12/19.59 }
62.12/19.59 if (next==lastReturned)
62.12/19.59 next = lastNext;
62.12/19.59 else
62.12/19.59 nextIndex--;
62.12/19.59 lastReturned = header;
62.12/19.59 expectedModCount++;
62.12/19.59 }
62.12/19.59
62.12/19.59 public void set(E e) {
62.12/19.59 if (lastReturned == header)
62.12/19.59 throw new IllegalStateException();
62.12/19.59 checkForComodification();
62.12/19.59 lastReturned.element = e;
62.12/19.59 }
62.12/19.59
62.12/19.59 public void add(E e) {
62.12/19.59 checkForComodification();
62.12/19.59 lastReturned = header;
62.12/19.59 addBefore(e, next);
62.12/19.59 nextIndex++;
62.12/19.59 expectedModCount++;
62.12/19.59 }
62.12/19.59
62.12/19.59 final void checkForComodification() {
62.12/19.59 if (modCount != expectedModCount)
62.12/19.59 throw new ConcurrentModificationException();
62.12/19.59 }
62.12/19.59 }
62.12/19.59
62.12/19.59 private static class Entry {
62.12/19.59 E element;
62.12/19.59 Entry next;
62.12/19.59 Entry previous;
62.12/19.59
62.12/19.59 Entry(E element, Entry next, Entry previous) {
62.12/19.59 this.element = element;
62.12/19.59 this.next = next;
62.12/19.59 this.previous = previous;
62.12/19.59 }
62.12/19.59 }
62.12/19.59
62.12/19.59 private Entry addBefore(E e, Entry entry) {
62.12/19.59 Entry newEntry = new Entry(e, entry, entry.previous);
62.12/19.59 newEntry.previous.next = newEntry;
62.12/19.59 newEntry.next.previous = newEntry;
62.12/19.59 size++;
62.12/19.59 modCount++;
62.12/19.59 return newEntry;
62.12/19.59 }
62.12/19.59
62.12/19.59 private E remove(Entry e) {
62.12/19.59 if (e == header)
62.12/19.59 throw new NoSuchElementException();
62.12/19.59
62.12/19.59 E result = e.element;
62.12/19.59 e.previous.next = e.next;
62.12/19.59 e.next.previous = e.previous;
62.12/19.59 e.next = e.previous = null;
62.12/19.59 e.element = null;
62.12/19.59 size--;
62.12/19.59 modCount++;
62.12/19.59 return result;
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * @since 1.6
62.12/19.59 */
62.12/19.59 public Iterator descendingIterator() {
62.12/19.59 return new DescendingIterator();
62.12/19.59 }
62.12/19.59
62.12/19.59 /** Adapter to provide descending iterators via ListItr.previous */
62.12/19.59 private class DescendingIterator implements Iterator {
62.12/19.59 final ListItr itr = new ListItr(size());
62.12/19.59 public boolean hasNext() {
62.12/19.59 return itr.hasPrevious();
62.12/19.59 }
62.12/19.59 public E next() {
62.12/19.59 return itr.previous();
62.12/19.59 }
62.12/19.59 public void remove() {
62.12/19.59 itr.remove();
62.12/19.59 }
62.12/19.59 }
62.12/19.59
62.12/19.59 /**
62.12/19.59 * Returns an array containing all of the elements in this list
62.18/19.59 * in proper sequence (from first to last element).
62.18/19.59 *
62.18/19.59 * The returned array will be "safe" in that no references to it are
62.18/19.59 * maintained by this list. (In other words, this method must allocate
62.18/19.59 * a new array). The caller is thus free to modify the returned array.
62.18/19.59 *
62.18/19.59 *
This method acts as bridge between array-based and collection-based
62.18/19.59 * APIs.
62.18/19.59 *
62.18/19.59 * @return an array containing all of the elements in this list
62.18/19.59 * in proper sequence
62.18/19.59 */
62.18/19.59 public Object[] toArray() {
62.18/19.59 Object[] result = new Object[size];
62.18/19.59 int i = 0;
62.18/19.59 for (Entry e = header.next; e != header; e = e.next)
62.18/19.59 result[i++] = e.element;
62.18/19.59 return result;
62.18/19.59 }
62.18/19.59
62.18/19.59 private static final long serialVersionUID = 876323262645176354L;
62.18/19.59 }
62.18/19.59
62.18/19.59
62.18/19.59 /*
62.18/19.59 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.59 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.59 *
62.18/19.59 * This code is free software; you can redistribute it and/or modify it
62.18/19.59 * under the terms of the GNU General Public License version 2 only, as
62.18/19.59 * published by the Free Software Foundation. Sun designates this
62.18/19.59 * particular file as subject to the "Classpath" exception as provided
62.18/19.59 * by Sun in the LICENSE file that accompanied this code.
62.18/19.59 *
62.18/19.59 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.59 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.59 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.59 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.59 * accompanied this code).
62.18/19.59 *
62.18/19.59 * You should have received a copy of the GNU General Public License version
62.18/19.59 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.59 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.59 *
62.18/19.59 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.59 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.59 * have any questions.
62.18/19.59 */
62.18/19.59
62.18/19.59 package javaUtilEx;
62.18/19.59
62.18/19.59 /**
62.18/19.59 * An iterator for lists that allows the programmer
62.18/19.59 * to traverse the list in either direction, modify
62.18/19.59 * the list during iteration, and obtain the iterator's
62.18/19.59 * current position in the list. A {@code ListIterator}
62.18/19.59 * has no current element; its cursor position always
62.18/19.59 * lies between the element that would be returned by a call
62.18/19.59 * to {@code previous()} and the element that would be
62.18/19.59 * returned by a call to {@code next()}.
62.18/19.59 * An iterator for a list of length {@code n} has {@code n+1} possible
62.18/19.59 * cursor positions, as illustrated by the carets ({@code ^}) below:
62.18/19.59 *
62.18/19.59 * Element(0) Element(1) Element(2) ... Element(n-1)
62.18/19.59 * cursor positions: ^ ^ ^ ^ ^
62.18/19.59 *
62.18/19.59 * Note that the {@link #remove} and {@link #set(Object)} methods are
62.18/19.59 * not defined in terms of the cursor position; they are defined to
62.18/19.59 * operate on the last element returned by a call to {@link #next} or
62.18/19.59 * {@link #previous()}.
62.18/19.59 *
62.18/19.59 * This interface is a member of the
62.18/19.59 *
62.18/19.59 * Java Collections Framework.
62.18/19.59 *
62.18/19.59 * @author Josh Bloch
62.18/19.59 * @see Collection
62.18/19.59 * @see List
62.18/19.59 * @see Iterator
62.18/19.59 * @see Enumeration
62.18/19.59 * @see List#listIterator()
62.18/19.59 * @since 1.2
62.18/19.59 */
62.18/19.59 public interface ListIterator extends Iterator {
62.18/19.59 // Query Operations
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns {@code true} if this list iterator has more elements when
62.18/19.59 * traversing the list in the forward direction. (In other words,
62.18/19.59 * returns {@code true} if {@link #next} would return an element rather
62.18/19.59 * than throwing an exception.)
62.18/19.59 *
62.18/19.59 * @return {@code true} if the list iterator has more elements when
62.18/19.59 * traversing the list in the forward direction
62.18/19.59 */
62.18/19.59 boolean hasNext();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns the next element in the list and advances the cursor position.
62.18/19.59 * This method may be called repeatedly to iterate through the list,
62.18/19.59 * or intermixed with calls to {@link #previous} to go back and forth.
62.18/19.59 * (Note that alternating calls to {@code next} and {@code previous}
62.18/19.59 * will return the same element repeatedly.)
62.18/19.59 *
62.18/19.59 * @return the next element in the list
62.18/19.59 * @throws NoSuchElementException if the iteration has no next element
62.18/19.59 */
62.18/19.59 E next();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns {@code true} if this list iterator has more elements when
62.18/19.59 * traversing the list in the reverse direction. (In other words,
62.18/19.59 * returns {@code true} if {@link #previous} would return an element
62.18/19.59 * rather than throwing an exception.)
62.18/19.59 *
62.18/19.59 * @return {@code true} if the list iterator has more elements when
62.18/19.59 * traversing the list in the reverse direction
62.18/19.59 */
62.18/19.59 boolean hasPrevious();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns the previous element in the list and moves the cursor
62.18/19.59 * position backwards. This method may be called repeatedly to
62.18/19.59 * iterate through the list backwards, or intermixed with calls to
62.18/19.59 * {@link #next} to go back and forth. (Note that alternating calls
62.18/19.59 * to {@code next} and {@code previous} will return the same
62.18/19.59 * element repeatedly.)
62.18/19.59 *
62.18/19.59 * @return the previous element in the list
62.18/19.59 * @throws NoSuchElementException if the iteration has no previous
62.18/19.59 * element
62.18/19.59 */
62.18/19.59 E previous();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns the index of the element that would be returned by a
62.18/19.59 * subsequent call to {@link #next}. (Returns list size if the list
62.18/19.59 * iterator is at the end of the list.)
62.18/19.59 *
62.18/19.59 * @return the index of the element that would be returned by a
62.18/19.59 * subsequent call to {@code next}, or list size if the list
62.18/19.59 * iterator is at the end of the list
62.18/19.59 */
62.18/19.59 int nextIndex();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns the index of the element that would be returned by a
62.18/19.59 * subsequent call to {@link #previous}. (Returns -1 if the list
62.18/19.59 * iterator is at the beginning of the list.)
62.18/19.59 *
62.18/19.59 * @return the index of the element that would be returned by a
62.18/19.59 * subsequent call to {@code previous}, or -1 if the list
62.18/19.59 * iterator is at the beginning of the list
62.18/19.59 */
62.18/19.59 int previousIndex();
62.18/19.59
62.18/19.59
62.18/19.59 // Modification Operations
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Removes from the list the last element that was returned by {@link
62.18/19.59 * #next} or {@link #previous} (optional operation). This call can
62.18/19.59 * only be made once per call to {@code next} or {@code previous}.
62.18/19.59 * It can be made only if {@link #add} has not been
62.18/19.59 * called after the last call to {@code next} or {@code previous}.
62.18/19.59 *
62.18/19.59 * @throws UnsupportedOperationException if the {@code remove}
62.18/19.59 * operation is not supported by this list iterator
62.18/19.59 * @throws IllegalStateException if neither {@code next} nor
62.18/19.59 * {@code previous} have been called, or {@code remove} or
62.18/19.59 * {@code add} have been called after the last call to
62.18/19.59 * {@code next} or {@code previous}
62.18/19.59 */
62.18/19.59 void remove();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Replaces the last element returned by {@link #next} or
62.18/19.59 * {@link #previous} with the specified element (optional operation).
62.18/19.59 * This call can be made only if neither {@link #remove} nor {@link
62.18/19.59 * #add} have been called after the last call to {@code next} or
62.18/19.59 * {@code previous}.
62.18/19.59 *
62.18/19.59 * @param e the element with which to replace the last element returned by
62.18/19.59 * {@code next} or {@code previous}
62.18/19.59 * @throws UnsupportedOperationException if the {@code set} operation
62.18/19.59 * is not supported by this list iterator
62.18/19.59 * @throws ClassCastException if the class of the specified element
62.18/19.59 * prevents it from being added to this list
62.18/19.59 * @throws IllegalArgumentException if some aspect of the specified
62.18/19.59 * element prevents it from being added to this list
62.18/19.59 * @throws IllegalStateException if neither {@code next} nor
62.18/19.59 * {@code previous} have been called, or {@code remove} or
62.18/19.59 * {@code add} have been called after the last call to
62.18/19.59 * {@code next} or {@code previous}
62.18/19.59 */
62.18/19.59 void set(E e);
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Inserts the specified element into the list (optional operation).
62.18/19.59 * The element is inserted immediately before the next element that
62.18/19.59 * would be returned by {@link #next}, if any, and after the next
62.18/19.59 * element that would be returned by {@link #previous}, if any. (If the
62.18/19.59 * list contains no elements, the new element becomes the sole element
62.18/19.59 * on the list.) The new element is inserted before the implicit
62.18/19.59 * cursor: a subsequent call to {@code next} would be unaffected, and a
62.18/19.59 * subsequent call to {@code previous} would return the new element.
62.18/19.59 * (This call increases by one the value that would be returned by a
62.18/19.59 * call to {@code nextIndex} or {@code previousIndex}.)
62.18/19.59 *
62.18/19.59 * @param e the element to insert
62.18/19.59 * @throws UnsupportedOperationException if the {@code add} method is
62.18/19.59 * not supported by this list iterator
62.18/19.59 * @throws ClassCastException if the class of the specified element
62.18/19.59 * prevents it from being added to this list
62.18/19.59 * @throws IllegalArgumentException if some aspect of this element
62.18/19.59 * prevents it from being added to this list
62.18/19.59 */
62.18/19.59 void add(E e);
62.18/19.59 }
62.18/19.59
62.18/19.59
62.18/19.59 /*
62.18/19.59 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.59 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.59 *
62.18/19.59 * This code is free software; you can redistribute it and/or modify it
62.18/19.59 * under the terms of the GNU General Public License version 2 only, as
62.18/19.59 * published by the Free Software Foundation. Sun designates this
62.18/19.59 * particular file as subject to the "Classpath" exception as provided
62.18/19.59 * by Sun in the LICENSE file that accompanied this code.
62.18/19.59 *
62.18/19.59 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.59 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.59 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.59 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.59 * accompanied this code).
62.18/19.59 *
62.18/19.59 * You should have received a copy of the GNU General Public License version
62.18/19.59 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.59 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.59 *
62.18/19.59 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.59 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.59 * have any questions.
62.18/19.59 */
62.18/19.59
62.18/19.59 package javaUtilEx;
62.18/19.59
62.18/19.59 /**
62.18/19.59 * An ordered collection (also known as a sequence). The user of this
62.18/19.59 * interface has precise control over where in the list each element is
62.18/19.59 * inserted. The user can access elements by their integer index (position in
62.18/19.59 * the list), and search for elements in the list.
62.18/19.59 *
62.18/19.59 * Unlike sets, lists typically allow duplicate elements. More formally,
62.18/19.59 * lists typically allow pairs of elements e1 and e2
62.18/19.59 * such that e1.equals(e2), and they typically allow multiple
62.18/19.59 * null elements if they allow null elements at all. It is not inconceivable
62.18/19.59 * that someone might wish to implement a list that prohibits duplicates, by
62.18/19.59 * throwing runtime exceptions when the user attempts to insert them, but we
62.18/19.59 * expect this usage to be rare.
62.18/19.59 *
62.18/19.59 * The List interface places additional stipulations, beyond those
62.18/19.59 * specified in the Collection interface, on the contracts of the
62.18/19.59 * iterator, add, remove, equals, and
62.18/19.59 * hashCode methods. Declarations for other inherited methods are
62.18/19.59 * also included here for convenience.
62.18/19.59 *
62.18/19.59 * The List interface provides four methods for positional (indexed)
62.18/19.59 * access to list elements. Lists (like Java arrays) are zero based. Note
62.18/19.59 * that these operations may execute in time proportional to the index value
62.18/19.59 * for some implementations (the LinkedList class, for
62.18/19.59 * example). Thus, iterating over the elements in a list is typically
62.18/19.59 * preferable to indexing through it if the caller does not know the
62.18/19.59 * implementation.
62.18/19.59 *
62.18/19.59 * The List interface provides a special iterator, called a
62.18/19.59 * ListIterator, that allows element insertion and replacement, and
62.18/19.59 * bidirectional access in addition to the normal operations that the
62.18/19.59 * Iterator interface provides. A method is provided to obtain a
62.18/19.59 * list iterator that starts at a specified position in the list.
62.18/19.59 *
62.18/19.59 * The List interface provides two methods to search for a specified
62.18/19.59 * object. From a performance standpoint, these methods should be used with
62.18/19.59 * caution. In many implementations they will perform costly linear
62.18/19.59 * searches.
62.18/19.59 *
62.18/19.59 * The List interface provides two methods to efficiently insert and
62.18/19.59 * remove multiple elements at an arbitrary point in the list.
62.18/19.59 *
62.18/19.59 * Note: While it is permissible for lists to contain themselves as elements,
62.18/19.59 * extreme caution is advised: the equals and hashCode
62.18/19.59 * methods are no longer well defined on such a list.
62.18/19.59 *
62.18/19.59 *
Some list implementations have restrictions on the elements that
62.18/19.59 * they may contain. For example, some implementations prohibit null elements,
62.18/19.59 * and some have restrictions on the types of their elements. Attempting to
62.18/19.59 * add an ineligible element throws an unchecked exception, typically
62.18/19.59 * NullPointerException or ClassCastException. Attempting
62.18/19.59 * to query the presence of an ineligible element may throw an exception,
62.18/19.59 * or it may simply return false; some implementations will exhibit the former
62.18/19.59 * behavior and some will exhibit the latter. More generally, attempting an
62.18/19.59 * operation on an ineligible element whose completion would not result in
62.18/19.59 * the insertion of an ineligible element into the list may throw an
62.18/19.59 * exception or it may succeed, at the option of the implementation.
62.18/19.59 * Such exceptions are marked as "optional" in the specification for this
62.18/19.59 * interface.
62.18/19.59 *
62.18/19.59 *
This interface is a member of the
62.18/19.59 *
62.18/19.59 * Java Collections Framework.
62.18/19.59 *
62.18/19.59 * @author Josh Bloch
62.18/19.59 * @author Neal Gafter
62.18/19.59 * @see Collection
62.18/19.59 * @see Set
62.18/19.59 * @see ArrayList
62.18/19.59 * @see LinkedList
62.18/19.59 * @see Vector
62.18/19.59 * @see Arrays#asList(Object[])
62.18/19.59 * @see Collections#nCopies(int, Object)
62.18/19.59 * @see Collections#EMPTY_LIST
62.18/19.59 * @see AbstractList
62.18/19.59 * @see AbstractSequentialList
62.18/19.59 * @since 1.2
62.18/19.59 */
62.18/19.59
62.18/19.59 public interface List extends Collection {
62.18/19.59 // Query Operations
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns the number of elements in this list. If this list contains
62.18/19.59 * more than Integer.MAX_VALUE elements, returns
62.18/19.59 * Integer.MAX_VALUE.
62.18/19.59 *
62.18/19.59 * @return the number of elements in this list
62.18/19.59 */
62.18/19.59 int size();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns true if this list contains no elements.
62.18/19.59 *
62.18/19.59 * @return true if this list contains no elements
62.18/19.59 */
62.18/19.59 boolean isEmpty();
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns true if this list contains the specified element.
62.18/19.59 * More formally, returns true if and only if this list contains
62.18/19.59 * at least one element e such that
62.18/19.59 * (o==null ? e==null : o.equals(e)).
62.18/19.59 *
62.18/19.59 * @param o element whose presence in this list is to be tested
62.18/19.59 * @return true if this list contains the specified element
62.18/19.59 * @throws ClassCastException if the type of the specified element
62.18/19.59 * is incompatible with this list (optional)
62.18/19.59 * @throws NullPointerException if the specified element is null and this
62.18/19.59 * list does not permit null elements (optional)
62.18/19.59 */
62.18/19.59 boolean contains(Object o);
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns an iterator over the elements in this list in proper sequence.
62.18/19.59 *
62.18/19.59 * @return an iterator over the elements in this list in proper sequence
62.18/19.59 */
62.18/19.59 Iterator iterator();
62.18/19.59
62.18/19.59 // Modification Operations
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Appends the specified element to the end of this list (optional
62.18/19.59 * operation).
62.18/19.59 *
62.18/19.59 * Lists that support this operation may place limitations on what
62.18/19.59 * elements may be added to this list. In particular, some
62.18/19.59 * lists will refuse to add null elements, and others will impose
62.18/19.59 * restrictions on the type of elements that may be added. List
62.18/19.59 * classes should clearly specify in their documentation any restrictions
62.18/19.59 * on what elements may be added.
62.18/19.59 *
62.18/19.59 * @param e element to be appended to this list
62.18/19.59 * @return true (as specified by {@link Collection#add})
62.18/19.59 * @throws UnsupportedOperationException if the add operation
62.18/19.59 * is not supported by this list
62.18/19.59 * @throws ClassCastException if the class of the specified element
62.18/19.59 * prevents it from being added to this list
62.18/19.59 * @throws NullPointerException if the specified element is null and this
62.18/19.59 * list does not permit null elements
62.18/19.59 * @throws IllegalArgumentException if some property of this element
62.18/19.59 * prevents it from being added to this list
62.18/19.59 */
62.18/19.59 boolean add(E e);
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Removes the first occurrence of the specified element from this list,
62.18/19.59 * if it is present (optional operation). If this list does not contain
62.18/19.59 * the element, it is unchanged. More formally, removes the element with
62.18/19.59 * the lowest index i such that
62.18/19.59 * (o==null ? get(i)==null : o.equals(get(i)))
62.18/19.59 * (if such an element exists). Returns true if this list
62.18/19.59 * contained the specified element (or equivalently, if this list changed
62.18/19.59 * as a result of the call).
62.18/19.59 *
62.18/19.59 * @param o element to be removed from this list, if present
62.18/19.59 * @return true if this list contained the specified element
62.18/19.59 * @throws ClassCastException if the type of the specified element
62.18/19.59 * is incompatible with this list (optional)
62.18/19.59 * @throws NullPointerException if the specified element is null and this
62.18/19.59 * list does not permit null elements (optional)
62.18/19.59 * @throws UnsupportedOperationException if the remove operation
62.18/19.59 * is not supported by this list
62.18/19.59 */
62.18/19.59 boolean remove(Object o);
62.18/19.59
62.18/19.59
62.18/19.59 // Bulk Modification Operations
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Returns true if this list contains all of the elements of the
62.18/19.59 * specified collection.
62.18/19.59 *
62.18/19.59 * @param c collection to be checked for containment in this list
62.18/19.59 * @return true if this list contains all of the elements of the
62.18/19.59 * specified collection
62.18/19.59 * @throws ClassCastException if the types of one or more elements
62.18/19.59 * in the specified collection are incompatible with this
62.18/19.59 * list (optional)
62.18/19.59 * @throws NullPointerException if the specified collection contains one
62.18/19.59 * or more null elements and this list does not permit null
62.18/19.59 * elements (optional), or if the specified collection is null
62.18/19.59 * @see #contains(Object)
62.18/19.59 */
62.18/19.59 boolean containsAll(Collection c);
62.18/19.59
62.18/19.59 /**
62.18/19.59 * Appends all of the elements in the specified collection to the end of
62.18/19.59 * this list, in the order that they are returned by the specified
62.18/19.59 * collection's iterator (optional operation). The behavior of this
62.18/19.59 * operation is undefined if the specified collection is modified while
62.18/19.59 * the operation is in progress. (Note that this will occur if the
62.18/19.59 * specified collection is this list, and it's nonempty.)
62.18/19.60 *
62.18/19.60 * @param c collection containing elements to be added to this list
62.18/19.60 * @return true if this list changed as a result of the call
62.18/19.60 * @throws UnsupportedOperationException if the addAll operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws ClassCastException if the class of an element of the specified
62.18/19.60 * collection prevents it from being added to this list
62.18/19.60 * @throws NullPointerException if the specified collection contains one
62.18/19.60 * or more null elements and this list does not permit null
62.18/19.60 * elements, or if the specified collection is null
62.18/19.60 * @throws IllegalArgumentException if some property of an element of the
62.18/19.60 * specified collection prevents it from being added to this list
62.18/19.60 * @see #add(Object)
62.18/19.60 */
62.18/19.60 boolean addAll(Collection c);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Inserts all of the elements in the specified collection into this
62.18/19.60 * list at the specified position (optional operation). Shifts the
62.18/19.60 * element currently at that position (if any) and any subsequent
62.18/19.60 * elements to the right (increases their indices). The new elements
62.18/19.60 * will appear in this list in the order that they are returned by the
62.18/19.60 * specified collection's iterator. The behavior of this operation is
62.18/19.60 * undefined if the specified collection is modified while the
62.18/19.60 * operation is in progress. (Note that this will occur if the specified
62.18/19.60 * collection is this list, and it's nonempty.)
62.18/19.60 *
62.18/19.60 * @param index index at which to insert the first element from the
62.18/19.60 * specified collection
62.18/19.60 * @param c collection containing elements to be added to this list
62.18/19.60 * @return true if this list changed as a result of the call
62.18/19.60 * @throws UnsupportedOperationException if the addAll operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws ClassCastException if the class of an element of the specified
62.18/19.60 * collection prevents it from being added to this list
62.18/19.60 * @throws NullPointerException if the specified collection contains one
62.18/19.60 * or more null elements and this list does not permit null
62.18/19.60 * elements, or if the specified collection is null
62.18/19.60 * @throws IllegalArgumentException if some property of an element of the
62.18/19.60 * specified collection prevents it from being added to this list
62.18/19.60 * @throws IndexOutOfBoundsException if the index is out of range
62.18/19.60 * (index < 0 || index > size())
62.18/19.60 */
62.18/19.60 boolean addAll(int index, Collection c);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Removes from this list all of its elements that are contained in the
62.18/19.60 * specified collection (optional operation).
62.18/19.60 *
62.18/19.60 * @param c collection containing elements to be removed from this list
62.18/19.60 * @return true if this list changed as a result of the call
62.18/19.60 * @throws UnsupportedOperationException if the removeAll operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws ClassCastException if the class of an element of this list
62.18/19.60 * is incompatible with the specified collection (optional)
62.18/19.60 * @throws NullPointerException if this list contains a null element and the
62.18/19.60 * specified collection does not permit null elements (optional),
62.18/19.60 * or if the specified collection is null
62.18/19.60 * @see #remove(Object)
62.18/19.60 * @see #contains(Object)
62.18/19.60 */
62.18/19.60 boolean removeAll(Collection c);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Retains only the elements in this list that are contained in the
62.18/19.60 * specified collection (optional operation). In other words, removes
62.18/19.60 * from this list all of its elements that are not contained in the
62.18/19.60 * specified collection.
62.18/19.60 *
62.18/19.60 * @param c collection containing elements to be retained in this list
62.18/19.60 * @return true if this list changed as a result of the call
62.18/19.60 * @throws UnsupportedOperationException if the retainAll operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws ClassCastException if the class of an element of this list
62.18/19.60 * is incompatible with the specified collection (optional)
62.18/19.60 * @throws NullPointerException if this list contains a null element and the
62.18/19.60 * specified collection does not permit null elements (optional),
62.18/19.60 * or if the specified collection is null
62.18/19.60 * @see #remove(Object)
62.18/19.60 * @see #contains(Object)
62.18/19.60 */
62.18/19.60 boolean retainAll(Collection c);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Removes all of the elements from this list (optional operation).
62.18/19.60 * The list will be empty after this call returns.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException if the clear operation
62.18/19.60 * is not supported by this list
62.18/19.60 */
62.18/19.60 void clear();
62.18/19.60
62.18/19.60
62.18/19.60 // Comparison and hashing
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Compares the specified object with this list for equality. Returns
62.18/19.60 * true if and only if the specified object is also a list, both
62.18/19.60 * lists have the same size, and all corresponding pairs of elements in
62.18/19.60 * the two lists are equal. (Two elements e1 and
62.18/19.60 * e2 are equal if (e1==null ? e2==null :
62.18/19.60 * e1.equals(e2)).) In other words, two lists are defined to be
62.18/19.60 * equal if they contain the same elements in the same order. This
62.18/19.60 * definition ensures that the equals method works properly across
62.18/19.60 * different implementations of the List interface.
62.18/19.60 *
62.18/19.60 * @param o the object to be compared for equality with this list
62.18/19.60 * @return true if the specified object is equal to this list
62.18/19.60 */
62.18/19.60 boolean equals(Object o);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns the hash code value for this list. The hash code of a list
62.18/19.60 * is defined to be the result of the following calculation:
62.18/19.60 *
62.18/19.60 * int hashCode = 1;
62.18/19.60 * for (E e : list)
62.18/19.60 * hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
62.18/19.60 *
62.18/19.60 * This ensures that list1.equals(list2) implies that
62.18/19.60 * list1.hashCode()==list2.hashCode() for any two lists,
62.18/19.60 * list1 and list2, as required by the general
62.18/19.60 * contract of {@link Object#hashCode}.
62.18/19.60 *
62.18/19.60 * @return the hash code value for this list
62.18/19.60 * @see Object#equals(Object)
62.18/19.60 * @see #equals(Object)
62.18/19.60 */
62.18/19.60 int hashCode();
62.18/19.60
62.18/19.60
62.18/19.60 // Positional Access Operations
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns the element at the specified position in this list.
62.18/19.60 *
62.18/19.60 * @param index index of the element to return
62.18/19.60 * @return the element at the specified position in this list
62.18/19.60 * @throws IndexOutOfBoundsException if the index is out of range
62.18/19.60 * (index < 0 || index >= size())
62.18/19.60 */
62.18/19.60 E get(int index);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Replaces the element at the specified position in this list with the
62.18/19.60 * specified element (optional operation).
62.18/19.60 *
62.18/19.60 * @param index index of the element to replace
62.18/19.60 * @param element element to be stored at the specified position
62.18/19.60 * @return the element previously at the specified position
62.18/19.60 * @throws UnsupportedOperationException if the set operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws ClassCastException if the class of the specified element
62.18/19.60 * prevents it from being added to this list
62.18/19.60 * @throws NullPointerException if the specified element is null and
62.18/19.60 * this list does not permit null elements
62.18/19.60 * @throws IllegalArgumentException if some property of the specified
62.18/19.60 * element prevents it from being added to this list
62.18/19.60 * @throws IndexOutOfBoundsException if the index is out of range
62.18/19.60 * (index < 0 || index >= size())
62.18/19.60 */
62.18/19.60 E set(int index, E element);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Inserts the specified element at the specified position in this list
62.18/19.60 * (optional operation). Shifts the element currently at that position
62.18/19.60 * (if any) and any subsequent elements to the right (adds one to their
62.18/19.60 * indices).
62.18/19.60 *
62.18/19.60 * @param index index at which the specified element is to be inserted
62.18/19.60 * @param element element to be inserted
62.18/19.60 * @throws UnsupportedOperationException if the add operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws ClassCastException if the class of the specified element
62.18/19.60 * prevents it from being added to this list
62.18/19.60 * @throws NullPointerException if the specified element is null and
62.18/19.60 * this list does not permit null elements
62.18/19.60 * @throws IllegalArgumentException if some property of the specified
62.18/19.60 * element prevents it from being added to this list
62.18/19.60 * @throws IndexOutOfBoundsException if the index is out of range
62.18/19.60 * (index < 0 || index > size())
62.18/19.60 */
62.18/19.60 void add(int index, E element);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Removes the element at the specified position in this list (optional
62.18/19.60 * operation). Shifts any subsequent elements to the left (subtracts one
62.18/19.60 * from their indices). Returns the element that was removed from the
62.18/19.60 * list.
62.18/19.60 *
62.18/19.60 * @param index the index of the element to be removed
62.18/19.60 * @return the element previously at the specified position
62.18/19.60 * @throws UnsupportedOperationException if the remove operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws IndexOutOfBoundsException if the index is out of range
62.18/19.60 * (index < 0 || index >= size())
62.18/19.60 */
62.18/19.60 E remove(int index);
62.18/19.60
62.18/19.60
62.18/19.60 // Search Operations
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns the index of the first occurrence of the specified element
62.18/19.60 * in this list, or -1 if this list does not contain the element.
62.18/19.60 * More formally, returns the lowest index i such that
62.18/19.60 * (o==null ? get(i)==null : o.equals(get(i))),
62.18/19.60 * or -1 if there is no such index.
62.18/19.60 *
62.18/19.60 * @param o element to search for
62.18/19.60 * @return the index of the first occurrence of the specified element in
62.18/19.60 * this list, or -1 if this list does not contain the element
62.18/19.60 * @throws ClassCastException if the type of the specified element
62.18/19.60 * is incompatible with this list (optional)
62.18/19.60 * @throws NullPointerException if the specified element is null and this
62.18/19.60 * list does not permit null elements (optional)
62.18/19.60 */
62.18/19.60 int indexOf(Object o);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns the index of the last occurrence of the specified element
62.18/19.60 * in this list, or -1 if this list does not contain the element.
62.18/19.60 * More formally, returns the highest index i such that
62.18/19.60 * (o==null ? get(i)==null : o.equals(get(i))),
62.18/19.60 * or -1 if there is no such index.
62.18/19.60 *
62.18/19.60 * @param o element to search for
62.18/19.60 * @return the index of the last occurrence of the specified element in
62.18/19.60 * this list, or -1 if this list does not contain the element
62.18/19.60 * @throws ClassCastException if the type of the specified element
62.18/19.60 * is incompatible with this list (optional)
62.18/19.60 * @throws NullPointerException if the specified element is null and this
62.18/19.60 * list does not permit null elements (optional)
62.18/19.60 */
62.18/19.60 int lastIndexOf(Object o);
62.18/19.60
62.18/19.60
62.18/19.60 // List Iterators
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns a list iterator over the elements in this list (in proper
62.18/19.60 * sequence).
62.18/19.60 *
62.18/19.60 * @return a list iterator over the elements in this list (in proper
62.18/19.60 * sequence)
62.18/19.60 */
62.18/19.60 ListIterator listIterator();
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns a list iterator over the elements in this list (in proper
62.18/19.60 * sequence), starting at the specified position in the list.
62.18/19.60 * The specified index indicates the first element that would be
62.18/19.60 * returned by an initial call to {@link ListIterator#next next}.
62.18/19.60 * An initial call to {@link ListIterator#previous previous} would
62.18/19.60 * return the element with the specified index minus one.
62.18/19.60 *
62.18/19.60 * @param index index of the first element to be returned from the
62.18/19.60 * list iterator (by a call to {@link ListIterator#next next})
62.18/19.60 * @return a list iterator over the elements in this list (in proper
62.18/19.60 * sequence), starting at the specified position in the list
62.18/19.60 * @throws IndexOutOfBoundsException if the index is out of range
62.18/19.60 * ({@code index < 0 || index > size()})
62.18/19.60 */
62.18/19.60 ListIterator listIterator(int index);
62.18/19.60
62.18/19.60 // View
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns a view of the portion of this list between the specified
62.18/19.60 * fromIndex, inclusive, and toIndex, exclusive. (If
62.18/19.60 * fromIndex and toIndex are equal, the returned list is
62.18/19.60 * empty.) The returned list is backed by this list, so non-structural
62.18/19.60 * changes in the returned list are reflected in this list, and vice-versa.
62.18/19.60 * The returned list supports all of the optional list operations supported
62.18/19.60 * by this list.
62.18/19.60 *
62.18/19.60 * This method eliminates the need for explicit range operations (of
62.18/19.60 * the sort that commonly exist for arrays). Any operation that expects
62.18/19.60 * a list can be used as a range operation by passing a subList view
62.18/19.60 * instead of a whole list. For example, the following idiom
62.18/19.60 * removes a range of elements from a list:
62.18/19.60 *
62.18/19.60 * list.subList(from, to).clear();
62.18/19.60 *
62.18/19.60 * Similar idioms may be constructed for indexOf and
62.18/19.60 * lastIndexOf, and all of the algorithms in the
62.18/19.60 * Collections class can be applied to a subList.
62.18/19.60 *
62.18/19.60 * The semantics of the list returned by this method become undefined if
62.18/19.60 * the backing list (i.e., this list) is structurally modified in
62.18/19.60 * any way other than via the returned list. (Structural modifications are
62.18/19.60 * those that change the size of this list, or otherwise perturb it in such
62.18/19.60 * a fashion that iterations in progress may yield incorrect results.)
62.18/19.60 *
62.18/19.60 * @param fromIndex low endpoint (inclusive) of the subList
62.18/19.60 * @param toIndex high endpoint (exclusive) of the subList
62.18/19.60 * @return a view of the specified range within this list
62.18/19.60 * @throws IndexOutOfBoundsException for an illegal endpoint index value
62.18/19.60 * (fromIndex < 0 || toIndex > size ||
62.18/19.60 * fromIndex > toIndex)
62.18/19.60 */
62.18/19.60 List subList(int fromIndex, int toIndex);
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 /*
62.18/19.60 * Copyright 1994-1998 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.60 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.60 *
62.18/19.60 * This code is free software; you can redistribute it and/or modify it
62.18/19.60 * under the terms of the GNU General Public License version 2 only, as
62.18/19.60 * published by the Free Software Foundation. Sun designates this
62.18/19.60 * particular file as subject to the "Classpath" exception as provided
62.18/19.60 * by Sun in the LICENSE file that accompanied this code.
62.18/19.60 *
62.18/19.60 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.60 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.60 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.60 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.60 * accompanied this code).
62.18/19.60 *
62.18/19.60 * You should have received a copy of the GNU General Public License version
62.18/19.60 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.60 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.60 *
62.18/19.60 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.60 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.60 * have any questions.
62.18/19.60 */
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Thrown by the nextElement method of an
62.18/19.60 * Enumeration to indicate that there are no more
62.18/19.60 * elements in the enumeration.
62.18/19.60 *
62.18/19.60 * @author unascribed
62.18/19.60 * @see java.util.Enumeration
62.18/19.60 * @see java.util.Enumeration#nextElement()
62.18/19.60 * @since JDK1.0
62.18/19.60 */
62.18/19.60 public
62.18/19.60 class NoSuchElementException extends RuntimeException {
62.18/19.60 /**
62.18/19.60 * Constructs a NoSuchElementException with null
62.18/19.60 * as its error message string.
62.18/19.60 */
62.18/19.60 public NoSuchElementException() {
62.18/19.60 super();
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Constructs a NoSuchElementException, saving a reference
62.18/19.60 * to the error message string s for later retrieval by the
62.18/19.60 * getMessage method.
62.18/19.60 *
62.18/19.60 * @param s the detail message.
62.18/19.60 */
62.18/19.60 public NoSuchElementException(String s) {
62.18/19.60 super(s);
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 /*
62.18/19.60 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.60 *
62.18/19.60 * This code is free software; you can redistribute it and/or modify it
62.18/19.60 * under the terms of the GNU General Public License version 2 only, as
62.18/19.60 * published by the Free Software Foundation. Sun designates this
62.18/19.60 * particular file as subject to the "Classpath" exception as provided
62.18/19.60 * by Sun in the LICENSE file that accompanied this code.
62.18/19.60 *
62.18/19.60 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.60 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.60 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.60 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.60 * accompanied this code).
62.18/19.60 *
62.18/19.60 * You should have received a copy of the GNU General Public License version
62.18/19.60 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.60 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.60 *
62.18/19.60 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.60 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.60 * have any questions.
62.18/19.60 */
62.18/19.60
62.18/19.60 /*
62.18/19.60 * This file is available under and governed by the GNU General Public
62.18/19.60 * License version 2 only, as published by the Free Software Foundation.
62.18/19.60 * However, the following notice accompanied the original version of this
62.18/19.60 * file:
62.18/19.60 *
62.18/19.60 * Written by Doug Lea with assistance from members of JCP JSR-166
62.18/19.60 * Expert Group and released to the public domain, as explained at
62.18/19.60 * http://creativecommons.org/licenses/publicdomain
62.18/19.60 */
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * A collection designed for holding elements prior to processing.
62.18/19.60 * Besides basic {@link java.util.Collection Collection} operations,
62.18/19.60 * queues provide additional insertion, extraction, and inspection
62.18/19.60 * operations. Each of these methods exists in two forms: one throws
62.18/19.60 * an exception if the operation fails, the other returns a special
62.18/19.60 * value (either null or false, depending on the
62.18/19.60 * operation). The latter form of the insert operation is designed
62.18/19.60 * specifically for use with capacity-restricted Queue
62.18/19.60 * implementations; in most implementations, insert operations cannot
62.18/19.60 * fail.
62.18/19.60 *
62.18/19.60 *
62.18/19.60 *
62.18/19.60 *
62.18/19.60 * |
62.18/19.60 * Throws exception |
62.18/19.60 * Returns special value |
62.18/19.60 *
62.18/19.60 *
62.18/19.60 * | Insert |
62.18/19.60 * {@link #add add(e)} |
62.18/19.60 * {@link #offer offer(e)} |
62.18/19.60 *
62.18/19.60 *
62.18/19.60 * | Remove |
62.18/19.60 * {@link #remove remove()} |
62.18/19.60 * {@link #poll poll()} |
62.18/19.60 *
62.18/19.60 *
62.18/19.60 * | Examine |
62.18/19.60 * {@link #element element()} |
62.18/19.60 * {@link #peek peek()} |
62.18/19.60 *
62.18/19.60 *
62.18/19.60 *
62.18/19.60 * Queues typically, but do not necessarily, order elements in a
62.18/19.60 * FIFO (first-in-first-out) manner. Among the exceptions are
62.18/19.60 * priority queues, which order elements according to a supplied
62.18/19.60 * comparator, or the elements' natural ordering, and LIFO queues (or
62.18/19.60 * stacks) which order the elements LIFO (last-in-first-out).
62.18/19.60 * Whatever the ordering used, the head of the queue is that
62.18/19.60 * element which would be removed by a call to {@link #remove() } or
62.18/19.60 * {@link #poll()}. In a FIFO queue, all new elements are inserted at
62.18/19.60 * the tail of the queue. Other kinds of queues may use
62.18/19.60 * different placement rules. Every Queue implementation
62.18/19.60 * must specify its ordering properties.
62.18/19.60 *
62.18/19.60 *
The {@link #offer offer} method inserts an element if possible,
62.18/19.60 * otherwise returning false. This differs from the {@link
62.18/19.60 * java.util.Collection#add Collection.add} method, which can fail to
62.18/19.60 * add an element only by throwing an unchecked exception. The
62.18/19.60 * offer method is designed for use when failure is a normal,
62.18/19.60 * rather than exceptional occurrence, for example, in fixed-capacity
62.18/19.60 * (or "bounded") queues.
62.18/19.60 *
62.18/19.60 *
The {@link #remove()} and {@link #poll()} methods remove and
62.18/19.60 * return the head of the queue.
62.18/19.60 * Exactly which element is removed from the queue is a
62.18/19.60 * function of the queue's ordering policy, which differs from
62.18/19.60 * implementation to implementation. The remove() and
62.18/19.60 * poll() methods differ only in their behavior when the
62.18/19.60 * queue is empty: the remove() method throws an exception,
62.18/19.60 * while the poll() method returns null.
62.18/19.60 *
62.18/19.60 *
The {@link #element()} and {@link #peek()} methods return, but do
62.18/19.60 * not remove, the head of the queue.
62.18/19.60 *
62.18/19.60 *
The Queue interface does not define the blocking queue
62.18/19.60 * methods, which are common in concurrent programming. These methods,
62.18/19.60 * which wait for elements to appear or for space to become available, are
62.18/19.60 * defined in the {@link java.util.concurrent.BlockingQueue} interface, which
62.18/19.60 * extends this interface.
62.18/19.60 *
62.18/19.60 *
Queue implementations generally do not allow insertion
62.18/19.60 * of null elements, although some implementations, such as
62.18/19.60 * {@link LinkedList}, do not prohibit insertion of null.
62.18/19.60 * Even in the implementations that permit it, null should
62.18/19.60 * not be inserted into a Queue, as null is also
62.18/19.60 * used as a special return value by the poll method to
62.18/19.60 * indicate that the queue contains no elements.
62.18/19.60 *
62.18/19.60 *
Queue implementations generally do not define
62.18/19.60 * element-based versions of methods equals and
62.18/19.60 * hashCode but instead inherit the identity based versions
62.18/19.60 * from class Object, because element-based equality is not
62.18/19.60 * always well-defined for queues with the same elements but different
62.18/19.60 * ordering properties.
62.18/19.60 *
62.18/19.60 *
62.18/19.60 *
This interface is a member of the
62.18/19.60 *
62.18/19.60 * Java Collections Framework.
62.18/19.60 *
62.18/19.60 * @see java.util.Collection
62.18/19.60 * @see LinkedList
62.18/19.60 * @see PriorityQueue
62.18/19.60 * @see java.util.concurrent.LinkedBlockingQueue
62.18/19.60 * @see java.util.concurrent.BlockingQueue
62.18/19.60 * @see java.util.concurrent.ArrayBlockingQueue
62.18/19.60 * @see java.util.concurrent.LinkedBlockingQueue
62.18/19.60 * @see java.util.concurrent.PriorityBlockingQueue
62.18/19.60 * @since 1.5
62.18/19.60 * @author Doug Lea
62.18/19.60 * @param the type of elements held in this collection
62.18/19.60 */
62.18/19.60 public interface Queue extends Collection {
62.18/19.60 /**
62.18/19.60 * Inserts the specified element into this queue if it is possible to do so
62.18/19.60 * immediately without violating capacity restrictions, returning
62.18/19.60 * true upon success and throwing an IllegalStateException
62.18/19.60 * if no space is currently available.
62.18/19.60 *
62.18/19.60 * @param e the element to add
62.18/19.60 * @return true (as specified by {@link Collection#add})
62.18/19.60 * @throws IllegalStateException if the element cannot be added at this
62.18/19.60 * time due to capacity restrictions
62.18/19.60 * @throws ClassCastException if the class of the specified element
62.18/19.60 * prevents it from being added to this queue
62.18/19.60 * @throws NullPointerException if the specified element is null and
62.18/19.60 * this queue does not permit null elements
62.18/19.60 * @throws IllegalArgumentException if some property of this element
62.18/19.60 * prevents it from being added to this queue
62.18/19.60 */
62.18/19.60 boolean add(E e);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Inserts the specified element into this queue if it is possible to do
62.18/19.60 * so immediately without violating capacity restrictions.
62.18/19.60 * When using a capacity-restricted queue, this method is generally
62.18/19.60 * preferable to {@link #add}, which can fail to insert an element only
62.18/19.60 * by throwing an exception.
62.18/19.60 *
62.18/19.60 * @param e the element to add
62.18/19.60 * @return true if the element was added to this queue, else
62.18/19.60 * false
62.18/19.60 * @throws ClassCastException if the class of the specified element
62.18/19.60 * prevents it from being added to this queue
62.18/19.60 * @throws NullPointerException if the specified element is null and
62.18/19.60 * this queue does not permit null elements
62.18/19.60 * @throws IllegalArgumentException if some property of this element
62.18/19.60 * prevents it from being added to this queue
62.18/19.60 */
62.18/19.60 boolean offer(E e);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Retrieves and removes the head of this queue. This method differs
62.18/19.60 * from {@link #poll poll} only in that it throws an exception if this
62.18/19.60 * queue is empty.
62.18/19.60 *
62.18/19.60 * @return the head of this queue
62.18/19.60 * @throws NoSuchElementException if this queue is empty
62.18/19.60 */
62.18/19.60 E remove();
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Retrieves and removes the head of this queue,
62.18/19.60 * or returns null if this queue is empty.
62.18/19.60 *
62.18/19.60 * @return the head of this queue, or null if this queue is empty
62.18/19.60 */
62.18/19.60 E poll();
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Retrieves, but does not remove, the head of this queue. This method
62.18/19.60 * differs from {@link #peek peek} only in that it throws an exception
62.18/19.60 * if this queue is empty.
62.18/19.60 *
62.18/19.60 * @return the head of this queue
62.18/19.60 * @throws NoSuchElementException if this queue is empty
62.18/19.60 */
62.18/19.60 E element();
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Retrieves, but does not remove, the head of this queue,
62.18/19.60 * or returns null if this queue is empty.
62.18/19.60 *
62.18/19.60 * @return the head of this queue, or null if this queue is empty
62.18/19.60 */
62.18/19.60 E peek();
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 /*
62.18/19.60 * Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.60 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.60 *
62.18/19.60 * This code is free software; you can redistribute it and/or modify it
62.18/19.60 * under the terms of the GNU General Public License version 2 only, as
62.18/19.60 * published by the Free Software Foundation. Sun designates this
62.18/19.60 * particular file as subject to the "Classpath" exception as provided
62.18/19.60 * by Sun in the LICENSE file that accompanied this code.
62.18/19.60 *
62.18/19.60 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.60 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.60 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.60 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.60 * accompanied this code).
62.18/19.60 *
62.18/19.60 * You should have received a copy of the GNU General Public License version
62.18/19.60 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.60 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.60 *
62.18/19.60 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.60 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.60 * have any questions.
62.18/19.60 */
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Marker interface used by List implementations to indicate that
62.18/19.60 * they support fast (generally constant time) random access. The primary
62.18/19.60 * purpose of this interface is to allow generic algorithms to alter their
62.18/19.60 * behavior to provide good performance when applied to either random or
62.18/19.60 * sequential access lists.
62.18/19.60 *
62.18/19.60 * The best algorithms for manipulating random access lists (such as
62.18/19.60 * ArrayList) can produce quadratic behavior when applied to
62.18/19.60 * sequential access lists (such as LinkedList). Generic list
62.18/19.60 * algorithms are encouraged to check whether the given list is an
62.18/19.60 * instanceof this interface before applying an algorithm that would
62.18/19.60 * provide poor performance if it were applied to a sequential access list,
62.18/19.60 * and to alter their behavior if necessary to guarantee acceptable
62.18/19.60 * performance.
62.18/19.60 *
62.18/19.60 *
It is recognized that the distinction between random and sequential
62.18/19.60 * access is often fuzzy. For example, some List implementations
62.18/19.60 * provide asymptotically linear access times if they get huge, but constant
62.18/19.60 * access times in practice. Such a List implementation
62.18/19.60 * should generally implement this interface. As a rule of thumb, a
62.18/19.60 * List implementation should implement this interface if,
62.18/19.60 * for typical instances of the class, this loop:
62.18/19.60 *
62.18/19.60 * for (int i=0, n=list.size(); i < n; i++)
62.18/19.60 * list.get(i);
62.18/19.60 *
62.18/19.60 * runs faster than this loop:
62.18/19.60 *
62.18/19.60 * for (Iterator i=list.iterator(); i.hasNext(); )
62.18/19.60 * i.next();
62.18/19.60 *
62.18/19.60 *
62.18/19.60 * This interface is a member of the
62.18/19.60 *
62.18/19.60 * Java Collections Framework.
62.18/19.60 *
62.18/19.60 * @since 1.4
62.18/19.60 */
62.18/19.60 public interface RandomAccess {
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 public class Random {
62.18/19.60 static String[] args;
62.18/19.60 static int index = 0;
62.18/19.60
62.18/19.60 public static int random() {
62.18/19.60 String string = args[index];
62.18/19.60 index++;
62.18/19.60 return string.length();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 /*
62.18/19.60 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.60 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.60 *
62.18/19.60 * This code is free software; you can redistribute it and/or modify it
62.18/19.60 * under the terms of the GNU General Public License version 2 only, as
62.18/19.60 * published by the Free Software Foundation. Sun designates this
62.18/19.60 * particular file as subject to the "Classpath" exception as provided
62.18/19.60 * by Sun in the LICENSE file that accompanied this code.
62.18/19.60 *
62.18/19.60 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.60 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.60 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.60 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.60 * accompanied this code).
62.18/19.60 *
62.18/19.60 * You should have received a copy of the GNU General Public License version
62.18/19.60 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.60 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.60 *
62.18/19.60 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.60 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.60 * have any questions.
62.18/19.60 */
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Thrown to indicate that the requested operation is not supported.
62.18/19.60 *
62.18/19.60 * This class is a member of the
62.18/19.60 *
62.18/19.60 * Java Collections Framework.
62.18/19.60 *
62.18/19.60 * @author Josh Bloch
62.18/19.60 * @since 1.2
62.18/19.60 */
62.18/19.60 public class UnsupportedOperationException extends RuntimeException {
62.18/19.60 /**
62.18/19.60 * Constructs an UnsupportedOperationException with no detail message.
62.18/19.60 */
62.18/19.60 public UnsupportedOperationException() {
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Constructs an UnsupportedOperationException with the specified
62.18/19.60 * detail message.
62.18/19.60 *
62.18/19.60 * @param message the detail message
62.18/19.60 */
62.18/19.60 public UnsupportedOperationException(String message) {
62.18/19.60 super(message);
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Constructs a new exception with the specified detail message and
62.18/19.60 * cause.
62.18/19.60 *
62.18/19.60 *
Note that the detail message associated with cause is
62.18/19.60 * not automatically incorporated in this exception's detail
62.18/19.60 * message.
62.18/19.60 *
62.18/19.60 * @param message the detail message (which is saved for later retrieval
62.18/19.60 * by the {@link Throwable#getMessage()} method).
62.18/19.60 * @param cause the cause (which is saved for later retrieval by the
62.18/19.60 * {@link Throwable#getCause()} method). (A null value
62.18/19.60 * is permitted, and indicates that the cause is nonexistent or
62.18/19.60 * unknown.)
62.18/19.60 * @since 1.5
62.18/19.60 */
62.18/19.60 public UnsupportedOperationException(String message, Throwable cause) {
62.18/19.60 super(message, cause);
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Constructs a new exception with the specified cause and a detail
62.18/19.60 * message of (cause==null ? null : cause.toString()) (which
62.18/19.60 * typically contains the class and detail message of cause).
62.18/19.60 * This constructor is useful for exceptions that are little more than
62.18/19.60 * wrappers for other throwables (for example, {@link
62.18/19.60 * java.security.PrivilegedActionException}).
62.18/19.60 *
62.18/19.60 * @param cause the cause (which is saved for later retrieval by the
62.18/19.60 * {@link Throwable#getCause()} method). (A null value is
62.18/19.60 * permitted, and indicates that the cause is nonexistent or
62.18/19.60 * unknown.)
62.18/19.60 * @since 1.5
62.18/19.60 */
62.18/19.60 public UnsupportedOperationException(Throwable cause) {
62.18/19.60 super(cause);
62.18/19.60 }
62.18/19.60
62.18/19.60 static final long serialVersionUID = -1242599979055084673L;
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60
62.18/19.60 ----------------------------------------
62.18/19.60
62.18/19.60 (1) BareJBCToJBCProof (EQUIVALENT)
62.18/19.60 initialized classpath
62.18/19.60 ----------------------------------------
62.18/19.60
62.18/19.60 (2)
62.18/19.60 Obligation:
62.18/19.60 need to prove termination of the following program:
62.18/19.60 /*
62.18/19.60 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.60 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.60 *
62.18/19.60 * This code is free software; you can redistribute it and/or modify it
62.18/19.60 * under the terms of the GNU General Public License version 2 only, as
62.18/19.60 * published by the Free Software Foundation. Sun designates this
62.18/19.60 * particular file as subject to the "Classpath" exception as provided
62.18/19.60 * by Sun in the LICENSE file that accompanied this code.
62.18/19.60 *
62.18/19.60 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.60 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.60 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.60 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.60 * accompanied this code).
62.18/19.60 *
62.18/19.60 * You should have received a copy of the GNU General Public License version
62.18/19.60 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.60 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.60 *
62.18/19.60 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.60 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.60 * have any questions.
62.18/19.60 */
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * This class provides a skeletal implementation of the Collection
62.18/19.60 * interface, to minimize the effort required to implement this interface.
62.18/19.60 *
62.18/19.60 * To implement an unmodifiable collection, the programmer needs only to
62.18/19.60 * extend this class and provide implementations for the iterator and
62.18/19.60 * size methods. (The iterator returned by the iterator
62.18/19.60 * method must implement hasNext and next.)
62.18/19.60 *
62.18/19.60 * To implement a modifiable collection, the programmer must additionally
62.18/19.60 * override this class's add method (which otherwise throws an
62.18/19.60 * UnsupportedOperationException), and the iterator returned by the
62.18/19.60 * iterator method must additionally implement its remove
62.18/19.60 * method.
62.18/19.60 *
62.18/19.60 * The programmer should generally provide a void (no argument) and
62.18/19.60 * Collection constructor, as per the recommendation in the
62.18/19.60 * Collection interface specification.
62.18/19.60 *
62.18/19.60 * The documentation for each non-abstract method in this class describes its
62.18/19.60 * implementation in detail. Each of these methods may be overridden if
62.18/19.60 * the collection being implemented admits a more efficient implementation.
62.18/19.60 *
62.18/19.60 * This class is a member of the
62.18/19.60 *
62.18/19.60 * Java Collections Framework.
62.18/19.60 *
62.18/19.60 * @author Josh Bloch
62.18/19.60 * @author Neal Gafter
62.18/19.60 * @see Collection
62.18/19.60 * @since 1.2
62.18/19.60 */
62.18/19.60
62.18/19.60 public abstract class AbstractCollection implements Collection {
62.18/19.60 /**
62.18/19.60 * Sole constructor. (For invocation by subclass constructors, typically
62.18/19.60 * implicit.)
62.18/19.60 */
62.18/19.60 protected AbstractCollection() {
62.18/19.60 }
62.18/19.60
62.18/19.60 // Query Operations
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns an iterator over the elements contained in this collection.
62.18/19.60 *
62.18/19.60 * @return an iterator over the elements contained in this collection
62.18/19.60 */
62.18/19.60 public abstract Iterator iterator();
62.18/19.60
62.18/19.60 public abstract int size();
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation returns size() == 0.
62.18/19.60 */
62.18/19.60 public boolean isEmpty() {
62.18/19.60 return size() == 0;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation iterates over the elements in the collection,
62.18/19.60 * checking each element in turn for equality with the specified element.
62.18/19.60 *
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public boolean contains(Object o) {
62.18/19.60 Iterator e = iterator();
62.18/19.60 if (o==null) {
62.18/19.60 while (e.hasNext())
62.18/19.60 if (e.next()==null)
62.18/19.60 return true;
62.18/19.60 } else {
62.18/19.60 while (e.hasNext())
62.18/19.60 if (o.equals(e.next()))
62.18/19.60 return true;
62.18/19.60 }
62.18/19.60 return false;
62.18/19.60 }
62.18/19.60
62.18/19.60 // Modification Operations
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation always throws an
62.18/19.60 * UnsupportedOperationException.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.60 * @throws IllegalStateException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public boolean add(E e) {
62.18/19.60 throw new UnsupportedOperationException();
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation iterates over the collection looking for the
62.18/19.60 * specified element. If it finds the element, it removes the element
62.18/19.60 * from the collection using the iterator's remove method.
62.18/19.60 *
62.18/19.60 *
Note that this implementation throws an
62.18/19.60 * UnsupportedOperationException if the iterator returned by this
62.18/19.60 * collection's iterator method does not implement the remove
62.18/19.60 * method and this collection contains the specified object.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public boolean remove(Object o) {
62.18/19.60 Iterator e = iterator();
62.18/19.60 if (o==null) {
62.18/19.60 while (e.hasNext()) {
62.18/19.60 if (e.next()==null) {
62.18/19.60 e.remove();
62.18/19.60 return true;
62.18/19.60 }
62.18/19.60 }
62.18/19.60 } else {
62.18/19.60 while (e.hasNext()) {
62.18/19.60 if (o.equals(e.next())) {
62.18/19.60 e.remove();
62.18/19.60 return true;
62.18/19.60 }
62.18/19.60 }
62.18/19.60 }
62.18/19.60 return false;
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 // Bulk Operations
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation iterates over the specified collection,
62.18/19.60 * checking each element returned by the iterator in turn to see
62.18/19.60 * if it's contained in this collection. If all elements are so
62.18/19.60 * contained true is returned, otherwise false.
62.18/19.60 *
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 * @see #contains(Object)
62.18/19.60 */
62.18/19.60 public boolean containsAll(Collection c) {
62.18/19.60 Iterator e = c.iterator();
62.18/19.60 while (e.hasNext())
62.18/19.60 if (!contains(e.next()))
62.18/19.60 return false;
62.18/19.60 return true;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation iterates over the specified collection, and adds
62.18/19.60 * each object returned by the iterator to this collection, in turn.
62.18/19.60 *
62.18/19.60 *
Note that this implementation will throw an
62.18/19.60 * UnsupportedOperationException unless add is
62.18/19.60 * overridden (assuming the specified collection is non-empty).
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.60 * @throws IllegalStateException {@inheritDoc}
62.18/19.60 *
62.18/19.60 * @see #add(Object)
62.18/19.60 */
62.18/19.60 public boolean addAll(Collection c) {
62.18/19.60 boolean modified = false;
62.18/19.60 Iterator e = c.iterator();
62.18/19.60 while (e.hasNext()) {
62.18/19.60 if (add(e.next()))
62.18/19.60 modified = true;
62.18/19.60 }
62.18/19.60 return modified;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation iterates over this collection, checking each
62.18/19.60 * element returned by the iterator in turn to see if it's contained
62.18/19.60 * in the specified collection. If it's so contained, it's removed from
62.18/19.60 * this collection with the iterator's remove method.
62.18/19.60 *
62.18/19.60 *
Note that this implementation will throw an
62.18/19.60 * UnsupportedOperationException if the iterator returned by the
62.18/19.60 * iterator method does not implement the remove method
62.18/19.60 * and this collection contains one or more elements in common with the
62.18/19.60 * specified collection.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 *
62.18/19.60 * @see #remove(Object)
62.18/19.60 * @see #contains(Object)
62.18/19.60 */
62.18/19.60 public boolean removeAll(Collection c) {
62.18/19.60 boolean modified = false;
62.18/19.60 Iterator e = iterator();
62.18/19.60 while (e.hasNext()) {
62.18/19.60 if (c.contains(e.next())) {
62.18/19.60 e.remove();
62.18/19.60 modified = true;
62.18/19.60 }
62.18/19.60 }
62.18/19.60 return modified;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation iterates over this collection, checking each
62.18/19.60 * element returned by the iterator in turn to see if it's contained
62.18/19.60 * in the specified collection. If it's not so contained, it's removed
62.18/19.60 * from this collection with the iterator's remove method.
62.18/19.60 *
62.18/19.60 *
Note that this implementation will throw an
62.18/19.60 * UnsupportedOperationException if the iterator returned by the
62.18/19.60 * iterator method does not implement the remove method
62.18/19.60 * and this collection contains one or more elements not present in the
62.18/19.60 * specified collection.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 *
62.18/19.60 * @see #remove(Object)
62.18/19.60 * @see #contains(Object)
62.18/19.60 */
62.18/19.60 public boolean retainAll(Collection c) {
62.18/19.60 boolean modified = false;
62.18/19.60 Iterator e = iterator();
62.18/19.60 while (e.hasNext()) {
62.18/19.60 if (!c.contains(e.next())) {
62.18/19.60 e.remove();
62.18/19.60 modified = true;
62.18/19.60 }
62.18/19.60 }
62.18/19.60 return modified;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation iterates over this collection, removing each
62.18/19.60 * element using the Iterator.remove operation. Most
62.18/19.60 * implementations will probably choose to override this method for
62.18/19.60 * efficiency.
62.18/19.60 *
62.18/19.60 *
Note that this implementation will throw an
62.18/19.60 * UnsupportedOperationException if the iterator returned by this
62.18/19.60 * collection's iterator method does not implement the
62.18/19.60 * remove method and this collection is non-empty.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public void clear() {
62.18/19.60 Iterator e = iterator();
62.18/19.60 while (e.hasNext()) {
62.18/19.60 e.next();
62.18/19.60 e.remove();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 // String conversion
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns a string representation of this collection. The string
62.18/19.60 * representation consists of a list of the collection's elements in the
62.18/19.60 * order they are returned by its iterator, enclosed in square brackets
62.18/19.60 * ("[]"). Adjacent elements are separated by the characters
62.18/19.60 * ", " (comma and space). Elements are converted to strings as
62.18/19.60 * by {@link String#valueOf(Object)}.
62.18/19.60 *
62.18/19.60 * @return a string representation of this collection
62.18/19.60 */
62.18/19.60 public String toString() {
62.18/19.60 Iterator i = iterator();
62.18/19.60 if (! i.hasNext())
62.18/19.60 return "[]";
62.18/19.60
62.18/19.60 String sb = "";
62.18/19.60 sb = sb + "[";
62.18/19.60 for (;;) {
62.18/19.60 E e = i.next();
62.18/19.60 sb = sb + (e == this ? "(this Collection)" : e);
62.18/19.60 if (! i.hasNext()) {
62.18/19.60 sb = sb + "]";
62.18/19.60 return sb;
62.18/19.60 }
62.18/19.60 sb = sb + ", ";
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 /*
62.18/19.60 * Copyright 1997-2007 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.60 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.60 *
62.18/19.60 * This code is free software; you can redistribute it and/or modify it
62.18/19.60 * under the terms of the GNU General Public License version 2 only, as
62.18/19.60 * published by the Free Software Foundation. Sun designates this
62.18/19.60 * particular file as subject to the "Classpath" exception as provided
62.18/19.60 * by Sun in the LICENSE file that accompanied this code.
62.18/19.60 *
62.18/19.60 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.60 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.60 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.60 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.60 * accompanied this code).
62.18/19.60 *
62.18/19.60 * You should have received a copy of the GNU General Public License version
62.18/19.60 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.60 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.60 *
62.18/19.60 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.60 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.60 * have any questions.
62.18/19.60 */
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * This class provides a skeletal implementation of the {@link List}
62.18/19.60 * interface to minimize the effort required to implement this interface
62.18/19.60 * backed by a "random access" data store (such as an array). For sequential
62.18/19.60 * access data (such as a linked list), {@link AbstractSequentialList} should
62.18/19.60 * be used in preference to this class.
62.18/19.60 *
62.18/19.60 * To implement an unmodifiable list, the programmer needs only to extend
62.18/19.60 * this class and provide implementations for the {@link #get(int)} and
62.18/19.60 * {@link List#size() size()} methods.
62.18/19.60 *
62.18/19.60 *
To implement a modifiable list, the programmer must additionally
62.18/19.60 * override the {@link #set(int, Object) set(int, E)} method (which otherwise
62.18/19.60 * throws an {@code UnsupportedOperationException}). If the list is
62.18/19.60 * variable-size the programmer must additionally override the
62.18/19.60 * {@link #add(int, Object) add(int, E)} and {@link #remove(int)} methods.
62.18/19.60 *
62.18/19.60 *
The programmer should generally provide a void (no argument) and collection
62.18/19.60 * constructor, as per the recommendation in the {@link Collection} interface
62.18/19.60 * specification.
62.18/19.60 *
62.18/19.60 *
Unlike the other abstract collection implementations, the programmer does
62.18/19.60 * not have to provide an iterator implementation; the iterator and
62.18/19.60 * list iterator are implemented by this class, on top of the "random access"
62.18/19.60 * methods:
62.18/19.60 * {@link #get(int)},
62.18/19.60 * {@link #set(int, Object) set(int, E)},
62.18/19.60 * {@link #add(int, Object) add(int, E)} and
62.18/19.60 * {@link #remove(int)}.
62.18/19.60 *
62.18/19.60 *
The documentation for each non-abstract method in this class describes its
62.18/19.60 * implementation in detail. Each of these methods may be overridden if the
62.18/19.60 * collection being implemented admits a more efficient implementation.
62.18/19.60 *
62.18/19.60 *
This class is a member of the
62.18/19.60 *
62.18/19.60 * Java Collections Framework.
62.18/19.60 *
62.18/19.60 * @author Josh Bloch
62.18/19.60 * @author Neal Gafter
62.18/19.60 * @since 1.2
62.18/19.60 */
62.18/19.60
62.18/19.60 public abstract class AbstractList extends AbstractCollection implements List {
62.18/19.60 /**
62.18/19.60 * Sole constructor. (For invocation by subclass constructors, typically
62.18/19.60 * implicit.)
62.18/19.60 */
62.18/19.60 protected AbstractList() {
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Appends the specified element to the end of this list (optional
62.18/19.60 * operation).
62.18/19.60 *
62.18/19.60 * Lists that support this operation may place limitations on what
62.18/19.60 * elements may be added to this list. In particular, some
62.18/19.60 * lists will refuse to add null elements, and others will impose
62.18/19.60 * restrictions on the type of elements that may be added. List
62.18/19.60 * classes should clearly specify in their documentation any restrictions
62.18/19.60 * on what elements may be added.
62.18/19.60 *
62.18/19.60 *
This implementation calls {@code add(size(), e)}.
62.18/19.60 *
62.18/19.60 *
Note that this implementation throws an
62.18/19.60 * {@code UnsupportedOperationException} unless
62.18/19.60 * {@link #add(int, Object) add(int, E)} is overridden.
62.18/19.60 *
62.18/19.60 * @param e element to be appended to this list
62.18/19.60 * @return {@code true} (as specified by {@link Collection#add})
62.18/19.60 * @throws UnsupportedOperationException if the {@code add} operation
62.18/19.60 * is not supported by this list
62.18/19.60 * @throws ClassCastException if the class of the specified element
62.18/19.60 * prevents it from being added to this list
62.18/19.60 * @throws NullPointerException if the specified element is null and this
62.18/19.60 * list does not permit null elements
62.18/19.60 * @throws IllegalArgumentException if some property of this element
62.18/19.60 * prevents it from being added to this list
62.18/19.60 */
62.18/19.60 public boolean add(E e) {
62.18/19.60 add(size(), e);
62.18/19.60 return true;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.60 */
62.18/19.60 abstract public E get(int index);
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation always throws an
62.18/19.60 * {@code UnsupportedOperationException}.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.60 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public E set(int index, E element) {
62.18/19.60 throw new UnsupportedOperationException();
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation always throws an
62.18/19.60 * {@code UnsupportedOperationException}.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.60 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public void add(int index, E element) {
62.18/19.60 throw new UnsupportedOperationException();
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation always throws an
62.18/19.60 * {@code UnsupportedOperationException}.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public E remove(int index) {
62.18/19.60 throw new UnsupportedOperationException();
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 // Search Operations
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation first gets a list iterator (with
62.18/19.60 * {@code listIterator()}). Then, it iterates over the list until the
62.18/19.60 * specified element is found or the end of the list is reached.
62.18/19.60 *
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public int indexOf(Object o) {
62.18/19.60 ListIterator e = listIterator();
62.18/19.60 if (o==null) {
62.18/19.60 while (e.hasNext())
62.18/19.60 if (e.next()==null)
62.18/19.60 return e.previousIndex();
62.18/19.60 } else {
62.18/19.60 while (e.hasNext())
62.18/19.60 if (o.equals(e.next()))
62.18/19.60 return e.previousIndex();
62.18/19.60 }
62.18/19.60 return -1;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation first gets a list iterator that points to the end
62.18/19.60 * of the list (with {@code listIterator(size())}). Then, it iterates
62.18/19.60 * backwards over the list until the specified element is found, or the
62.18/19.60 * beginning of the list is reached.
62.18/19.60 *
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public int lastIndexOf(Object o) {
62.18/19.60 ListIterator e = listIterator(size());
62.18/19.60 if (o==null) {
62.18/19.60 while (e.hasPrevious())
62.18/19.60 if (e.previous()==null)
62.18/19.60 return e.nextIndex();
62.18/19.60 } else {
62.18/19.60 while (e.hasPrevious())
62.18/19.60 if (o.equals(e.previous()))
62.18/19.60 return e.nextIndex();
62.18/19.60 }
62.18/19.60 return -1;
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 // Bulk Operations
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Removes all of the elements from this list (optional operation).
62.18/19.60 * The list will be empty after this call returns.
62.18/19.60 *
62.18/19.60 * This implementation calls {@code removeRange(0, size())}.
62.18/19.60 *
62.18/19.60 *
Note that this implementation throws an
62.18/19.60 * {@code UnsupportedOperationException} unless {@code remove(int
62.18/19.60 * index)} or {@code removeRange(int fromIndex, int toIndex)} is
62.18/19.60 * overridden.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException if the {@code clear} operation
62.18/19.60 * is not supported by this list
62.18/19.60 */
62.18/19.60 public void clear() {
62.18/19.60 removeRange(0, size());
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 *
This implementation gets an iterator over the specified collection
62.18/19.60 * and iterates over it, inserting the elements obtained from the
62.18/19.60 * iterator into this list at the appropriate position, one at a time,
62.18/19.60 * using {@code add(int, E)}.
62.18/19.60 * Many implementations will override this method for efficiency.
62.18/19.60 *
62.18/19.60 *
Note that this implementation throws an
62.18/19.60 * {@code UnsupportedOperationException} unless
62.18/19.60 * {@link #add(int, Object) add(int, E)} is overridden.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.60 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public boolean addAll(int index, Collection c) {
62.18/19.60 rangeCheckForAdd(index);
62.18/19.60 boolean modified = false;
62.18/19.60 Iterator e = c.iterator();
62.18/19.60 while (e.hasNext()) {
62.18/19.60 add(index++, e.next());
62.18/19.60 modified = true;
62.18/19.60 }
62.18/19.60 return modified;
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 // Iterators
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns an iterator over the elements in this list in proper sequence.
62.18/19.60 *
62.18/19.60 *
This implementation returns a straightforward implementation of the
62.18/19.60 * iterator interface, relying on the backing list's {@code size()},
62.18/19.60 * {@code get(int)}, and {@code remove(int)} methods.
62.18/19.60 *
62.18/19.60 *
Note that the iterator returned by this method will throw an
62.18/19.60 * {@link UnsupportedOperationException} in response to its
62.18/19.60 * {@code remove} method unless the list's {@code remove(int)} method is
62.18/19.60 * overridden.
62.18/19.60 *
62.18/19.60 *
This implementation can be made to throw runtime exceptions in the
62.18/19.60 * face of concurrent modification, as described in the specification
62.18/19.60 * for the (protected) {@link #modCount} field.
62.18/19.60 *
62.18/19.60 * @return an iterator over the elements in this list in proper sequence
62.18/19.60 */
62.18/19.60 public Iterator iterator() {
62.18/19.60 return new Itr();
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation returns {@code listIterator(0)}.
62.18/19.60 *
62.18/19.60 * @see #listIterator(int)
62.18/19.60 */
62.18/19.60 public ListIterator listIterator() {
62.18/19.60 return listIterator(0);
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation returns a straightforward implementation of the
62.18/19.60 * {@code ListIterator} interface that extends the implementation of the
62.18/19.60 * {@code Iterator} interface returned by the {@code iterator()} method.
62.18/19.60 * The {@code ListIterator} implementation relies on the backing list's
62.18/19.60 * {@code get(int)}, {@code set(int, E)}, {@code add(int, E)}
62.18/19.60 * and {@code remove(int)} methods.
62.18/19.60 *
62.18/19.60 *
Note that the list iterator returned by this implementation will
62.18/19.60 * throw an {@link UnsupportedOperationException} in response to its
62.18/19.60 * {@code remove}, {@code set} and {@code add} methods unless the
62.18/19.60 * list's {@code remove(int)}, {@code set(int, E)}, and
62.18/19.60 * {@code add(int, E)} methods are overridden.
62.18/19.60 *
62.18/19.60 *
This implementation can be made to throw runtime exceptions in the
62.18/19.60 * face of concurrent modification, as described in the specification for
62.18/19.60 * the (protected) {@link #modCount} field.
62.18/19.60 *
62.18/19.60 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public ListIterator listIterator(final int index) {
62.18/19.60 rangeCheckForAdd(index);
62.18/19.60
62.18/19.60 return new ListItr(index);
62.18/19.60 }
62.18/19.60
62.18/19.60 private class Itr implements Iterator {
62.18/19.60 /**
62.18/19.60 * Index of element to be returned by subsequent call to next.
62.18/19.60 */
62.18/19.60 int cursor = 0;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Index of element returned by most recent call to next or
62.18/19.60 * previous. Reset to -1 if this element is deleted by a call
62.18/19.60 * to remove.
62.18/19.60 */
62.18/19.60 int lastRet = -1;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * The modCount value that the iterator believes that the backing
62.18/19.60 * List should have. If this expectation is violated, the iterator
62.18/19.60 * has detected concurrent modification.
62.18/19.60 */
62.18/19.60 int expectedModCount = modCount;
62.18/19.60
62.18/19.60 public boolean hasNext() {
62.18/19.60 return cursor != size();
62.18/19.60 }
62.18/19.60
62.18/19.60 public E next() {
62.18/19.60 checkForComodification();
62.18/19.60 try {
62.18/19.60 int i = cursor;
62.18/19.60 E next = get(i);
62.18/19.60 lastRet = i;
62.18/19.60 cursor = i + 1;
62.18/19.60 return next;
62.18/19.60 } catch (IndexOutOfBoundsException e) {
62.18/19.60 checkForComodification();
62.18/19.60 throw new NoSuchElementException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 public void remove() {
62.18/19.60 if (lastRet < 0)
62.18/19.60 throw new IllegalStateException();
62.18/19.60 checkForComodification();
62.18/19.60
62.18/19.60 try {
62.18/19.60 AbstractList.this.remove(lastRet);
62.18/19.60 if (lastRet < cursor)
62.18/19.60 cursor--;
62.18/19.60 lastRet = -1;
62.18/19.60 expectedModCount = modCount;
62.18/19.60 } catch (IndexOutOfBoundsException e) {
62.18/19.60 throw new ConcurrentModificationException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 final void checkForComodification() {
62.18/19.60 if (modCount != expectedModCount)
62.18/19.60 throw new ConcurrentModificationException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 private class ListItr extends Itr implements ListIterator {
62.18/19.60 ListItr(int index) {
62.18/19.60 cursor = index;
62.18/19.60 }
62.18/19.60
62.18/19.60 public boolean hasPrevious() {
62.18/19.60 return cursor != 0;
62.18/19.60 }
62.18/19.60
62.18/19.60 public E previous() {
62.18/19.60 checkForComodification();
62.18/19.60 try {
62.18/19.60 int i = cursor - 1;
62.18/19.60 E previous = get(i);
62.18/19.60 lastRet = cursor = i;
62.18/19.60 return previous;
62.18/19.60 } catch (IndexOutOfBoundsException e) {
62.18/19.60 checkForComodification();
62.18/19.60 throw new NoSuchElementException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 public int nextIndex() {
62.18/19.60 return cursor;
62.18/19.60 }
62.18/19.60
62.18/19.60 public int previousIndex() {
62.18/19.60 return cursor-1;
62.18/19.60 }
62.18/19.60
62.18/19.60 public void set(E e) {
62.18/19.60 if (lastRet < 0)
62.18/19.60 throw new IllegalStateException();
62.18/19.60 checkForComodification();
62.18/19.60
62.18/19.60 try {
62.18/19.60 AbstractList.this.set(lastRet, e);
62.18/19.60 expectedModCount = modCount;
62.18/19.60 } catch (IndexOutOfBoundsException ex) {
62.18/19.60 throw new ConcurrentModificationException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 public void add(E e) {
62.18/19.60 checkForComodification();
62.18/19.60
62.18/19.60 try {
62.18/19.60 int i = cursor;
62.18/19.60 AbstractList.this.add(i, e);
62.18/19.60 lastRet = -1;
62.18/19.60 cursor = i + 1;
62.18/19.60 expectedModCount = modCount;
62.18/19.60 } catch (IndexOutOfBoundsException ex) {
62.18/19.60 throw new ConcurrentModificationException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * {@inheritDoc}
62.18/19.60 *
62.18/19.60 * This implementation returns a list that subclasses
62.18/19.60 * {@code AbstractList}. The subclass stores, in private fields, the
62.18/19.60 * offset of the subList within the backing list, the size of the subList
62.18/19.60 * (which can change over its lifetime), and the expected
62.18/19.60 * {@code modCount} value of the backing list. There are two variants
62.18/19.60 * of the subclass, one of which implements {@code RandomAccess}.
62.18/19.60 * If this list implements {@code RandomAccess} the returned list will
62.18/19.60 * be an instance of the subclass that implements {@code RandomAccess}.
62.18/19.60 *
62.18/19.60 *
The subclass's {@code set(int, E)}, {@code get(int)},
62.18/19.60 * {@code add(int, E)}, {@code remove(int)}, {@code addAll(int,
62.18/19.60 * Collection)} and {@code removeRange(int, int)} methods all
62.18/19.60 * delegate to the corresponding methods on the backing abstract list,
62.18/19.60 * after bounds-checking the index and adjusting for the offset. The
62.18/19.60 * {@code addAll(Collection c)} method merely returns {@code addAll(size,
62.18/19.60 * c)}.
62.18/19.60 *
62.18/19.60 *
The {@code listIterator(int)} method returns a "wrapper object"
62.18/19.60 * over a list iterator on the backing list, which is created with the
62.18/19.60 * corresponding method on the backing list. The {@code iterator} method
62.18/19.60 * merely returns {@code listIterator()}, and the {@code size} method
62.18/19.60 * merely returns the subclass's {@code size} field.
62.18/19.60 *
62.18/19.60 *
All methods first check to see if the actual {@code modCount} of
62.18/19.60 * the backing list is equal to its expected value, and throw a
62.18/19.60 * {@code ConcurrentModificationException} if it is not.
62.18/19.60 *
62.18/19.60 * @throws IndexOutOfBoundsException if an endpoint index value is out of range
62.18/19.60 * {@code (fromIndex < 0 || toIndex > size)}
62.18/19.60 * @throws IllegalArgumentException if the endpoint indices are out of order
62.18/19.60 * {@code (fromIndex > toIndex)}
62.18/19.60 */
62.18/19.60 public List subList(int fromIndex, int toIndex) {
62.18/19.60 return (this instanceof RandomAccess ?
62.18/19.60 new RandomAccessSubList(this, fromIndex, toIndex) :
62.18/19.60 new SubList(this, fromIndex, toIndex));
62.18/19.60 }
62.18/19.60
62.18/19.60 // Comparison and hashing
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Compares the specified object with this list for equality. Returns
62.18/19.60 * {@code true} if and only if the specified object is also a list, both
62.18/19.60 * lists have the same size, and all corresponding pairs of elements in
62.18/19.60 * the two lists are equal. (Two elements {@code e1} and
62.18/19.60 * {@code e2} are equal if {@code (e1==null ? e2==null :
62.18/19.60 * e1.equals(e2))}.) In other words, two lists are defined to be
62.18/19.60 * equal if they contain the same elements in the same order.
62.18/19.60 *
62.18/19.60 * This implementation first checks if the specified object is this
62.18/19.60 * list. If so, it returns {@code true}; if not, it checks if the
62.18/19.60 * specified object is a list. If not, it returns {@code false}; if so,
62.18/19.60 * it iterates over both lists, comparing corresponding pairs of elements.
62.18/19.60 * If any comparison returns {@code false}, this method returns
62.18/19.60 * {@code false}. If either iterator runs out of elements before the
62.18/19.60 * other it returns {@code false} (as the lists are of unequal length);
62.18/19.60 * otherwise it returns {@code true} when the iterations complete.
62.18/19.60 *
62.18/19.60 * @param o the object to be compared for equality with this list
62.18/19.60 * @return {@code true} if the specified object is equal to this list
62.18/19.60 */
62.18/19.60 public boolean equals(Object o) {
62.18/19.60 if (o == this)
62.18/19.60 return true;
62.18/19.60 if (!(o instanceof List))
62.18/19.60 return false;
62.18/19.60
62.18/19.60 ListIterator e1 = listIterator();
62.18/19.60 ListIterator e2 = ((List) o).listIterator();
62.18/19.60 while(e1.hasNext() && e2.hasNext()) {
62.18/19.60 E o1 = e1.next();
62.18/19.60 Object o2 = e2.next();
62.18/19.60 if (!(o1==null ? o2==null : o1.equals(o2)))
62.18/19.60 return false;
62.18/19.60 }
62.18/19.60 return !(e1.hasNext() || e2.hasNext());
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns the hash code value for this list.
62.18/19.60 *
62.18/19.60 * This implementation uses exactly the code that is used to define the
62.18/19.60 * list hash function in the documentation for the {@link List#hashCode}
62.18/19.60 * method.
62.18/19.60 *
62.18/19.60 * @return the hash code value for this list
62.18/19.60 */
62.18/19.60 public int hashCode() {
62.18/19.60 int hashCode = 1;
62.18/19.60 Iterator it = this.iterator();
62.18/19.60 while (it.hasNext()) {
62.18/19.60 E e = it.next();
62.18/19.60 hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
62.18/19.60 }
62.18/19.60 return hashCode;
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Removes from this list all of the elements whose index is between
62.18/19.60 * {@code fromIndex}, inclusive, and {@code toIndex}, exclusive.
62.18/19.60 * Shifts any succeeding elements to the left (reduces their index).
62.18/19.60 * This call shortens the list by {@code (toIndex - fromIndex)} elements.
62.18/19.60 * (If {@code toIndex==fromIndex}, this operation has no effect.)
62.18/19.60 *
62.18/19.60 * This method is called by the {@code clear} operation on this list
62.18/19.60 * and its subLists. Overriding this method to take advantage of
62.18/19.60 * the internals of the list implementation can substantially
62.18/19.60 * improve the performance of the {@code clear} operation on this list
62.18/19.60 * and its subLists.
62.18/19.60 *
62.18/19.60 *
This implementation gets a list iterator positioned before
62.18/19.60 * {@code fromIndex}, and repeatedly calls {@code ListIterator.next}
62.18/19.60 * followed by {@code ListIterator.remove} until the entire range has
62.18/19.60 * been removed. Note: if {@code ListIterator.remove} requires linear
62.18/19.60 * time, this implementation requires quadratic time.
62.18/19.60 *
62.18/19.60 * @param fromIndex index of first element to be removed
62.18/19.60 * @param toIndex index after last element to be removed
62.18/19.60 */
62.18/19.60 protected void removeRange(int fromIndex, int toIndex) {
62.18/19.60 ListIterator it = listIterator(fromIndex);
62.18/19.60 for (int i=0, n=toIndex-fromIndex; istructurally modified.
62.18/19.60 * Structural modifications are those that change the size of the
62.18/19.60 * list, or otherwise perturb it in such a fashion that iterations in
62.18/19.60 * progress may yield incorrect results.
62.18/19.60 *
62.18/19.60 * This field is used by the iterator and list iterator implementation
62.18/19.60 * returned by the {@code iterator} and {@code listIterator} methods.
62.18/19.60 * If the value of this field changes unexpectedly, the iterator (or list
62.18/19.60 * iterator) will throw a {@code ConcurrentModificationException} in
62.18/19.60 * response to the {@code next}, {@code remove}, {@code previous},
62.18/19.60 * {@code set} or {@code add} operations. This provides
62.18/19.60 * fail-fast behavior, rather than non-deterministic behavior in
62.18/19.60 * the face of concurrent modification during iteration.
62.18/19.60 *
62.18/19.60 *
Use of this field by subclasses is optional. If a subclass
62.18/19.60 * wishes to provide fail-fast iterators (and list iterators), then it
62.18/19.60 * merely has to increment this field in its {@code add(int, E)} and
62.18/19.60 * {@code remove(int)} methods (and any other methods that it overrides
62.18/19.60 * that result in structural modifications to the list). A single call to
62.18/19.60 * {@code add(int, E)} or {@code remove(int)} must add no more than
62.18/19.60 * one to this field, or the iterators (and list iterators) will throw
62.18/19.60 * bogus {@code ConcurrentModificationExceptions}. If an implementation
62.18/19.60 * does not wish to provide fail-fast iterators, this field may be
62.18/19.60 * ignored.
62.18/19.60 */
62.18/19.60 protected transient int modCount = 0;
62.18/19.60
62.18/19.60 private void rangeCheckForAdd(int index) {
62.18/19.60 if (index < 0 || index > size())
62.18/19.60 throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
62.18/19.60 }
62.18/19.60
62.18/19.60 private String outOfBoundsMsg(int index) {
62.18/19.60 return "";
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 class SubList extends AbstractList {
62.18/19.60 private final AbstractList l;
62.18/19.60 private final int offset;
62.18/19.60 private int size;
62.18/19.60
62.18/19.60 SubList(AbstractList list, int fromIndex, int toIndex) {
62.18/19.60 if (fromIndex < 0)
62.18/19.60 throw new IndexOutOfBoundsException();
62.18/19.60 if (toIndex > list.size())
62.18/19.60 throw new IndexOutOfBoundsException();
62.18/19.60 if (fromIndex > toIndex)
62.18/19.60 throw new IllegalArgumentException();
62.18/19.60 l = list;
62.18/19.60 offset = fromIndex;
62.18/19.60 size = toIndex - fromIndex;
62.18/19.60 this.modCount = l.modCount;
62.18/19.60 }
62.18/19.60
62.18/19.60 public E set(int index, E element) {
62.18/19.60 rangeCheck(index);
62.18/19.60 checkForComodification();
62.18/19.60 return l.set(index+offset, element);
62.18/19.60 }
62.18/19.60
62.18/19.60 public E get(int index) {
62.18/19.60 rangeCheck(index);
62.18/19.60 checkForComodification();
62.18/19.60 return l.get(index+offset);
62.18/19.60 }
62.18/19.60
62.18/19.60 public int size() {
62.18/19.60 checkForComodification();
62.18/19.60 return size;
62.18/19.60 }
62.18/19.60
62.18/19.60 public void add(int index, E element) {
62.18/19.60 rangeCheckForAdd(index);
62.18/19.60 checkForComodification();
62.18/19.60 l.add(index+offset, element);
62.18/19.60 this.modCount = l.modCount;
62.18/19.60 size++;
62.18/19.60 }
62.18/19.60
62.18/19.60 public E remove(int index) {
62.18/19.60 rangeCheck(index);
62.18/19.60 checkForComodification();
62.18/19.60 E result = l.remove(index+offset);
62.18/19.60 this.modCount = l.modCount;
62.18/19.60 size--;
62.18/19.60 return result;
62.18/19.60 }
62.18/19.60
62.18/19.60 protected void removeRange(int fromIndex, int toIndex) {
62.18/19.60 checkForComodification();
62.18/19.60 l.removeRange(fromIndex+offset, toIndex+offset);
62.18/19.60 this.modCount = l.modCount;
62.18/19.60 size -= (toIndex-fromIndex);
62.18/19.60 }
62.18/19.60
62.18/19.60 public boolean addAll(Collection c) {
62.18/19.60 return addAll(size, c);
62.18/19.60 }
62.18/19.60
62.18/19.60 public boolean addAll(int index, Collection c) {
62.18/19.60 rangeCheckForAdd(index);
62.18/19.60 int cSize = c.size();
62.18/19.60 if (cSize==0)
62.18/19.60 return false;
62.18/19.60
62.18/19.60 checkForComodification();
62.18/19.60 l.addAll(offset+index, c);
62.18/19.60 this.modCount = l.modCount;
62.18/19.60 size += cSize;
62.18/19.60 return true;
62.18/19.60 }
62.18/19.60
62.18/19.60 public Iterator iterator() {
62.18/19.60 return listIterator();
62.18/19.60 }
62.18/19.60
62.18/19.60 public ListIterator listIterator(final int index) {
62.18/19.60 checkForComodification();
62.18/19.60 rangeCheckForAdd(index);
62.18/19.60
62.18/19.60 return new ListIterator() {
62.18/19.60 private final ListIterator i = l.listIterator(index+offset);
62.18/19.60
62.18/19.60 public boolean hasNext() {
62.18/19.60 return nextIndex() < size;
62.18/19.60 }
62.18/19.60
62.18/19.60 public E next() {
62.18/19.60 if (hasNext())
62.18/19.60 return i.next();
62.18/19.60 else
62.18/19.60 throw new NoSuchElementException();
62.18/19.60 }
62.18/19.60
62.18/19.60 public boolean hasPrevious() {
62.18/19.60 return previousIndex() >= 0;
62.18/19.60 }
62.18/19.60
62.18/19.60 public E previous() {
62.18/19.60 if (hasPrevious())
62.18/19.60 return i.previous();
62.18/19.60 else
62.18/19.60 throw new NoSuchElementException();
62.18/19.60 }
62.18/19.60
62.18/19.60 public int nextIndex() {
62.18/19.60 return i.nextIndex() - offset;
62.18/19.60 }
62.18/19.60
62.18/19.60 public int previousIndex() {
62.18/19.60 return i.previousIndex() - offset;
62.18/19.60 }
62.18/19.60
62.18/19.60 public void remove() {
62.18/19.60 i.remove();
62.18/19.60 SubList.this.modCount = l.modCount;
62.18/19.60 size--;
62.18/19.60 }
62.18/19.60
62.18/19.60 public void set(E e) {
62.18/19.60 i.set(e);
62.18/19.60 }
62.18/19.60
62.18/19.60 public void add(E e) {
62.18/19.60 i.add(e);
62.18/19.60 SubList.this.modCount = l.modCount;
62.18/19.60 size++;
62.18/19.60 }
62.18/19.60 };
62.18/19.60 }
62.18/19.60
62.18/19.60 public List subList(int fromIndex, int toIndex) {
62.18/19.60 return new SubList(this, fromIndex, toIndex);
62.18/19.60 }
62.18/19.60
62.18/19.60 private void rangeCheck(int index) {
62.18/19.60 if (index < 0 || index >= size)
62.18/19.60 throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
62.18/19.60 }
62.18/19.60
62.18/19.60 private void rangeCheckForAdd(int index) {
62.18/19.60 if (index < 0 || index > size)
62.18/19.60 throw new IndexOutOfBoundsException(outOfBoundsMsg(index));
62.18/19.60 }
62.18/19.60
62.18/19.60 private String outOfBoundsMsg(int index) {
62.18/19.60 return "";
62.18/19.60 }
62.18/19.60
62.18/19.60 private void checkForComodification() {
62.18/19.60 if (this.modCount != l.modCount)
62.18/19.60 throw new ConcurrentModificationException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 class RandomAccessSubList extends SubList implements RandomAccess {
62.18/19.60 RandomAccessSubList(AbstractList list, int fromIndex, int toIndex) {
62.18/19.60 super(list, fromIndex, toIndex);
62.18/19.60 }
62.18/19.60
62.18/19.60 public List subList(int fromIndex, int toIndex) {
62.18/19.60 return new RandomAccessSubList(this, fromIndex, toIndex);
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60
62.18/19.60 /*
62.18/19.60 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.60 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.60 *
62.18/19.60 * This code is free software; you can redistribute it and/or modify it
62.18/19.60 * under the terms of the GNU General Public License version 2 only, as
62.18/19.60 * published by the Free Software Foundation. Sun designates this
62.18/19.60 * particular file as subject to the "Classpath" exception as provided
62.18/19.60 * by Sun in the LICENSE file that accompanied this code.
62.18/19.60 *
62.18/19.60 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.60 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.60 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.60 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.60 * accompanied this code).
62.18/19.60 *
62.18/19.60 * You should have received a copy of the GNU General Public License version
62.18/19.60 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.60 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.60 *
62.18/19.60 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.60 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.60 * have any questions.
62.18/19.60 */
62.18/19.60
62.18/19.60 package javaUtilEx;
62.18/19.60
62.18/19.60 /**
62.18/19.60 * This class provides a skeletal implementation of the List
62.18/19.60 * interface to minimize the effort required to implement this interface
62.18/19.60 * backed by a "sequential access" data store (such as a linked list). For
62.18/19.60 * random access data (such as an array), AbstractList should be used
62.18/19.60 * in preference to this class.
62.18/19.60 *
62.18/19.60 * This class is the opposite of the AbstractList class in the sense
62.18/19.60 * that it implements the "random access" methods (get(int index),
62.18/19.60 * set(int index, E element), add(int index, E element) and
62.18/19.60 * remove(int index)) on top of the list's list iterator, instead of
62.18/19.60 * the other way around.
62.18/19.60 *
62.18/19.60 * To implement a list the programmer needs only to extend this class and
62.18/19.60 * provide implementations for the listIterator and size
62.18/19.60 * methods. For an unmodifiable list, the programmer need only implement the
62.18/19.60 * list iterator's hasNext, next, hasPrevious,
62.18/19.60 * previous and index methods.
62.18/19.60 *
62.18/19.60 * For a modifiable list the programmer should additionally implement the list
62.18/19.60 * iterator's set method. For a variable-size list the programmer
62.18/19.60 * should additionally implement the list iterator's remove and
62.18/19.60 * add methods.
62.18/19.60 *
62.18/19.60 * The programmer should generally provide a void (no argument) and collection
62.18/19.60 * constructor, as per the recommendation in the Collection interface
62.18/19.60 * specification.
62.18/19.60 *
62.18/19.60 * This class is a member of the
62.18/19.60 *
62.18/19.60 * Java Collections Framework.
62.18/19.60 *
62.18/19.60 * @author Josh Bloch
62.18/19.60 * @author Neal Gafter
62.18/19.60 * @see Collection
62.18/19.60 * @see List
62.18/19.60 * @see AbstractList
62.18/19.60 * @see AbstractCollection
62.18/19.60 * @since 1.2
62.18/19.60 */
62.18/19.60
62.18/19.60 public abstract class AbstractSequentialList extends AbstractList {
62.18/19.60 /**
62.18/19.60 * Sole constructor. (For invocation by subclass constructors, typically
62.18/19.60 * implicit.)
62.18/19.60 */
62.18/19.60 protected AbstractSequentialList() {
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Returns the element at the specified position in this list.
62.18/19.60 *
62.18/19.60 * This implementation first gets a list iterator pointing to the
62.18/19.60 * indexed element (with listIterator(index)). Then, it gets
62.18/19.60 * the element using ListIterator.next and returns it.
62.18/19.60 *
62.18/19.60 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.60 */
62.18/19.60 public E get(int index) {
62.18/19.60 try {
62.18/19.60 return listIterator(index).next();
62.18/19.60 } catch (NoSuchElementException exc) {
62.18/19.60 throw new IndexOutOfBoundsException();
62.18/19.60 }
62.18/19.60 }
62.18/19.60
62.18/19.60 /**
62.18/19.60 * Replaces the element at the specified position in this list with the
62.18/19.60 * specified element (optional operation).
62.18/19.60 *
62.18/19.60 *
This implementation first gets a list iterator pointing to the
62.18/19.60 * indexed element (with listIterator(index)). Then, it gets
62.18/19.60 * the current element using ListIterator.next and replaces it
62.18/19.60 * with ListIterator.set.
62.18/19.60 *
62.18/19.60 *
Note that this implementation will throw an
62.18/19.60 * UnsupportedOperationException if the list iterator does not
62.18/19.60 * implement the set operation.
62.18/19.60 *
62.18/19.60 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.60 * @throws ClassCastException {@inheritDoc}
62.18/19.60 * @throws NullPointerException {@inheritDoc}
62.18/19.60 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public E set(int index, E element) {
62.18/19.61 try {
62.18/19.61 ListIterator e = listIterator(index);
62.18/19.61 E oldVal = e.next();
62.18/19.61 e.set(element);
62.18/19.61 return oldVal;
62.18/19.61 } catch (NoSuchElementException exc) {
62.18/19.61 throw new IndexOutOfBoundsException();
62.18/19.61 }
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the specified position in this list
62.18/19.61 * (optional operation). Shifts the element currently at that position
62.18/19.61 * (if any) and any subsequent elements to the right (adds one to their
62.18/19.61 * indices).
62.18/19.61 *
62.18/19.61 * This implementation first gets a list iterator pointing to the
62.18/19.61 * indexed element (with listIterator(index)). Then, it
62.18/19.61 * inserts the specified element with ListIterator.add.
62.18/19.61 *
62.18/19.61 *
Note that this implementation will throw an
62.18/19.61 * UnsupportedOperationException if the list iterator does not
62.18/19.61 * implement the add operation.
62.18/19.61 *
62.18/19.61 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.61 * @throws ClassCastException {@inheritDoc}
62.18/19.61 * @throws NullPointerException {@inheritDoc}
62.18/19.61 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public void add(int index, E element) {
62.18/19.61 try {
62.18/19.61 listIterator(index).add(element);
62.18/19.61 } catch (NoSuchElementException exc) {
62.18/19.61 throw new IndexOutOfBoundsException();
62.18/19.61 }
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes the element at the specified position in this list (optional
62.18/19.61 * operation). Shifts any subsequent elements to the left (subtracts one
62.18/19.61 * from their indices). Returns the element that was removed from the
62.18/19.61 * list.
62.18/19.61 *
62.18/19.61 *
This implementation first gets a list iterator pointing to the
62.18/19.61 * indexed element (with listIterator(index)). Then, it removes
62.18/19.61 * the element with ListIterator.remove.
62.18/19.61 *
62.18/19.61 *
Note that this implementation will throw an
62.18/19.61 * UnsupportedOperationException if the list iterator does not
62.18/19.61 * implement the remove operation.
62.18/19.61 *
62.18/19.61 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public E remove(int index) {
62.18/19.61 try {
62.18/19.61 ListIterator e = listIterator(index);
62.18/19.61 E outCast = e.next();
62.18/19.61 e.remove();
62.18/19.61 return outCast;
62.18/19.61 } catch (NoSuchElementException exc) {
62.18/19.61 throw new IndexOutOfBoundsException();
62.18/19.61 }
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 // Bulk Operations
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts all of the elements in the specified collection into this
62.18/19.61 * list at the specified position (optional operation). Shifts the
62.18/19.61 * element currently at that position (if any) and any subsequent
62.18/19.61 * elements to the right (increases their indices). The new elements
62.18/19.61 * will appear in this list in the order that they are returned by the
62.18/19.61 * specified collection's iterator. The behavior of this operation is
62.18/19.61 * undefined if the specified collection is modified while the
62.18/19.61 * operation is in progress. (Note that this will occur if the specified
62.18/19.61 * collection is this list, and it's nonempty.)
62.18/19.61 *
62.18/19.61 * This implementation gets an iterator over the specified collection and
62.18/19.61 * a list iterator over this list pointing to the indexed element (with
62.18/19.61 * listIterator(index)). Then, it iterates over the specified
62.18/19.61 * collection, inserting the elements obtained from the iterator into this
62.18/19.61 * list, one at a time, using ListIterator.add followed by
62.18/19.61 * ListIterator.next (to skip over the added element).
62.18/19.61 *
62.18/19.61 *
Note that this implementation will throw an
62.18/19.61 * UnsupportedOperationException if the list iterator returned by
62.18/19.61 * the listIterator method does not implement the add
62.18/19.61 * operation.
62.18/19.61 *
62.18/19.61 * @throws UnsupportedOperationException {@inheritDoc}
62.18/19.61 * @throws ClassCastException {@inheritDoc}
62.18/19.61 * @throws NullPointerException {@inheritDoc}
62.18/19.61 * @throws IllegalArgumentException {@inheritDoc}
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public boolean addAll(int index, Collection c) {
62.18/19.61 try {
62.18/19.61 boolean modified = false;
62.18/19.61 ListIterator e1 = listIterator(index);
62.18/19.61 Iterator e2 = c.iterator();
62.18/19.61 while (e2.hasNext()) {
62.18/19.61 e1.add(e2.next());
62.18/19.61 modified = true;
62.18/19.61 }
62.18/19.61 return modified;
62.18/19.61 } catch (NoSuchElementException exc) {
62.18/19.61 throw new IndexOutOfBoundsException();
62.18/19.61 }
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 // Iterators
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns an iterator over the elements in this list (in proper
62.18/19.61 * sequence).
62.18/19.61 *
62.18/19.61 * This implementation merely returns a list iterator over the list.
62.18/19.61 *
62.18/19.61 * @return an iterator over the elements in this list (in proper sequence)
62.18/19.61 */
62.18/19.61 public Iterator iterator() {
62.18/19.61 return listIterator();
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns a list iterator over the elements in this list (in proper
62.18/19.61 * sequence).
62.18/19.61 *
62.18/19.61 * @param index index of first element to be returned from the list
62.18/19.61 * iterator (by a call to the next method)
62.18/19.61 * @return a list iterator over the elements in this list (in proper
62.18/19.61 * sequence)
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public abstract ListIterator listIterator(int index);
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 /*
62.18/19.61 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.61 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.61 *
62.18/19.61 * This code is free software; you can redistribute it and/or modify it
62.18/19.61 * under the terms of the GNU General Public License version 2 only, as
62.18/19.61 * published by the Free Software Foundation. Sun designates this
62.18/19.61 * particular file as subject to the "Classpath" exception as provided
62.18/19.61 * by Sun in the LICENSE file that accompanied this code.
62.18/19.61 *
62.18/19.61 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.61 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.61 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.61 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.61 * accompanied this code).
62.18/19.61 *
62.18/19.61 * You should have received a copy of the GNU General Public License version
62.18/19.61 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.61 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.61 *
62.18/19.61 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.61 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.61 * have any questions.
62.18/19.61 */
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * The root interface in the collection hierarchy. A collection
62.18/19.61 * represents a group of objects, known as its elements. Some
62.18/19.61 * collections allow duplicate elements and others do not. Some are ordered
62.18/19.61 * and others unordered. The JDK does not provide any direct
62.18/19.61 * implementations of this interface: it provides implementations of more
62.18/19.61 * specific subinterfaces like Set and List. This interface
62.18/19.61 * is typically used to pass collections around and manipulate them where
62.18/19.61 * maximum generality is desired.
62.18/19.61 *
62.18/19.61 * Bags or multisets (unordered collections that may contain
62.18/19.61 * duplicate elements) should implement this interface directly.
62.18/19.61 *
62.18/19.61 *
All general-purpose Collection implementation classes (which
62.18/19.61 * typically implement Collection indirectly through one of its
62.18/19.61 * subinterfaces) should provide two "standard" constructors: a void (no
62.18/19.61 * arguments) constructor, which creates an empty collection, and a
62.18/19.61 * constructor with a single argument of type Collection, which
62.18/19.61 * creates a new collection with the same elements as its argument. In
62.18/19.61 * effect, the latter constructor allows the user to copy any collection,
62.18/19.61 * producing an equivalent collection of the desired implementation type.
62.18/19.61 * There is no way to enforce this convention (as interfaces cannot contain
62.18/19.61 * constructors) but all of the general-purpose Collection
62.18/19.61 * implementations in the Java platform libraries comply.
62.18/19.61 *
62.18/19.61 *
The "destructive" methods contained in this interface, that is, the
62.18/19.61 * methods that modify the collection on which they operate, are specified to
62.18/19.61 * throw UnsupportedOperationException if this collection does not
62.18/19.61 * support the operation. If this is the case, these methods may, but are not
62.18/19.61 * required to, throw an UnsupportedOperationException if the
62.18/19.61 * invocation would have no effect on the collection. For example, invoking
62.18/19.61 * the {@link #addAll(Collection)} method on an unmodifiable collection may,
62.18/19.61 * but is not required to, throw the exception if the collection to be added
62.18/19.61 * is empty.
62.18/19.61 *
62.18/19.61 *
Some collection implementations have restrictions on the elements that
62.18/19.61 * they may contain. For example, some implementations prohibit null elements,
62.18/19.61 * and some have restrictions on the types of their elements. Attempting to
62.18/19.61 * add an ineligible element throws an unchecked exception, typically
62.18/19.61 * NullPointerException or ClassCastException. Attempting
62.18/19.61 * to query the presence of an ineligible element may throw an exception,
62.18/19.61 * or it may simply return false; some implementations will exhibit the former
62.18/19.61 * behavior and some will exhibit the latter. More generally, attempting an
62.18/19.61 * operation on an ineligible element whose completion would not result in
62.18/19.61 * the insertion of an ineligible element into the collection may throw an
62.18/19.61 * exception or it may succeed, at the option of the implementation.
62.18/19.61 * Such exceptions are marked as "optional" in the specification for this
62.18/19.61 * interface.
62.18/19.61 *
62.18/19.61 *
It is up to each collection to determine its own synchronization
62.18/19.61 * policy. In the absence of a stronger guarantee by the
62.18/19.61 * implementation, undefined behavior may result from the invocation
62.18/19.61 * of any method on a collection that is being mutated by another
62.18/19.61 * thread; this includes direct invocations, passing the collection to
62.18/19.61 * a method that might perform invocations, and using an existing
62.18/19.61 * iterator to examine the collection.
62.18/19.61 *
62.18/19.61 *
Many methods in Collections Framework interfaces are defined in
62.18/19.61 * terms of the {@link Object#equals(Object) equals} method. For example,
62.18/19.61 * the specification for the {@link #contains(Object) contains(Object o)}
62.18/19.61 * method says: "returns true if and only if this collection
62.18/19.61 * contains at least one element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e))." This specification should
62.18/19.61 * not be construed to imply that invoking Collection.contains
62.18/19.61 * with a non-null argument o will cause o.equals(e) to be
62.18/19.61 * invoked for any element e. Implementations are free to implement
62.18/19.61 * optimizations whereby the equals invocation is avoided, for
62.18/19.61 * example, by first comparing the hash codes of the two elements. (The
62.18/19.61 * {@link Object#hashCode()} specification guarantees that two objects with
62.18/19.61 * unequal hash codes cannot be equal.) More generally, implementations of
62.18/19.61 * the various Collections Framework interfaces are free to take advantage of
62.18/19.61 * the specified behavior of underlying {@link Object} methods wherever the
62.18/19.61 * implementor deems it appropriate.
62.18/19.61 *
62.18/19.61 *
This interface is a member of the
62.18/19.61 *
62.18/19.61 * Java Collections Framework.
62.18/19.61 *
62.18/19.61 * @author Josh Bloch
62.18/19.61 * @author Neal Gafter
62.18/19.61 * @see Set
62.18/19.61 * @see List
62.18/19.61 * @see Map
62.18/19.61 * @see SortedSet
62.18/19.61 * @see SortedMap
62.18/19.61 * @see HashSet
62.18/19.61 * @see TreeSet
62.18/19.61 * @see ArrayList
62.18/19.61 * @see LinkedList
62.18/19.61 * @see Vector
62.18/19.61 * @see Collections
62.18/19.61 * @see Arrays
62.18/19.61 * @see AbstractCollection
62.18/19.61 * @since 1.2
62.18/19.61 */
62.18/19.61
62.18/19.61 public interface Collection {
62.18/19.61 // Query Operations
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the number of elements in this collection. If this collection
62.18/19.61 * contains more than Integer.MAX_VALUE elements, returns
62.18/19.61 * Integer.MAX_VALUE.
62.18/19.61 *
62.18/19.61 * @return the number of elements in this collection
62.18/19.61 */
62.18/19.61 int size();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns true if this collection contains no elements.
62.18/19.61 *
62.18/19.61 * @return true if this collection contains no elements
62.18/19.61 */
62.18/19.61 boolean isEmpty();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns true if this collection contains the specified element.
62.18/19.61 * More formally, returns true if and only if this collection
62.18/19.61 * contains at least one element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e)).
62.18/19.61 *
62.18/19.61 * @param o element whose presence in this collection is to be tested
62.18/19.61 * @return true if this collection contains the specified
62.18/19.61 * element
62.18/19.61 * @throws ClassCastException if the type of the specified element
62.18/19.61 * is incompatible with this collection (optional)
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * collection does not permit null elements (optional)
62.18/19.61 */
62.18/19.61 boolean contains(Object o);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns an iterator over the elements in this collection. There are no
62.18/19.61 * guarantees concerning the order in which the elements are returned
62.18/19.61 * (unless this collection is an instance of some class that provides a
62.18/19.61 * guarantee).
62.18/19.61 *
62.18/19.61 * @return an Iterator over the elements in this collection
62.18/19.61 */
62.18/19.61 Iterator iterator();
62.18/19.61
62.18/19.61 // Modification Operations
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Ensures that this collection contains the specified element (optional
62.18/19.61 * operation). Returns true if this collection changed as a
62.18/19.61 * result of the call. (Returns false if this collection does
62.18/19.61 * not permit duplicates and already contains the specified element.)
62.18/19.61 *
62.18/19.61 * Collections that support this operation may place limitations on what
62.18/19.61 * elements may be added to this collection. In particular, some
62.18/19.61 * collections will refuse to add null elements, and others will
62.18/19.61 * impose restrictions on the type of elements that may be added.
62.18/19.61 * Collection classes should clearly specify in their documentation any
62.18/19.61 * restrictions on what elements may be added.
62.18/19.61 *
62.18/19.61 * If a collection refuses to add a particular element for any reason
62.18/19.61 * other than that it already contains the element, it must throw
62.18/19.61 * an exception (rather than returning false). This preserves
62.18/19.61 * the invariant that a collection always contains the specified element
62.18/19.61 * after this call returns.
62.18/19.61 *
62.18/19.61 * @param e element whose presence in this collection is to be ensured
62.18/19.61 * @return true if this collection changed as a result of the
62.18/19.61 * call
62.18/19.61 * @throws UnsupportedOperationException if the add operation
62.18/19.61 * is not supported by this collection
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this collection
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * collection does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the element
62.18/19.61 * prevents it from being added to this collection
62.18/19.61 * @throws IllegalStateException if the element cannot be added at this
62.18/19.61 * time due to insertion restrictions
62.18/19.61 */
62.18/19.61 boolean add(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes a single instance of the specified element from this
62.18/19.61 * collection, if it is present (optional operation). More formally,
62.18/19.61 * removes an element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e)), if
62.18/19.61 * this collection contains one or more such elements. Returns
62.18/19.61 * true if this collection contained the specified element (or
62.18/19.61 * equivalently, if this collection changed as a result of the call).
62.18/19.61 *
62.18/19.61 * @param o element to be removed from this collection, if present
62.18/19.61 * @return true if an element was removed as a result of this call
62.18/19.61 * @throws ClassCastException if the type of the specified element
62.18/19.61 * is incompatible with this collection (optional)
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * collection does not permit null elements (optional)
62.18/19.61 * @throws UnsupportedOperationException if the remove operation
62.18/19.61 * is not supported by this collection
62.18/19.61 */
62.18/19.61 boolean remove(Object o);
62.18/19.61
62.18/19.61
62.18/19.61 // Bulk Operations
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns true if this collection contains all of the elements
62.18/19.61 * in the specified collection.
62.18/19.61 *
62.18/19.61 * @param c collection to be checked for containment in this collection
62.18/19.61 * @return true if this collection contains all of the elements
62.18/19.61 * in the specified collection
62.18/19.61 * @throws ClassCastException if the types of one or more elements
62.18/19.61 * in the specified collection are incompatible with this
62.18/19.61 * collection (optional)
62.18/19.61 * @throws NullPointerException if the specified collection contains one
62.18/19.61 * or more null elements and this collection does not permit null
62.18/19.61 * elements (optional), or if the specified collection is null
62.18/19.61 * @see #contains(Object)
62.18/19.61 */
62.18/19.61 boolean containsAll(Collection c);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Adds all of the elements in the specified collection to this collection
62.18/19.61 * (optional operation). The behavior of this operation is undefined if
62.18/19.61 * the specified collection is modified while the operation is in progress.
62.18/19.61 * (This implies that the behavior of this call is undefined if the
62.18/19.61 * specified collection is this collection, and this collection is
62.18/19.61 * nonempty.)
62.18/19.61 *
62.18/19.61 * @param c collection containing elements to be added to this collection
62.18/19.61 * @return true if this collection changed as a result of the call
62.18/19.61 * @throws UnsupportedOperationException if the addAll operation
62.18/19.61 * is not supported by this collection
62.18/19.61 * @throws ClassCastException if the class of an element of the specified
62.18/19.61 * collection prevents it from being added to this collection
62.18/19.61 * @throws NullPointerException if the specified collection contains a
62.18/19.61 * null element and this collection does not permit null elements,
62.18/19.61 * or if the specified collection is null
62.18/19.61 * @throws IllegalArgumentException if some property of an element of the
62.18/19.61 * specified collection prevents it from being added to this
62.18/19.61 * collection
62.18/19.61 * @throws IllegalStateException if not all the elements can be added at
62.18/19.61 * this time due to insertion restrictions
62.18/19.61 * @see #add(Object)
62.18/19.61 */
62.18/19.61 boolean addAll(Collection c);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes all of this collection's elements that are also contained in the
62.18/19.61 * specified collection (optional operation). After this call returns,
62.18/19.61 * this collection will contain no elements in common with the specified
62.18/19.61 * collection.
62.18/19.61 *
62.18/19.61 * @param c collection containing elements to be removed from this collection
62.18/19.61 * @return true if this collection changed as a result of the
62.18/19.61 * call
62.18/19.61 * @throws UnsupportedOperationException if the removeAll method
62.18/19.61 * is not supported by this collection
62.18/19.61 * @throws ClassCastException if the types of one or more elements
62.18/19.61 * in this collection are incompatible with the specified
62.18/19.61 * collection (optional)
62.18/19.61 * @throws NullPointerException if this collection contains one or more
62.18/19.61 * null elements and the specified collection does not support
62.18/19.61 * null elements (optional), or if the specified collection is null
62.18/19.61 * @see #remove(Object)
62.18/19.61 * @see #contains(Object)
62.18/19.61 */
62.18/19.61 boolean removeAll(Collection c);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retains only the elements in this collection that are contained in the
62.18/19.61 * specified collection (optional operation). In other words, removes from
62.18/19.61 * this collection all of its elements that are not contained in the
62.18/19.61 * specified collection.
62.18/19.61 *
62.18/19.61 * @param c collection containing elements to be retained in this collection
62.18/19.61 * @return true if this collection changed as a result of the call
62.18/19.61 * @throws UnsupportedOperationException if the retainAll operation
62.18/19.61 * is not supported by this collection
62.18/19.61 * @throws ClassCastException if the types of one or more elements
62.18/19.61 * in this collection are incompatible with the specified
62.18/19.61 * collection (optional)
62.18/19.61 * @throws NullPointerException if this collection contains one or more
62.18/19.61 * null elements and the specified collection does not permit null
62.18/19.61 * elements (optional), or if the specified collection is null
62.18/19.61 * @see #remove(Object)
62.18/19.61 * @see #contains(Object)
62.18/19.61 */
62.18/19.61 boolean retainAll(Collection c);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes all of the elements from this collection (optional operation).
62.18/19.61 * The collection will be empty after this method returns.
62.18/19.61 *
62.18/19.61 * @throws UnsupportedOperationException if the clear operation
62.18/19.61 * is not supported by this collection
62.18/19.61 */
62.18/19.61 void clear();
62.18/19.61
62.18/19.61
62.18/19.61 // Comparison and hashing
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Compares the specified object with this collection for equality.
62.18/19.61 *
62.18/19.61 * While the Collection interface adds no stipulations to the
62.18/19.61 * general contract for the Object.equals, programmers who
62.18/19.61 * implement the Collection interface "directly" (in other words,
62.18/19.61 * create a class that is a Collection but is not a Set
62.18/19.61 * or a List) must exercise care if they choose to override the
62.18/19.61 * Object.equals. It is not necessary to do so, and the simplest
62.18/19.61 * course of action is to rely on Object's implementation, but
62.18/19.61 * the implementor may wish to implement a "value comparison" in place of
62.18/19.61 * the default "reference comparison." (The List and
62.18/19.61 * Set interfaces mandate such value comparisons.)
62.18/19.61 *
62.18/19.61 * The general contract for the Object.equals method states that
62.18/19.61 * equals must be symmetric (in other words, a.equals(b) if and
62.18/19.61 * only if b.equals(a)). The contracts for List.equals
62.18/19.61 * and Set.equals state that lists are only equal to other lists,
62.18/19.61 * and sets to other sets. Thus, a custom equals method for a
62.18/19.61 * collection class that implements neither the List nor
62.18/19.61 * Set interface must return false when this collection
62.18/19.61 * is compared to any list or set. (By the same logic, it is not possible
62.18/19.61 * to write a class that correctly implements both the Set and
62.18/19.61 * List interfaces.)
62.18/19.61 *
62.18/19.61 * @param o object to be compared for equality with this collection
62.18/19.61 * @return true if the specified object is equal to this
62.18/19.61 * collection
62.18/19.61 *
62.18/19.61 * @see Object#equals(Object)
62.18/19.61 * @see Set#equals(Object)
62.18/19.61 * @see List#equals(Object)
62.18/19.61 */
62.18/19.61 boolean equals(Object o);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the hash code value for this collection. While the
62.18/19.61 * Collection interface adds no stipulations to the general
62.18/19.61 * contract for the Object.hashCode method, programmers should
62.18/19.61 * take note that any class that overrides the Object.equals
62.18/19.61 * method must also override the Object.hashCode method in order
62.18/19.61 * to satisfy the general contract for the Object.hashCodemethod.
62.18/19.61 * In particular, c1.equals(c2) implies that
62.18/19.61 * c1.hashCode()==c2.hashCode().
62.18/19.61 *
62.18/19.61 * @return the hash code value for this collection
62.18/19.61 *
62.18/19.61 * @see Object#hashCode()
62.18/19.61 * @see Object#equals(Object)
62.18/19.61 */
62.18/19.61 int hashCode();
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 /*
62.18/19.61 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.61 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.61 *
62.18/19.61 * This code is free software; you can redistribute it and/or modify it
62.18/19.61 * under the terms of the GNU General Public License version 2 only, as
62.18/19.61 * published by the Free Software Foundation. Sun designates this
62.18/19.61 * particular file as subject to the "Classpath" exception as provided
62.18/19.61 * by Sun in the LICENSE file that accompanied this code.
62.18/19.61 *
62.18/19.61 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.61 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.61 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.61 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.61 * accompanied this code).
62.18/19.61 *
62.18/19.61 * You should have received a copy of the GNU General Public License version
62.18/19.61 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.61 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.61 *
62.18/19.61 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.61 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.61 * have any questions.
62.18/19.61 */
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * This exception may be thrown by methods that have detected concurrent
62.18/19.61 * modification of an object when such modification is not permissible.
62.18/19.61 *
62.18/19.61 * For example, it is not generally permissible for one thread to modify a Collection
62.18/19.61 * while another thread is iterating over it. In general, the results of the
62.18/19.61 * iteration are undefined under these circumstances. Some Iterator
62.18/19.61 * implementations (including those of all the general purpose collection implementations
62.18/19.61 * provided by the JRE) may choose to throw this exception if this behavior is
62.18/19.61 * detected. Iterators that do this are known as fail-fast iterators,
62.18/19.61 * as they fail quickly and cleanly, rather that risking arbitrary,
62.18/19.61 * non-deterministic behavior at an undetermined time in the future.
62.18/19.61 *
62.18/19.61 * Note that this exception does not always indicate that an object has
62.18/19.61 * been concurrently modified by a different thread. If a single
62.18/19.61 * thread issues a sequence of method invocations that violates the
62.18/19.61 * contract of an object, the object may throw this exception. For
62.18/19.61 * example, if a thread modifies a collection directly while it is
62.18/19.61 * iterating over the collection with a fail-fast iterator, the iterator
62.18/19.61 * will throw this exception.
62.18/19.61 *
62.18/19.61 *
Note that fail-fast behavior cannot be guaranteed as it is, generally
62.18/19.61 * speaking, impossible to make any hard guarantees in the presence of
62.18/19.61 * unsynchronized concurrent modification. Fail-fast operations
62.18/19.61 * throw ConcurrentModificationException on a best-effort basis.
62.18/19.61 * Therefore, it would be wrong to write a program that depended on this
62.18/19.61 * exception for its correctness: ConcurrentModificationException
62.18/19.61 * should be used only to detect bugs.
62.18/19.61 *
62.18/19.61 * @author Josh Bloch
62.18/19.61 * @see Collection
62.18/19.61 * @see Iterator
62.18/19.61 * @see ListIterator
62.18/19.61 * @see Vector
62.18/19.61 * @see LinkedList
62.18/19.61 * @see HashSet
62.18/19.61 * @see Hashtable
62.18/19.61 * @see TreeMap
62.18/19.61 * @see AbstractList
62.18/19.61 * @since 1.2
62.18/19.61 */
62.18/19.61 public class ConcurrentModificationException extends RuntimeException {
62.18/19.61 /**
62.18/19.61 * Constructs a ConcurrentModificationException with no
62.18/19.61 * detail message.
62.18/19.61 */
62.18/19.61 public ConcurrentModificationException() {
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs a ConcurrentModificationException with the
62.18/19.61 * specified detail message.
62.18/19.61 *
62.18/19.61 * @param message the detail message pertaining to this exception.
62.18/19.61 */
62.18/19.61 public ConcurrentModificationException(String message) {
62.18/19.61 super(message);
62.18/19.61 }
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 /*
62.18/19.61 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.61 *
62.18/19.61 * This code is free software; you can redistribute it and/or modify it
62.18/19.61 * under the terms of the GNU General Public License version 2 only, as
62.18/19.61 * published by the Free Software Foundation. Sun designates this
62.18/19.61 * particular file as subject to the "Classpath" exception as provided
62.18/19.61 * by Sun in the LICENSE file that accompanied this code.
62.18/19.61 *
62.18/19.61 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.61 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.61 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.61 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.61 * accompanied this code).
62.18/19.61 *
62.18/19.61 * You should have received a copy of the GNU General Public License version
62.18/19.61 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.61 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.61 *
62.18/19.61 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.61 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.61 * have any questions.
62.18/19.61 */
62.18/19.61
62.18/19.61 /*
62.18/19.61 * This file is available under and governed by the GNU General Public
62.18/19.61 * License version 2 only, as published by the Free Software Foundation.
62.18/19.61 * However, the following notice accompanied the original version of this
62.18/19.61 * file:
62.18/19.61 *
62.18/19.61 * Written by Doug Lea and Josh Bloch with assistance from members of
62.18/19.61 * JCP JSR-166 Expert Group and released to the public domain, as explained
62.18/19.61 * at http://creativecommons.org/licenses/publicdomain
62.18/19.61 */
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * A linear collection that supports element insertion and removal at
62.18/19.61 * both ends. The name deque is short for "double ended queue"
62.18/19.61 * and is usually pronounced "deck". Most Deque
62.18/19.61 * implementations place no fixed limits on the number of elements
62.18/19.61 * they may contain, but this interface supports capacity-restricted
62.18/19.61 * deques as well as those with no fixed size limit.
62.18/19.61 *
62.18/19.61 *
This interface defines methods to access the elements at both
62.18/19.61 * ends of the deque. Methods are provided to insert, remove, and
62.18/19.61 * examine the element. Each of these methods exists in two forms:
62.18/19.61 * one throws an exception if the operation fails, the other returns a
62.18/19.61 * special value (either null or false, depending on
62.18/19.61 * the operation). The latter form of the insert operation is
62.18/19.61 * designed specifically for use with capacity-restricted
62.18/19.61 * Deque implementations; in most implementations, insert
62.18/19.61 * operations cannot fail.
62.18/19.61 *
62.18/19.61 *
The twelve methods described above are summarized in the
62.18/19.61 * following table:
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * |
62.18/19.61 * First Element (Head) |
62.18/19.61 * Last Element (Tail) |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * |
62.18/19.61 * Throws exception |
62.18/19.61 * Special value |
62.18/19.61 * Throws exception |
62.18/19.61 * Special value |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | Insert |
62.18/19.61 * {@link #addFirst addFirst(e)} |
62.18/19.61 * {@link #offerFirst offerFirst(e)} |
62.18/19.61 * {@link #addLast addLast(e)} |
62.18/19.61 * {@link #offerLast offerLast(e)} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | Remove |
62.18/19.61 * {@link #removeFirst removeFirst()} |
62.18/19.61 * {@link #pollFirst pollFirst()} |
62.18/19.61 * {@link #removeLast removeLast()} |
62.18/19.61 * {@link #pollLast pollLast()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | Examine |
62.18/19.61 * {@link #getFirst getFirst()} |
62.18/19.61 * {@link #peekFirst peekFirst()} |
62.18/19.61 * {@link #getLast getLast()} |
62.18/19.61 * {@link #peekLast peekLast()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * This interface extends the {@link Queue} interface. When a deque is
62.18/19.61 * used as a queue, FIFO (First-In-First-Out) behavior results. Elements are
62.18/19.61 * added at the end of the deque and removed from the beginning. The methods
62.18/19.61 * inherited from the Queue interface are precisely equivalent to
62.18/19.61 * Deque methods as indicated in the following table:
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | Queue Method |
62.18/19.61 * Equivalent Deque Method |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link java.util.Queue#add add(e)} |
62.18/19.61 * {@link #addLast addLast(e)} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link java.util.Queue#offer offer(e)} |
62.18/19.61 * {@link #offerLast offerLast(e)} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link java.util.Queue#remove remove()} |
62.18/19.61 * {@link #removeFirst removeFirst()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link java.util.Queue#poll poll()} |
62.18/19.61 * {@link #pollFirst pollFirst()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link java.util.Queue#element element()} |
62.18/19.61 * {@link #getFirst getFirst()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link java.util.Queue#peek peek()} |
62.18/19.61 * {@link #peek peekFirst()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * Deques can also be used as LIFO (Last-In-First-Out) stacks. This
62.18/19.61 * interface should be used in preference to the legacy {@link Stack} class.
62.18/19.61 * When a deque is used as a stack, elements are pushed and popped from the
62.18/19.61 * beginning of the deque. Stack methods are precisely equivalent to
62.18/19.61 * Deque methods as indicated in the table below:
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | Stack Method |
62.18/19.61 * Equivalent Deque Method |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link #push push(e)} |
62.18/19.61 * {@link #addFirst addFirst(e)} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link #pop pop()} |
62.18/19.61 * {@link #removeFirst removeFirst()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * | {@link #peek peek()} |
62.18/19.61 * {@link #peekFirst peekFirst()} |
62.18/19.61 *
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * Note that the {@link #peek peek} method works equally well when
62.18/19.61 * a deque is used as a queue or a stack; in either case, elements are
62.18/19.61 * drawn from the beginning of the deque.
62.18/19.61 *
62.18/19.61 *
This interface provides two methods to remove interior
62.18/19.61 * elements, {@link #removeFirstOccurrence removeFirstOccurrence} and
62.18/19.61 * {@link #removeLastOccurrence removeLastOccurrence}.
62.18/19.61 *
62.18/19.61 *
Unlike the {@link List} interface, this interface does not
62.18/19.61 * provide support for indexed access to elements.
62.18/19.61 *
62.18/19.61 *
While Deque implementations are not strictly required
62.18/19.61 * to prohibit the insertion of null elements, they are strongly
62.18/19.61 * encouraged to do so. Users of any Deque implementations
62.18/19.61 * that do allow null elements are strongly encouraged not to
62.18/19.61 * take advantage of the ability to insert nulls. This is so because
62.18/19.61 * null is used as a special return value by various methods
62.18/19.61 * to indicated that the deque is empty.
62.18/19.61 *
62.18/19.61 *
Deque implementations generally do not define
62.18/19.61 * element-based versions of the equals and hashCode
62.18/19.61 * methods, but instead inherit the identity-based versions from class
62.18/19.61 * Object.
62.18/19.61 *
62.18/19.61 *
This interface is a member of the Java Collections
62.18/19.61 * Framework.
62.18/19.61 *
62.18/19.61 * @author Doug Lea
62.18/19.61 * @author Josh Bloch
62.18/19.61 * @since 1.6
62.18/19.61 * @param the type of elements held in this collection
62.18/19.61 */
62.18/19.61
62.18/19.61 public interface Deque extends Queue {
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the front of this deque if it is
62.18/19.61 * possible to do so immediately without violating capacity restrictions.
62.18/19.61 * When using a capacity-restricted deque, it is generally preferable to
62.18/19.61 * use method {@link #offerFirst}.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 * @throws IllegalStateException if the element cannot be added at this
62.18/19.61 * time due to capacity restrictions
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this deque
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the specified
62.18/19.61 * element prevents it from being added to this deque
62.18/19.61 */
62.18/19.61 void addFirst(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the end of this deque if it is
62.18/19.61 * possible to do so immediately without violating capacity restrictions.
62.18/19.61 * When using a capacity-restricted deque, it is generally preferable to
62.18/19.61 * use method {@link #offerLast}.
62.18/19.61 *
62.18/19.61 * This method is equivalent to {@link #add}.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 * @throws IllegalStateException if the element cannot be added at this
62.18/19.61 * time due to capacity restrictions
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this deque
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the specified
62.18/19.61 * element prevents it from being added to this deque
62.18/19.61 */
62.18/19.61 void addLast(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the front of this deque unless it would
62.18/19.61 * violate capacity restrictions. When using a capacity-restricted deque,
62.18/19.61 * this method is generally preferable to the {@link #addFirst} method,
62.18/19.61 * which can fail to insert an element only by throwing an exception.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 * @return true if the element was added to this deque, else
62.18/19.61 * false
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this deque
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the specified
62.18/19.61 * element prevents it from being added to this deque
62.18/19.61 */
62.18/19.61 boolean offerFirst(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the end of this deque unless it would
62.18/19.61 * violate capacity restrictions. When using a capacity-restricted deque,
62.18/19.61 * this method is generally preferable to the {@link #addLast} method,
62.18/19.61 * which can fail to insert an element only by throwing an exception.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 * @return true if the element was added to this deque, else
62.18/19.61 * false
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this deque
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the specified
62.18/19.61 * element prevents it from being added to this deque
62.18/19.61 */
62.18/19.61 boolean offerLast(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the first element of this deque. This method
62.18/19.61 * differs from {@link #pollFirst pollFirst} only in that it throws an
62.18/19.61 * exception if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the head of this deque
62.18/19.61 * @throws NoSuchElementException if this deque is empty
62.18/19.61 */
62.18/19.61 E removeFirst();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the last element of this deque. This method
62.18/19.61 * differs from {@link #pollLast pollLast} only in that it throws an
62.18/19.61 * exception if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the tail of this deque
62.18/19.61 * @throws NoSuchElementException if this deque is empty
62.18/19.61 */
62.18/19.61 E removeLast();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the first element of this deque,
62.18/19.61 * or returns null if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the head of this deque, or null if this deque is empty
62.18/19.61 */
62.18/19.61 E pollFirst();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the last element of this deque,
62.18/19.61 * or returns null if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the tail of this deque, or null if this deque is empty
62.18/19.61 */
62.18/19.61 E pollLast();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the first element of this deque.
62.18/19.61 *
62.18/19.61 * This method differs from {@link #peekFirst peekFirst} only in that it
62.18/19.61 * throws an exception if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the head of this deque
62.18/19.61 * @throws NoSuchElementException if this deque is empty
62.18/19.61 */
62.18/19.61 E getFirst();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the last element of this deque.
62.18/19.61 * This method differs from {@link #peekLast peekLast} only in that it
62.18/19.61 * throws an exception if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the tail of this deque
62.18/19.61 * @throws NoSuchElementException if this deque is empty
62.18/19.61 */
62.18/19.61 E getLast();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the first element of this deque,
62.18/19.61 * or returns null if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the head of this deque, or null if this deque is empty
62.18/19.61 */
62.18/19.61 E peekFirst();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the last element of this deque,
62.18/19.61 * or returns null if this deque is empty.
62.18/19.61 *
62.18/19.61 * @return the tail of this deque, or null if this deque is empty
62.18/19.61 */
62.18/19.61 E peekLast();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes the first occurrence of the specified element from this deque.
62.18/19.61 * If the deque does not contain the element, it is unchanged.
62.18/19.61 * More formally, removes the first element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e))
62.18/19.61 * (if such an element exists).
62.18/19.61 * Returns true if this deque contained the specified element
62.18/19.61 * (or equivalently, if this deque changed as a result of the call).
62.18/19.61 *
62.18/19.61 * @param o element to be removed from this deque, if present
62.18/19.61 * @return true if an element was removed as a result of this call
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * is incompatible with this deque (optional)
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements (optional)
62.18/19.61 */
62.18/19.61 boolean removeFirstOccurrence(Object o);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes the last occurrence of the specified element from this deque.
62.18/19.61 * If the deque does not contain the element, it is unchanged.
62.18/19.61 * More formally, removes the last element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e))
62.18/19.61 * (if such an element exists).
62.18/19.61 * Returns true if this deque contained the specified element
62.18/19.61 * (or equivalently, if this deque changed as a result of the call).
62.18/19.61 *
62.18/19.61 * @param o element to be removed from this deque, if present
62.18/19.61 * @return true if an element was removed as a result of this call
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * is incompatible with this deque (optional)
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements (optional)
62.18/19.61 */
62.18/19.61 boolean removeLastOccurrence(Object o);
62.18/19.61
62.18/19.61 // *** Queue methods ***
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element into the queue represented by this deque
62.18/19.61 * (in other words, at the tail of this deque) if it is possible to do so
62.18/19.61 * immediately without violating capacity restrictions, returning
62.18/19.61 * true upon success and throwing an
62.18/19.61 * IllegalStateException if no space is currently available.
62.18/19.61 * When using a capacity-restricted deque, it is generally preferable to
62.18/19.61 * use {@link #offer(Object) offer}.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #addLast}.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 * @return true (as specified by {@link Collection#add})
62.18/19.61 * @throws IllegalStateException if the element cannot be added at this
62.18/19.61 * time due to capacity restrictions
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this deque
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the specified
62.18/19.61 * element prevents it from being added to this deque
62.18/19.61 */
62.18/19.61 boolean add(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element into the queue represented by this deque
62.18/19.61 * (in other words, at the tail of this deque) if it is possible to do so
62.18/19.61 * immediately without violating capacity restrictions, returning
62.18/19.61 * true upon success and false if no space is currently
62.18/19.61 * available. When using a capacity-restricted deque, this method is
62.18/19.61 * generally preferable to the {@link #add} method, which can fail to
62.18/19.61 * insert an element only by throwing an exception.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #offerLast}.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 * @return true if the element was added to this deque, else
62.18/19.61 * false
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this deque
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the specified
62.18/19.61 * element prevents it from being added to this deque
62.18/19.61 */
62.18/19.61 boolean offer(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the head of the queue represented by this deque
62.18/19.61 * (in other words, the first element of this deque).
62.18/19.61 * This method differs from {@link #poll poll} only in that it throws an
62.18/19.61 * exception if this deque is empty.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #removeFirst()}.
62.18/19.61 *
62.18/19.61 * @return the head of the queue represented by this deque
62.18/19.61 * @throws NoSuchElementException if this deque is empty
62.18/19.61 */
62.18/19.61 E remove();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the head of the queue represented by this deque
62.18/19.61 * (in other words, the first element of this deque), or returns
62.18/19.61 * null if this deque is empty.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #pollFirst()}.
62.18/19.61 *
62.18/19.61 * @return the first element of this deque, or null if
62.18/19.61 * this deque is empty
62.18/19.61 */
62.18/19.61 E poll();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the head of the queue represented by
62.18/19.61 * this deque (in other words, the first element of this deque).
62.18/19.61 * This method differs from {@link #peek peek} only in that it throws an
62.18/19.61 * exception if this deque is empty.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #getFirst()}.
62.18/19.61 *
62.18/19.61 * @return the head of the queue represented by this deque
62.18/19.61 * @throws NoSuchElementException if this deque is empty
62.18/19.61 */
62.18/19.61 E element();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the head of the queue represented by
62.18/19.61 * this deque (in other words, the first element of this deque), or
62.18/19.61 * returns null if this deque is empty.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #peekFirst()}.
62.18/19.61 *
62.18/19.61 * @return the head of the queue represented by this deque, or
62.18/19.61 * null if this deque is empty
62.18/19.61 */
62.18/19.61 E peek();
62.18/19.61
62.18/19.61
62.18/19.61 // *** Stack methods ***
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Pushes an element onto the stack represented by this deque (in other
62.18/19.61 * words, at the head of this deque) if it is possible to do so
62.18/19.61 * immediately without violating capacity restrictions, returning
62.18/19.61 * true upon success and throwing an
62.18/19.61 * IllegalStateException if no space is currently available.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #addFirst}.
62.18/19.61 *
62.18/19.61 * @param e the element to push
62.18/19.61 * @throws IllegalStateException if the element cannot be added at this
62.18/19.61 * time due to capacity restrictions
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * prevents it from being added to this deque
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements
62.18/19.61 * @throws IllegalArgumentException if some property of the specified
62.18/19.61 * element prevents it from being added to this deque
62.18/19.61 */
62.18/19.61 void push(E e);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Pops an element from the stack represented by this deque. In other
62.18/19.61 * words, removes and returns the first element of this deque.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #removeFirst()}.
62.18/19.61 *
62.18/19.61 * @return the element at the front of this deque (which is the top
62.18/19.61 * of the stack represented by this deque)
62.18/19.61 * @throws NoSuchElementException if this deque is empty
62.18/19.61 */
62.18/19.61 E pop();
62.18/19.61
62.18/19.61
62.18/19.61 // *** Collection methods ***
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes the first occurrence of the specified element from this deque.
62.18/19.61 * If the deque does not contain the element, it is unchanged.
62.18/19.61 * More formally, removes the first element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e))
62.18/19.61 * (if such an element exists).
62.18/19.61 * Returns true if this deque contained the specified element
62.18/19.61 * (or equivalently, if this deque changed as a result of the call).
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #removeFirstOccurrence}.
62.18/19.61 *
62.18/19.61 * @param o element to be removed from this deque, if present
62.18/19.61 * @return true if an element was removed as a result of this call
62.18/19.61 * @throws ClassCastException if the class of the specified element
62.18/19.61 * is incompatible with this deque (optional)
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements (optional)
62.18/19.61 */
62.18/19.61 boolean remove(Object o);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns true if this deque contains the specified element.
62.18/19.61 * More formally, returns true if and only if this deque contains
62.18/19.61 * at least one element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e)).
62.18/19.61 *
62.18/19.61 * @param o element whose presence in this deque is to be tested
62.18/19.61 * @return true if this deque contains the specified element
62.18/19.61 * @throws ClassCastException if the type of the specified element
62.18/19.61 * is incompatible with this deque (optional)
62.18/19.61 * @throws NullPointerException if the specified element is null and this
62.18/19.61 * deque does not permit null elements (optional)
62.18/19.61 */
62.18/19.61 boolean contains(Object o);
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the number of elements in this deque.
62.18/19.61 *
62.18/19.61 * @return the number of elements in this deque
62.18/19.61 */
62.18/19.61 public int size();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns an iterator over the elements in this deque in proper sequence.
62.18/19.61 * The elements will be returned in order from first (head) to last (tail).
62.18/19.61 *
62.18/19.61 * @return an iterator over the elements in this deque in proper sequence
62.18/19.61 */
62.18/19.61 Iterator iterator();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns an iterator over the elements in this deque in reverse
62.18/19.61 * sequential order. The elements will be returned in order from
62.18/19.61 * last (tail) to first (head).
62.18/19.61 *
62.18/19.61 * @return an iterator over the elements in this deque in reverse
62.18/19.61 * sequence
62.18/19.61 */
62.18/19.61 Iterator descendingIterator();
62.18/19.61
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 /*
62.18/19.61 * Copyright 1994-2003 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.61 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.61 *
62.18/19.61 * This code is free software; you can redistribute it and/or modify it
62.18/19.61 * under the terms of the GNU General Public License version 2 only, as
62.18/19.61 * published by the Free Software Foundation. Sun designates this
62.18/19.61 * particular file as subject to the "Classpath" exception as provided
62.18/19.61 * by Sun in the LICENSE file that accompanied this code.
62.18/19.61 *
62.18/19.61 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.61 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.61 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.61 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.61 * accompanied this code).
62.18/19.61 *
62.18/19.61 * You should have received a copy of the GNU General Public License version
62.18/19.61 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.61 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.61 *
62.18/19.61 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.61 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.61 * have any questions.
62.18/19.61 */
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Thrown to indicate that a method has been passed an illegal or
62.18/19.61 * inappropriate argument.
62.18/19.61 *
62.18/19.61 * @author unascribed
62.18/19.61 * @see java.lang.Thread#setPriority(int)
62.18/19.61 * @since JDK1.0
62.18/19.61 */
62.18/19.61 public
62.18/19.61 class IllegalArgumentException extends RuntimeException {
62.18/19.61 /**
62.18/19.61 * Constructs an IllegalArgumentException with no
62.18/19.61 * detail message.
62.18/19.61 */
62.18/19.61 public IllegalArgumentException() {
62.18/19.61 super();
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs an IllegalArgumentException with the
62.18/19.61 * specified detail message.
62.18/19.61 *
62.18/19.61 * @param s the detail message.
62.18/19.61 */
62.18/19.61 public IllegalArgumentException(String s) {
62.18/19.61 super(s);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs a new exception with the specified detail message and
62.18/19.61 * cause.
62.18/19.61 *
62.18/19.61 * Note that the detail message associated with cause is
62.18/19.61 * not automatically incorporated in this exception's detail
62.18/19.61 * message.
62.18/19.61 *
62.18/19.61 * @param message the detail message (which is saved for later retrieval
62.18/19.61 * by the {@link Throwable#getMessage()} method).
62.18/19.61 * @param cause the cause (which is saved for later retrieval by the
62.18/19.61 * {@link Throwable#getCause()} method). (A null value
62.18/19.61 * is permitted, and indicates that the cause is nonexistent or
62.18/19.61 * unknown.)
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public IllegalArgumentException(String message, Throwable cause) {
62.18/19.61 super(message, cause);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs a new exception with the specified cause and a detail
62.18/19.61 * message of (cause==null ? null : cause.toString()) (which
62.18/19.61 * typically contains the class and detail message of cause).
62.18/19.61 * This constructor is useful for exceptions that are little more than
62.18/19.61 * wrappers for other throwables (for example, {@link
62.18/19.61 * java.security.PrivilegedActionException}).
62.18/19.61 *
62.18/19.61 * @param cause the cause (which is saved for later retrieval by the
62.18/19.61 * {@link Throwable#getCause()} method). (A null value is
62.18/19.61 * permitted, and indicates that the cause is nonexistent or
62.18/19.61 * unknown.)
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public IllegalArgumentException(Throwable cause) {
62.18/19.61 super(cause);
62.18/19.61 }
62.18/19.61
62.18/19.61 private static final long serialVersionUID = -5365630128856068164L;
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 /*
62.18/19.61 * Copyright 1996-2003 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.61 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.61 *
62.18/19.61 * This code is free software; you can redistribute it and/or modify it
62.18/19.61 * under the terms of the GNU General Public License version 2 only, as
62.18/19.61 * published by the Free Software Foundation. Sun designates this
62.18/19.61 * particular file as subject to the "Classpath" exception as provided
62.18/19.61 * by Sun in the LICENSE file that accompanied this code.
62.18/19.61 *
62.18/19.61 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.61 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.61 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.61 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.61 * accompanied this code).
62.18/19.61 *
62.18/19.61 * You should have received a copy of the GNU General Public License version
62.18/19.61 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.61 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.61 *
62.18/19.61 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.61 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.61 * have any questions.
62.18/19.61 */
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Signals that a method has been invoked at an illegal or
62.18/19.61 * inappropriate time. In other words, the Java environment or
62.18/19.61 * Java application is not in an appropriate state for the requested
62.18/19.61 * operation.
62.18/19.61 *
62.18/19.61 * @author Jonni Kanerva
62.18/19.61 * @since JDK1.1
62.18/19.61 */
62.18/19.61 public
62.18/19.61 class IllegalStateException extends RuntimeException {
62.18/19.61 /**
62.18/19.61 * Constructs an IllegalStateException with no detail message.
62.18/19.61 * A detail message is a String that describes this particular exception.
62.18/19.61 */
62.18/19.61 public IllegalStateException() {
62.18/19.61 super();
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs an IllegalStateException with the specified detail
62.18/19.61 * message. A detail message is a String that describes this particular
62.18/19.61 * exception.
62.18/19.61 *
62.18/19.61 * @param s the String that contains a detailed message
62.18/19.61 */
62.18/19.61 public IllegalStateException(String s) {
62.18/19.61 super(s);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs a new exception with the specified detail message and
62.18/19.61 * cause.
62.18/19.61 *
62.18/19.61 *
Note that the detail message associated with cause is
62.18/19.61 * not automatically incorporated in this exception's detail
62.18/19.61 * message.
62.18/19.61 *
62.18/19.61 * @param message the detail message (which is saved for later retrieval
62.18/19.61 * by the {@link Throwable#getMessage()} method).
62.18/19.61 * @param cause the cause (which is saved for later retrieval by the
62.18/19.61 * {@link Throwable#getCause()} method). (A null value
62.18/19.61 * is permitted, and indicates that the cause is nonexistent or
62.18/19.61 * unknown.)
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public IllegalStateException(String message, Throwable cause) {
62.18/19.61 super(message, cause);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs a new exception with the specified cause and a detail
62.18/19.61 * message of (cause==null ? null : cause.toString()) (which
62.18/19.61 * typically contains the class and detail message of cause).
62.18/19.61 * This constructor is useful for exceptions that are little more than
62.18/19.61 * wrappers for other throwables (for example, {@link
62.18/19.61 * java.security.PrivilegedActionException}).
62.18/19.61 *
62.18/19.61 * @param cause the cause (which is saved for later retrieval by the
62.18/19.61 * {@link Throwable#getCause()} method). (A null value is
62.18/19.61 * permitted, and indicates that the cause is nonexistent or
62.18/19.61 * unknown.)
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public IllegalStateException(Throwable cause) {
62.18/19.61 super(cause);
62.18/19.61 }
62.18/19.61
62.18/19.61 static final long serialVersionUID = -1848914673093119416L;
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 /*
62.18/19.61 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.61 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.61 *
62.18/19.61 * This code is free software; you can redistribute it and/or modify it
62.18/19.61 * under the terms of the GNU General Public License version 2 only, as
62.18/19.61 * published by the Free Software Foundation. Sun designates this
62.18/19.61 * particular file as subject to the "Classpath" exception as provided
62.18/19.61 * by Sun in the LICENSE file that accompanied this code.
62.18/19.61 *
62.18/19.61 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.61 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.61 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.61 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.61 * accompanied this code).
62.18/19.61 *
62.18/19.61 * You should have received a copy of the GNU General Public License version
62.18/19.61 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.61 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.61 *
62.18/19.61 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.61 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.61 * have any questions.
62.18/19.61 */
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * An iterator over a collection. {@code Iterator} takes the place of
62.18/19.61 * {@link Enumeration} in the Java Collections Framework. Iterators
62.18/19.61 * differ from enumerations in two ways:
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * - Iterators allow the caller to remove elements from the
62.18/19.61 * underlying collection during the iteration with well-defined
62.18/19.61 * semantics.
62.18/19.61 *
- Method names have been improved.
62.18/19.61 *
62.18/19.61 *
62.18/19.61 * This interface is a member of the
62.18/19.61 *
62.18/19.61 * Java Collections Framework.
62.18/19.61 *
62.18/19.61 * @author Josh Bloch
62.18/19.61 * @see Collection
62.18/19.61 * @see ListIterator
62.18/19.61 * @see Iterable
62.18/19.61 * @since 1.2
62.18/19.61 */
62.18/19.61 public interface Iterator {
62.18/19.61 /**
62.18/19.61 * Returns {@code true} if the iteration has more elements.
62.18/19.61 * (In other words, returns {@code true} if {@link #next} would
62.18/19.61 * return an element rather than throwing an exception.)
62.18/19.61 *
62.18/19.61 * @return {@code true} if the iteration has more elements
62.18/19.61 */
62.18/19.61 boolean hasNext();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the next element in the iteration.
62.18/19.61 *
62.18/19.61 * @return the next element in the iteration
62.18/19.61 * @throws NoSuchElementException if the iteration has no more elements
62.18/19.61 */
62.18/19.61 E next();
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes from the underlying collection the last element returned
62.18/19.61 * by this iterator (optional operation). This method can be called
62.18/19.61 * only once per call to {@link #next}. The behavior of an iterator
62.18/19.61 * is unspecified if the underlying collection is modified while the
62.18/19.61 * iteration is in progress in any way other than by calling this
62.18/19.61 * method.
62.18/19.61 *
62.18/19.61 * @throws UnsupportedOperationException if the {@code remove}
62.18/19.61 * operation is not supported by this iterator
62.18/19.61 *
62.18/19.61 * @throws IllegalStateException if the {@code next} method has not
62.18/19.61 * yet been called, or the {@code remove} method has already
62.18/19.61 * been called after the last call to the {@code next}
62.18/19.61 * method
62.18/19.61 */
62.18/19.61 void remove();
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 public class juLinkedListCreateAddAllAt {
62.18/19.61 public static void main(String[] args) {
62.18/19.61 Random.args = args;
62.18/19.61
62.18/19.61 LinkedList l1 = createList(Random.random());
62.18/19.61 LinkedList l2 = createList(Random.random());
62.18/19.61 l1.addAll(Random.random(), l2);
62.18/19.61 }
62.18/19.61
62.18/19.61 public static LinkedList createList(int n) {
62.18/19.61 LinkedList l = new LinkedList();
62.18/19.61 while (n > 0) {
62.18/19.61 l.addLast(new Content(Random.random()));
62.18/19.61 n--;
62.18/19.61 }
62.18/19.61 return l;
62.18/19.61 }
62.18/19.61 }
62.18/19.61
62.18/19.61 final class Content {
62.18/19.61 int val;
62.18/19.61
62.18/19.61 public Content(int v) {
62.18/19.61 this.val = v;
62.18/19.61 }
62.18/19.61
62.18/19.61 public int hashCode() {
62.18/19.61 return val^31;
62.18/19.61 }
62.18/19.61
62.18/19.61 public boolean equals(Object o) {
62.18/19.61 if (o instanceof Content) {
62.18/19.61 return this.val == ((Content) o).val;
62.18/19.61 }
62.18/19.61 return false;
62.18/19.61 }
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 /*
62.18/19.61 * Copyright 1997-2006 Sun Microsystems, Inc. All Rights Reserved.
62.18/19.61 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
62.18/19.61 *
62.18/19.61 * This code is free software; you can redistribute it and/or modify it
62.18/19.61 * under the terms of the GNU General Public License version 2 only, as
62.18/19.61 * published by the Free Software Foundation. Sun designates this
62.18/19.61 * particular file as subject to the "Classpath" exception as provided
62.18/19.61 * by Sun in the LICENSE file that accompanied this code.
62.18/19.61 *
62.18/19.61 * This code is distributed in the hope that it will be useful, but WITHOUT
62.18/19.61 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
62.18/19.61 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
62.18/19.61 * version 2 for more details (a copy is included in the LICENSE file that
62.18/19.61 * accompanied this code).
62.18/19.61 *
62.18/19.61 * You should have received a copy of the GNU General Public License version
62.18/19.61 * 2 along with this work; if not, write to the Free Software Foundation,
62.18/19.61 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
62.18/19.61 *
62.18/19.61 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
62.18/19.61 * CA 95054 USA or visit www.sun.com if you need additional information or
62.18/19.61 * have any questions.
62.18/19.61 */
62.18/19.61
62.18/19.61 package javaUtilEx;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Linked list implementation of the List interface. Implements all
62.18/19.61 * optional list operations, and permits all elements (including
62.18/19.61 * null). In addition to implementing the List interface,
62.18/19.61 * the LinkedList class provides uniformly named methods to
62.18/19.61 * get, remove and insert an element at the
62.18/19.61 * beginning and end of the list. These operations allow linked lists to be
62.18/19.61 * used as a stack, {@linkplain Queue queue}, or {@linkplain Deque
62.18/19.61 * double-ended queue}.
62.18/19.61 *
62.18/19.61 * The class implements the Deque interface, providing
62.18/19.61 * first-in-first-out queue operations for add,
62.18/19.61 * poll, along with other stack and deque operations.
62.18/19.61 *
62.18/19.61 * All of the operations perform as could be expected for a doubly-linked
62.18/19.61 * list. Operations that index into the list will traverse the list from
62.18/19.61 * the beginning or the end, whichever is closer to the specified index.
62.18/19.61 *
62.18/19.61 *
Note that this implementation is not synchronized.
62.18/19.61 * If multiple threads access a linked list concurrently, and at least
62.18/19.61 * one of the threads modifies the list structurally, it must be
62.18/19.61 * synchronized externally. (A structural modification is any operation
62.18/19.61 * that adds or deletes one or more elements; merely setting the value of
62.18/19.61 * an element is not a structural modification.) This is typically
62.18/19.61 * accomplished by synchronizing on some object that naturally
62.18/19.61 * encapsulates the list.
62.18/19.61 *
62.18/19.61 * If no such object exists, the list should be "wrapped" using the
62.18/19.61 * {@link Collections#synchronizedList Collections.synchronizedList}
62.18/19.61 * method. This is best done at creation time, to prevent accidental
62.18/19.61 * unsynchronized access to the list:
62.18/19.61 * List list = Collections.synchronizedList(new LinkedList(...));
62.18/19.61 *
62.18/19.61 * The iterators returned by this class's iterator and
62.18/19.61 * listIterator methods are fail-fast: if the list is
62.18/19.61 * structurally modified at any time after the iterator is created, in
62.18/19.61 * any way except through the Iterator's own remove or
62.18/19.61 * add methods, the iterator will throw a {@link
62.18/19.61 * ConcurrentModificationException}. Thus, in the face of concurrent
62.18/19.61 * modification, the iterator fails quickly and cleanly, rather than
62.18/19.61 * risking arbitrary, non-deterministic behavior at an undetermined
62.18/19.61 * time in the future.
62.18/19.61 *
62.18/19.61 *
Note that the fail-fast behavior of an iterator cannot be guaranteed
62.18/19.61 * as it is, generally speaking, impossible to make any hard guarantees in the
62.18/19.61 * presence of unsynchronized concurrent modification. Fail-fast iterators
62.18/19.61 * throw ConcurrentModificationException on a best-effort basis.
62.18/19.61 * Therefore, it would be wrong to write a program that depended on this
62.18/19.61 * exception for its correctness: the fail-fast behavior of iterators
62.18/19.61 * should be used only to detect bugs.
62.18/19.61 *
62.18/19.61 *
This class is a member of the
62.18/19.61 *
62.18/19.61 * Java Collections Framework.
62.18/19.61 *
62.18/19.61 * @author Josh Bloch
62.18/19.61 * @see List
62.18/19.61 * @see ArrayList
62.18/19.61 * @see Vector
62.18/19.61 * @since 1.2
62.18/19.61 * @param the type of elements held in this collection
62.18/19.61 */
62.18/19.61
62.18/19.61 public class LinkedList
62.18/19.61 extends AbstractSequentialList
62.18/19.61 implements List, Deque
62.18/19.61 {
62.18/19.61 private transient Entry header = new Entry(null, null, null);
62.18/19.61 private transient int size = 0;
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs an empty list.
62.18/19.61 */
62.18/19.61 public LinkedList() {
62.18/19.61 header.next = header.previous = header;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Constructs a list containing the elements of the specified
62.18/19.61 * collection, in the order they are returned by the collection's
62.18/19.61 * iterator.
62.18/19.61 *
62.18/19.61 * @param c the collection whose elements are to be placed into this list
62.18/19.61 * @throws NullPointerException if the specified collection is null
62.18/19.61 */
62.18/19.61 public LinkedList(Collection c) {
62.18/19.61 this();
62.18/19.61 addAll(c);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the first element in this list.
62.18/19.61 *
62.18/19.61 * @return the first element in this list
62.18/19.61 * @throws NoSuchElementException if this list is empty
62.18/19.61 */
62.18/19.61 public E getFirst() {
62.18/19.61 if (size==0)
62.18/19.61 throw new NoSuchElementException();
62.18/19.61
62.18/19.61 return header.next.element;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the last element in this list.
62.18/19.61 *
62.18/19.61 * @return the last element in this list
62.18/19.61 * @throws NoSuchElementException if this list is empty
62.18/19.61 */
62.18/19.61 public E getLast() {
62.18/19.61 if (size==0)
62.18/19.61 throw new NoSuchElementException();
62.18/19.61
62.18/19.61 return header.previous.element;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes and returns the first element from this list.
62.18/19.61 *
62.18/19.61 * @return the first element from this list
62.18/19.61 * @throws NoSuchElementException if this list is empty
62.18/19.61 */
62.18/19.61 public E removeFirst() {
62.18/19.61 return remove(header.next);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes and returns the last element from this list.
62.18/19.61 *
62.18/19.61 * @return the last element from this list
62.18/19.61 * @throws NoSuchElementException if this list is empty
62.18/19.61 */
62.18/19.61 public E removeLast() {
62.18/19.61 return remove(header.previous);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the beginning of this list.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 */
62.18/19.61 public void addFirst(E e) {
62.18/19.61 addBefore(e, header.next);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Appends the specified element to the end of this list.
62.18/19.61 *
62.18/19.61 * This method is equivalent to {@link #add}.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 */
62.18/19.61 public void addLast(E e) {
62.18/19.61 addBefore(e, header);
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns true if this list contains the specified element.
62.18/19.61 * More formally, returns true if and only if this list contains
62.18/19.61 * at least one element e such that
62.18/19.61 * (o==null ? e==null : o.equals(e)).
62.18/19.61 *
62.18/19.61 * @param o element whose presence in this list is to be tested
62.18/19.61 * @return true if this list contains the specified element
62.18/19.61 */
62.18/19.61 public boolean contains(Object o) {
62.18/19.61 return indexOf(o) != -1;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the number of elements in this list.
62.18/19.61 *
62.18/19.61 * @return the number of elements in this list
62.18/19.61 */
62.18/19.61 public int size() {
62.18/19.61 return size;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Appends the specified element to the end of this list.
62.18/19.61 *
62.18/19.61 *
This method is equivalent to {@link #addLast}.
62.18/19.61 *
62.18/19.61 * @param e element to be appended to this list
62.18/19.61 * @return true (as specified by {@link Collection#add})
62.18/19.61 */
62.18/19.61 public boolean add(E e) {
62.18/19.61 addBefore(e, header);
62.18/19.61 return true;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes the first occurrence of the specified element from this list,
62.18/19.61 * if it is present. If this list does not contain the element, it is
62.18/19.61 * unchanged. More formally, removes the element with the lowest index
62.18/19.61 * i such that
62.18/19.61 * (o==null ? get(i)==null : o.equals(get(i)))
62.18/19.61 * (if such an element exists). Returns true if this list
62.18/19.61 * contained the specified element (or equivalently, if this list
62.18/19.61 * changed as a result of the call).
62.18/19.61 *
62.18/19.61 * @param o element to be removed from this list, if present
62.18/19.61 * @return true if this list contained the specified element
62.18/19.61 */
62.18/19.61 public boolean remove(Object o) {
62.18/19.61 if (o==null) {
62.18/19.61 for (Entry e = header.next; e != header; e = e.next) {
62.18/19.61 if (e.element==null) {
62.18/19.61 remove(e);
62.18/19.61 return true;
62.18/19.61 }
62.18/19.61 }
62.18/19.61 } else {
62.18/19.61 for (Entry e = header.next; e != header; e = e.next) {
62.18/19.61 if (o.equals(e.element)) {
62.18/19.61 remove(e);
62.18/19.61 return true;
62.18/19.61 }
62.18/19.61 }
62.18/19.61 }
62.18/19.61 return false;
62.18/19.61 }
62.18/19.61 /**
62.18/19.61 * Removes all of the elements from this list.
62.18/19.61 */
62.18/19.61 public void clear() {
62.18/19.61 Entry e = header.next;
62.18/19.61 while (e != header) {
62.18/19.61 Entry next = e.next;
62.18/19.61 e.next = e.previous = null;
62.18/19.61 e.element = null;
62.18/19.61 e = next;
62.18/19.61 }
62.18/19.61 header.next = header.previous = header;
62.18/19.61 size = 0;
62.18/19.61 modCount++;
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 // Positional Access Operations
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the element at the specified position in this list.
62.18/19.61 *
62.18/19.61 * @param index index of the element to return
62.18/19.61 * @return the element at the specified position in this list
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public E get(int index) {
62.18/19.61 return entry(index).element;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Replaces the element at the specified position in this list with the
62.18/19.61 * specified element.
62.18/19.61 *
62.18/19.61 * @param index index of the element to replace
62.18/19.61 * @param element element to be stored at the specified position
62.18/19.61 * @return the element previously at the specified position
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public E set(int index, E element) {
62.18/19.61 Entry e = entry(index);
62.18/19.61 E oldVal = e.element;
62.18/19.61 e.element = element;
62.18/19.61 return oldVal;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the specified position in this list.
62.18/19.61 * Shifts the element currently at that position (if any) and any
62.18/19.61 * subsequent elements to the right (adds one to their indices).
62.18/19.61 *
62.18/19.61 * @param index index at which the specified element is to be inserted
62.18/19.61 * @param element element to be inserted
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public void add(int index, E element) {
62.18/19.61 addBefore(element, (index==size ? header : entry(index)));
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Removes the element at the specified position in this list. Shifts any
62.18/19.61 * subsequent elements to the left (subtracts one from their indices).
62.18/19.61 * Returns the element that was removed from the list.
62.18/19.61 *
62.18/19.61 * @param index the index of the element to be removed
62.18/19.61 * @return the element previously at the specified position
62.18/19.61 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.61 */
62.18/19.61 public E remove(int index) {
62.18/19.61 return remove(entry(index));
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the indexed entry.
62.18/19.61 */
62.18/19.61 private Entry entry(int index) {
62.18/19.61 if (index < 0 || index >= size)
62.18/19.61 throw new IndexOutOfBoundsException();
62.18/19.61 Entry e = header;
62.18/19.61 if (index < (size >> 1)) {
62.18/19.61 for (int i = 0; i <= index; i++)
62.18/19.61 e = e.next;
62.18/19.61 } else {
62.18/19.61 for (int i = size; i > index; i--)
62.18/19.61 e = e.previous;
62.18/19.61 }
62.18/19.61 return e;
62.18/19.61 }
62.18/19.61
62.18/19.61
62.18/19.61 // Search Operations
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the index of the first occurrence of the specified element
62.18/19.61 * in this list, or -1 if this list does not contain the element.
62.18/19.61 * More formally, returns the lowest index i such that
62.18/19.61 * (o==null ? get(i)==null : o.equals(get(i))),
62.18/19.61 * or -1 if there is no such index.
62.18/19.61 *
62.18/19.61 * @param o element to search for
62.18/19.61 * @return the index of the first occurrence of the specified element in
62.18/19.61 * this list, or -1 if this list does not contain the element
62.18/19.61 */
62.18/19.61 public int indexOf(Object o) {
62.18/19.61 int index = 0;
62.18/19.61 if (o==null) {
62.18/19.61 for (Entry e = header.next; e != header; e = e.next) {
62.18/19.61 if (e.element==null)
62.18/19.61 return index;
62.18/19.61 index++;
62.18/19.61 }
62.18/19.61 } else {
62.18/19.61 for (Entry e = header.next; e != header; e = e.next) {
62.18/19.61 if (o.equals(e.element))
62.18/19.61 return index;
62.18/19.61 index++;
62.18/19.61 }
62.18/19.61 }
62.18/19.61 return -1;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Returns the index of the last occurrence of the specified element
62.18/19.61 * in this list, or -1 if this list does not contain the element.
62.18/19.61 * More formally, returns the highest index i such that
62.18/19.61 * (o==null ? get(i)==null : o.equals(get(i))),
62.18/19.61 * or -1 if there is no such index.
62.18/19.61 *
62.18/19.61 * @param o element to search for
62.18/19.61 * @return the index of the last occurrence of the specified element in
62.18/19.61 * this list, or -1 if this list does not contain the element
62.18/19.61 */
62.18/19.61 public int lastIndexOf(Object o) {
62.18/19.61 int index = size;
62.18/19.61 if (o==null) {
62.18/19.61 for (Entry e = header.previous; e != header; e = e.previous) {
62.18/19.61 index--;
62.18/19.61 if (e.element==null)
62.18/19.61 return index;
62.18/19.61 }
62.18/19.61 } else {
62.18/19.61 for (Entry e = header.previous; e != header; e = e.previous) {
62.18/19.61 index--;
62.18/19.61 if (o.equals(e.element))
62.18/19.61 return index;
62.18/19.61 }
62.18/19.61 }
62.18/19.61 return -1;
62.18/19.61 }
62.18/19.61
62.18/19.61 // Queue operations.
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the head (first element) of this list.
62.18/19.61 * @return the head of this list, or null if this list is empty
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public E peek() {
62.18/19.61 if (size==0)
62.18/19.61 return null;
62.18/19.61 return getFirst();
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the head (first element) of this list.
62.18/19.61 * @return the head of this list
62.18/19.61 * @throws NoSuchElementException if this list is empty
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public E element() {
62.18/19.61 return getFirst();
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the head (first element) of this list
62.18/19.61 * @return the head of this list, or null if this list is empty
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public E poll() {
62.18/19.61 if (size==0)
62.18/19.61 return null;
62.18/19.61 return removeFirst();
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves and removes the head (first element) of this list.
62.18/19.61 *
62.18/19.61 * @return the head of this list
62.18/19.61 * @throws NoSuchElementException if this list is empty
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public E remove() {
62.18/19.61 return removeFirst();
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Adds the specified element as the tail (last element) of this list.
62.18/19.61 *
62.18/19.61 * @param e the element to add
62.18/19.61 * @return true (as specified by {@link Queue#offer})
62.18/19.61 * @since 1.5
62.18/19.61 */
62.18/19.61 public boolean offer(E e) {
62.18/19.61 return add(e);
62.18/19.61 }
62.18/19.61
62.18/19.61 // Deque operations
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the front of this list.
62.18/19.61 *
62.18/19.61 * @param e the element to insert
62.18/19.61 * @return true (as specified by {@link Deque#offerFirst})
62.18/19.61 * @since 1.6
62.18/19.61 */
62.18/19.61 public boolean offerFirst(E e) {
62.18/19.61 addFirst(e);
62.18/19.61 return true;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Inserts the specified element at the end of this list.
62.18/19.61 *
62.18/19.61 * @param e the element to insert
62.18/19.61 * @return true (as specified by {@link Deque#offerLast})
62.18/19.61 * @since 1.6
62.18/19.61 */
62.18/19.61 public boolean offerLast(E e) {
62.18/19.61 addLast(e);
62.18/19.61 return true;
62.18/19.61 }
62.18/19.61
62.18/19.61 /**
62.18/19.61 * Retrieves, but does not remove, the first element of this list,
62.18/19.61 * or returns null if this list is empty.
62.18/19.61 *
62.18/19.61 * @return the first element of this list, or null
62.18/19.61 * if this list is empty
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public E peekFirst() {
62.18/19.62 if (size==0)
62.18/19.62 return null;
62.18/19.62 return getFirst();
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Retrieves, but does not remove, the last element of this list,
62.18/19.62 * or returns null if this list is empty.
62.18/19.62 *
62.18/19.62 * @return the last element of this list, or null
62.18/19.62 * if this list is empty
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public E peekLast() {
62.18/19.62 if (size==0)
62.18/19.62 return null;
62.18/19.62 return getLast();
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Retrieves and removes the first element of this list,
62.18/19.62 * or returns null if this list is empty.
62.18/19.62 *
62.18/19.62 * @return the first element of this list, or null if
62.18/19.62 * this list is empty
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public E pollFirst() {
62.18/19.62 if (size==0)
62.18/19.62 return null;
62.18/19.62 return removeFirst();
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Retrieves and removes the last element of this list,
62.18/19.62 * or returns null if this list is empty.
62.18/19.62 *
62.18/19.62 * @return the last element of this list, or null if
62.18/19.62 * this list is empty
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public E pollLast() {
62.18/19.62 if (size==0)
62.18/19.62 return null;
62.18/19.62 return removeLast();
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Pushes an element onto the stack represented by this list. In other
62.18/19.62 * words, inserts the element at the front of this list.
62.18/19.62 *
62.18/19.62 * This method is equivalent to {@link #addFirst}.
62.18/19.62 *
62.18/19.62 * @param e the element to push
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public void push(E e) {
62.18/19.62 addFirst(e);
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Pops an element from the stack represented by this list. In other
62.18/19.62 * words, removes and returns the first element of this list.
62.18/19.62 *
62.18/19.62 *
This method is equivalent to {@link #removeFirst()}.
62.18/19.62 *
62.18/19.62 * @return the element at the front of this list (which is the top
62.18/19.62 * of the stack represented by this list)
62.18/19.62 * @throws NoSuchElementException if this list is empty
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public E pop() {
62.18/19.62 return removeFirst();
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Removes the first occurrence of the specified element in this
62.18/19.62 * list (when traversing the list from head to tail). If the list
62.18/19.62 * does not contain the element, it is unchanged.
62.18/19.62 *
62.18/19.62 * @param o element to be removed from this list, if present
62.18/19.62 * @return true if the list contained the specified element
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public boolean removeFirstOccurrence(Object o) {
62.18/19.62 return remove(o);
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Removes the last occurrence of the specified element in this
62.18/19.62 * list (when traversing the list from head to tail). If the list
62.18/19.62 * does not contain the element, it is unchanged.
62.18/19.62 *
62.18/19.62 * @param o element to be removed from this list, if present
62.18/19.62 * @return true if the list contained the specified element
62.18/19.62 * @since 1.6
62.18/19.62 */
62.18/19.62 public boolean removeLastOccurrence(Object o) {
62.18/19.62 if (o==null) {
62.18/19.62 for (Entry e = header.previous; e != header; e = e.previous) {
62.18/19.62 if (e.element==null) {
62.18/19.62 remove(e);
62.18/19.62 return true;
62.18/19.62 }
62.18/19.62 }
62.18/19.62 } else {
62.18/19.62 for (Entry e = header.previous; e != header; e = e.previous) {
62.18/19.62 if (o.equals(e.element)) {
62.18/19.62 remove(e);
62.18/19.62 return true;
62.18/19.62 }
62.18/19.62 }
62.18/19.62 }
62.18/19.62 return false;
62.18/19.62 }
62.18/19.62
62.18/19.62 /**
62.18/19.62 * Returns a list-iterator of the elements in this list (in proper
62.18/19.62 * sequence), starting at the specified position in the list.
62.18/19.62 * Obeys the general contract of List.listIterator(int).
62.18/19.62 *
62.18/19.62 * The list-iterator is fail-fast: if the list is structurally
62.18/19.62 * modified at any time after the Iterator is created, in any way except
62.18/19.62 * through the list-iterator's own remove or add
62.18/19.62 * methods, the list-iterator will throw a
62.18/19.62 * ConcurrentModificationException. Thus, in the face of
62.18/19.62 * concurrent modification, the iterator fails quickly and cleanly, rather
62.18/19.62 * than risking arbitrary, non-deterministic behavior at an undetermined
62.18/19.62 * time in the future.
62.18/19.62 *
62.18/19.62 * @param index index of the first element to be returned from the
62.18/19.62 * list-iterator (by a call to next)
62.18/19.62 * @return a ListIterator of the elements in this list (in proper
62.18/19.62 * sequence), starting at the specified position in the list
62.18/19.62 * @throws IndexOutOfBoundsException {@inheritDoc}
62.18/19.62 * @see List#listIterator(int)
62.18/19.62 */
62.18/19.62 public ListIterator listIterator(int index) {
62.18/19.62 return new ListItr(index);
62.18/19.62 }
62.18/19.62
62.18/19.62 private class ListItr implements ListIterator {
62.18/19.62 private Entry lastReturned = header;
62.18/19.62 private Entry next;
62.18/19.62 private int nextIndex;
62.18/19.62 private int expectedModCount = modCount;
62.18/19.62
62.18/19.62 ListItr(int index) {
62.18/19.62 if (index < 0 || index > size)
62.18/19.62 throw new IndexOutOfBoundsException();
62.18/19.62 if (index < (size >> 1)) {
62.18/19.62 next = header.next;
62.18/19.62 for (nextIndex=0; nextIndexindex; nextIndex--)
62.18/19.62 next = next.previous;
62.18/19.62 }
62.18/19.62 }
62.18/19.62
62.18/19.62 public boolean hasNext() {
62.18/19.62 return nextIndex != size;
62.18/19.62 }
62.18/19.62
62.18/19.62 public E next() {
62.18/19.62 checkForComodification();
62.18/19.62 if (nextIndex == size)
62.18/19.62 throw new NoSuchElementException();
62.18/19.62
62.18/19.62 lastReturned = next;
62.18/19.62 next = next.next;
62.18/19.62 nextIndex++;
62.18/19.62 return lastReturned.element;
62.18/19.62 }
62.18/19.62
62.18/19.62 public boolean hasPrevious() {
62.18/19.62 return nextIndex != 0;
62.18/19.62 }
62.18/19.62
62.18/19.62 public E previous() {
62.18/19.62 if (nextIndex == 0)
62.18/19.62 throw new NoSuchElementException();
62.18/19.62
62.18/19.62 lastReturned = next = next.previous;
62.18/19.62 nextIndex--;
62.18/19.62 checkForComodification();
62.18/19.62 return lastReturned.element;
62.18/19.62 }
62.18/19.62
62.18/19.62 public int nextIndex() {
62.18/19.62 return nextIndex;
62.18/19.62 }
62.18/19.62
62.18/19.62 public int previousIndex() {
62.18/19.62 return nextIndex-1;
62.18/19.62 }
62.18/19.62
62.18/19.62 public void remove() {
62.18/19.62 checkForComodification();
62.18/19.62 Entry lastNext = lastReturned.next;
62.18/19.62 try {
62.18/19.62 LinkedList.this.remove(lastReturned);
62.18/19.62 } catch (NoSuchElementException e) {
62.18/19.62 throw new IllegalStateException();
62.18/19.62 }
62.18/19.62 if (next==lastReturned)
62.18/19.62 next = lastNext;
62.18/19.62 else
62.18/19.62 nextIndex--;
62.18/19.62 lastReturned = header;
62.18/19.62 expectedModCount++;
62.18/19.62 }
62.18/19.62
62.18/19.62 public void set(E e) {
62.18/19.62 if (lastReturned == header)
62.18/19.62 throw new IllegalStateException();
62.18/19.62 checkForComodification();
62.18/19.62 lastReturned.element = e;
62.18/19.62 }
62.18/19.62
62.18/19.62 public void add(E e) {
62.18/19.62 checkForComodification();
62.18/19.62 lastReturned = header;
62.18/19.62 addBefore(e, next);
62.18/19.62 nextIndex++;
62.18/19.62 expectedModCount++;
62.18/19.62 }
62.18/19.62
62.18/19.62 final void checkForComodification() {
62.18/19.62 if (modCount != expectedModCount)
62.18/19.62 throw new ConcurrentModificationException();
62.18/19.62 }
62.18/19.62 }
62.18/19.62
62.18/19.62 private static class Entry {
62.18/19.62 E element;
62.18/19.62 Entry next;
62.18/19.62 Entry