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