/*
   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.string;
   import xbn.XBNObject;
   import xbn.array.APString;
   import xbn.array.primitive.PARSCBad;

/**
   <P>Configuration for UtilSOB.getContainedIdxs.  See <A HREF="~JD~utilsob~EJD~">UtilSOB</A>.<A HREF="~JD~utilsob#getContainedIdxs(sob[],gcic)~EJD~">getContainedIdxs</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/string/GCIConfig.java">GCIConfig.java</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 GCIConfig extends XBNObject  {

   private String sCallingClassFunc = null;
   private String[] asNames = null;
   private boolean bEqualOk = false;
   private PARSCBad parscb = null;

   /**
      <P>Create a GCIConfig with default settings.</P>

      <P>Equal to <CODE><A HREF="~JD~gcic(b)~EJD~">GCIConfig</A>(false)</CODE></P>
    **/
   public GCIConfig()  {
      this(false);
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,b)~EJD~">GCIConfig</A>(s_callingClsFnc, false)</CODE></P>
    **/
   public GCIConfig(String s_callingClsFnc)  {
      this(s_callingClsFnc, false);
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,b)~EJD~">GCIConfig</A>(null, b_equalOk)</CODE></P>
    **/
   public GCIConfig(boolean b_equalOk)  {
      this(null, b_equalOk);
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,parscb)~EJD~">GCIConfig</A>(null, parsc_bad)</CODE></P>
    **/
   public GCIConfig(PARSCBad parsc_bad)  {
      this(null, parsc_bad);
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,s[],b)~EJD~">GCIConfig</A>(s_callingClsFnc, as_names, false)</CODE></P>
    **/
   public GCIConfig(String s_callingClsFnc, String[] as_names)  {
      this(s_callingClsFnc, as_names, false);
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,s[],b)~EJD~">GCIConfig</A>(s_callingClsFnc, null, b_equalOk)</CODE></P>
    **/
   public GCIConfig(String s_callingClsFnc, boolean b_equalOk)  {
      this(s_callingClsFnc, null, b_equalOk);
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,s[],parscb)~EJD~">GCIConfig</A>(s_callingClsFnc, null, parsc_bad)</CODE></P>
    **/
   public GCIConfig(String s_callingClsFnc, PARSCBad parsc_bad)  {
      this(s_callingClsFnc, null, parsc_bad);
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,b,parscb)~EJD~">GCIConfig</A>(null, b_equalOk, parsc_bad)</CODE></P>
    **/
   public GCIConfig(boolean b_equalOk, PARSCBad parsc_bad)  {
      this(null, b_equalOk, parsc_bad);
   }
   /**
      <P>Create a GCIConfig.</P>

      <P>Equal to <CODE><A HREF="~JD~gcic(s,s[],b,parscb)~EJD~">GCIConfig</A>(s_callingClsFnc, as_names, b_equalOk, (new <A HREF="~JD~parscb#parscb()~EJD~">PARSCBad</A>()))</CODE></P>
    **/
   public GCIConfig(String s_callingClsFnc, String[] as_names, boolean b_equalOk)  {
      this(s_callingClsFnc, as_names, b_equalOk, (new PARSCBad()));
   }

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

      <P>Equal to <CODE><A HREF="~JD~gcic(s,s[],b,parscb)~EJD~">GCIConfig</A>(s_callingClsFnc, as_names, false, parsc_bad)</CODE></P>
    **/
   public GCIConfig(String s_callingClsFnc, String[] as_names, PARSCBad parsc_bad)  {
      this(s_callingClsFnc, as_names, false, parsc_bad);
   }
   /**
      <P>Create a GCIConfig.</P>

      <P>Equal to <CODE><A HREF="~JD~gcic(s,s[],b,parscb)~EJD~">GCIConfig</A>(s_callingClsFnc, null, b_equalOk, parsc_bad)</CODE></P>
    **/
   public GCIConfig(String s_callingClsFnc, boolean b_equalOk, PARSCBad parsc_bad)  {
      this(s_callingClsFnc, null, b_equalOk, parsc_bad);
   }

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

      <P>This documentation discusses <A HREF="~JD~utilsob~EJD~">UtilSOB</A>.<A HREF="~JD~utilsob#getContainedIdxs(sob[],gcic)~EJD~">getContainedIdxs</A>, including it's parameters (a_strOrBfr and gci_config) and returned value (an informational <A HREF="~JD~s_s~EJD~">s_s</A>).</P>

      @param  s_callingClsFnc  The name of the class-plus-function for potential error messages, when getContainedIdxs detects a containment violation.  If null, an informational <A HREF="~JD~i_i_i~EJD~">i_i_i</A> is returned.  If non-null, an <A HREF="~JD~ax~EJD~">AssertException</A> is thrown with a message describing the violation (where this class-plus-function is where the error will appear to have been caused).  See <a href="#getCallingClassFunc()">getCallingClassFunc</a>.
      @param  as_names  The array of descriptive names for every element in a_strOrBfr.  If non-null, these names are used in potential error messages (element <I>X</I> in as_names is the name of element <I>X</I> in a_strOrBfr).  If null, then "<CODE>a_strOrBfr[INDEX]</CODE>" is the name assigned to each element.  When non-null, this must be exactly the same length as a_strOrBfr.  All elements should be non-null and at least one character in length, although this is not enforced.  If s_callingClsFnc is null, then this must be null as well.  See <a href="#getAOSNames()">getAOSNames</a>.
      @param  b_equalOk  Should equality also be considered illegal?  If true, then containment is illegal, but equality is not.  If false, both containment and equality are considered illegal.  See <a href="#isEqualOk()">isEqualOk</a>.
      @param  parsc_bad  Defines extra rules for containment.  May not be null.  See <a href="#getPARSCBad()">getPARSCBad</a>.
    **/
   public GCIConfig(String s_callingClsFnc, String[] as_names, boolean b_equalOk, PARSCBad parsc_bad)  {
      throwAXIfNull(parsc_bad, "parsc_bad", sCNSTR);

      if(s_callingClsFnc == null  &&  as_names != null)  {
         throwAX("constructor:  s_callingClsFnc is null, but as_names is not.");
      }

      sCallingClassFunc = s_callingClsFnc;
      asNames = as_names;
      bEqualOk = b_equalOk;
      parscb = parsc_bad;
   }

   /**
      <P>Get the name of the class-plus-function for potential error messages.</P>

      <P>If this returns <B>null</B>, an informational <A HREF="~JD~i_i_i~EJD~">i_i_i</A> is returned by <A HREF="~JD~utilsob#getContainedIdxs(sob[],gcic)~EJD~">getContainedIdxs</A>.  If <B>non-null</B>, an <A HREF="~JD~ax~EJD~">AssertException</A> is thrown with a message describing the violation (where this class-plus-function is where the error will appear to have been caused).</P>

      @return  <B>s_callingClsFnc</B>  Exactly as provided to the <A HREF="~JD~gcic(s,s[],b,parscb)~EJD~">constructor</A>.
    **/
   public final String getCallingClassFunc()  {
      return sCallingClassFunc;
   }

   /**
      <P>Get the array of descriptive names for every element in a_strOrBfr.  See <A HREF="~JD~utilsob#getContainedIdxs(sob[],gcic)~EJD~">getContainedIdxs</A> for information on the a_strOrBfr parameter.</P>

      <P>If this returns a non-null value, it is an <B>array of strings</B> containing the names to be used in potential error messages (element <I>X</I> in this is the name of element <I>X</I> in a_strOrBfr).  If null, then "<CODE>a_strOrBfr[INDEX]</CODE>" is the name assigned to each element.</P>

      <P>When <a href="#getCallingClassFunc()">getCallingClassFunc</a> returns null, this also returns null.  When getCallingClassFunc is non-null, this may or may not return null.</P>

      @return  <B>s_callingClsFnc</B>  Exactly as provided to the <A HREF="~JD~gcic(s,s[],b,parscb)~EJD~">constructor</A>.
    **/
   public final String[] getAOSNames()  {
      return asNames;
   }

   /**
      <P>Is equality also considered illegal?</P>

      <P>If this returns <B>true</B>, then containment is illegal, but equality is not.  If <B>false</B>, both containment and equality are considered illegal.</P>

      @return  <B>b_equalOk</B>  Exactly as provided to the <A HREF="~JD~gcic(s,s[],b,parscb)~EJD~">constructor</A>.
    **/
   public final boolean isEqualOk()  {
      return bEqualOk;
   }

   /**
      <P>Get the PARSCBad, which defines extra containment rules.</P>

      @return  <B>parsc_bad</B>  Exactly as provided to the <A HREF="~JD~gcic(s,s[],b,parscb)~EJD~">constructor</A>.
    **/
   public final PARSCBad getPARSCBad()  {
      return parscb;
   }

   /**
      <P>Get some information about this GCIConfig.</P>
    **/
   public final String toString()  {
      return this.getClass().getName() + ":  getCallingClassFunc()='" + getCallingClassFunc() + "', getAOSNames()=[" + (new APString(getAOSNames())).getList() + "], isEqualOk()=" + isEqualOk() + ", [" + getPARSCBad().toString() + "]";
   }
}