[cvs] / jsr166 / src / main / java / util / Vector.java Repository:
ViewVC logotype

Diff of /jsr166/src/main/java/util/Vector.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.13, Sun May 28 23:36:29 2006 UTC revision 1.14, Sun Jun 25 19:41:52 2006 UTC
# Line 8  Line 8 
8  package java.util;  package java.util;
9    
10  /**  /**
11   * The <code>Vector</code> class implements a growable array of   * The {@code Vector} class implements a growable array of
12   * objects. Like an array, it contains components that can be   * objects. Like an array, it contains components that can be
13   * accessed using an integer index. However, the size of a   * accessed using an integer index. However, the size of a
14   * <code>Vector</code> can grow or shrink as needed to accommodate   * {@code Vector} can grow or shrink as needed to accommodate
15   * adding and removing items after the <code>Vector</code> has been created.   * adding and removing items after the {@code Vector} has been created.
16   *   *
17   * <p>Each vector tries to optimize storage management by maintaining a   * <p>Each vector tries to optimize storage management by maintaining a
18   * <code>capacity</code> and a <code>capacityIncrement</code>. The   * {@code capacity} and a {@code capacityIncrement}. The
19   * <code>capacity</code> is always at least as large as the vector   * {@code capacity} is always at least as large as the vector
20   * size; it is usually larger because as components are added to the   * size; it is usually larger because as components are added to the
21   * vector, the vector's storage increases in chunks the size of   * vector, the vector's storage increases in chunks the size of
22   * <code>capacityIncrement</code>. An application can increase the   * {@code capacityIncrement}. An application can increase the
23   * capacity of a vector before inserting a large number of   * capacity of a vector before inserting a large number of
24   * components; this reduces the amount of incremental reallocation.   * components; this reduces the amount of incremental reallocation.
25   *   *
# Line 36  Line 36 
36   * <p>Note that the fail-fast behavior of an iterator cannot be guaranteed   * <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   * as it is, generally speaking, impossible to make any hard guarantees in the
38   * presence of unsynchronized concurrent modification.  Fail-fast iterators   * presence of unsynchronized concurrent modification.  Fail-fast iterators
39   * throw <tt>ConcurrentModificationException</tt> on a best-effort basis.   * throw {@code ConcurrentModificationException} on a best-effort basis.
40   * Therefore, it would be wrong to write a program that depended on this   * 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   * exception for its correctness:  <i>the fail-fast behavior of iterators
42   * should be used only to detect bugs.</i>   * should be used only to detect bugs.</i>
# Line 72  Line 72 
72      protected Object[] elementData;      protected Object[] elementData;
73    
74      /**      /**
75       * The number of valid components in this <tt>Vector</tt> object.       * The number of valid components in this {@code Vector} object.
76       * Components <tt>elementData[0]</tt> through       * Components {@code elementData[0]} through
77       * <tt>elementData[elementCount-1]</tt> are the actual items.       * {@code elementData[elementCount-1]} are the actual items.
78       *       *
79       * @serial       * @serial
80       */       */
# Line 126  Line 126 
126    
127      /**      /**
128       * Constructs an empty vector so that its internal data array       * Constructs an empty vector so that its internal data array
129       * has size <tt>10</tt> and its standard capacity increment is       * has size {@code 10} and its standard capacity increment is
130       * zero.       * zero.
131       */       */
132      public Vector() {      public Vector() {
# Line 153  Line 153 
153    
154      /**      /**
155       * Copies the components of this vector into the specified array.       * Copies the components of this vector into the specified array.
156       * The item at index <tt>k</tt> in this vector is copied into       * The item at index {@code k} in this vector is copied into
157       * component <tt>k</tt> of <tt>anArray</tt>.       * component {@code k} of {@code anArray}.
158       *       *
159       * @param  anArray the array into which the components get copied       * @param  anArray the array into which the components get copied
160       * @throws NullPointerException if the given array is null       * @throws NullPointerException if the given array is null
# Line 172  Line 172 
172       * Trims the capacity of this vector to be the vector's current       * 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       * 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       * size, then the capacity is changed to equal the size by replacing
175       * its internal data array, kept in the field <tt>elementData</tt>,       * its internal data array, kept in the field {@code elementData},
176       * with a smaller one. An application can use this operation to       * with a smaller one. An application can use this operation to
177       * minimize the storage of a vector.       * minimize the storage of a vector.
178       */       */
# Line 190  Line 190 
190       * the minimum capacity argument.       * the minimum capacity argument.
191       *       *
192       * <p>If the current capacity of this vector is less than       * <p>If the current capacity of this vector is less than
193       * <tt>minCapacity</tt>, then its capacity is increased by replacing its       * {@code minCapacity}, then its capacity is increased by replacing its
194       * internal data array, kept in the field <tt>elementData</tt>, with a       * 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       * larger one.  The size of the new data array will be the old size plus
196       * <tt>capacityIncrement</tt>, unless the value of       * {@code capacityIncrement}, unless the value of
197       * <tt>capacityIncrement</tt> is less than or equal to zero, in which case       * {@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       * 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       * is still smaller than {@code minCapacity}, then the new capacity will
200       * be <tt>minCapacity</tt>.       * be {@code minCapacity}.
201       *       *
202       * @param minCapacity the desired minimum capacity       * @param minCapacity the desired minimum capacity
203       */       */
# Line 229  Line 229 
229    
230      /**      /**
231       * Sets the size of this vector. If the new size is greater than the       * 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       * 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       * the vector. If the new size is less than the current size, all
234       * components at index <code>newSize</code> and greater are discarded.       * components at index {@code newSize} and greater are discarded.
235       *       *
236       * @param   newSize   the new size of this vector       * @param   newSize   the new size of this vector
237       * @throws  ArrayIndexOutOfBoundsException if new size is negative       * @throws  ArrayIndexOutOfBoundsException if new size is negative
# Line 252  Line 252 
252       * Returns the current capacity of this vector.       * Returns the current capacity of this vector.
253       *       *
254       * @return  the current capacity (the length of its internal       * @return  the current capacity (the length of its internal
255       *          data array, kept in the field <tt>elementData</tt>       *          data array, kept in the field {@code elementData}
256       *          of this vector)       *          of this vector)
257       */       */
258      public synchronized int capacity() {      public synchronized int capacity() {
# Line 271  Line 271 
271      /**      /**
272       * Tests if this vector has no components.       * Tests if this vector has no components.
273       *       *
274       * @return  <code>true</code> if and only if this vector has       * @return  {@code true} if and only if this vector has
275       *          no components, that is, its size is zero;       *          no components, that is, its size is zero;
276       *          <code>false</code> otherwise.       *          {@code false} otherwise.
277       */       */
278      public synchronized boolean isEmpty() {      public synchronized boolean isEmpty() {
279          return elementCount == 0;          return elementCount == 0;
# Line 281  Line 281 
281    
282      /**      /**
283       * Returns an enumeration of the components of this vector. The       * Returns an enumeration of the components of this vector. The
284       * returned <tt>Enumeration</tt> object will generate all items in       * returned {@code Enumeration} object will generate all items in
285       * this vector. The first item generated is the item at index <tt>0</tt>,       * this vector. The first item generated is the item at index {@code 0},
286       * then the item at index <tt>1</tt>, and so on.       * then the item at index {@code 1}, and so on.
287       *       *
288       * @return  an enumeration of the components of this vector       * @return  an enumeration of the components of this vector
289       * @see     Enumeration       * @see     Enumeration
# Line 309  Line 309 
309      }      }
310    
311      /**      /**
312       * Returns <tt>true</tt> if this vector contains the specified element.       * Returns {@code true} if this vector contains the specified element.
313       * More formally, returns <tt>true</tt> if and only if this vector       * More formally, returns {@code true} if and only if this vector
314       * contains at least one element <tt>e</tt> such that       * contains at least one element {@code e} such that
315       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.       * <tt>(o==null&nbsp;?&nbsp;e==null&nbsp;:&nbsp;o.equals(e))</tt>.
316       *       *
317       * @param o element whose presence in this vector is to be tested       * @param o element whose presence in this vector is to be tested
318       * @return <tt>true</tt> if this vector contains the specified element       * @return {@code true} if this vector contains the specified element
319       */       */
320      public boolean contains(Object o) {      public boolean contains(Object o) {
321          return indexOf(o, 0) >= 0;          return indexOf(o, 0) >= 0;
# Line 324  Line 324 
324      /**      /**
325       * Returns the index of the first occurrence of the specified element       * Returns the index of the first occurrence of the specified element
326       * in this vector, or -1 if this vector does not contain the element.       * in this vector, or -1 if this vector does not contain the element.
327       * More formally, returns the lowest index <tt>i</tt> such that       * More formally, returns the lowest index {@code i} such that
328       * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,       * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
329       * or -1 if there is no such index.       * or -1 if there is no such index.
330       *       *
# Line 338  Line 338 
338    
339      /**      /**
340       * Returns the index of the first occurrence of the specified element in       * Returns the index of the first occurrence of the specified element in
341       * this vector, searching forwards from <tt>index</tt>, or returns -1 if       * this vector, searching forwards from {@code index}, or returns -1 if
342       * the element is not found.       * the element is not found.
343       * More formally, returns the lowest index <tt>i</tt> such that       * More formally, returns the lowest index {@code i} such that
344       * <tt>(i&nbsp;&gt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i))))</tt>,       * <tt>(i&nbsp;&gt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i))))</tt>,
345       * or -1 if there is no such index.       * or -1 if there is no such index.
346       *       *
347       * @param o element to search for       * @param o element to search for
348       * @param index index to start searching from       * @param index index to start searching from
349       * @return the index of the first occurrence of the element in       * @return the index of the first occurrence of the element in
350       *         this vector at position <tt>index</tt> or later in the vector;       *         this vector at position {@code index} or later in the vector;
351       *         <tt>-1</tt> if the element is not found.       *         {@code -1} if the element is not found.
352       * @throws IndexOutOfBoundsException if the specified index is negative       * @throws IndexOutOfBoundsException if the specified index is negative
353       * @see     Object#equals(Object)       * @see     Object#equals(Object)
354       */       */
# Line 368  Line 368 
368      /**      /**
369       * Returns the index of the last occurrence of the specified element       * Returns the index of the last occurrence of the specified element
370       * in this vector, or -1 if this vector does not contain the element.       * in this vector, or -1 if this vector does not contain the element.
371       * More formally, returns the highest index <tt>i</tt> such that       * More formally, returns the highest index {@code i} such that
372       * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,       * <tt>(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i)))</tt>,
373       * or -1 if there is no such index.       * or -1 if there is no such index.
374       *       *
# Line 382  Line 382 
382    
383      /**      /**
384       * Returns the index of the last occurrence of the specified element in       * Returns the index of the last occurrence of the specified element in
385       * this vector, searching backwards from <tt>index</tt>, or returns -1 if       * this vector, searching backwards from {@code index}, or returns -1 if
386       * the element is not found.       * the element is not found.
387       * More formally, returns the highest index <tt>i</tt> such that       * More formally, returns the highest index {@code i} such that
388       * <tt>(i&nbsp;&lt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i))))</tt>,       * <tt>(i&nbsp;&lt;=&nbsp;index&nbsp;&amp;&amp;&nbsp;(o==null&nbsp;?&nbsp;get(i)==null&nbsp;:&nbsp;o.equals(get(i))))</tt>,
389       * or -1 if there is no such index.       * or -1 if there is no such index.
390       *       *
391       * @param o element to search for       * @param o element to search for
392       * @param index index to start searching backwards from       * @param index index to start searching backwards from
393       * @return the index of the last occurrence of the element at position       * @return the index of the last occurrence of the element at position
394       *         less than or equal to <tt>index</tt> in this vector;       *         less than or equal to {@code index} in this vector;
395       *         -1 if the element is not found.       *         -1 if the element is not found.
396       * @throws IndexOutOfBoundsException if the specified index is greater       * @throws IndexOutOfBoundsException if the specified index is greater
397       *         than or equal to the current size of this vector       *         than or equal to the current size of this vector
# Line 420  Line 420 
420       *       *
421       * @param      index   an index into this vector       * @param      index   an index into this vector
422       * @return     the component at the specified index       * @return     the component at the specified index
423       * @exception  ArrayIndexOutOfBoundsException  if the <tt>index</tt>       * @exception  ArrayIndexOutOfBoundsException  if the {@code index}
424       *             is negative or not less than the current size of this       *             is negative or not less than the current size of this
425       *             <tt>Vector</tt> object.       *             {@code Vector} object.
426       * @see        #get(int)       * @see        #get(int)
427       * @see        List       * @see        List
428       */       */
# Line 435  Line 435 
435      }      }
436    
437      /**      /**
438       * Returns the first component (the item at index <tt>0</tt>) of       * Returns the first component (the item at index {@code 0}) of
439       * this vector.       * this vector.
440       *       *
441       * @return     the first component of this vector       * @return     the first component of this vector
# Line 463  Line 463 
463      }      }
464    
465      /**      /**
466       * Sets the component at the specified <code>index</code> of this       * Sets the component at the specified {@code index} of this
467       * vector to be the specified object. The previous component at that       * vector to be the specified object. The previous component at that
468       * position is discarded.<p>       * position is discarded.<p>
469       *       *
470       * The index must be a value greater than or equal to <code>0</code>       * The index must be a value greater than or equal to {@code 0}
471       * and less than the current size of the vector. <p>       * and less than the current size of the vector. <p>
472       *       *
473       * This method is identical in functionality to the set method       * This method is identical in functionality to the set method
# Line 494  Line 494 
494      /**      /**
495       * Deletes the component at the specified index. Each component in       * Deletes the component at the specified index. Each component in
496       * this vector with an index greater or equal to the specified       * this vector with an index greater or equal to the specified
497       * <code>index</code> is shifted downward to have an index one       * {@code index} is shifted downward to have an index one
498       * smaller than the value it had previously. The size of this vector       * smaller than the value it had previously. The size of this vector
499       * is decreased by <tt>1</tt>.<p>       * is decreased by {@code 1}.<p>
500       *       *
501       * The index must be a value greater than or equal to <code>0</code>       * The index must be a value greater than or equal to {@code 0}
502       * and less than the current size of the vector. <p>       * and less than the current size of the vector. <p>
503       *       *
504       * This method is identical in functionality to the remove method       * This method is identical in functionality to the remove method
# Line 530  Line 530 
530    
531      /**      /**
532       * Inserts the specified object as a component in this vector at the       * Inserts the specified object as a component in this vector at the
533       * specified <code>index</code>. Each component in this vector with       * specified {@code index}. Each component in this vector with
534       * an index greater or equal to the specified <code>index</code> is       * an index greater or equal to the specified {@code index} is
535       * shifted upward to have an index one greater than the value it had       * shifted upward to have an index one greater than the value it had
536       * previously. <p>       * previously. <p>
537       *       *
538       * The index must be a value greater than or equal to <code>0</code>       * The index must be a value greater than or equal to {@code 0}
539       * and less than or equal to the current size of the vector. (If the       * and less than or equal to the current size of the vector. (If the
540       * index is equal to the current size of the vector, the new element       * index is equal to the current size of the vector, the new element
541       * is appended to the Vector.)<p>       * is appended to the Vector.)<p>
# Line 592  Line 592 
592       * method (which is part of the List interface).       * method (which is part of the List interface).
593       *       *
594       * @param   obj   the component to be removed       * @param   obj   the component to be removed
595       * @return  <code>true</code> if the argument was a component of this       * @return  {@code true} if the argument was a component of this
596       *          vector; <code>false</code> otherwise.       *          vector; {@code false} otherwise.
597       * @see     List#remove(Object)       * @see     List#remove(Object)
598       * @see     List       * @see     List
599       */       */
# Line 628  Line 628 
628      /**      /**
629       * Returns a clone of this vector. The copy will contain a       * Returns a clone of this vector. The copy will contain a
630       * reference to a clone of the internal data array, not a reference       * reference to a clone of the internal data array, not a reference
631       * to the original internal data array of this <tt>Vector</tt> object.       * to the original internal data array of this {@code Vector} object.
632       *       *
633       * @return  a clone of this vector       * @return  a clone of this vector
634       */       */
# Line 731  Line 731 
731       * Appends the specified element to the end of this Vector.       * Appends the specified element to the end of this Vector.
732       *       *
733       * @param e element to be appended to this Vector       * @param e element to be appended to this Vector
734       * @return <tt>true</tt> (as specified by {@link Collection#add})       * @return {@code true} (as specified by {@link Collection#add})
735       * @since 1.2       * @since 1.2
736       */       */
737      public synchronized boolean add(E e) {      public synchronized boolean add(E e) {
# Line 745  Line 745 
745       * Removes the first occurrence of the specified element in this Vector       * Removes the first occurrence of the specified element in this Vector
746       * If the Vector does not contain the element, it is unchanged.  More       * If the Vector does not contain the element, it is unchanged.  More
747       * formally, removes the element with the lowest index i such that       * formally, removes the element with the lowest index i such that
748       * <code>(o==null ? get(i)==null : o.equals(get(i)))</code> (if such       * {@code (o==null ? get(i)==null : o.equals(get(i)))} (if such
749       * an element exists).       * an element exists).
750       *       *
751       * @param o element to be removed from this Vector, if present       * @param o element to be removed from this Vector, if present
# Line 832  Line 832 
832       * specified Collection is this Vector, and this Vector is nonempty.)       * specified Collection is this Vector, and this Vector is nonempty.)
833       *       *
834       * @param c elements to be inserted into this Vector       * @param c elements to be inserted into this Vector
835       * @return <tt>true</tt> if this Vector changed as a result of the call       * @return {@code true} if this Vector changed as a result of the call
836       * @throws NullPointerException if the specified collection is null       * @throws NullPointerException if the specified collection is null
837       * @since 1.2       * @since 1.2
838       */       */
# Line 895  Line 895 
895       * @param index index at which to insert the first element from the       * @param index index at which to insert the first element from the
896       *              specified collection       *              specified collection
897       * @param c elements to be inserted into this Vector       * @param c elements to be inserted into this Vector
898       * @return <tt>true</tt> if this Vector changed as a result of the call       * @return {@code true} if this Vector changed as a result of the call
899       * @exception ArrayIndexOutOfBoundsException index out of range (index       * @exception ArrayIndexOutOfBoundsException index out of range (index
900       *            &lt; 0 || index &gt; size())       *            &lt; 0 || index &gt; size())
901       * @throws NullPointerException if the specified collection is null       * @throws NullPointerException if the specified collection is null
# Line 924  Line 924 
924       * Compares the specified Object with this Vector for equality.  Returns       * Compares the specified Object with this Vector for equality.  Returns
925       * true if and only if the specified Object is also a List, both Lists       * true if and only if the specified Object is also a List, both Lists
926       * have the same size, and all corresponding pairs of elements in the two       * have the same size, and all corresponding pairs of elements in the two
927       * Lists are <em>equal</em>.  (Two elements <code>e1</code> and       * Lists are <em>equal</em>.  (Two elements {@code e1} and
928       * <code>e2</code> are <em>equal</em> if <code>(e1==null ? e2==null :       * {@code e2} are <em>equal</em> if {@code (e1==null ? e2==null :
929       * e1.equals(e2))</code>.)  In other words, two Lists are defined to be       * e1.equals(e2))}.)  In other words, two Lists are defined to be
930       * equal if they contain the same elements in the same order.       * equal if they contain the same elements in the same order.
931       *       *
932       * @param o the Object to be compared for equality with this Vector       * @param o the Object to be compared for equality with this Vector
# Line 974  Line 974 
974      }      }
975    
976      /**      /**
977       * Save the state of the <tt>Vector</tt> instance to a stream (that       * Save the state of the {@code Vector} instance to a stream (that
978       * is, serialize it).  This method is present merely for synchronization.       * is, serialize it).  This method is present merely for synchronization.
979       * It just calls the default writeObject method.       * It just calls the default writeObject method.
980       */       */

Legend:
Removed from v.1.13  
changed lines
  Added in v.1.14

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8