home *** CD-ROM | disk | FTP | other *** search
/ DOS/V Power Report 1998 February / VPR9802A.ISO / APP_DEMO / VC / MAIN.BIN / Vector.java < prev    next >
Text File  |  1997-10-27  |  18KB  |  548 lines
  1. /*
  2.  * @(#)Vector.java    1.36 97/01/28
  3.  * 
  4.  * Copyright (c) 1995, 1996 Sun Microsystems, Inc. All Rights Reserved.
  5.  * 
  6.  * This software is the confidential and proprietary information of Sun
  7.  * Microsystems, Inc. ("Confidential Information").  You shall not
  8.  * disclose such Confidential Information and shall use it only in
  9.  * accordance with the terms of the license agreement you entered into
  10.  * with Sun.
  11.  * 
  12.  * SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
  13.  * SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  14.  * IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  15.  * PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
  16.  * SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
  17.  * THIS SOFTWARE OR ITS DERIVATIVES.
  18.  * 
  19.  * CopyrightVersion 1.1_beta
  20.  * 
  21.  */
  22.  
  23. package java.util;
  24.  
  25. /**
  26.  * The <code>Vector</code> class implements a growable array of 
  27.  * objects. Like an array, it contains components that can be 
  28.  * accessed using an integer index. However, the size of a 
  29.  * <code>Vector</code> can grow or shrink as needed to accommodate 
  30.  * adding and removing items after the <code>Vector</code> has been created.
  31.  * <p>
  32.  * Each vector tries to optimize storage management by maintaining a 
  33.  * <code>capacity</code> and a <code>capacityIncrement</code>. The 
  34.  * <code>capacity</code> is always at least as large as the vector 
  35.  * size; it is usually larger because as components are added to the 
  36.  * vector, the vector's storage increases in chunks the size of 
  37.  * <code>capacityIncrement</code>. An application can increase the 
  38.  * capacity of a vector before inserting a large number of 
  39.  * components; this reduces the amount of incremental reallocation. 
  40.  *
  41.  * @author  Lee Boynton
  42.  * @author  Jonathan Payne
  43.  * @version 1.36, 01/28/97
  44.  * @since   JDK1.0
  45.  */
  46. public
  47. class Vector implements Cloneable, java.io.Serializable {
  48.     /**
  49.      * The array buffer into which the components of the vector are 
  50.      * stored. The capacity of the vector is the length of this array buffer.
  51.      *
  52.      * @since   JDK1.0
  53.      */
  54.     protected Object elementData[];
  55.  
  56.     /**
  57.      * The number of valid components in the vector. 
  58.      *
  59.      * @since   JDK1.0
  60.      */
  61.     protected int elementCount;
  62.  
  63.     /**
  64.      * The amount by which the capacity of the vector is automatically 
  65.      * incremented when its size becomes greater than its capacity. If 
  66.      * the capacity is <code>0</code>, the capacity of the vector is 
  67.      * doubled each time it needs to grow. 
  68.      *
  69.      * @since   JDK1.0
  70.      */
  71.     protected int capacityIncrement;
  72.  
  73.     /** use serialVersionUID from JDK 1.0.2 for interoperability */
  74.     private static final long serialVersionUID = -2767605614048989439L;
  75.  
  76.     /**
  77.      * Constructs an empty vector with the specified initial capacity and
  78.      * capacity increment. 
  79.      *
  80.      * @param   initialCapacity     the initial capacity of the vector.
  81.      * @param   capacityIncrement   the amount by which the capacity is
  82.      *                              increased when the vector overflows.
  83.      * @since   JDK1.0
  84.      */
  85.     public Vector(int initialCapacity, int capacityIncrement) {
  86.     super();
  87.     this.elementData = new Object[initialCapacity];
  88.     this.capacityIncrement = capacityIncrement;
  89.     }
  90.  
  91.     /**
  92.      * Constructs an empty vector with the specified initial capacity.
  93.      *
  94.      * @param   initialCapacity   the initial capacity of the vector.
  95.      * @since   JDK1.0
  96.      */
  97.     public Vector(int initialCapacity) {
  98.     this(initialCapacity, 0);
  99.     }
  100.  
  101.     /**
  102.      * Constructs an empty vector. 
  103.      *
  104.      * @since   JDK1.0
  105.      */
  106.     public Vector() {
  107.     this(10);
  108.     }
  109.  
  110.     /**
  111.      * Copies the components of this vector into the specified array. 
  112.      * The array must be big enough to hold all the objects in this  vector.
  113.      *
  114.      * @param   anArray   the array into which the components get copied.
  115.      * @since   JDK1.0
  116.      */
  117.     public final synchronized void copyInto(Object anArray[]) {
  118.     int i = elementCount;
  119.     while (i-- > 0) {
  120.         anArray[i] = elementData[i];
  121.     }
  122.     }
  123.  
  124.     /**
  125.      * Trims the capacity of this vector to be the vector's current 
  126.      * size. An application can use this operation to minimize the 
  127.      * storage of a vector. 
  128.      *
  129.      * @since   JDK1.0
  130.      */
  131.     public final synchronized void trimToSize() {
  132.     int oldCapacity = elementData.length;
  133.     if (elementCount < oldCapacity) {
  134.         Object oldData[] = elementData;
  135.         elementData = new Object[elementCount];
  136.         System.arraycopy(oldData, 0, elementData, 0, elementCount);
  137.     }
  138.     }
  139.  
  140.     /**
  141.      * Increases the capacity of this vector, if necessary, to ensure 
  142.      * that it can hold at least the number of components specified by 
  143.      * the minimum capacity argument. 
  144.      *
  145.      * @param   minCapacity   the desired minimum capacity.
  146.      * @since   JDK1.0
  147.      */
  148.     public final synchronized void ensureCapacity(int minCapacity) {
  149.     int oldCapacity = elementData.length;
  150.     if (minCapacity > oldCapacity) {
  151.         Object oldData[] = elementData;
  152.         int newCapacity = (capacityIncrement > 0) ?
  153.         (oldCapacity + capacityIncrement) : (oldCapacity * 2);
  154.             if (newCapacity < minCapacity) {
  155.         newCapacity = minCapacity;
  156.         }
  157.         elementData = new Object[newCapacity];
  158.         System.arraycopy(oldData, 0, elementData, 0, elementCount);
  159.     }
  160.     }
  161.  
  162.     /**
  163.      * Sets the size of this vector. If the new size is greater than the 
  164.      * current size, new <code>null</code> items are added to the end of 
  165.      * the vector. If the new size is less than the current size, all 
  166.      * components at index <code>newSize</code> and greater are discarded.
  167.      *
  168.      * @param   newSize   the new size of this vector.
  169.      * @since   JDK1.0
  170.      */
  171.     public final synchronized void setSize(int newSize) {
  172.     if (newSize > elementCount) {
  173.         ensureCapacity(newSize);
  174.     } else {
  175.         for (int i = newSize ; i < elementCount ; i++) {
  176.         elementData[i] = null;
  177.         }
  178.     }
  179.     elementCount = newSize;
  180.     }
  181.  
  182.     /**
  183.      * Returns the current capacity of this vector.
  184.      *
  185.      * @return  the current capacity of this vector.
  186.      * @since   JDK1.0
  187.      */
  188.     public final int capacity() {
  189.     return elementData.length;
  190.     }
  191.  
  192.     /**
  193.      * Returns the number of components in this vector.
  194.      *
  195.      * @return  the number of components in this vector.
  196.      * @since   JDK1.0
  197.      */
  198.     public final int size() {
  199.     return elementCount;
  200.     }
  201.  
  202.     /**
  203.      * Tests if this vector has no components.
  204.      *
  205.      * @return  <code>true</code> if this vector has no components;
  206.      *          <code>false</code> otherwise.
  207.      * @since   JDK1.0
  208.      */
  209.     public final boolean isEmpty() {
  210.     return elementCount == 0;
  211.     }
  212.  
  213.     /**
  214.      * Returns an enumeration of the components of this vector.
  215.      *
  216.      * @return  an enumeration of the components of this vector.
  217.      * @see     java.util.Enumeration
  218.      * @since   JDK1.0
  219.      */
  220.     public final synchronized Enumeration elements() {
  221.     return new VectorEnumerator(this);
  222.     }
  223.     
  224.     /**
  225.      * Tests if the specified object is a component in this vector.
  226.      *
  227.      * @param   elem   an object.
  228.      * @return  <code>true</code> if the specified object is a component in
  229.      *          this vector; <code>false</code> otherwise.
  230.      * @since   JDK1.0
  231.      */
  232.     public final boolean contains(Object elem) {
  233.     return indexOf(elem, 0) >= 0;
  234.     }
  235.  
  236.     /**
  237.      * Searches for the first occurence of the given argument, testing 
  238.      * for equality using the <code>equals</code> method. 
  239.      *
  240.      * @param   elem   an object.
  241.      * @return  the index of the first occurrence of the argument in this
  242.      *          vector; returns <code>-1</code> if the object is not found.
  243.      * @see     java.lang.Object#equals(java.lang.Object)
  244.      * @since   JDK1.0
  245.      */
  246.     public final int indexOf(Object elem) {
  247.     return indexOf(elem, 0);
  248.     }
  249.  
  250.     /**
  251.      * Searches for the first occurence of the given argument, beginning 
  252.      * the search at <code>index</code>, and testing for equality using 
  253.      * the <code>equals</code> method. 
  254.      *
  255.      * @param   elem    an object.
  256.      * @param   index   the index to start searching from.
  257.      * @return  the index of the first occurrence of the object argument in
  258.      *          this vector at position <code>index</code> or later in the
  259.      *          vector; returns <code>-1</code> if the object is not found.
  260.      * @see     java.lang.Object#equals(java.lang.Object)
  261.      * @since   JDK1.0
  262.      */
  263.     public final synchronized int indexOf(Object elem, int index) {
  264.     for (int i = index ; i < elementCount ; i++) {
  265.         if (elem.equals(elementData[i])) {
  266.         return i;
  267.         }
  268.     }
  269.     return -1;
  270.     }
  271.  
  272.     /**
  273.      * Returns the index of the last occurrence of the specified object in
  274.      * this vector.
  275.      *
  276.      * @param   elem   the desired component.
  277.      * @return  the index of the last occurrence of the specified object in
  278.      *          this vector; returns <code>-1</code> if the object is not found.
  279.      * @since   JDK1.0
  280.      */
  281.     public final int lastIndexOf(Object elem) {
  282.     return lastIndexOf(elem, elementCount-1);
  283.     }
  284.  
  285.     /**
  286.      * Searches backwards for the specified object, starting from the 
  287.      * specified index, and returns an index to it. 
  288.      *
  289.      * @param   elem    the desired component.
  290.      * @param   index   the index to start searching from.
  291.      * @return  the index of the last occurrence of the specified object in this
  292.      *          vector at position less than <code>index</code> in the vector;
  293.      *          <code>-1</code> if the object is not found.
  294.      * @since   JDK1.0
  295.      */
  296.     public final synchronized int lastIndexOf(Object elem, int index) {
  297.     for (int i = index ; i >= 0 ; i--) {
  298.         if (elem.equals(elementData[i])) {
  299.         return i;
  300.         }
  301.     }
  302.     return -1;
  303.     }
  304.  
  305.     /**
  306.      * Returns the component at the specified index.
  307.      *
  308.      * @param      index   an index into this vector.
  309.      * @return     the component at the specified index.
  310.      * @exception  ArrayIndexOutOfBoundsException  if an invalid index was
  311.      *               given.
  312.      * @since      JDK1.0
  313.      */
  314.     public final synchronized Object elementAt(int index) {
  315.     if (index >= elementCount) {
  316.         throw new ArrayIndexOutOfBoundsException(index + " >= " + elementCount);
  317.     }
  318.     /* Since try/catch is free, except when the exception is thrown,
  319.        put in this extra try/catch to catch negative indexes and
  320.        display a more informative error message.  This might not
  321.        be appropriate, especially if we have a decent debugging
  322.        environment - JP. */
  323.     try {
  324.         return elementData[index];
  325.     } catch (ArrayIndexOutOfBoundsException e) {
  326.         throw new ArrayIndexOutOfBoundsException(index + " < 0");
  327.     }
  328.     }
  329.  
  330.     /**
  331.      * Returns the first component of this vector.
  332.      *
  333.      * @return     the first component of this vector.
  334.      * @exception  NoSuchElementException  if this vector has no components.
  335.      * @since      JDK1.0
  336.      */
  337.     public final synchronized Object firstElement() {
  338.     if (elementCount == 0) {
  339.         throw new NoSuchElementException();
  340.     }
  341.     return elementData[0];
  342.     }
  343.  
  344.     /**
  345.      * Returns the last component of the vector.
  346.      *
  347.      * @return  the last component of the vector, i.e., the component at index
  348.      *          <code>size() - 1</code>.
  349.      * @exception  NoSuchElementException  if this vector is empty.
  350.      * @since   JDK1.0
  351.      */
  352.     public final synchronized Object lastElement() {
  353.     if (elementCount == 0) {
  354.         throw new NoSuchElementException();
  355.     }
  356.     return elementData[elementCount - 1];
  357.     }
  358.  
  359.     /**
  360.      * Sets the component at the specified <code>index</code> of this 
  361.      * vector to be the specified object. The previous component at that 
  362.      * position is discarded. 
  363.      * <p>
  364.      * The index must be a value greater than or equal to <code>0</code> 
  365.      * and less than the current size of the vector. 
  366.      *
  367.      * @param      obj     what the component is to be set to.
  368.      * @param      index   the specified index.
  369.      * @exception  ArrayIndexOutOfBoundsException  if the index was invalid.
  370.      * @see        java.util.Vector#size()
  371.      * @since      JDK1.0
  372.      */
  373.     public final synchronized void setElementAt(Object obj, int index) {
  374.     if (index >= elementCount) {
  375.         throw new ArrayIndexOutOfBoundsException(index + " >= " + 
  376.                              elementCount);
  377.     }
  378.     elementData[index] = obj;
  379.     }
  380.  
  381.     /**
  382.      * Deletes the component at the specified index. Each component in 
  383.      * this vector with an index greater or equal to the specified 
  384.      * <code>index</code> is shifted downward to have an index one 
  385.      * smaller than the value it had previously. 
  386.      * <p>
  387.      * The index must be a value greater than or equal to <code>0</code> 
  388.      * and less than the current size of the vector. 
  389.      *
  390.      * @param      index   the index of the object to remove.
  391.      * @exception  ArrayIndexOutOfBoundsException  if the index was invalid.
  392.      * @see        java.util.Vector#size()
  393.      * @since      JDK1.0
  394.      */
  395.     public final synchronized void removeElementAt(int index) {
  396.     if (index >= elementCount) {
  397.         throw new ArrayIndexOutOfBoundsException(index + " >= " + 
  398.                              elementCount);
  399.     }
  400.     else if (index < 0) {
  401.         throw new ArrayIndexOutOfBoundsException(index);
  402.     }
  403.     int j = elementCount - index - 1;
  404.     if (j > 0) {
  405.         System.arraycopy(elementData, index + 1, elementData, index, j);
  406.     }
  407.     elementCount--;
  408.     elementData[elementCount] = null; /* to let gc do its work */
  409.     }
  410.  
  411.     /**
  412.      * Inserts the specified object as a component in this vector at the 
  413.      * specified <code>index</code>. Each component in this vector with 
  414.      * an index greater or equal to the specified <code>index</code> is 
  415.      * shifted upward to have an index one greater than the value it had 
  416.      * previously. 
  417.      * <p>
  418.      * The index must be a value greater than or equal to <code>0</code> 
  419.      * and less than or equal to the current size of the vector. 
  420.      *
  421.      * @param      obj     the component to insert.
  422.      * @param      index   where to insert the new component.
  423.      * @exception  ArrayIndexOutOfBoundsException  if the index was invalid.
  424.      * @see        java.util.Vector#size()
  425.      * @since      JDK1.0
  426.      */
  427.     public final synchronized void insertElementAt(Object obj, int index) {
  428.     if (index >= elementCount + 1) {
  429.         throw new ArrayIndexOutOfBoundsException(index
  430.                              + " > " + elementCount);
  431.     }
  432.     ensureCapacity(elementCount + 1);
  433.     System.arraycopy(elementData, index, elementData, index + 1, elementCount - index);
  434.     elementData[index] = obj;
  435.     elementCount++;
  436.     }
  437.  
  438.     /**
  439.      * Adds the specified component to the end of this vector, 
  440.      * increasing its size by one. The capacity of this vector is 
  441.      * increased if its size becomes greater than its capacity. 
  442.      *
  443.      * @param   obj   the component to be added.
  444.      * @since   JDK1.0
  445.      */
  446.     public final synchronized void addElement(Object obj) {
  447.     ensureCapacity(elementCount + 1);
  448.     elementData[elementCount++] = obj;
  449.     }
  450.  
  451.     /**
  452.      * Removes the first occurrence of the argument from this vector. If 
  453.      * the object is found in this vector, each component in the vector 
  454.      * with an index greater or equal to the object's index is shifted 
  455.      * downward to have an index one smaller than the value it had previously.
  456.      *
  457.      * @param   obj   the component to be removed.
  458.      * @return  <code>true</code> if the argument was a component of this
  459.      *          vector; <code>false</code> otherwise.
  460.      * @since   JDK1.0
  461.      */
  462.     public final synchronized boolean removeElement(Object obj) {
  463.     int i = indexOf(obj);
  464.     if (i >= 0) {
  465.         removeElementAt(i);
  466.         return true;
  467.     }
  468.     return false;
  469.     }
  470.  
  471.     /**
  472.      * Removes all components from this vector and sets its size to zero.
  473.      *
  474.      * @since   JDK1.0
  475.      */
  476.     public final synchronized void removeAllElements() {
  477.     for (int i = 0; i < elementCount; i++) {
  478.         elementData[i] = null;
  479.     }
  480.     elementCount = 0;
  481.     }
  482.  
  483.     /**
  484.      * Returns a clone of this vector.
  485.      *
  486.      * @return  a clone of this vector.
  487.      * @since   JDK1.0
  488.      */
  489.     public synchronized Object clone() {
  490.     try { 
  491.         Vector v = (Vector)super.clone();
  492.         v.elementData = new Object[elementCount];
  493.         System.arraycopy(elementData, 0, v.elementData, 0, elementCount);
  494.         return v;
  495.     } catch (CloneNotSupportedException e) { 
  496.         // this shouldn't happen, since we are Cloneable
  497.         throw new InternalError();
  498.     }
  499.     }
  500.  
  501.     /**
  502.      * Returns a string representation of this vector. 
  503.      *
  504.      * @return  a string representation of this vector.
  505.      * @since   JDK1.0
  506.      */
  507.     public final synchronized String toString() {
  508.     int max = size() - 1;
  509.     StringBuffer buf = new StringBuffer();
  510.     Enumeration e = elements();
  511.     buf.append("[");
  512.  
  513.     for (int i = 0 ; i <= max ; i++) {
  514.         String s = e.nextElement().toString();
  515.         buf.append(s);
  516.         if (i < max) {
  517.         buf.append(", ");
  518.         }
  519.     }
  520.     buf.append("]");
  521.     return buf.toString();
  522.     }
  523. }
  524.  
  525. final
  526. class VectorEnumerator implements Enumeration {
  527.     Vector vector;
  528.     int count;
  529.  
  530.     VectorEnumerator(Vector v) {
  531.     vector = v;
  532.     count = 0;
  533.     }
  534.  
  535.     public boolean hasMoreElements() {
  536.     return count < vector.elementCount;
  537.     }
  538.  
  539.     public Object nextElement() {
  540.     synchronized (vector) {
  541.         if (count < vector.elementCount) {
  542.         return vector.elementData[count++];
  543.         }
  544.     }
  545.     throw new NoSuchElementException("VectorEnumerator");
  546.     }
  547. }
  548.