ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/main/java/util/Vector.java
(Generate patch)

Comparing jsr166/src/main/java/util/Vector.java (file contents):
Revision 1.11 by jsr166, Thu Apr 20 21:49:36 2006 UTC vs.
Revision 1.15 by jsr166, Sun Jun 25 19:58:14 2006 UTC

# Line 1 | Line 1
1   /*
2 < * @(#)Vector.java      1.103 05/12/06
2 > * %W% %E%
3   *
4   * Copyright 2006 Sun Microsystems, Inc. All rights reserved.
5   * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
# Line 8 | Line 8
8   package java.util;
9  
10   /**
11 < * The <code>Vector</code> class implements a growable array of
11 > * The {@code Vector} class implements a growable array of
12   * objects. Like an array, it contains components that can be
13   * accessed using an integer index. However, the size of a
14 < * <code>Vector</code> can grow or shrink as needed to accommodate
15 < * adding and removing items after the <code>Vector</code> has been created.
14 > * {@code Vector} can grow or shrink as needed to accommodate
15 > * adding and removing items after the {@code Vector} has been created.
16   *
17   * <p>Each vector tries to optimize storage management by maintaining a
18 < * <code>capacity</code> and a <code>capacityIncrement</code>. The
19 < * <code>capacity</code> is always at least as large as the vector
18 > * {@code capacity} and a {@code capacityIncrement}. The
19 > * {@code capacity} is always at least as large as the vector
20   * size; it is usually larger because as components are added to the
21   * vector, the vector's storage increases in chunks the size of
22 < * <code>capacityIncrement</code>. An application can increase the
22 > * {@code capacityIncrement}. An application can increase the
23   * capacity of a vector before inserting a large number of
24   * components; this reduces the amount of incremental reallocation.
25   *
# Line 36 | Line 36 | package java.util;
36   * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed
37   * as it is, generally speaking, impossible to make any hard guarantees in the
38   * presence of unsynchronized concurrent modification.  Fail-fast iterators
39 < * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.
39 > * throw {@code ConcurrentModificationException} on a best-effort basis.
40   * Therefore, it would be wrong to write a program that depended on this
41   * exception for its correctness:  <i>the fail-fast behavior of iterators
42   * should be used only to detect bugs.</i>
43   *
44   * <p>As of the Java 2 platform v1.2, this class was retrofitted to
45   * implement the {@link List} interface, making it a member of the
46 < * <a href="{@docRoot}/../guide/collections/index.html"> Java
46 > * <a href="{@docRoot}/../technotes/guides/collections/index.html"> Java
47   * Collections Framework</a>.  Unlike the new collection
48   * implementations, {@code Vector} is synchronized.
49   *
50   * @author  Lee Boynton
51   * @author  Jonathan Payne
52 < * @version 1.103, 12/06/05
52 > * @version %I%, %G%
53   * @see Collection
54   * @see List
55   * @see ArrayList
# Line 63 | Line 63 | public class Vector<E>
63      /**
64       * The array buffer into which the components of the vector are
65       * stored. The capacity of the vector is the length of this array buffer,
66 <     * and is at least large enough to contain all the vector's elements.<p>
66 >     * and is at least large enough to contain all the vector's elements.
67       *
68 <     * Any array elements following the last element in the Vector are null.
68 >     * <p>Any array elements following the last element in the Vector are null.
69       *
70       * @serial
71       */
72      protected Object[] elementData;
73  
74      /**
75 <     * The number of valid components in this <tt>Vector</tt> object.
76 <     * Components <tt>elementData[0]</tt> through
77 <     * <tt>elementData[elementCount-1]</tt> are the actual items.
75 >     * The number of valid components in this {@code Vector} object.
76 >     * Components {@code elementData[0]} through
77 >     * {@code elementData[elementCount-1]} are the actual items.
78       *
79       * @serial
80       */
# Line 100 | Line 100 | public class Vector<E>
100       * @param   initialCapacity     the initial capacity of the vector
101       * @param   capacityIncrement   the amount by which the capacity is
102       *                              increased when the vector overflows
103 <     * @exception IllegalArgumentException if the specified initial capacity
104 <     *               is negative
103 >     * @throws IllegalArgumentException if the specified initial capacity
104 >     *         is negative
105       */
106      public Vector(int initialCapacity, int capacityIncrement) {
107          super();
# Line 117 | Line 117 | public class Vector<E>
117       * with its capacity increment equal to zero.
118       *
119       * @param   initialCapacity   the initial capacity of the vector
120 <     * @exception IllegalArgumentException if the specified initial capacity
121 <     *               is negative
120 >     * @throws IllegalArgumentException if the specified initial capacity
121 >     *         is negative
122       */
123      public Vector(int initialCapacity) {
124          this(initialCapacity, 0);
# Line 126 | Line 126 | public class Vector<E>
126  
127      /**
128       * Constructs an empty vector so that its internal data array
129 <     * has size <tt>10</tt> and its standard capacity increment is
129 >     * has size {@code 10} and its standard capacity increment is
130       * zero.
131       */
132      public Vector() {
# Line 153 | Line 153 | public class Vector<E>
153  
154      /**
155       * Copies the components of this vector into the specified array.
156 <     * The item at index <tt>k</tt> in this vector is copied into
157 <     * component <tt>k</tt> of <tt>anArray</tt>.
156 >     * The item at index {@code k} in this vector is copied into
157 >     * component {@code k} of {@code anArray}.
158       *
159       * @param  anArray the array into which the components get copied
160       * @throws NullPointerException if the given array is null
# Line 172 | Line 172 | public class Vector<E>
172       * Trims the capacity of this vector to be the vector's current
173       * size. If the capacity of this vector is larger than its current
174       * size, then the capacity is changed to equal the size by replacing
175 <     * its internal data array, kept in the field <tt>elementData</tt>,
175 >     * its internal data array, kept in the field {@code elementData},
176       * with a smaller one. An application can use this operation to
177       * minimize the storage of a vector.
178       */
# Line 190 | Line 190 | public class Vector<E>
190       * the minimum capacity argument.
191       *
192       * <p>If the current capacity of this vector is less than
193 <     * <tt>minCapacity</tt>, then its capacity is increased by replacing its
194 <     * internal data array, kept in the field <tt>elementData</tt>, with a
193 >     * {@code minCapacity}, then its capacity is increased by replacing its
194 >     * internal data array, kept in the field {@code elementData}, with a
195       * larger one.  The size of the new data array will be the old size plus
196 <     * <tt>capacityIncrement</tt>, unless the value of
197 <     * <tt>capacityIncrement</tt> is less than or equal to zero, in which case
196 >     * {@code capacityIncrement}, unless the value of
197 >     * {@code capacityIncrement} is less than or equal to zero, in which case
198       * the new capacity will be twice the old capacity; but if this new size
199 <     * is still smaller than <tt>minCapacity</tt>, then the new capacity will
200 <     * be <tt>minCapacity</tt>.
199 >     * is still smaller than {@code minCapacity}, then the new capacity will
200 >     * be {@code minCapacity}.
201       *
202       * @param minCapacity the desired minimum capacity
203       */
# Line 212 | Line 212 | public class Vector<E>
212       * method for ensuring capacity without incurring the cost of an
213       * extra synchronization.
214       *
215 <     * @see java.util.Vector#ensureCapacity(int)
215 >     * @see #ensureCapacity(int)
216       */
217      private void ensureCapacityHelper(int minCapacity) {
218          int oldCapacity = elementData.length;
# Line 229 | Line 229 | public class Vector<E>
229  
230      /**
231       * Sets the size of this vector. If the new size is greater than the
232 <     * current size, new <code>null</code> items are added to the end of
232 >     * current size, new {@code null} items are added to the end of
233       * the vector. If the new size is less than the current size, all
234 <     * components at index <code>newSize</code> and greater are discarded.
234 >     * components at index {@code newSize} and greater are discarded.
235       *
236       * @param   newSize   the new size of this vector
237       * @throws  ArrayIndexOutOfBoundsException if new size is negative
# Line 252 | Line 252 | public class Vector<E>
252       * Returns the current capacity of this vector.
253       *
254       * @return  the current capacity (the length of its internal
255 <     *          data array, kept in the field <tt>elementData</tt>
255 >     *          data array, kept in the field {@code elementData}
256       *          of this vector)
257       */
258      public synchronized int capacity() {
# Line 271 | Line 271 | public class Vector<E>
271      /**
272       * Tests if this vector has no components.
273       *
274 <     * @return  <code>true</code> if and only if this vector has
274 >     * @return  {@code true} if and only if this vector has
275       *          no components, that is, its size is zero;
276 <     *          <code>false</code> otherwise.
276 >     *          {@code false} otherwise.
277       */
278      public synchronized boolean isEmpty() {
279          return elementCount == 0;
# Line 281 | Line 281 | public class Vector<E>
281  
282      /**
283       * Returns an enumeration of the components of this vector. The
284 <     * returned <tt>Enumeration</tt> object will generate all items in
285 <     * this vector. The first item generated is the item at index <tt>0</tt>,
286 <     * then the item at index <tt>1</tt>, and so on.
284 >     * returned {@code Enumeration} object will generate all items in
285 >     * this vector. The first item generated is the item at index {@code 0},
286 >     * then the item at index {@code 1}, and so on.
287       *
288       * @return  an enumeration of the components of this vector
289 –     * @see     Enumeration
289       * @see     Iterator
290       */
291      public Enumeration<E> elements() {
# Line 309 | Line 308 | public class Vector<E>
308      }
309  
310      /**
311 <     * Returns <tt>true</tt> if this vector contains the specified element.
312 <     * More formally, returns <tt>true</tt> if and only if this vector
313 <     * contains at least one element <tt>e</tt> such that
311 >     * Returns {@code true} if this vector contains the specified element.
312 >     * More formally, returns {@code true} if and only if this vector
313 >     * contains at least one element {@code e} such that
314       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
315       *
316       * @param o element whose presence in this vector is to be tested
317 <     * @return <tt>true</tt> if this vector contains the specified element
317 >     * @return {@code true} if this vector contains the specified element
318       */
319      public boolean contains(Object o) {
320          return indexOf(o, 0) >= 0;
# Line 324 | Line 323 | public class Vector<E>
323      /**
324       * Returns the index of the first occurrence of the specified element
325       * in this vector, or -1 if this vector does not contain the element.
326 <     * More formally, returns the lowest index <tt>i</tt> such that
326 >     * More formally, returns the lowest index {@code i} such that
327       * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
328       * or -1 if there is no such index.
329       *
# Line 338 | Line 337 | public class Vector<E>
337  
338      /**
339       * Returns the index of the first occurrence of the specified element in
340 <     * this vector, searching forwards from <tt>index</tt>, or returns -1 if
340 >     * this vector, searching forwards from {@code index}, or returns -1 if
341       * the element is not found.
342 <     * More formally, returns the lowest index <tt>i</tt> such that
342 >     * More formally, returns the lowest index {@code i} such that
343       * <tt>(i&nbsp;&gt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i))))</tt>,
344       * or -1 if there is no such index.
345       *
346       * @param o element to search for
347       * @param index index to start searching from
348       * @return the index of the first occurrence of the element in
349 <     *         this vector at position <tt>index</tt> or later in the vector;
350 <     *         <tt>-1</tt> if the element is not found.
349 >     *         this vector at position {@code index} or later in the vector;
350 >     *         {@code -1} if the element is not found.
351       * @throws IndexOutOfBoundsException if the specified index is negative
352       * @see     Object#equals(Object)
353       */
# Line 368 | Line 367 | public class Vector<E>
367      /**
368       * Returns the index of the last occurrence of the specified element
369       * in this vector, or -1 if this vector does not contain the element.
370 <     * More formally, returns the highest index <tt>i</tt> such that
370 >     * More formally, returns the highest index {@code i} such that
371       * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
372       * or -1 if there is no such index.
373       *
# Line 382 | Line 381 | public class Vector<E>
381  
382      /**
383       * Returns the index of the last occurrence of the specified element in
384 <     * this vector, searching backwards from <tt>index</tt>, or returns -1 if
384 >     * this vector, searching backwards from {@code index}, or returns -1 if
385       * the element is not found.
386 <     * More formally, returns the highest index <tt>i</tt> such that
386 >     * More formally, returns the highest index {@code i} such that
387       * <tt>(i&nbsp;&lt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i))))</tt>,
388       * or -1 if there is no such index.
389       *
390       * @param o element to search for
391       * @param index index to start searching backwards from
392       * @return the index of the last occurrence of the element at position
393 <     *         less than or equal to <tt>index</tt> in this vector;
393 >     *         less than or equal to {@code index} in this vector;
394       *         -1 if the element is not found.
395       * @throws IndexOutOfBoundsException if the specified index is greater
396       *         than or equal to the current size of this vector
# Line 413 | Line 412 | public class Vector<E>
412      }
413  
414      /**
415 <     * Returns the component at the specified index.<p>
415 >     * Returns the component at the specified index.
416       *
417 <     * This method is identical in functionality to the get method
418 <     * (which is part of the List interface).
417 >     * <p>This method is identical in functionality to the {@link #get(int)}
418 >     * method (which is part of the {@link List} interface).
419       *
420       * @param      index   an index into this vector
421       * @return     the component at the specified index
422 <     * @exception  ArrayIndexOutOfBoundsException  if the <tt>index</tt>
423 <     *             is negative or not less than the current size of this
425 <     *             <tt>Vector</tt> object.
426 <     * @see        #get(int)
427 <     * @see        List
422 >     * @throws ArrayIndexOutOfBoundsException if the index is out of range
423 >     *         ({@code index < 0 || index >= size()})
424       */
425      public synchronized E elementAt(int index) {
426          if (index >= elementCount) {
# Line 435 | Line 431 | public class Vector<E>
431      }
432  
433      /**
434 <     * Returns the first component (the item at index <tt>0</tt>) of
434 >     * Returns the first component (the item at index {@code 0}) of
435       * this vector.
436       *
437       * @return     the first component of this vector
438 <     * @exception  NoSuchElementException  if this vector has no components
438 >     * @throws NoSuchElementException if this vector has no components
439       */
440      public synchronized E firstElement() {
441          if (elementCount == 0) {
# Line 453 | Line 449 | public class Vector<E>
449       *
450       * @return  the last component of the vector, i.e., the component at index
451       *          <code>size()&nbsp;-&nbsp;1</code>.
452 <     * @exception  NoSuchElementException  if this vector is empty
452 >     * @throws NoSuchElementException if this vector is empty
453       */
454      public synchronized E lastElement() {
455          if (elementCount == 0) {
# Line 463 | Line 459 | public class Vector<E>
459      }
460  
461      /**
462 <     * Sets the component at the specified <code>index</code> of this
462 >     * Sets the component at the specified {@code index} of this
463       * vector to be the specified object. The previous component at that
464       * position is discarded.<p>
465       *
466 <     * The index must be a value greater than or equal to <code>0</code>
466 >     * The index must be a value greater than or equal to {@code 0}
467       * and less than the current size of the vector. <p>
468       *
469       * This method is identical in functionality to the set method
# Line 478 | Line 474 | public class Vector<E>
474       *
475       * @param      obj     what the component is to be set to
476       * @param      index   the specified index
477 <     * @exception  ArrayIndexOutOfBoundsException  if the index was invalid
477 >     * @throws  ArrayIndexOutOfBoundsException  if the index was invalid
478       * @see        #size()
479       * @see        List
480       * @see        #set(int, java.lang.Object)
# Line 494 | Line 490 | public class Vector<E>
490      /**
491       * Deletes the component at the specified index. Each component in
492       * this vector with an index greater or equal to the specified
493 <     * <code>index</code> is shifted downward to have an index one
493 >     * {@code index} is shifted downward to have an index one
494       * smaller than the value it had previously. The size of this vector
495 <     * is decreased by <tt>1</tt>.<p>
495 >     * is decreased by {@code 1}.
496       *
497 <     * The index must be a value greater than or equal to <code>0</code>
498 <     * and less than the current size of the vector. <p>
497 >     * <p>The index must be a value greater than or equal to {@code 0}
498 >     * and less than the current size of the vector.
499       *
500 <     * This method is identical in functionality to the remove method
500 >     * <p>This method is identical in functionality to the remove method
501       * (which is part of the List interface).  Note that the remove method
502       * returns the old value that was stored at the specified position.
503       *
# Line 530 | Line 526 | public class Vector<E>
526  
527      /**
528       * Inserts the specified object as a component in this vector at the
529 <     * specified <code>index</code>. Each component in this vector with
530 <     * an index greater or equal to the specified <code>index</code> is
529 >     * specified {@code index}. Each component in this vector with
530 >     * an index greater or equal to the specified {@code index} is
531       * shifted upward to have an index one greater than the value it had
532 <     * previously. <p>
532 >     * previously.
533       *
534 <     * The index must be a value greater than or equal to <code>0</code>
534 >     * <p>The index must be a value greater than or equal to {@code 0}
535       * and less than or equal to the current size of the vector. (If the
536       * index is equal to the current size of the vector, the new element
537 <     * is appended to the Vector.)<p>
537 >     * is appended to the Vector.)
538       *
539 <     * This method is identical in functionality to the add(Object, int) method
539 >     * <p>This method is identical in functionality to the add(Object, int) method
540       * (which is part of the List interface). Note that the add method reverses
541       * the order of the parameters, to more closely match array usage.
542       *
# Line 592 | Line 588 | public class Vector<E>
588       * method (which is part of the List interface).
589       *
590       * @param   obj   the component to be removed
591 <     * @return  <code>true</code> if the argument was a component of this
592 <     *          vector; <code>false</code> otherwise.
591 >     * @return  {@code true} if the argument was a component of this
592 >     *          vector; {@code false} otherwise.
593       * @see     List#remove(Object)
594       * @see     List
595       */
# Line 628 | Line 624 | public class Vector<E>
624      /**
625       * Returns a clone of this vector. The copy will contain a
626       * reference to a clone of the internal data array, not a reference
627 <     * to the original internal data array of this <tt>Vector</tt> object.
627 >     * to the original internal data array of this {@code Vector} object.
628       *
629       * @return  a clone of this vector
630       */
# Line 731 | Line 727 | public class Vector<E>
727       * Appends the specified element to the end of this Vector.
728       *
729       * @param e element to be appended to this Vector
730 <     * @return <tt>true</tt> (as specified by {@link Collection#add})
730 >     * @return {@code true} (as specified by {@link Collection#add})
731       * @since 1.2
732       */
733      public synchronized boolean add(E e) {
# Line 745 | Line 741 | public class Vector<E>
741       * Removes the first occurrence of the specified element in this Vector
742       * If the Vector does not contain the element, it is unchanged.  More
743       * formally, removes the element with the lowest index i such that
744 <     * <code>(o==null ? get(i)==null : o.equals(get(i)))</code> (if such
744 >     * {@code (o==null ? get(i)==null : o.equals(get(i)))} (if such
745       * an element exists).
746       *
747       * @param o element to be removed from this Vector, if present
# Line 832 | Line 828 | public class Vector<E>
828       * specified Collection is this Vector, and this Vector is nonempty.)
829       *
830       * @param c elements to be inserted into this Vector
831 <     * @return <tt>true</tt> if this Vector changed as a result of the call
831 >     * @return {@code true} if this Vector changed as a result of the call
832       * @throws NullPointerException if the specified collection is null
833       * @since 1.2
834       */
# Line 895 | Line 891 | public class Vector<E>
891       * @param index index at which to insert the first element from the
892       *              specified collection
893       * @param c elements to be inserted into this Vector
894 <     * @return <tt>true</tt> if this Vector changed as a result of the call
894 >     * @return {@code true} if this Vector changed as a result of the call
895       * @exception ArrayIndexOutOfBoundsException index out of range (index
896       *            &lt; 0 || index &gt; size())
897       * @throws NullPointerException if the specified collection is null
# Line 924 | Line 920 | public class Vector<E>
920       * Compares the specified Object with this Vector for equality.  Returns
921       * true if and only if the specified Object is also a List, both Lists
922       * have the same size, and all corresponding pairs of elements in the two
923 <     * Lists are <em>equal</em>.  (Two elements <code>e1</code> and
924 <     * <code>e2</code> are <em>equal</em> if <code>(e1==null ? e2==null :
925 <     * e1.equals(e2))</code>.)  In other words, two Lists are defined to be
923 >     * Lists are <em>equal</em>.  (Two elements {@code e1} and
924 >     * {@code e2} are <em>equal</em> if {@code (e1==null ? e2==null :
925 >     * e1.equals(e2))}.)  In other words, two Lists are defined to be
926       * equal if they contain the same elements in the same order.
927       *
928       * @param o the Object to be compared for equality with this Vector
# Line 974 | Line 970 | public class Vector<E>
970      }
971  
972      /**
973 <     * Save the state of the <tt>Vector</tt> instance to a stream (that
973 >     * Save the state of the {@code Vector} instance to a stream (that
974       * is, serialize it).  This method is present merely for synchronization.
975       * It just calls the default writeObject method.
976       */

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines