51  * the size of the array used to store the elements in the list.  It is always
  52  * at least as large as the list size.  As elements are added to an IdentityArrayList,
  53  * its capacity grows automatically.  The details of the growth policy are not
  54  * specified beyond the fact that adding an element has constant amortized
  55  * time cost.<p>
  56  *
  57  * An application can increase the capacity of an <tt>IdentityArrayList</tt> instance
  58  * before adding a large number of elements using the <tt>ensureCapacity</tt>
  59  * operation.  This may reduce the amount of incremental reallocation.
  60  *
  61  * <p><strong>Note that this implementation is not synchronized.</strong>
  62  * If multiple threads access an <tt>IdentityArrayList</tt> instance concurrently,
  63  * and at least one of the threads modifies the list structurally, it
  64  * <i>must</i> be synchronized externally.  (A structural modification is
  65  * any operation that adds or deletes one or more elements, or explicitly
  66  * resizes the backing array; merely setting the value of an element is not
  67  * a structural modification.)  This is typically accomplished by
  68  * synchronizing on some object that naturally encapsulates the list.
  69  *
  70  * If no such object exists, the list should be "wrapped" using the
  71  * {@link Collections#synchronizedList Collections.synchronizedList}
  72  * method.  This is best done at creation time, to prevent accidental
  73  * unsynchronized access to the list:<pre>
  74  *   List list = Collections.synchronizedList(new IdentityArrayList(...));</pre>
  75  *
  76  * <p>The iterators returned by this class's <tt>iterator</tt> and
  77  * <tt>listIterator</tt> methods are <i>fail-fast</i>: if the list is
  78  * structurally modified at any time after the iterator is created, in any way
  79  * except through the iterator's own <tt>remove</tt> or <tt>add</tt> methods,
  80  * the iterator will throw a {@link ConcurrentModificationException}.  Thus, in
  81  * the face of concurrent modification, the iterator fails quickly and cleanly,
  82  * rather than risking arbitrary, non-deterministic behavior at an undetermined
  83  * time in the future.<p>
  84  *
  85  * Note that the fail-fast behavior of an iterator cannot be guaranteed
  86  * as it is, generally speaking, impossible to make any hard guarantees in the
  87  * presence of unsynchronized concurrent modification.  Fail-fast iterators
  88  * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
  89  * Therefore, it would be wrong to write a program that depended on this
  90  * exception for its correctness: <i>the fail-fast behavior of iterators
  91  * should be used only to detect bugs.</i><p>

  51  * the size of the array used to store the elements in the list.  It is always
  52  * at least as large as the list size.  As elements are added to an IdentityArrayList,
  53  * its capacity grows automatically.  The details of the growth policy are not
  54  * specified beyond the fact that adding an element has constant amortized
  55  * time cost.<p>
  56  *
  57  * An application can increase the capacity of an <tt>IdentityArrayList</tt> instance
  58  * before adding a large number of elements using the <tt>ensureCapacity</tt>
  59  * operation.  This may reduce the amount of incremental reallocation.
  60  *
  61  * <p><strong>Note that this implementation is not synchronized.</strong>
  62  * If multiple threads access an <tt>IdentityArrayList</tt> instance concurrently,
  63  * and at least one of the threads modifies the list structurally, it
  64  * <i>must</i> be synchronized externally.  (A structural modification is
  65  * any operation that adds or deletes one or more elements, or explicitly
  66  * resizes the backing array; merely setting the value of an element is not
  67  * a structural modification.)  This is typically accomplished by
  68  * synchronizing on some object that naturally encapsulates the list.
  69  *
  70  * If no such object exists, the list should be "wrapped" using the
  71  * {@link java.util.Collections#synchronizedList Collections.synchronizedList}
  72  * method.  This is best done at creation time, to prevent accidental
  73  * unsynchronized access to the list:<pre>
  74  *   List list = Collections.synchronizedList(new IdentityArrayList(...));</pre>
  75  *
  76  * <p>The iterators returned by this class's <tt>iterator</tt> and
  77  * <tt>listIterator</tt> methods are <i>fail-fast</i>: if the list is
  78  * structurally modified at any time after the iterator is created, in any way
  79  * except through the iterator's own <tt>remove</tt> or <tt>add</tt> methods,
  80  * the iterator will throw a {@link ConcurrentModificationException}.  Thus, in
  81  * the face of concurrent modification, the iterator fails quickly and cleanly,
  82  * rather than risking arbitrary, non-deterministic behavior at an undetermined
  83  * time in the future.<p>
  84  *
  85  * Note that the fail-fast behavior of an iterator cannot be guaranteed
  86  * as it is, generally speaking, impossible to make any hard guarantees in the
  87  * presence of unsynchronized concurrent modification.  Fail-fast iterators
  88  * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
  89  * Therefore, it would be wrong to write a program that depended on this
  90  * exception for its correctness: <i>the fail-fast behavior of iterators
  91  * should be used only to detect bugs.</i><p>