/*
   XBN Java:  Generically useful, non-GUI Java code.
   http://sourceforge.net/projects/xbnjava

   Copyright (C) 1997-2003, Jeff Epstein
   All rights reserved.

   Modifications: No

   Redistribution in binary form, with or without modifications, are permitted provided that the following conditions are met:

      * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
      * If modifications are made to source code then this license should indicate that fact in the "Modifications" section above.
      * Neither the author, nor the contributors may be used to endorse or promote products derived from this software without specific prior written permission.

   THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   [NOTE:  This license contains NO advertising clause.]
 */
package xbn.array;
   import java.util.Vector;

/**
   <P>A VectorWrapper for java.lang.Strings.  See java.lang.<A HREF="~JD~s~EJD~">String</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/array/VWString.java">VWString.java</A>. &nbsp;<B>Example code</B> &nbsp;See the similar example code for <A HREF="VWInt.html">VWInt</A>.</I></CODE></P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class VWString extends VectorWrapper implements Cloneable  {
   private BinarySearchData bsd = null;
   /**
      <P>Create a VWString with default settings.</P>

      <P>Equal to <CODE><A HREF="~JD~vw#vw()~EJD~">VectorWrapper</A>()</CODE></P>
    **/
   public VWString()  {
      super();
   }

   /**
      <P>Create a VWString.</P>

      <P>Equal to <CODE><A HREF="~JD~vw#vw(vctr)~EJD~">VectorWrapper</A>(v_ector)</CODE></P>

      <P>Note:  It is expected that this Vector contain only strings.</P>
    **/
   public VWString(Vector v_ector)  {
      super(v_ector);
   }

   /**
      <P>Create a VWString.</P>

      <P>Equal to <CODE><A HREF="~JD~vw#vw(b)~EJD~">VectorWrapper</A>(b_orderDirAscDesc)</CODE></P>
    **/
   public VWString(boolean b_orderDirAscDesc)  {
      super(b_orderDirAscDesc);
   }

   /**
      <P>Create a VWString.</P>

      <P>Equal to <CODE><A HREF="~JD~vw#vw(vctr,b)~EJD~">VectorWrapper</A>(v_ector, b_orderDirAscDesc)</CODE></P>

      <P>Note:  It is expected that this Vector contain only strings.</P>
    **/
   public VWString(Vector v_ector, boolean b_orderDirAscDesc)  {
      super(v_ector, b_orderDirAscDesc);
   }


   /**
      <P>Create a VWString.</P>

      <P>Equal to <CODE><A HREF="~JD~vw#vw(b,b)~EJD~">VectorWrapper</A>(b_addInOrder, b_orderDirAscDesc)</CODE></P>
    **/
   public VWString(boolean b_addInOrder, boolean b_orderDirAscDesc)  {
      super(b_addInOrder, b_orderDirAscDesc);
   }


   /**
      <P>Create a VWString.</P>

      <P>Equal to <CODE><A HREF="~JD~vw#vw(vctr,b,b)~EJD~">VectorWrapper</A>(v_ector, b_addInOrder, b_orderDisAscDesc)</CODE></P>

      <P>Note:  It is expected that this Vector contain only strings.</P>
    **/
   public VWString(Vector v_ector, boolean b_addInOrder, boolean b_orderDirAscDesc)  {
      super(v_ector, b_addInOrder, b_orderDirAscDesc);
   }

   /**
      <P>Add a string.</P>

      @param  s_tr  The string to add.  May not be null.  If not <A HREF="~JD~vw~EJD~#doAddInOrder()">adding in order</A>, then this may not be less than zero characters in length.  If adding in order, may not be less than one character in length.
    **/
   public final void add(String s_tr)  {

      if(!doAddInOrder())  {
         throwAXIfNull(s_tr, "s_tr", "add");
         getVector().addElement(s_tr);
         return;
      }
      //DO add in order.

      getVector().insertElementAt(s_tr, getInsertAddIdx(s_tr));

      //We've just changed the size of the "array", so the bsd
      //is no longer valid.  This will be recreated in
      //getArrIdx().
      bsd = null;
   }

   /**
      <P>Get the index at which to insert the provided string.  This function is only meaningful when doAddInOrder() equals true.  See <a href="~JD~vw~EJD~#doAddInOrder()">doAddInOrder</a>.</P>

      @param  s_tr  The string you're about to insert.  May not be null.
      @return  If...<UL>
         <LI>...<a href="~JD~vw~EJD~#doAddInOrder()">adding is done in order</a>:  The array index at which s_tr should be added to preserve the requested ordering.  Note that when there are one or more strings equaling s_tr have already been added, then you'll get the array index of (randomly) one of those existing elements.</LI>
         <LI>...<a href="~JD~vw~EJD~#size()">size</a> equals zero:  <B>0</B></LI>
         <LI>...adding is not done in order:  <B>0</B></LI>
      </UL>
    **/
   public final int getInsertAddIdx(String s_tr)  {
      return getArrIdx("getInsertAddIdx", s_tr, false);
   }

   /**
      <P>Get the index at which the string actually exists.</P>

      @param  s_tr  The string that may already exist in this VWString.  May not be null.
      @return  <B>The array index</B> at which s_tr exists.  Note that in the case of multiple instances of s_tr, the first (when not adding in order) or random (when adding in order) one is returned.
      <BR><B>-1</B>  If no other string equalling s_tr have yet been added.
    **/
   public final int getFoundIdx(String s_tr)  {
      return getArrIdx("getFoundIdx", s_tr, true);
   }

   /**
      <P>Was a string already added?</P>

      @param  s_tr  The string who's existence you want to test.  May not be null.
      @return  <B>true</B>  If the string s_tr exists.
      <BR><B>false</B> if s_tr does not exist.
    **/
   public final boolean doesExist(String s_tr)  {
      return (getFoundIdx(s_tr) != -1);
   }

   /**
      <P>Add a character.</P>

      <P>Equal to <CODE><A HREF="~JD~add(s)~EJD~">add</A>(new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_har).toString())</CODE></P>
    **/
   public final void addChar(char c_har)  {
      add(new Character(c_har).toString());
   }

   /**
      <P>Add an int.</P>

      <P>Equal to <CODE><A HREF="~JD~add(s)~EJD~">add</A>(new <A HREF="~JD~I#I(i)~EJD~">Integer</A>(i_nt).toString())</CODE></P>
    **/
   public final void addInt(int i_nt)  {
      add(new Integer(i_nt).toString());
   }

   /**
      <P>Add an array of strings.</P>

      <P>For each element in a_string, this calls, in order:  <CODE><A HREF="~JD~add(s)~EJD~">add</A>(a_string[<I>X</I>])</CODE></P>

      @param  a_string  The string array to add.  May not be null, nor may any element be null.
    **/
   public final void addArray(String[] a_string)  {
      try  {
         for(int i = 0; i < a_string.length; i++)  {
            add(a_string[i]);
         }
      }  catch(NullPointerException npx)  {
         throwAX("addArray:  a_string is null.");
      }
   }


   /**
      <P>Add an array of strings, as protected by the provided APString.</P>

      <P>For each element in ap_string, this calls, in order:  <CODE><A HREF="~JD~add(s)~EJD~">add</A>(ap_string.getString(<I>X</I>))</CODE></P>

      @param  ap_string  The APString, whose internally-held string array should be added.  May not be null.
    **/
   public final void addAPString(APString ap_string)  {
      try  {
         for(int i = 0; i < ap_string.getLength(); i++)  {
            add(ap_string.getString(i));
         }
      }  catch(NullPointerException npx)  {
         throwAX("addAPString:  ap_string is null.");
      }
   }

   /**
      <P>Add an array of chars.</P>

      <P>For each element in a_string, this calls, in order:  <CODE><A HREF="~JD~add(s)~EJD~">add</A>(a_string[<I>X</I>])</CODE></P>

      @param  a_char  The char array to <A HREF="~JD~addChar(c)~EJD~">add</A>.  May not be null.
    **/
   public final void addAOChar(char[] a_char)  {
      try  {
         for(int i = 0; i < a_char.length; i++)  {
            addChar(a_char[i]);
         }
      }  catch(NullPointerException npx)  {
         throwAX("addAOChar:  a_char is null.");
      }
   }


   /**
      <P>Add an array of chars, as protected by the provided APChar.</P>

      <P>Equal to <CODE><A HREF="~JD~addAOChar(c[])~EJD~">addAOChar</A>(ap_char.[<I>The internally-held char array</I>])</CODE></P>

      @param  ap_char  The APChar to add.  May not be null.
    **/
   public final void addAPChar(APChar ap_char)  {
      try  {
         addAOChar(ap_char.getAOChar());
      }  catch(NullPointerException npx)  {
         throwAX("addAPChar:  ap_char is null.");
      }
   }

   /**
      <P>Add an array of ints.</P>

      @param  a_int  The int array to <A HREF="~JD~addInt(i)~EJD~">add</A>.  May not be null.
    **/
   public final void addAOInt(int[] a_int)  {
      try  {
         for(int i = 0; i < a_int.length; i++)  {
            addInt(a_int[i]);
         }
      }  catch(NullPointerException npx)  {
         throwAX("addArray:  a_int is null.");
      }
   }


   /**
      <P>Add an array of chars, as protected by the provided APInt.</P>

      <P>Equal to <CODE><A HREF="~JD~addAOInt(i[])~EJD~">addAOInt</A>(ap_int.[<I>The internally-held char array</I>])</CODE></P>

      @param  ap_int  The APInt to add.  May not be null.
    **/
   public final void addAPInt(APInt ap_int)  {
      try  {
         addAOInt(ap_int.getAOInt());
      }  catch(NullPointerException npx)  {
         throwAX("addAPInt:  ap_int is null.");
      }
   }

   /**
      <P>Get a string from the vector, at the required array index.</P>

      @param  i_dx  The array index.  Must range 0..<CODE>[<A HREF="~JD~vw~EJD~#size()">size</A>() - 1]</CODE>, inclusive.
    **/
   public final String getString(int i_dx)  {
      try  {
         return (String)getVector().elementAt(i_dx);
      }  catch(ClassCastException ccx)  {
         throwAX("getString:  Element i_dx (" + i_dx + ") is not an String, which it must be.  It is actually a " + getVector().elementAt(i_dx).getClass().getName() + ".  It seems you provided an inaccurate Vector to the constructor.");
      }  catch(ArrayIndexOutOfBoundsException aioobx)  {
         throwAX("getString:  i_dx (" + i_dx + ") is invalid.  size()=" + size() + ".");
      }

      //Never reached.  Required for compile.
      return null;
   }

   public final boolean isNull(int i_dx)  {
      return (getString(i_dx) == null);
   }

   /**
      <P>Get the array of strings.  This array is composed of all those strings <A HREF="~JD~add(s)~EJD~">add</A>ed since this object was created, or since the last time this function was called.</P>

      @return  An array containing all strings added, in the same order as originally added (if not ordered when added), or in order (if ordered when added).
    **/
   public final String[] getAOString()  {
      String as[] = new String[getVector().size()];

      if(as.length == 0)  {
         return as;
      }

      //The array is at least one element in length.

      getVector().copyInto(as);
      return as;
   }

   //Cloning...START
      /**
         <P>Get a full (deep) copy of this VWString.</P>

         @return  <CODE>(VWString)<A HREF="#clone()">clone</A>()</CODE>
       **/
      public final VWString getVWSClone()  {
         try  {
            return (VWString)clone();
         }  catch(CloneNotSupportedException cnsx)  {
            throwAX("getVWSClone [SHOULD NEVER HAPPEN!]:  " + cnsx.toString());
         }

         //Never reached.  Required for compile.
         return null;
      }

      /**
         <P>Get a full (deep) copy of this VWString as an Object.</P>
       **/
      protected final Object clone() throws CloneNotSupportedException  {
         VWString acsClone = new VWString();
         for(int i = 0; i < size(); i++)  {
            acsClone.add(getString(i));
         }

         return acsClone;
      }
   //Cloning...END



   private final int getArrIdx(String s_callingFunc, String s_tr, boolean b_onlyIfFound)  {
      if(s_tr == null  ||  s_tr.length() < 1)  {
         throwAX(s_callingFunc + ":  s_tr ('" + s_tr + "') is null or zero characters in length.");
      }

      if(size() == 0)  {
         //There are no elements yet

         return b_onlyIfFound  ?
            -1  :
            0;
      }

      //There is at least one element.


      if(!doAddInOrder())  {
         //Adding is not done in order.  Binary searching is
         //pointless.

         if(b_onlyIfFound)  {
            //We only want to know the index at which c_har is
            //found.

            for(int i = 0; i < size(); i++)  {
               if(s_tr.equals(getString(i)))  {
                  return i;
               }
            }


         }  //ELSE:  We only want the array index at which to
            //       *insert*.  Since it's not ordered, just
            //       return zero.

         return b_onlyIfFound  ?
            -1  :
            0;
      }

      //Adding IS done in order.  Binary searching is
      //useful.

      if(bsd == null)  {
         //This is either (1) the first time using this
         //function, or this is (2) the first time using
         //this function since adding something.
         bsd = new BinarySearchData(size(), getOrderDirAscDesc());
      }

      bsd.reset();

      int iPrevMidIdx = -1;

      while(bsd.getIdxMiddle() != -1)  {
         int iMiddleIdx = bsd.getIdxMiddle();
         String sAtMiddle = getString(bsd.getIdxMiddle());

         //Used only after the end of this while block.
         iPrevMidIdx = iMiddleIdx;


         if(s_tr.equals(sAtMiddle))  {
            //Found.  Duplicates (which are okay) are added at
            //the same point, pushing the duplicate to the right.
            return iMiddleIdx;
         }

         bsd.prepareForNextSearch(s_tr.compareTo(sAtMiddle) < 0);
      }
      //The char to be inserted does not currently exist in the
      //array.

      if(s_tr.compareTo(getString(iPrevMidIdx)) < 0)  {
         if(!getOrderDirAscDesc())  {
            //Insert s_tr at the index right *after* the
            //element it is just-less than.
            iPrevMidIdx++;

         }  //ELSE:  The order is ascending, so insert it *at*
            //       the element s_tr is just-less than.  This
            //       pushes the existing element one to the
            //       right.

      }  else  {
         //s_tr is greater than the existing "middle" element.

         if(getOrderDirAscDesc())  {
            //Insert s_tr at the index right *after* the
            //element it is just-greater than.
            iPrevMidIdx++;

         }  //ELSE:  The order is descending, so insert it *at*
            //       the element s_tr is just-less than.  This
            //       pushes the existing element one to the
            //       right.
      }


      return  b_onlyIfFound  ?
         -1  :
         iPrevMidIdx;
   }
}