/*
   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.primitive;
   import xbn.util.XBNLocked;
   import xbn.string.SOBString;
   import xbn.string.SOBStringBuffer;

/**
   <P>Wraps around anything to make it appear like an array of primitives (including Strings).</P>

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

   <P>Note that this class extends <A HREF="~JD~xbnl~EJD~">XBNLocked</A>, and not <A HREF="~JD~xbno~EJD~">XBNObject</A>.  This is in anticipation of many extending classes needing to optionally protect/un-protect access to the thing that is being wrapped.</P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public abstract class PrimitiveArray extends XBNLocked  {
   private PrimitiveArrayRule par = null;
   private String sFQClassName = null;
   private String sFQClassNameFunc = null;
   private PAViolation pav = null;

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

      @param  s_fqClassName  The fully qualified name of the class extending this one.  This is used when the default <A HREF="#crashIfBad()">crashIfBad</A> function is used.
      @param  pa_rule  The definition of the rule that the array-wrapped-by-this-PrimitiveArray must follow.  May not be null.
    **/
   protected PrimitiveArray(String s_fqClassName, PrimitiveArrayRule pa_rule)  {
      throwAXIfNull(pa_rule, "pa_rule", sCNSTR);

      par = pa_rule;
      sFQClassName = s_fqClassName;
      sFQClassNameFunc = s_fqClassName + ".crashIfBad";
      pav = null;
   }

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

      @return  <B>pa_rule</B>  Exactly as provided to <A HREF="~JD~pa(s,par)~EJD~">constructor</A>.
    **/
   public final PrimitiveArrayRule getPrimitiveArrayRule()  {
      return par;
   }

   /**
      <P>Get the element at the requested array index, as a string.</P>

      @param  i_dx  The array index.  Must range 0..<CODE>[<A HREF="#getLength()">getLength</A>() - 1]</CODE>, inclusive.
      @param  AssertException  If <A HREF="~JD~pa~EJD~#isNull()">isNull</A> equals true.
    **/
   public abstract String getString(int i_dx);

   /**
      <P>Get the element at the requested array index, as an SOBString.</P>

      @return  <CODE>(new <A HREF="~JD~ss#ss(s)~EJD~">SOBString</A>(<A HREF="~JD~pa#getString(i)~EJD~">getString</A>(i_dx)))</CODE>
    **/
   public SOBString getSOBString(int i_dx)  {
      return(new SOBString(getString(i_dx)));
   }

   /**
      <P>Get the element at the requested array index, as an SOBStringBuffer.</P>

      @return  <CODE>(new <A HREF="~JD~ssb#ssb(s)~EJD~">SOBStringBuffer</A>(<A HREF="~JD~pa#getString(i)~EJD~">getString</A>(i_dx)))</CODE>
    **/
   public SOBStringBuffer getSOBStringBuffer(int i_dx)  {
      return(new SOBStringBuffer(getString(i_dx)));
   }

   /**
      <P>How many items exist in this PrimitiveArray?</P>
      @exception  AssertException  If <A HREF="~JD~pa~EJD~#isNull()">isNull</A> equals true.
    **/
   public abstract int getLength();

   /**
      <P>What is the fully qualified class name of this PrimitiveArray?</P>

      @return  <B>s_fqClassName</B>  Exactly as provided to the <A HREF="~JD~pa(s,par)~EJD~">constructor</A>.
    **/
   public final String getFQClassName()  {
      return sFQClassName;
   }

   /**
      <P>Is the [thing being wrapped by this PrimitiveArray] null?</P>
    **/
   public abstract boolean isNull();

   /**
      <P>Is the [thing] at the requested array index null?</P>

      @param  i_dx  The array index.  Must range 0..<CODE>[<A HREF="#getLength()">getLength</A>() - 1]</CODE>, inclusive
      @param  AssertException  If <A HREF="~JD~pa~EJD~#isNull()">isNull</A> equals true.
    **/
   public abstract boolean isNull(int i_dx);

   /**
      <P>Are the two elements equal?</P>

      @return <CODE><A HREF="~JD~areLmntsEqual(i,pa,i)~EJD~">areLmntsEqual</A>(i_idx1, this, i_idx2)</CODE>
    **/
   public final boolean areLmntsEqual(int i_idx1, int i_idx2)  {
      return areLmntsEqual(i_idx1, this, i_idx2);
   }

   /**
      <P>Are the two elements equal?</P>

      @param  i_idxThis  The array index.  Must range 0..<CODE>[<A HREF="~JD~pa~EJD~#getLength()">getLength</A>() - 1]</CODE>, inclusive
      @param  pa_other  The PrimitiveArray to retrieve element i_idxOther from.  May not be null.
      @param  i_idxOther  The array index of the desired element in pa_other.  Must be valid for pa_other.
    **/
   public abstract boolean areLmntsEqual(int i_idxThis, PrimitiveArray pa_other, int i_idxOther);

   /**
      <P>Is the array legal, according to the PrimitiveArrayRule?</P>

      @return <CODE>isValid(null, null)</CODE>
    **/
   public final boolean isValid()  {
      return isValid(null, null);
   }

   /**
      <P>Is the array legal, according to the PrimitiveArrayRule?</P>

      @param  s_callingClsFnc  The name of the class-plus-function, only for use in the potential error message.  When either this and/or s_varName are non-null, an <A HREF="~JD~ax~EJD~">AssertException</A> is thrown when the array is deemed invalid.  When <I>both</I> parameters are null, false is returned when the array is invalid.
      @param  s_varName  The name of the array variable, only for use in the potential error message.
      @return  <B>true</B>  When the array is completely valid.  Note:  The moment this function returns true, <A HREF="#wasValidated()">wasValidated</A> equals true.
      <BR><B>false</B>  When the array is invalid, and both s_callingClsFnc and s_varName are null.
    **/
   public abstract boolean isValid(String s_callingClsFnc, String s_varName);

   /**
      <P>Declare that this PrimitiveArray and its contents are truly valid.</P>

      <P>Right before your version of isValid returns true, be sure to also call this function.  See <A HREF="~JD~isValid(s,s)~EJD~">isValid</A>.</P>

      <P>This causes <A HREF="#wasValidated()">wasValidated</A> to return true.  There is no way to undo this without recreating the object.</P>

      <P><B>Be careful when calling this function directly.</B>  You can call this function manually, but if the [thing being wrapped to look like an array] is not valid, you will get unpredictable results when using this class or its functions.  Moral:  Don't call this function unless you know what you're doing.</P>

      <P>Equal to <CODE><A HREF="~JD~setPAViolation(pav)~EJD~">setPAViolation</A>(new <A HREF="~JD~pav#pav()~EJD~">PAViolation</A>())</CODE></P>
    **/
   protected final void declareNoViolation()  {
      setPAViolation(new PAViolation());
   }

   protected final void setPAViolation(PAViolation pa_violation)  {
      throwAXIfNull(pa_violation, "pa_violation", "setPAViolation");
      pav = pa_violation;
   }

   public final PAViolation getPAViolation()  {
      return pav;
   }

   /**
      <P>Was the array deemed valid?</P>

      @return  <CODE>(<A HREF="#getPAViolation()">getPAViolation</A>() != null  &amp;&amp;  getPAViolation().<A HREF="~JD~pav~EJD~#hasNoViolation()">hasNoViolation</A>())</CODE>
    **/
   public final boolean wasValidated()  {
      return (getPAViolation() != null  &&  getPAViolation().hasNoViolation());
   }

   /**
      <P>If the char array is not legal, then an AssertException should be thrown with a descriptive error message.  Otherwise, do nothing.</P>

      <P>Equal to <CODE><A HREF="~JD~crashIfBad(s,s)~EJD~">crashIfBad</A>(<A HREF="#getFQClassName()">getFQClassName</A>() + ".crashIfBad", "[the object wrapped by this PrimitiveArray]")</CODE></P>
    **/
   public final void crashIfBad()  {
      crashIfBad(sFQClassNameFunc, "[the object wrapped by this PrimitiveArray]");
   }

   /**
      <P>If the char array is not legal, then an AssertException should be thrown with a descriptive error message.  Otherwise, do nothing.</P>

      <P>Equal to <CODE><A HREF="~JD~isValid(s,s)~EJD~">isValid</A>(s_callingClsFnc, s_varName)</CODE></P>

      <P>Before isValid is called, it is verified that both parameters are non-null, and at least one character in length.</P>
    **/
   public final void crashIfBad(String s_callingClsFnc, String s_varName)  {
      throwAXIfBadStr(s_callingClsFnc, "s_callingClsFnc", "crashIfBad");
      throwAXIfBadStr(s_varName, "s_varName", "crashIfBad");
      boolean bUNRTRND = isValid(s_callingClsFnc, s_varName);
   }

   /**
      <P>Get a <I>new</I> array of strings, based upon all strings existing (via getString) in this PrimitiveArrayString.  See <A HREF="#getString(int)">getString</A></P>

      @return  <B>null</B>  If <A HREF="~JD~pa~EJD~#isNull()">isNull</A> is true.
      <BR>An array of strings where each element is equal to getString([ARRAY_INDEX])
    **/
   public final String[] getNewAOString()  {
      if(isNull())  {
         return null;
      }

      String[] as = new String[getLength()];
      for(int i = 0; i < getLength(); i++)  {
         as[i] = getString(i);
      }

      return as;
   }


   /**
      <P>Get a <I>new</I> array of SOBStrings.  See <A HREF="#getSOBString(int)">getSOBString</A></P>

      @return  <B>null</B>  If <A HREF="~JD~pa~EJD~#isNull()">isNull</A> is true.
      <BR>An array of SOBStrings where each element is equal to getSOBString([ARRAY_INDEX])
    **/
   public final SOBString[] getNewAOSOBString()  {
      if(isNull())  {
         return null;
      }

      SOBString[] asob = new SOBString[getLength()];
      for(int i = 0; i < getLength(); i++)  {
         asob[i] = getSOBString(i);
      }

      return asob;
   }


   /**
      <P>Get a <I>new</I> array of SOBStringBuffers.  See <A HREF="#getSOBStringBuffer(int)">getSOBStringBuffer</A></P>

      @return  <B>null</B>  If <A HREF="~JD~pa~EJD~#isNull()">isNull</A> is true.
      <BR>An array of SOBStringBuffers where each element is equal to getSOBStringBuffer([ARRAY_INDEX])
    **/
   public final SOBStringBuffer[] getNewAOSOBStringBuffer()  {
      if(isNull())  {
         return null;
      }

      SOBStringBuffer[] ass = new SOBStringBuffer[getLength()];
      for(int i = 0; i < getLength(); i++)  {
         ass[i] = getSOBStringBuffer(i);
      }

      return ass;
   }

   /**
      <P>Get a listing of every item in this Primitive array.</P>

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

   /**
      <P>Get a listing of every item in this Primitive array.</P>

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

   /**
      <P>Get a listing of every item in this Primitive array.</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>(this)</CODE>
    **/
   public String getList(String s_prefix, String s_postfix)  {
      return (new ListPA(s_prefix, s_postfix)).get(this);
   }

   /**
      <P>Get a listing of every item in this Primitive array.</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>(this)</CODE>
    **/
   public String getList(String s_prefix, String s_divider, String s_postfix)  {
      return (new ListPA(s_prefix, s_divider, s_postfix)).get(this);
   }


   /**
      <P>To be used by implementations of isValid.  See <A HREF="~JD~isValid(s,s)~EJD~">isValid</A>.</P>
    **/
   protected final void throwAXIllegal(String s_callingClsFnc, String s_varName, String s_currently)  {
      throwAXSpoof(s_callingClsFnc + ":  " + s_varName + " is illegal according to [" + getPrimitiveArrayRule().toString() + "].  Currently, " + s_currently);
   }

   /**
      <P>To be used by implementations of areLmntsEqual.  See <A HREF="~JD~areLmntsEqual(i,pa,i)~EJD~">areLmntsEqual</A>.</P>
    **/
   protected final void throwLmntsEqualAioobx(int i_idxThis, String s_paOtherName, PrimitiveArray pa_other, int i_idxOther)  {
      String s = null;
      if(i_idxThis < 0  ||  i_idxThis >= getLength())  {
         s = "i_idxThis (" + i_idxThis + ") invalid.  getLength()=" + getLength() + ".";
      }

      try  {
         if(i_idxOther < 0  ||  i_idxOther >= pa_other.getLength())  {
            if(s != null)  {
               s += "  ";
            }

            s += "i_idxThis (" + i_idxThis + ") invalid.  " + s_paOtherName + ".getLength()=" + pa_other.getLength() + ".";
         }
      }  catch(NullPointerException npx)  {
         throwAX("throwLmntsEqualAioobx:  pa_other is null.  Original parameters:  i_idxThis=" + i_idxThis + ", s_paOtherName='" + s_paOtherName + "', i_idxOther=" + i_idxOther);
      }


      throwAX("areLmntsEqual:  " + s);
   }
}