/*
   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.named;
   import xbn.XBNObject;
   import xbn.AssertException;
   import xbn.array.AOSLookup;
   import xbn.array.AOSLHashtable;
   import xbn.array.UtilArray;
   import xbn.array.primitive.ListPA;
   import xbn.array.primitive.PARSStrict;
   import xbn.string.SOBStringBuffer;
   import xbn.string.UtilString;


/**
   <P>Manage an array of any object implementing the Named interface.  Using a <A HREF="~JD~aosl~EJD~">AOSLookup</A>, this class provides quick access to the array, with error protection.</P>

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

   <P>This object holds both the array of Named objects, as well as the AOSLookup.  NamedArray also implements Named, therefore having a name itself.  Because of this, you could have a NamedArray <I>of</I> NamedArrays.  Pretty cool, eh?  <CODE>:' )</CODE></P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class NamedArray extends XBNObject implements Named  {
   private UtilString uStr = new UtilString();

   private String sName = null;
   private APNamed apn = null;
   private AOSLookup aosl = null;

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

      <P>Equal to <CODE><A HREF="~JD~na(n[],b)~EJD~">NamedArray</A>(a_named, true)</CODE></P>
    **/
   public NamedArray(Named[] a_named)  {
      this(a_named, true);
   }

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

      <P>Equal to <CODE><A HREF="~JD~na(s,n[],b)~EJD~">NamedArray</A>(null, a_named, true)</CODE></P>
    **/
   public NamedArray(Named[] a_named, boolean b_listNames)  {
      this(null, a_named, b_listNames);
   }

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

      <P>Equal to <CODE><A HREF="~JD~na(s,n[],b)~EJD~">NamedArray</A>(s_name, a_named, true)</CODE></P>
    **/
   public NamedArray(String s_name, Named[] a_named)  {
      this(s_name, a_named, true);
   }


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

      @param  s_name  The name of this NamedArray.  See <A HREF="#getName()">getName</A>.
      @param  a_named  The array of Named objects.  Must be non-null, at least one element in length, no elements may be null, and every element's name must be unique.  Note that the array is cloned, but all Named elements are unaltered (in other words, the Named elements are not altered, but the array they are contained in, is).  See <A HREF="UtilNamed.html">UtilNamed</A>.<A HREF="~JD~utiln#getShallowClone(n[])~EJD~">getShallowClone</A>.
      @param  b_listNames  Passed directly to the <A HREF="~JD~utila~EJD~">UtilArray</A>.<A HREF="~JD~utila#getAOSLFromPA(pa,b)~EJD~">getAOSLFromPA</A>, which creates the internal <A HREF="~JD~aosl~EJD~">AOSLookup</A> for this class.
    **/
   public NamedArray(String s_name, Named[] a_named, boolean b_listNames)  {
      sName = s_name;

      PASNamed pasn = new PASNamed(a_named, (new PARSStrict()));
      pasn.crashIfBad("xbn.named.NamedArray.constructor", "a_named");


      aosl = (new UtilArray()).getAOSLFromPA(pasn, b_listNames);
      apn = new APNamed(a_named, true);

   }

   public NamedArray(String s_name, Named[] a_named, AOSLookup aos_lookup)  {
      this(s_name, a_named, aos_lookup, true);
   }

   /**
      <P>Create a NamedArray manually.</P>
    **/
   public NamedArray(String s_name, Named[] a_named, AOSLookup aos_lookup, boolean b_validate)  {
      this(s_name, (new APNamed(a_named, true)), aos_lookup, b_validate);
   }

   /**
      <P>Create a NamedArray manually.</P>

      @param  s_name  The name of this NamedArray.
      @param  a_named  The array of Named objects.  Must be non-null, and the names of these Named objects must map one-to-one with those existing in aos_lookup.
      @param  aos_lookup  The AOSLookup for a_named.  Must be non-null, and the names contained in it must map one-to-one with those existing in a_named.  This is only enforced when b_validate is true.
      @param  b_validate  If true, then verify that aos_lookup and a_named are legal for a NamedArray.  If false, then you're on your own, as far as this object behaving as documented.  If you are absolutely certain that things are okay, it will give you somewhat of a speed increase to make this false.
    **/
   public NamedArray(String s_name, APNamed ap_named, AOSLookup aos_lookup, boolean b_validate)  {
      if(b_validate)  {
         try  {
            ap_named.getPASNamed(new PARSStrict()).crashIfBad("xbn.named.NamedArray.constructor", "a_named");
         }  catch(NullPointerException npx)  {
            throwAX("constructor:  ap_named is null.");
         }

         try  {
            aos_lookup.crashIfBadInternalObjs(sCNSTR);
         }  catch(NullPointerException npx)  {
            throwAX("constructor:  aos_lookup is null.");
         }
      }

      sName = s_name;
      aosl = aos_lookup;
      apn = ap_named;
   }


   /**
      <P>Create an as-deep-as-possible copy of the provided NamedArray.  Everything down-to-but-not-including the Named objects are deeply cloned.</P>

      <P>If you need a deep copy, you must manually do the copying yourself, and use the manual constructor.  Since Named is just an interface, it is not possible to clone it here.</P>

      @param  named_array  The NamedArray to copy.  May not be null.
    **/
   public NamedArray(NamedArray named_array)  {
      try  {
         sName = named_array.sName;
      }  catch(NullPointerException npx)  {
         throwAX("constructor:  named_array is null.");
      }

      apn = named_array.getAPNamed().getAPNClone();
      aosl = named_array.getAOSLookup().getAOSLClone();
   }

   /**
      <P>Return the AOSLookup for direct manipulation.</P>
    **/
   public final AOSLookup getAOSLookup()  {
      return aosl;
   }

   /**
      <P>Return the AOSLHashtable for direct manipulation.</P>
    **/
   public final AOSLHashtable getAOSLHashtable()  {
      return getAOSLookup().getAOSLHashtable();
   }

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

      @return  <B>ap_named</B>  Exactly as provided to the <A HREF="~JD~na(s,apn,aosl,b)~EJD~">constructor</A>.
    **/
   public final APNamed getAPNamed()  {
      return apn;
   }

   /**
      <P>Get a listing of every name.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa()~EJD~">ListPA</A>()).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="#getAPNamed()">getAPNamed</A>().<A HREF="~JD~apn~EJD~#getPASNamed()">getPASNamed</A>())</CODE>
    **/
   public final String getNameList()  {
      return (new ListPA()).get(getAPNamed().getPASNamed());
   }

   /**
      <P>Get a listing of every name.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_divider)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="#getAPNamed()">getAPNamed</A>().<A HREF="~JD~apn~EJD~#getPASNamed()">getPASNamed</A>())</CODE>
    **/
   public final String getNameList(String s_divider)  {
      return (new ListPA(s_divider)).get(getAPNamed().getPASNamed());
   }

   /**
      <P>Get a listing of every name.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_prefix, s_postfix)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="#getAPNamed()">getAPNamed</A>().<A HREF="~JD~apn~EJD~#getPASNamed()">getPASNamed</A>())</CODE>
    **/
   public final String getNameList(String s_prefix, String s_postfix)  {
      return (new ListPA(s_prefix, s_postfix)).get(getAPNamed().getPASNamed());
   }

   /**
      <P>Get a listing of every name.</P>

      @return <CODE>(new <A HREF="~JD~lpa#lpa(lpac)~EJD~">ListPA</A>(s_prefix, s_divider, s_postfix)).<A HREF="~JD~lpa#get(pa)~EJD~">get</A>(<A HREF="#getAPNamed()">getAPNamed</A>().<A HREF="~JD~apn~EJD~#getPASNamed()">getPASNamed</A>())</CODE>
    **/
   public final String getNameList(String s_prefix, String s_divider, String s_postfix)  {
      return (new ListPA(s_prefix, s_divider, s_postfix)).get(getAPNamed().getPASNamed());
   }

   /**
      <P>How many Named objects exist in this NamedArray?</P>

      @return  <CODE><A HREF="#getAPNamed()">getAPNamed</A>().<A HREF="~JD~ap~EJD~#getLength()">getLength</A>()</CODE>
    **/
   public final int getLength()  {
      return getAPNamed().getLength();
   }

   /**
      <P>Does the provided name represent an actually-existing Named object?</P>

      @return  <CODE><A HREF="#getAOSLHashtable()">getAOSLHashtable</A>().<A HREF="~JD~aoslh#containsKey(s)~EJD~">containsKey</A>(s_name)</CODE>
    **/
   public final boolean doesExist(String s_name)  {
      return getAOSLHashtable().containsKey(s_name);
   }

   /**
      <P>Get the Named object at the requested array index.</P>

      @param  i_dx  Must be between 0 and (<A HREF="#getLength()">getCount</A> - 1), inclusive.
    **/
   public final int getArrIdx(String s_name)  {
      try  {
         return getAOSLHashtable().getUniqueString(s_name).getUnqArrIdx();
      }  catch(AssertException ax)  {
         throwAX("getArrIdx:  doesExist('" + s_name + "') equals false.");
      }

      //Never reached.  Required for compile.
      return -1;
   }

   /**
      <P>Get the Named object at the requested array index.</P>

      @param  i_dx  Must be between 0 and (<A HREF="#getLength()">getCount</A> - 1), inclusive.
    **/
   public final Named getNamed(String s_name)  {
      return getAPNamed().getNamed(getArrIdx(s_name));
   }

   /**
      <P>Get the Named object at the requested array index.</P>

      @param  i_dx  Must be between 0 and (<A HREF="#getLength()">getCount</A> - 1), inclusive.
    **/
   public final Named getNamed(int i_dx)  {
      return getAPNamed().getNamed(i_dx);
   }

   /**
      <P>Get the name of the Named object at the requested array index.</P>

      @param  i_dx  Must be valid.
    **/
   public String getName(int i_dx)  {
      return getNamed(i_dx).getName();
   }

   //REQUIRED BY xbn.named.Named...START
      public String getName()  {
         return sName;
      }
   //REQUIRED BY xbn.named.Named...END



   /**
      <P>Get some information about this NamedArray.</P>

      @return <CODE><A HREF="~JD~na#toString(b)~EJD~">toString</A>(true)</CODE>
    **/
   public String toString()  {
      return toString(true);
   }


   /**
      <P>Throw an exception with getName() as part of the message.</P>

      <P>Equal to <CODE><A HREF="~JD~xbno#throwAX(s)~EJD~">throwAX</A>(s_callingFunc +
<BR>&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;[<A HREF="~JD~utils~EJD~">UtilString</A>].<A HREF="~JD~utils#getConditional(s,s,s)~EJD~">getConditional</A>(&quot; [getName()=&quot;, <A HREF="#getName()">getName</A>(), &quot;]&quot;) +
<BR>&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&quot;:&nbsp; &quot; + s_errorMsg)</CODE></P>
    **/
   protected void throwAXWithName(String s_callingFunc, String s_errorMsg)  {
      throwAX(s_callingFunc +
         uStr.getConditional(" [getName()=", getName(), "]") +
         ":  " + s_errorMsg);
   }

   /**
      <P>Get some information about this NVArray object, and optionally about the Atomic levels herein.</P>

      @param  b_subTS  If true, then display all toStrings for the sub-Named objects.  If false, then display the <I>names</I> of all internal Named objects.
    **/
   public String toString(boolean b_subTS)  {
      String sName = uStr.getConditional("getName()=", getName(), ", ");

      SOBStringBuffer ssbSubTS = new SOBStringBuffer(sES);
      if(b_subTS)  {
         (new UtilArray()).appendTSList(ssbSubTS, getAPNamed().getAONShallowClone(), null, "  |  ", null, null, null, null);
      }  else  {
         ssbSubTS.append("SUB TO STRINGS NOT DISPLAYED");
      }

      return this.getClass().getName() + ":  " + sName + "[" + ssbSubTS.toString() + "]";
   }
}