/*
   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 xbn.XBNObject;
   import xbn.array.primitive.ListPA;
   import xbn.array.primitive.LPAConfig;
   import xbn.array.primitive.PARDNLGoodUnq;
   import xbn.array.primitive.PARDupNullLen;
   import xbn.array.primitive.PARSGoodUnq;
   import xbn.array.primitive.PARString;
   import xbn.util.RCLength;

/**
   <P>Holds metadata about an array of strings.  For easy creation of an AOSLookup, see <A HREF="~JD~aoslc~EJD~">AOSLCreator</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/array/AOSLookup.java">AOSLookup.java</A></I></CODE></P>

   <P>Note that the original array of strings is not held in this object.  You need to hold it externally.</P>

   <H3>The objects in an AOSLookup</H3>

   <P>Take this array of strings: &nbsp; <CODE>["aaa", "ccc", "bbb", "bbb", "aaa", "ddd", "ccc", "bbb"]</CODE></P>

   <H4><A NAME="unique_us_array"></A>Unique array of UniqueStrings</H4>

   <P>The central piece of information in this AOSLookup is the unique array of <A HREF="~JD~unqs~EJD~">UniqueString</A>s (wrapped by a <A HREF="~JD~usap~EJD~">UniqueStringAP</A>):</P>

   <P><TABLE ALIGN="center" BORDER="0" CELLSPACING="0" CELLPADDING="0" WIDTH="40%" BGCOLOR="#EEEEEE"><TR ALIGN="left" VALIGN="middle">
      <TD><CODE><A HREF="~JD~unqs~EJD~#getString()">getString</A>()</CODE></TD>
      <TD><CODE><A HREF="~JD~unqs~EJD~#getUnqArrIdx()">getUnqArrIdx</A>()</CODE></TD>
      <TD><CODE><A HREF="~JD~unqs~EJD~#getInstanceCount()">getInstanceCount</A>()</CODE></TD>
   </TR><TR>
      <TD>aaa</TD>
      <TD>0</TD>
      <TD>2</TD>
   </TR><TR>
      <TD>ccc</TD>
      <TD>1</TD>
      <TD>2</TD>
   </TR><TR>
      <TD>bbb</TD>
      <TD>2</TD>
      <TD>3</TD>
   </TR><TR>
      <TD>ddd</TD>
      <TD>3</TD>
      <TD>1</TD>
   </TR></TABLE></P>

   <P>This array contains metadata about each unique string existing in the string array, in the same order as the <I>first instance</I> found.  The <CODE>getUnqArrIdx</CODE> value is simply the array index of itself (useless here, but read on...).</P>

   <H4><A NAME="absolute_us_array"></A>Absolute array of UniqueStrings</H4>

   <P>The second object is the absolute array of UniqueStrings (wrapped by a UniqueStringAP), in the same order as the string array, and with the same duplication:</P>

   <P><TABLE ALIGN="center" BORDER="0" CELLSPACING="0" CELLPADDING="0" WIDTH="40%" BGCOLOR="#EEEEEE"><TR ALIGN="left" VALIGN="middle">
      <TD><CODE>getString()</CODE></TD>
      <TD><CODE>getUnqArrIdx()</CODE></TD>
      <TD><CODE>getInstanceCount()</CODE></TD>
   </TR><TR>
      <TD>aaa</TD>
      <TD>0</TD>
      <TD>2</TD>
   </TR><TR>
      <TD>ccc</TD>
      <TD>1</TD>
      <TD>2</TD>
   </TR><TR>
      <TD>bbb</TD>
      <TD>2</TD>
      <TD>3</TD>
   </TR><TR>
      <TD>bbb</TD>
      <TD>2</TD>
      <TD>3</TD>
   </TR><TR>
      <TD>aaa</TD>
      <TD>0</TD>
      <TD>2</TD>
   </TR><TR>
      <TD>ddd</TD>
      <TD>3</TD>
      <TD>1</TD>
   </TR><TR>
      <TD>ccc</TD>
      <TD>1</TD>
      <TD>2</TD>
   </TR><TR>
      <TD>bbb</TD>
      <TD>2</TD>
      <TD>3</TD>
   </TR></TABLE></P>

   <P>These UniqueString objects are are not new instances.  They are references to the original object, as exists in the unique array of UniqueStrings.  It is in this array in which the <CODE>getUnqArrIdx</CODE> value becomes useful.</P>

   <P><I>The <CODE>getInstanceCount</CODE> value is extra information.  It's not critical to AOSLookup.</I></P>

   <H4><A NAME="aoslh"></A>AOSLHashtable</H4>

   <P>The final object is an <A HREF="~JD~aoslh~EJD~">AOSLHashtable</A>.  An AOSLHashtable wraps around a Hashtable, where the key is a unique string, and the value is the UniqueString object representing it:</P>

   <P><TABLE ALIGN="center" BORDER="0" CELLSPACING="0" CELLPADDING="0" WIDTH="40%" BGCOLOR="#EEEEEE"><TR ALIGN="left" VALIGN="middle">
      <TD><CODE>Key (unique string)</CODE></TD>
      <TD><CODE>Value (UniqueString)</CODE></TD>
   </TR><TR>
      <TD><B>aaa</B></TD>
      <TD><CODE>[aaa, 0, 2]</CODE></TD>
   </TR><TR>
      <TD><B>bbb</B></TD>
      <TD><CODE>[bbb, 2, 3]</CODE></TD>
   </TR><TR>
      <TD><B>ccc</B></TD>
      <TD><CODE>[ccc, 1, 2]</CODE></TD>
   </TR><TR>
      <TD><B>ddd</B></TD>
      <TD><CODE>[ddd, 3, 1]</CODE></TD>
   </TR></TABLE></P>

   <P>Again, these UniqueString value objects are references to the original objects, as exist in the unique array of UniqueStrings.  Note that the ordering presented here is made up.  A Hashtable keeps its ordering behind the scenes.</P>

   <H3>The benefits of these objects</H3>

   <P>With these three objects, you can quickly access any piece of information from any other.</P>

   <P>From the <B>string value</B>, you can retrieve the unique array index with:</P>

   <P>&nbsp; &nbsp;&nbsp; &nbsp;<CODE><A HREF="#getAOSLHashtable()">getAOSLHashtable</A>().<A HREF="~JD~aoslh#getUniqueString(s)~EJD~">getUniqueString</A>(__THE_STRING__).<A HREF="~JD~unqs~EJD~#getUnqArrIdx()">getUnqArrIdx</A>()</CODE></P>

   <P>From the <B>unique array index</B>, you can retrieve the string value:</P>

   <P>&nbsp; &nbsp;&nbsp; &nbsp;<CODE><A HREF="#getUSAPUnique()">getUSAPUnique</A>().<A HREF="~JD~usap#getUniqueString(i)~EJD~">getUniqueString</A>(__THE_UNQ_ARR_IDX__).<A HREF="~JD~unqs~EJD~#getString()">getString</A>()</CODE></P>

   <P>From the <B>absolute array index</B>, you can retrieve the string value...</P>

   <P>&nbsp; &nbsp;&nbsp; &nbsp;<CODE><A HREF="#getUSAPAbsolute()">getUSAPAbsolute</A>().<A HREF="~JD~usap#getUniqueString(i)~EJD~">getUniqueString</A>(__THE_ABS_ARR_IDX__).<A HREF="~JD~unqs~EJD~#getString()">getString</A>()</CODE></P>

   <P>...or the unique array index:</P>

   <P>&nbsp; &nbsp;&nbsp; &nbsp;<CODE><A HREF="#getUSAPAbsolute()">getUSAPAbsolute</A>().<A HREF="~JD~usap#getUniqueString(i)~EJD~">getUniqueString</A>(__THE_ABS_ARR_IDX__).<A HREF="~JD~unqs~EJD~#getUnqArrIdx()">getUnqArrIdx</A>()</CODE></P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class AOSLookup extends XBNObject  {
   private AOSLHashtable aoslh = null;
   private UniqueStringAP usapUnique = null;
   private UniqueStringAP usapAbsolute = null;
   private boolean bListUnqStrs = false;

   /**
      <P>Create an AOSLookup.<I>unique</I> UniqueStringAP, and <I>absolute</I> UniqueStringAP.</P>

      <P>Equal to <CODE><A HREF="~JD~aosl(aoslh,usap,usap,b)~EJD~">AOSLookup</A>(aosl_hashtable, usap_unique, usap_absolute, b_listUnqStrs, true)</CODE></P>
    **/
   public AOSLookup(AOSLHashtable aosl_hashtable, UniqueStringAP usap_unique, UniqueStringAP usap_absolute)  {
      this(aosl_hashtable, usap_unique, usap_absolute, true);
   }

   /**
      <P>Create an AOSLookup.<I>unique</I> UniqueStringAP, <I>absolute</I> UniqueStringAP, and list-unique-string setting.</P>

      <P>Equal to <CODE><A HREF="~JD~aosl(aoslh,usap,usap,b,b)~EJD~">AOSLookup</A>(aosl_hashtable, usap_unique, usap_absolute, b_listUnqStrs, b_validateParams, true)</CODE></P>
    **/
   public AOSLookup(AOSLHashtable aosl_hashtable, UniqueStringAP usap_unique, UniqueStringAP usap_absolute, boolean b_listUnqStrs)  {
      this(aosl_hashtable, usap_unique, usap_absolute, b_listUnqStrs, true);
   }


   /**
      <P>Create an AOSLookup.<I>unique</I> UniqueStringAP, <I>absolute</I> UniqueStringAP, and list-unique-string and validate-parameters settings.</P>

      @param  aosl_hashtable  The <A HREF="#aoslh">AOSLHashtable</A>.  May not be null.
      @param  usap_unique  The UniqueStringAP representing the <A HREF="#unique_us_array">unique strings in the string array</A>.  May not be null, each element must be non-null.
      @param  usap_absolute  The UniqueStringAP representing the <A HREF="#absolute_us_array">absolute strings in the string array</A>.  May not be null, and no element may be null.
      @param  b_listUnqStrs  Should <A HREF="~JD~getUnqStrList(s,s)~EJD~">getUnqStrList</A> and <A HREF="~JD~appendUSLToSB(sb,s,s)~EJD~">appendUSLToSB</A> actually list the strings (absolutely), or should you get a "strings not listed" message?
      @param  b_validateParams  .................
    **/
   public AOSLookup(AOSLHashtable aosl_hashtable, UniqueStringAP usap_unique, UniqueStringAP usap_absolute, boolean b_listUnqStrs, boolean b_validateParams)  {

      aoslh = aosl_hashtable;
      usapUnique = usap_unique;
      usapAbsolute = usap_absolute;
      bListUnqStrs = b_listUnqStrs;

      if(b_validateParams)  {
         crashIfBadInternalObjs(sCNSTR);
      }
   }

   /**
      <P>Get the AOSLHashtable for direct manipulation.</P>

      @return  <B>aosl_hashtable</B>  Exactly as provided to the <A HREF="~JD~aosl(aoslh,usap,usap,b,b)~EJD~">constructor</A>
    **/
   public final AOSLHashtable getAOSLHashtable()  {
      return aoslh;
   }

   /**
      <P>Get the <I>unique</I> UniqueStringAP for direct manipulation.</P>

      <P>See the <A HREF="#unique_us_array">section regarding this object</A> in the overall documentation.</P>

      @return  <B>usap_unique</B>  Exactly as provided to the <A HREF="~JD~aosl(aoslh,usap,usap,b,b)~EJD~">constructor</A>
    **/
   public final UniqueStringAP getUSAPUnique()  {
      return usapUnique;
   }

   /**
      <P>Get the <I>absolute</I> UniqueStringAP for direct manipulation.</P>

      <P>See the <A HREF="#absolute_us_array">section regarding this object</A> in the overall documentation.</P>

      @return  <B>usap_absolute</B>  Exactly as provided to the <A HREF="~JD~aosl(aoslh,usap,usap,b,b)~EJD~">constructor</A>
    **/
   public final UniqueStringAP getUSAPAbsolute()  {
      return usapAbsolute;
   }

   /**
      <P>Should getUnqStrList and appendUSLToSB print out the list of strings?</P>

      @return  <B>b_listUnqStrs</B>  Exactly as provided to the <A HREF="~JD~aosl(aoslh,usap,usap,b,b)~EJD~">constructor</A>
    **/
   public final boolean doListUnqStrs()  {
      return bListUnqStrs;
   }

   /**
      <P>Get the list of strings in the original array as a list.</P>

      @return  <CODE><A HREF="~JD~getUnqStrList(s)~EJD~">getUnqStrList</A>("")</CODE>
    **/
   public final String getUnqStrList()  {
      return getUnqStrList(sES);
   }

   /**
      <P>Get the list of strings in the original array as a list.</P>

      @return  <CODE><A HREF="~JD~getUnqStrList(s,s)~EJD~">getUnqStrList</A>(s_prefix, "")</CODE>
    **/
   public final String getUnqStrList(String s_prefix)  {
      return getUnqStrList(s_prefix, sES);
   }

   /**
      <P>Get the list of strings in the original array as a list.</P>

      @return  The resulting value contained in the StringBuffer, after calling <CODE><A HREF="~JD~appendUSLToSB(sb,s,s)~EJD~">appendUSLToSB</A>((new <A HREF="~JD~sb#sb(s)~EJD~">StringBuffer</A>("")), s_prefix, "")</CODE>
    **/
   public final String getUnqStrList(String s_prefix, String s_whenNoList)  {
      StringBuffer sb = new StringBuffer(sES);
      appendUSLToSB(sb, s_prefix, s_whenNoList);
      return sb.toString();
   }

   /**
      <P>Append the list of strings to the provided StringBuffer.</P>

      <P>Equal to <CODE><A HREF="~JD~appendUSLToSB(sb,s)~EJD~">appendUSLToSB</A>(str_buffer, "")</CODE></P>
    **/
   public final void appendUSLToSB(StringBuffer str_buffer)  {
      appendUSLToSB(str_buffer, sES);
   }

   /**
      <P>Append the list of strings to the provided StringBuffer.</P>

      <P>Equal to <CODE><A HREF="~JD~appendUSLToSB(sb,s,s)~EJD~">appendUSLToSB</A>(str_buffer, s_prefix, "")</CODE></P>
    **/
   public final void appendUSLToSB(StringBuffer str_buffer, String s_prefix)  {
      appendUSLToSB(str_buffer, s_prefix, sES);
   }

   /**
      <P>Append the list of strings to the provided StringBuffer.</P>

      @param  s_prefix  What should be first appended to str_buffer, regardless of the <A HREF="#doListUnqStrs()">doListUnqStrs</A> setting.  If null, no prefix is desired.
      @param  s_whenNoList  If doListUnqStrs equals false, then this is the string appended to str_buffer (after s_prefix).
    **/
   public final void appendUSLToSB(StringBuffer str_buffer, String s_prefix, String s_whenNoList)  {
      if(s_prefix != null)  {
         str_buffer.append(s_prefix);
      }

      if(doListUnqStrs())  {
         LPAConfig lpac = new LPAConfig("['", "', '", "']", "null");
         (new ListPA(lpac)).append(str_buffer, getUSAPUnique().getUniqueStringPAS());

      }  else  {
         str_buffer.append(s_whenNoList);
      }
   }


   /**
      <P>Verifies that all internal objects are correctly formatted, and crashes if they are not.</P>

      <P>Equal to <CODE><A HREF="~JD~crashIfBadInternalObjs(s)~EJD~">crashIfBadInternalObjs</A>("crashIfBadInternalObjs")</CODE></P>
    **/
   public final void crashIfBadInternalObjs()  {
      crashIfBadInternalObjs("crashIfBadInternalObjs");
   }

   /**
      <P>Verifies that all internal objects are correctly formatted, and crashes if they are not.</P>

      <P>This class verifies that ..............</P>

      @param  s_callingClsFnc  The class-plus-function name from which potential error messages should appear like they're coming from.
    **/
   public final void crashIfBadInternalObjs(String s_callingClsFnc)  {
      throwAXIfNull(usapUnique, "usap_unique", s_callingClsFnc);
      throwAXIfNull(usapAbsolute, "usap_absolute", s_callingClsFnc);
      throwAXIfNull(aoslh, "aosl_hashtable", s_callingClsFnc);

      CompareArrays ca = new CompareArrays(new CACExact());

      UniqueStringPAS pasUnq = usapUnique.getUniqueStringPAS(new PARSGoodUnq(new PARDNLGoodUnq(new RCLength(1, -1, false))));
      pasUnq.crashIfBad("xbn.array.AOSLookup." + s_callingClsFnc, "usap_unique");

      UniqueStringPAS pasAbsolute = usapAbsolute.getUniqueStringPAS(new PARString(new PARDupNullLen(true, false, (new RCLength(1, -1, false)))));
      pasAbsolute.crashIfBad("xbn.array.AOSLookup." + s_callingClsFnc, "usap_absolute");

      ca.crashIfBadValues("xbn.array.AOSLookup." + s_callingClsFnc, "usap_unique", "usap_absolute", pasUnq, pasAbsolute);
   }

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

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

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


      /**
         <P>Get a full (deep) copy of this AOSLookup as an Object.</P>
       **/
      protected Object clone() throws CloneNotSupportedException  {
         AOSLHashtable aoslh2 = aoslh.getAOSLHClone();
         UniqueStringAP usapUnq2 = usapUnique.getUSAPClone();
         UniqueStringAP usapAbs2 = usapAbsolute.getUSAPClone();
         return (new AOSLookup(aoslh2, usapUnq2, usapAbs2, bListUnqStrs));
      }
   //Cloning...END
}