/*
   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.placeholder.i_i_i;

   import java.util.Date;
   import java.text.SimpleDateFormat;
      import java.text.ParseException;

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

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/string/UtilString.java">UtilString.java</A>. &nbsp;<B>Unit tests:</B> &nbsp;xbn_junit.string.<A HREF="../../../CODE/xbn_junit/string/JUTUtilString.java">JUTUtilString.java</A> and also see the unit tests for <A HREF="~JD~utilsob~EJD~">UtilSOB</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 UtilString extends UtilSOB  {

   /**
      <P>To shorten code and Javadoc.</P>

      <P>Equal to <B>"xbn.string.UtilString."</B></P>
    **/
   public static final String sUS = "xbn.string.UtilString.";

   /**
      <P>Create a UtilString.  This constructor does nothing.</P>
    **/
   public UtilString()  {
   }

   private UtilChar uChar = new UtilChar();
   public final String[] getAOHexDigitAsStr(String s_tr)  {
      String[] as = new String[s_tr.length()];

      try  {
         for(int i = 0; i < s_tr.length(); i++)  {
            as[i] = uChar.getHexDigitAsString(s_tr.charAt(i));
         }
      }  catch(NullPointerException npx)  {
         throwAX("getAOHexDigitAsStr:  s_tr is null.");
      }

      return as;
   }

   /**
      <P>Get a random hex number with the requested number of digits.</P>

      @param  i_digits  The number of digits in length the returned value should be.  Must be greater than -1.
      @return  <B>""</B>  If i_digits is zero.
      <BR><B>[A hex digit of i_digits length]</B>  If i_digits is anything but zero.
    **/
   public String getRandomHex(int i_digits)  {
      if(i_digits < 0)  {
         throwAX("getRandomHexDigit:  i_digits must be equal to or greater than zero.");
      }

      StringBuffer sb = new StringBuffer(sES);

      for(int i = 0; i < i_digits; i++)  {
         int j = (new Double(Math.random() * 1000000)).intValue();
         sb.append(UtilChar.getAOCHexLetters()[j % 16]);
      }

      return sb.toString();
   }



   /**
      <P>Conditionally get the string, if it's not null.</P>

      <P>Equal to <CODE><A HREF="~JD~getConditional(s,s)~EJD~">getConditional</A>(s_value, "")</CODE></P>
    **/
   public String getConditional(String s_value)  {
      return getConditional(s_value, sES);
   }

   /**
      <P>Conditionally get the string, if it's not null.</P>

      <P>Equal to <CODE><A HREF="~JD~getConditional(s,s,s,s)~EJD~">getConditional</A>(null, s_value, null, s_whenObjectNull)</CODE></P>
    **/
   public String getConditional(String s_value, String s_whenObjectNull)  {
      return getConditional(null, s_value, null, s_whenObjectNull);
   }


   /**
      <P>Convenience function to conditionally display a variable when non-null.</P>

      <P>Equal to <CODE><A HREF="~JD~getConditional(s,s,s,s)~EJD~">getConditional</A>(s_prefix, s_value, s_postfix, "")</CODE></P>
    **/
   public String getConditional(String s_prefix, String s_value, String s_postfix)  {
      return getConditional(s_prefix, s_value, s_postfix, sES);
   }

   /**
      <P>Convenience function to conditionally display a variable when non-null.</P>

      <P>Equal to <CODE><A HREF="~JD~getConditional(s,s,s,s,s)~EJD~">getConditional</A>(s_prefix, s_value, s_postfix, s_whenValueNull, "")</CODE></P>
    **/
   public String getConditional(String s_prefix, String s_value, String s_postfix, String s_whenValueNull)  {
      return getConditional(s_prefix, s_value, s_postfix, s_whenValueNull, sES);
   }

   /**
      <P>Get the string value (plus prefix and postfix) only when not-null.  When null, get the alternative ("when-null") value.</P>

      @param  s_prefix  The string to put before the non-null value.  When null, no prefix is used (which is the same behavior as when this is equal to empty string).
      @param  s_value  The value.  When null, all parameters except s_whenValueNull are ignored.  When not null, (only) s_whenValueNull is ignored.
      @param  s_prefix  The string to put after the non-null value.  When null, no postfix is used (which is the same behavior as when this is equal to empty string).
      @param  s_whenValueNull  When s_value is null, then this is the <I>entire</I> text that is returned (no prefix or postfix).  When s_value is not null, this parameter is ignored.  May be null or any number of characters in length.  To emphasize, if both an s_value are null, then 'null' is returned.
      @param  s_whenValueEmpty  When s_value is zero characters in length, then this is the <I>entire</I> text that is returned (no prefix or postfix).  When s_value is not empty, this parameter is ignored.  May be null or any number of characters in length.  This behaves in the same manner as s_whenValueNull, when s_value is empty.

      @return  <B>s_whenValueNull</B>  If s_value is null.
      <BR><CODE>s_prefix + s_value + s_postfix</CODE>  If s_value is not null.  Note that if s_prefix is null, it is omitted.  If s_postfix is null, it is omitted.
    **/
   public String getConditional(String s_prefix, String s_value, String s_postfix, String s_whenValueNull, String s_whenValueEmpty)  {
      if(s_value == null)  {
         return s_whenValueNull;
      }

      if(s_value.length() < 1)  {
         return s_whenValueEmpty;
      }

      StringBuffer sb = new StringBuffer(s_value);

      if(s_prefix != null)  {
         //There is a prefix, and it goes first, before
         //everything else.
         sb.insert(0, s_prefix);
      }

      if(s_postfix != null)  {
         //There is a prefix, and it goes last, after
         //everything else.
         sb.append(s_postfix);
      }

      return sb.toString();
   }



   /**
      <P>Get a boolean from the value in the string.</P>

      @param  s_potentialBoolean  The string containing a boolean value.
      @return  <B>true</B>  If s_potentialBoolean equals "true" (case sensitive).
      <BR><B>false</B>  If s_potentialBoolean equals "false" (case sensitive).
      @exception  AssertException  If s_potentialBoolean is null, or contains a value other than "true" or "false".
    **/
   public boolean getBoolean(String s_potentialBoolean)  {
      throwAXIfNull(s_potentialBoolean, "s_potentialBoolean", "getBoolean");

      if(s_potentialBoolean.equals("true"))  {
         return true;
      }

      if(s_potentialBoolean.equals("false"))  {
         return false;
      }

      throwAX("getBoolean:  s_potentialBoolean is not null, but is also not equal to 'true' or 'false'.  Currently '" + s_potentialBoolean + "'");

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

   /**
      <P>Get an int from the value in the string.</P>

      <P>Equal to <CODE><A HREF="~JD~getInt(s,b)~EJD~">getInt</A>(s_potentialInt, false)</CODE></P>
    **/
   public int getInt(String s_potentialInt)  {
      return getInt(s_potentialInt, false);
   }

   /**
      <P>Get an int from the value in the string.</P>

      <P><I>TODO:  A critical difference between this and <A HREF="~JD~isNumber(s,b)~EJD~">isNumber</A>:  This function uses <CODE>Integer.valueOf</CODE>, and therefore a huge number (like 8374018734087120847104387208472784) is considered invalid according to this function, but valid according to isNumber (would return true).</I></P>

      @param  s_potentialInt  The string containing an int value.
      @param  b_nfxInsteadOfax  If the s_potentialInt is null, or contains an illegal value, according to <CODE><A HREF="~JD~I~EJD~">Integer</A>.<A HREF="~JD~I#valueOf(s)~EJD~">valueOf</A>(s_potentialInt).<A HREF="~JD~I~EJD~#intValue()">intValue</A>()</CODE>
    **/
   public int getInt(String s_potentialInt, boolean b_nfxInsteadOfax)  {
      throwAXIfNull(s_potentialInt, "s_potentialInt", "getInt");

      try  {
         return Integer.valueOf(s_potentialInt).intValue();
      }  catch(NumberFormatException nfx)  {

         String sMsg = "ERROR in UtilString.getInt:  s_potentialInt ('" + s_potentialInt + "') is not null, but is also not a valid int according Integer.valueOf('" + s_potentialInt + "').intValue().";

         if(b_nfxInsteadOfax)  {
            throw new NumberFormatException(sMsg);
         }

         //They want ax and not nfx
         throwAX(sMsg);
      }

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

   /**
      <P>Get an long from the value in the string.</P>

      <P>Equal to <CODE><A HREF="~JD~getLong(s,b)~EJD~">getLong</A>(s_potentialLong, false)</CODE></P>
    **/
   public long getLong(String s_potentialLong)  {
      return getLong(s_potentialLong, false);
   }

   /**
      <P>Get an long from the value in the string.</P>

      @param  s_potentialLong  The string containing an long value.
      @param  b_nfxInsteadOfax  If the s_potentialLong is null, or contains an illegal value, according to <CODE><A HREF="~JD~L~EJD~">Long</A>.<A HREF="~JD~I#valueOf(s)~EJD~">valueOf</A>(s_potentialLong).<A HREF="~JD~I~EJD~#longValue()">longValue</A>()</CODE>
    **/
   public long getLong(String s_potentialLong, boolean b_nfxInsteadOfax)  {
      throwAXIfNull(s_potentialLong, "s_potentialLong", "getLong");

      try  {
         return Long.valueOf(s_potentialLong).longValue();
      }  catch(NumberFormatException nfx)  {

         String sMsg = "ERROR in UtilString.getLong:  s_potentialLong ('" + s_potentialLong + "') is not null, but is also not a valid long according Long.valueOf('" + s_potentialLong + "').longValue().";

         if(b_nfxInsteadOfax)  {
            throw new NumberFormatException(sMsg);
         }

         //They want ax and not nfx
         throwAX(sMsg);
      }

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

   /**
      <P>Get a Date object from the potential date string and date format.</P>

      @return  <CODE><A HREF="~JD~getDate(s,sdf)~EJD~">getDate</A>(s_potentialDate, new <A HREF="~JD~sdf#sdf(s)~EJD~">SimpleDateFormat</A>(s_dateFormat))</CODE>
    **/
   public Date getDate(String s_potentialDate, String s_dateFormat)  {
      try  {
         getDate(s_potentialDate, new SimpleDateFormat(s_dateFormat));
      }  catch(NullPointerException npx)  {
         throwAX("getDate:  s_dateFormat is null.");
      }  catch(IllegalArgumentException iax)  {
         throwAX("getDate:  s_dateFormat ('" + s_dateFormat + "') is illegal according to SimpleDateFormat.constructor:  " + iax.toString());
      }

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

   /**
      <P>Get a Date object from the potential date string and SimpleDateFormat.</P>

      @param  s_potentialDate  String containing a date that conforms to s_dateFormat.  May not be null.
      @param  simple_dateFormat  The SimpleDateFormat that s_potentialDate must conform to.  May not be null.
      @return  <CODE>simple_dateFormat.<A HREF="~JD~dtfmt#parse(s)~EJD~">parse</A>(s_potentialDate)</CODE>
    **/
   public Date getDate(String s_potentialDate, SimpleDateFormat simple_dateFormat)  {
      try  {
         return simple_dateFormat.parse(s_potentialDate);
      }  catch(ParseException px)  {
         throwAX("getDate:  s_potentialDate ('" + s_potentialDate + "') does not conform to simple_dateFormat [" + simple_dateFormat.toString() + "]:  " + px.toString());
      }

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


   /**
      <P>Is the string a legally formatted email address?</P>

      @param  s_potentialEmail  The string to analyze.
      @return  <B>false</B>  If any of the following conditions are met:<UL>
         <LI>s_potentialEmail is null or zero characters in length.</LI>
         <LI>There are zero @.</LI>
         <LI>There are more than one @.</LI>
         <LI>@ is the first or last character.</LI>
         <LI>. is the first or last character.</LI>
         <LI>There is one or more spaces (" "), commas (","), escape slashes ("\\\\"), or slashes ("/")</LI>
         <LI>Contains a period immediately followed by an @, or vice-versa.</LI>
         <LI>Contains two periods in a row.</LI>
         <LI>The <I>last</I> period is found before the @.</LI>
      </UL>
      <BR><B>true</B>  If otherwise.
    **/
   public boolean isEmail(String s_potentialEmail)  {
      if(s_potentialEmail == null  ||  s_potentialEmail.length() < 1)  {
         return false;
      }

      int iAt = s_potentialEmail.indexOf("@");
      if(iAt == -1  ||  iAt == 0  ||  iAt == s_potentialEmail.length() - 1  ||
            iAt!= s_potentialEmail.lastIndexOf("@"))  {
         //It does not have any '@', contains more than one '@', or
         //starts or ends with '@'.
         return false;
      }

      if(s_potentialEmail.startsWith(".")  ||
         	s_potentialEmail.endsWith("."))  {
         return false;
      }

      if(s_potentialEmail.indexOf(" ") != -1  ||
         	s_potentialEmail.indexOf(",") != -1  ||
         	s_potentialEmail.indexOf("\\") != -1  ||
         	s_potentialEmail.indexOf("/") != -1)  {
         return false;
      }

      if(s_potentialEmail.indexOf(".@") != -1  ||
         	s_potentialEmail.indexOf("@.") != -1  ||
         	s_potentialEmail.indexOf("..") != -1)  {
         return false;
      }

      if(s_potentialEmail.lastIndexOf(".") < iAt)  {
         //The *last* period is found before the at sign.
         return false;
      }

      return true;
   }


   /**
      <P>Does the string contain a valid boolean value?.  Note that the behavior of this function is distinct from java.lang.<A HREF="~JD~B~EJD~">Boolean</A>.<A HREF="~JD~B#valueOf(s)~EJD~">valueOf</A>.</P>

      @param  s_potentialBoolean  The string to analyze.
      @return  <B>true</B>  If s_potentialBoolean equals "true" or "false".
      <BR><B>false</B>  If s_potentialBoolean is null, or does not equal "true" or "false".
    **/
   public boolean isBoolean(String s_potentialBoolean)  {
      if(s_potentialBoolean == null  ||  s_potentialBoolean.length() < 1)  {
         //The string is either null, or empty string.  Either way,
         //it ain't a boolean.
         return false;
      }

      //If it's equal to "true" or equal to "false", return true.
      //Otherwise, return false.
      return (s_potentialBoolean.equals("true")  ||
              s_potentialBoolean.equals("false"));
   }



   /**
      <P>Is the string a valid integer?.  An integer is a number without a decimal point.</P>

      <P>Equal to <CODE><A HREF="~JD~isNumber(s,b)~EJD~">isNumber</A>(s_potentialDigit, false)</CODE></P>
    **/
   public boolean isInteger(String s_potentialInteger)  {
      return isNumber(s_potentialInteger, false);
   }

   /**
      <P>Is the string a valid decimal number?.  A decimal number may or may not have a decimal point.</P>

      <P>Equal to <CODE><A HREF="~JD~isNumber(s,b)~EJD~">isNumber</A>(s_potentialDigit, true)</CODE></P>
    **/
   public boolean isDecimal(String s_potentialDigit)  {
      return isNumber(s_potentialDigit, true);
   }

   /**
      <P>Is the string a valid digit?</P>

      <P>A digit is defined with the following rules:<UL>
         <LI>s_potentialDigit is not null, and at least one character in length.</LI>
         <LI>The first character may be a dash (negative sign), as long as the length of the string is more than one.</LI>
         <LI>There may be exactly one decimal point in the digit ("."), as long as it is not the last character in the string.</LI>
         <LI>All characters aside from the (potential) dash and decimal point must be a digit (0..9).</LI>
      </UL></P>

      <P><I>TODO:  A critical difference between this and <A HREF="~JD~getInt(s,b)~EJD~">getInt</A>:  This function does string analysis, and therefore a huge number (8374018734087120847104387208472784) is considered valid according to this function, while invalid according to getInt (would throw an exception)</I></P>

      @param  s_potentialDigit  The string to analyze.
      @param  b_decimalAllowed  If true, then the digit is allowed to have (exactly one) decimal point.  If false, the digit is not allowed to have a decimal point, and therefore must be an integer.

      @return <B>true</B>  If the string conforms to the rules.
      <BR><B>false</B>  If the string breaks any of the rules.
    **/
   public boolean isNumber(String s_potentialDigit, boolean b_decimalAllowed)  {
      if(s_potentialDigit == null  ||  s_potentialDigit.length() < 1)  {
         //The string is either null, or empty string.  Either way,
         //it ain't a digit.
         return false;
      }

      int iPosition = 0;

      //The decimal point has not yet been found.
      boolean bDecimalFound = false;

      //Get the first character in this string
      char c = s_potentialDigit.charAt(0);

      //Only the first character is allowed to be a
      //dash, a negative symbol...
      if(c == '-')  {
         //...and it is.

         if(s_potentialDigit.length() == 1)  {
            //There is only one character in this string.
            //The first and last character in this string is
            //a dash.  This is not a valid digit.
            return false;

         }  else  {
            //Increment the position to the second character.
            //We know the first character is a dash, so it's
            //definitely not a decimal or digit.
            iPosition = 1;
         }
      }

      //If the first character is not a dash, then i equals 0.
      //Otherwise, the first character *is* a dash, and i equals 1,
      //AND the length of the string is greater than 1 (there are
      //at least two characters in the string).

      for(; iPosition < s_potentialDigit.length(); iPosition++)  {
         c = s_potentialDigit.charAt(iPosition);

         if(c == '.')  {
            if(!b_decimalAllowed)  {
               return false;
            }

            if(bDecimalFound)  {
               //A decimal point was already found before this character.
               //There cannot be more than one decimal point in a digit.
               return false;

            }  else if(s_potentialDigit.length() == (iPosition + 1))  {
               //This is the first decimal point found, but it's also
               //the last character in the string.  A decimal poboolean belongs
               //before the last character in the string.
               return false;

            }  else  {
               //This is the first decimal point found, but is
               //also the last character in the string.
               bDecimalFound = true;
            }

         }  else if(!Character.isDigit(c))  {
            //Not only is this character not a decimal or dash,
            //it's not even a number.
            return false;
         }

         //So far, the string is a valid digit...
      }

      //This string is definitely a valid digit.
      return true;
   }

   private static final String sGCI = "getContainedIdx";

   /**
      <P>If either string is contained in or equal to the other, get information describing the containment.</P>

      @return  <CODE><A HREF="~JD~utilsob#getContainedIdxs(sob,sob)~EJD~">getContainedIdx</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_x, "getContainedIdx"), getSOBS(s_y, "getContainedIdx"))</CODE>
    **/
   public final i_i_i getContainedIdxs(String s_x, String s_y)  {
      return getContainedIdxs(getSOBS(s_x, sGCI), getSOBS(s_y, sGCI));
   }

   /**
      <P>If either string is contained in (or equal to) the other, get information describing the containment.</P>

      @return  <CODE><A HREF="~JD~utilsob#getContainedIdxs(sob,sob,gcic2)~EJD~">getContainedIdx</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_x, "getContainedIdx"), getSOBS(s_y, "getContainedIdx"), gcic_two)</CODE>

      <P><I>The array is created only once, and populated in this function repeatedly.</I></P>
    **/
   public final i_i_i getContainedIdxs(String s_x, String s_y, GCICTwo gcic_two)  {
      return getContainedIdxs(getSOBS(s_x, sGCI), getSOBS(s_y, sGCI), gcic_two);
   }

   /**
      <P>If any string is contained in (or equal to) any other, get information describing the containment.</P>

      <P>Equal to <CODE><A HREF="~JD~utilsob#getContainedIdxs(sob[],gcic)~EJD~">getContainedIdxs</A>(<A HREF="~JD~getAOSOBS(s[])~EJD~">getAOSOBS</A>(a_string), (new <A HREF="~JD~gcic#gcic()~EJD~">GCIConfig</A>()))</CODE></P>
    **/
   public final i_i_i getContainedIdxs(String[] a_string)  {
      return getContainedIdxs(getAOSOBS(a_string));
   }

   /**
      <P>If any string is contained in any other, get information describing the containment.</P>

      <P>Equal to <CODE><A HREF="~JD~utilsob#getContainedIdxs(sob[],gcic)~EJD~">getContainedIdxs</A>(<A HREF="~JD~getAOSOBS(s[])~EJD~">getAOSOBS</A>(a_string), (new <A HREF="~JD~gcic#gcic()~EJD~">GCIConfig</A>()))</CODE></P>
    **/
   public final i_i_i getContainedIdxs(String[] a_string, GCIConfig gci_config)  {
      return getContainedIdxs(getAOSOBS(a_string), gci_config);
   }


   private static final String sGQL = "getQuotedLines";

   /**
      <P>Get a copy of the String where each line is quoted.</P>

      @return  <CODE><A HREF="~JD~utilsob#getQuotedLines(sob)~EJD~">getQuotedLines</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + "getQuotedLines")).<A HREF="~JD~ss~EJD~#toString()">toString</A>()</CODE>
    **/
   public final String getQuotedLines(String s_tr)  {
      return getQuotedLines(getSOBSB(s_tr, sUS + sGQL)).toString();
   }

   /**
      <P>Get a copy of the String where each line is quoted.</P>

      @return  <CODE><A HREF="~JD~utilsob#getQuotedLines(sob,s)~EJD~">getQuotedLines</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + "getQuotedLines"), s_quote).<A HREF="~JD~ss~EJD~#toString()">toString</A>()</CODE>
    **/
   public final String getQuotedLines(String s_tr, String s_quote)  {
      return getQuotedLines(getSOBSB(s_tr, sUS + sGQL), s_quote).toString();
   }

   /**
      <P>Get a copy of the String where each line is quoted.</P>

      @return  <CODE><A HREF="~JD~utilsob#getQuotedLines(sob,s,s)~EJD~">getQuotedLines</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + "getQuotedLines"), s_quoteStart, s_quoteEnd).<A HREF="~JD~ss~EJD~#toString()">toString</A>()</CODE>
    **/
   public final String getQuotedLines(String s_tr, String s_quoteStart, String s_quoteEnd)  {
      return getQuotedLines(getSOBSB(s_tr, sUS + sGQL), s_quoteStart, s_quoteEnd).toString();
   }


   /**
      <P>Get a copy of the String where each line is quoted.</P>

      @return  <CODE><A HREF="~JD~utilsob#getQuotedLines(sob,s,s)~EJD~">getQuotedLines</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + "getQuotedLines"), s_quoteStart, s_quoteEnd, s_lineSep).<A HREF="~JD~ss~EJD~#toString()">toString</A>()</CODE>
    **/
   public final String getQuotedLines(String s_tr, String s_quoteStart, String s_quoteEnd, String s_lineSep)  {
      return getQuotedLines(getSOBSB(s_tr, sUS + sGQL), s_quoteStart, s_quoteEnd, s_lineSep).toString();
   }


   /**
      <P>Is the value of the String a valid hexidecimal number?</P>

      @return  <CODE><A HREF="~JD~utilsob#isHexidecimal(sob)~EJD~">isHexidecimal</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_potentialHex, "s_potentialHex", <A HREF="#sUS">sUS</A> + ".isHexidecimal"))</CODE>
    **/
   public boolean isHexidecimal(String s_potentialHex)  {
      return isHexidecimal(getSOBS(s_potentialHex, "s_potentialHex", sUS + ".isHexidecimal"));
   }

   /**
      <P>Does the String contain only whitespace?</P>

      @param  s_potentialTabSpace  The String analyzed, to see if it contains only whitespace characters.  May not be null or zero characters in length.
      @return  <CODE><A HREF="~JD~utilsob#isTabSpace(sob)~EJD~">isTabSpace</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_potentialTabSpace, "s_potentialTabSpace", <A HREF="#sUS">sUS</A> + ".isTabSpace"))</CODE></P>
    **/
   public boolean isTabSpace(String s_potentialTabSpace)  {
      return isTabSpace(getSOBS(s_potentialTabSpace, "s_potentialTabSpace", "isTabSpace"));
   }

   /**
      <P>Does the String <I>not</I> contain any whitespace characters?</P>

      @param  s_tr  The String analyzed, to see if it contains only non-whitespace characters.  May not be null or zero characters in length.
      @return  <CODE><A HREF="~JD~utilsob#hasNoTabSpace(sob)~EJD~">hasNoTabSpace</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasNoTabSpace"))</CODE></P>
    **/
   public boolean hasNoTabSpace(String s_tr)  {
      return hasNoTabSpace(getSOBS(s_tr, sUS + "hasNoTabSpace"));
   }

   /**
      <P>Get a copy of the String, after appending a duplicated string onto it.</P>

      @return  <CODE><A HREF="~JD~utilsob#dupAppend(sob,s,i)~EJD~">dupAppend</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + ".getDupAppend"), s_toDuplicate, i_dupCount).<A HREF="~JD~ss~EJD~#toString()">toString</A>()</CODE>
    **/
   public final String getDupAppend(String s_tr, String s_toDuplicate, int i_dupCount)  {
      return getDupAppend(getSOBSB(s_tr, sUS + "getDupAppend"), s_toDuplicate, i_dupCount).toString();
   }


   /**
      <P>Get the priovided string, duplicated.</P>

      @return  <CODE><A HREF="~JD~getDupAppend(s,s,i)~EJD~">getDupAppend</A>("", s_tr, i_dupCount)</CODE>
    **/
   public String getDuped(String s_tr, int i_dupCount)  {
      return getDupAppend(sES, s_tr, i_dupCount);
   }

   /**
      <P>Get the array index of the first non-white-space character.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOf1stNonWS(sob)~EJD~">getIdxOf1stNonWS</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".getIdxOf1stNonWS"))</CODE></P>
    **/
   public final int getIdxOf1stNonWS(String s_tr)  {
      return getIdxOf1stNonWS(getSOBS(s_tr, sUS + "getIdxOf1stNonWS"));
   }

   /**
      <P>Get the array index of the last non-white-space character.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOfLastNonWS(sob)~EJD~">getIdxOfLastNonWS</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".getIdxOfLastNonWS"))</CODE>
    **/
   public final int getIdxOfLastNonWS(String s_tr)  {
      return getIdxOfLastNonWS(getSOBS(s_tr, sUS + "getIdxOfLastNonWS"));
   }

   private static final String sGIO1CNIA = "getIdxOf1stCharNIA";

   /**
      <P>Get the array index of the first character that is not a member of the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOf1stCharNIA(sob,c[])~EJD~">getIdxOf1stCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOf1stCharNIA"), a_char)</CODE>
    **/
   public final int getIdxOf1stCharNIA(String s_tr, char[] a_char)  {
      return getIdxOf1stCharNIA(getSOBS(s_tr, sUS + sGIO1CNIA), a_char);
   }

   /**
      <P>Get the array index of the first character that is not a member of the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOf1stCharNIA(sob,c[],i,i,b)~EJD~">getIdxOf1stCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOf1stCharNIA"), a_char, 0, <A HREF="~JD~sob~EJD~#length()">s_tr</A>.<A HREF="~JD~s~EJD~#length()">length</A>(), b_validateAOC)</CODE>
    **/
   public final int getIdxOf1stCharNIA(String s_tr, char[] a_char, boolean b_validateAOC)  {
      try  {
         return getIdxOf1stCharNIA(getSOBS(s_tr, sUS + sGIO1CNIA), a_char, 0, s_tr.length(), b_validateAOC);
      }  catch(NullPointerException npx)  {
         throwAX("getIdxOf1stCharNIA:  s_tr is null.");
      }

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

   /**
      <P>Get the array index of the first character that is not a member of the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOf1stCharNIA(sob,c[],i,i)~EJD~">getIdxOf1stCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOf1stCharNIA"), a_char, i_idxStart, i_idxAfterEnd)</CODE>
    **/
   public final int getIdxOf1stCharNIA(String s_tr, char[] a_char, int i_idxStart, int i_idxAfterEnd)  {
      return getIdxOf1stCharNIA(getSOBS(s_tr, sUS + sGIO1CNIA), a_char, i_idxStart, i_idxAfterEnd);
   }

   /**
      <P>Get the array index of the first character that does not exist in the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOf1stCharNIA(sob,c[],i,i,b)~EJD~">getIdxOf1stCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOf1stCharNIA"), a_char, i_idxStart, i_idxAfterEnd, b_validateAOC)</CODE>
    **/
   public final int getIdxOf1stCharNIA(String s_tr, char[] a_char, int i_idxStart, int i_idxAfterEnd, boolean b_validateAOC)  {
      return getIdxOf1stCharNIA(getSOBS(s_tr, sUS + sGIO1CNIA), a_char, i_idxStart, i_idxAfterEnd, b_validateAOC);
   }


   private static final String sGIOLCNIA = "getIdxOfLastCharNIA";

   /**
      <P>Get the array index of the last character that is not a member of the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOfLastCharNIA(sob,c[])~EJD~">getIdxOfLastCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOfLastCharNIA"), a_char)</CODE>
    **/
   public final int getIdxOfLastCharNIA(String s_tr, char[] a_char)  {
      return getIdxOfLastCharNIA(getSOBS(s_tr, sUS + sGIOLCNIA), a_char);
   }

   /**
      <P>Get the array index of the last character that is not a member of the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOfLastCharNIA(sob,c[],i,i,b)~EJD~">getIdxOfLastCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOfLastCharNIA"), a_char, 0, <A HREF="~JD~s~EJD~#length()">length</A>(), b_validateAOC)</CODE>
    **/
   public final int getIdxOfLastCharNIA(String s_tr, char[] a_char, boolean b_validateAOC)  {
      try  {
         return getIdxOfLastCharNIA(getSOBS(s_tr, sUS + sGIOLCNIA), a_char, 0, s_tr.length(), b_validateAOC);
      }  catch(NullPointerException npx)  {
         throwAX("getIdxOf1stCharNIA:  s_tr is null.");
      }

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

   /**
      <P>Get the array index of the last character that is not a member of the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOfLastCharNIA(sob,c[],i,i)~EJD~">getIdxOfLastCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOfLastCharNIA"), a_char, i_idxStart, i_idxAfterEnd)</CODE>
    **/
   public final int getIdxOfLastCharNIA(String s_tr, char[] a_char, int i_idxStart, int i_idxAfterEnd)  {
      return getIdxOfLastCharNIA(getSOBS(s_tr, sUS + sGIOLCNIA), a_char, i_idxStart, i_idxAfterEnd);
   }

   /**
      <P>Get the array index of the last character that does not exist in the array.</P>

      @return  <CODE><A HREF="~JD~utilsob#getIdxOfLastCharNIA(sob,c[],i,i,b)~EJD~">getIdxOfLastCharNIA</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + "getIdxOfLastCharNIA"), a_char, i_idxStart, i_idxAfterEnd, b_validateAOC)</CODE>
    **/
   public final int getIdxOfLastCharNIA(String s_tr, char[] a_char, int i_idxStart, int i_idxAfterEnd, boolean b_validateAOC)  {
      return getIdxOfLastCharNIA(getSOBS(s_tr, sUS + sGIOLCNIA), a_char, i_idxStart, i_idxAfterEnd, b_validateAOC);
   }


   /**
      <P>Get a copy of the String, where the contents' invisible characters are made visible.</P>

      @return  <CODE><A HREF="~JD~utilsob#getVisible(sob)~EJD~">getVisible</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + ".getVisible").<A HREF="~JD~ss~EJD~#toString()">toString</A>()</CODE>
    **/
   public final String getVisible(String s_tr)  {
      return getVisible(getSOBSB(s_tr, sUS + "getVisible")).toString();
   }

   /**
      <P>Does the string contain only letters, digits and underscores?</P>

      @return <CODE><A HREF="~JD~utilsob#isLetterDigitUnderscore(sob)~EJD~">isLetterDigitUnderscore</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isLetterDigitUnderscore"))</CODE>
    **/
   public boolean isLetterDigitUnderscore(String s_tr)  {
      return isLetterDigitUnderscore(getSOBS(s_tr, sUS + "isLetterDigitUnderscore"));
   }


   /**
      <P>Does the string contain only letters and (other provided) legal characters?</P>

      @return <CODE><A HREF="~JD~utilsob#hasLettersOrInAOC(sob,b,c[])~EJD~">hasLettersOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasLettersOrInAOC"), b_digitsOkOpt, ac_legal)</CODE>
    **/
   public boolean hasLettersOrInAOC(String s_tr, boolean b_digitsOkOpt, char[] ac_legal)  {
      return hasLettersOrInAOC(getSOBS(s_tr, sUS + "hasLettersOrInAOC"), b_digitsOkOpt, ac_legal);
   }

   /**
      <P>Does the string contain only letters and (other provided) legal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#hasLettersOrInAOC(sob,b,c[],b)~EJD~">hasLettersOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasLettersOrInAOC"), b_digitsOkOpt, ac_legal, b_validateAOC)</CODE>
    **/
   public boolean hasLettersOrInAOC(String s_tr, boolean b_digitsOkOpt, char[] ac_legal, boolean b_validateAOC)  {
      return hasLettersOrInAOC(getSOBS(s_tr, sUS + "hasLettersOrInAOC"), b_digitsOkOpt, ac_legal, b_validateAOC);
   }

   /**
      <P>Does the string contain only digits and (other provided) legal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#hasDigitsOrInAOC(sob,b,c[])~EJD~">hasDigitsOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasDigitsOrInAOC"), b_lettersOkOpt, ac_legal)</CODE>
    **/
   public boolean hasDigitsOrInAOC(String s_tr, boolean b_lettersOkOpt, char[] ac_legal)  {
      return hasDigitsOrInAOC(getSOBS(s_tr, sUS + "hasDigitsOrInAOC"), b_lettersOkOpt, ac_legal);
   }
   /**
      <P>Does the string contain only digits and (other provided) legal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#hasDigitsOrInAOC(sob,b,c[],b)~EJD~">hasDigitsOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasDigitsOrInAOC"), b_lettersOkOpt, ac_legal, b_validateAOC)</CODE>
    **/
   public boolean hasDigitsOrInAOC(String s_tr, boolean b_lettersOkOpt, char[] ac_legal, boolean b_validateAOC)  {
      return hasDigitsOrInAOC(getSOBS(s_tr, sUS + "hasDigitsOrInAOC"), b_lettersOkOpt, ac_legal, b_validateAOC);
   }

   /**
      <P>Does the string contain only letters, digits and (other provided) legal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#hasLDOrInAOC(sob,c[])~EJD~">hasLDOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasLDOrInAOC"), ac_legal)</CODE>
    **/
   public boolean hasLDOrInAOC(String s_tr, char[] ac_legal)  {
      return hasLDOrInAOC(getSOBS(s_tr, sUS + "hasLDOrInAOC"), ac_legal);
   }
   /**
      <P>Does the string contain only letters, digits and (other provided) legal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#hasLDOrInAOC(sob,c[],b)~EJD~">hasLDOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasLDOrInAOC"), ac_legal, b_validateAOC)</CODE>
    **/
   public boolean hasLDOrInAOC(String s_tr, char[] ac_legal, boolean b_validateAOC)  {
      return hasLDOrInAOC(getSOBS(s_tr, sUS + "hasLDOrInAOC"), ac_legal, b_validateAOC);
   }

   /**
      <P>Does the string contain only legal characters?</P>

      @return <CODE><A HREF="~JD~utilsob#hasLegalChars(sob,c[])~EJD~">hasLegalChars</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasLegalChars"), ac_legal)</CODE>
    **/
   public boolean hasLegalChars(String s_tr, char[] ac_legal)  {
      return hasLegalChars(getSOBS(s_tr, sUS + "hasLegalChars"), ac_legal);
   }


   /**
      <P>Does the string contain only legal characters?</P>

      @return <CODE><A HREF="~JD~utilsob#isLegal(sob,b,b,c[],b)~EJD~">isLegal</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasLegalChars"), false, false, ac_legal, b_validateAOC)</CODE>
    **/
   public boolean hasLegalChars(String s_tr, char[] ac_legal, boolean b_validateAOC)  {
      return isLegal(getSOBS(s_tr, sUS + "hasLegalChars"), false, false, ac_legal, b_validateAOC);
   }

   /**
      <P>Does the string contain only legal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isLegal(sob,b,b,c[])~EJD~">isLegal</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isLegal"), b_lettersOkOpt, b_digitsOkOpt, ac_legal)</CODE>
    **/
   public boolean isLegal(String s_tr, boolean b_lettersOkOpt, boolean b_digitsOkOpt, char[] ac_legal)  {
      return isLegal(getSOBS(s_tr, sUS + "isLegal"), b_lettersOkOpt, b_digitsOkOpt, ac_legal);
   }

   /**
      <P>Does the string contain only legal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isLegal(sob,b,b,c[],b)~EJD~">isLegal</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isLegal"), b_lettersOkOpt, b_digitsOkOpt, ac_legal, b_validateAOC)</CODE>
    **/
   public boolean isLegal(String s_tr, boolean b_lettersOkOpt, boolean b_digitsOkOpt, char[] ac_legal, boolean b_validateAOC)  {
      return isLegal(getSOBS(s_tr, sUS + "isLegal"), b_lettersOkOpt, b_digitsOkOpt, ac_legal, b_validateAOC);
   }



   /**
      <P>Does the string <I>not</I> contain any letters or (other provided) illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotLettersOrInAOC(sob,b,c[])~EJD~">isNotLettersOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotLettersOrInAOC"), b_digitsBadOpt, ac_legal)</CODE>
    **/
   public boolean isNotLettersOrInAOC(String s_tr, boolean b_digitsBadOpt, char[] ac_legal)  {
      return isNotLettersOrInAOC(getSOBS(s_tr, sUS + "isNotLettersOrInAOC"), b_digitsBadOpt, ac_legal);
   }
   /**
      <P>Does the string <I>not</I> contain any letters or (other provided) illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotLettersOrInAOC(sob,b,c[],b)~EJD~">isNotLettersOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotLettersOrInAOC"), b_digitsBadOpt, ac_legal, b_validateAOC)</CODE>
    **/
   public boolean isNotLettersOrInAOC(String s_tr, boolean b_digitsBadOpt, char[] ac_legal, boolean b_validateAOC)  {
      return isNotLettersOrInAOC(getSOBS(s_tr, sUS + "isNotLettersOrInAOC"), b_digitsBadOpt, ac_legal, b_validateAOC);
   }

   /**
      <P>Does the string <I>not</I> contain any digits or (other provided) illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotDigitsOrInAOC(sob,b,c[])~EJD~">isNotDigitsOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotDigitsOrInAOC"), b_digitsBadOpt, ac_legal)</CODE>
    **/
   public boolean isNotDigitsOrInAOC(String s_tr, boolean b_lettersBadOpt, char[] ac_legal)  {
      return isNotDigitsOrInAOC(getSOBS(s_tr, sUS + "isNotDigitsOrInAOC"), b_lettersBadOpt, ac_legal);
   }
   /**
      <P>Does the string <I>not</I> contain any digits or (other provided) illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotDigitsOrInAOC(sob,b,c[],b)~EJD~">isNotDigitsOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotDigitsOrInAOC"), b_lettersBadOpt, ac_legal, b_validateAOC)</CODE>
    **/
   public boolean isNotDigitsOrInAOC(String s_tr, boolean b_lettersBadOpt, char[] ac_legal, boolean b_validateAOC)  {
      return isNotDigitsOrInAOC(getSOBS(s_tr, sUS + "isNotDigitsOrInAOC"), b_lettersBadOpt, ac_legal, b_validateAOC);
   }

   /**
      <P>Does the string <I>not</I> contain any letters, digits or (other provided) illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotLDOrInAOC(sob,c[])~EJD~">isNotLDOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotLDOrInAOC"), ac_legal)</CODE>
    **/
   public boolean isNotLDOrInAOC(String s_tr, char[] ac_legal)  {
      return isNotLDOrInAOC(getSOBS(s_tr, sUS + "isNotLDOrInAOC"), ac_legal);
   }
   /**
      <P>Does the string <I>not</I> contain any letters, digits or (other provided) illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotLDOrInAOC(sob,c[],b)~EJD~">isNotLDOrInAOC</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotLDOrInAOC"), ac_legal, b_validateAOC)</CODE>
    **/
   public boolean isNotLDOrInAOC(String s_tr, char[] ac_legal, boolean b_validateAOC)  {
      return isNotLDOrInAOC(getSOBS(s_tr, sUS + "isNotLDOrInAOC"), ac_legal, b_validateAOC);
   }

   /**
      <P>Does the string <I>not</I> contain any illegal characters?</P>

      @return <CODE><A HREF="~JD~utilsob#hasNoIllegalChars(sob,c[])~EJD~">hasNoIllegalChars</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasNoIllegalChars"), ac_illegal)</CODE>
    **/
   public boolean hasNoIllegalChars(String s_tr, char[] ac_illegal)  {
      return hasNoIllegalChars(getSOBS(s_tr, sUS + "hasNoIllegalChars"), ac_illegal);
   }


   /**
      <P>Does the string <I>not</I> contain any illegal characters?</P>

      @return <CODE><A HREF="~JD~utilsob#isNotIllegal(sob,b,b,c[],b)~EJD~">isNotIllegal</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".hasNoIllegalChars"), false, false, ac_illegal, b_validateAOC)</CODE>
    **/
   public boolean hasNoIllegalChars(String s_tr, char[] ac_illegal, boolean b_validateAOC)  {
      return isLegal(getSOBS(s_tr, sUS + "hasNoIllegalChars"), false, false, ac_illegal, b_validateAOC);
   }

   /**
      <P>Does the string <I>not</I> contain any illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotIllegal(sob,b,b,c[])~EJD~">isNotIllegal</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotIllegal"), b_lettersBadOpt, b_digitsBadOpt, ac_illegal)</CODE>
    **/
   public boolean isNotIllegal(String s_tr, boolean b_lettersBadOpt, boolean b_digitsBadOpt, char[] ac_illegal)  {
      return isNotIllegal(getSOBS(s_tr, sUS + "isNotIllegal"), b_lettersBadOpt, b_digitsBadOpt, ac_illegal);
   }

   /**
      <P>Does the string <I>not</I> contain any illegal characters?</P>

      @return  <CODE><A HREF="~JD~utilsob#isNotIllegal(sob,b,b,c[],b)~EJD~">isNotIllegal</A>(<A HREF="~JD~getSOBS(s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".isNotLegal"), b_lettersBadOpt, b_digitsBadOpt, ac_illegal, b_validateAOC)</CODE>
    **/
   public boolean isNotIllegal(String s_tr, boolean b_lettersBadOpt, boolean b_digitsBadOpt, char[] ac_illegal, boolean b_validateAOC)  {
      return isNotIllegal(getSOBS(s_tr, sUS + "isNotLegal"), b_lettersBadOpt, b_digitsBadOpt, ac_illegal, b_validateAOC);
   }



   /**
      <P>Create an SOBStringBuffer with the String.</P>

      @return  <B>null</B>  If s_tr is null.
      <BR><CODE>(new StringBuffer(s_tr))</CODE>  If s_tr is non-null.
    **/
   public StringBuffer getSB(String s_tr)  {
      if(s_tr == null)  {
         return null;
      }

      return (new StringBuffer(s_tr));
   }


   /**
      <P>Return a copy of the provided string, in which all occurances are replaced.</P>

      @return  <CODE><A HREF="~JD~utilsob#getReplaceAll(sob,s,s)~EJD~">getReplaceAll</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + ".getReplaceAll"), s_replaceWhat, s_replaceWith)</CODE>
    **/
   public final String getReplaceAll(String s_tr, String s_replaceWhat, String s_replaceWith)  {
      return getReplaceAll(getSOBSB(s_tr, sUS + "getReplaceAll"), s_replaceWhat, s_replaceWith).toString();
   }



   /**
      <P>Replace all occurances, with multiple passes, until no instances of the search string remain.</P>

      @return  <CODE><A HREF="~JD~utilsob#getReplaceUntil(sob,s,s)~EJD~">getReplaceUntil</A>(<A HREF="~JD~getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, <A HREF="#sUS">sUS</A> + ".getReplaceUntil"), s_replaceWhat, s_replaceWith)</CODE>
    **/
   public final String getReplaceUntil(String s_tr, String s_replaceWhat, String s_replaceWith)  {
      return getReplaceUntil(getSOBSB(s_tr, sUS + "replaceUntil"), s_replaceWhat, s_replaceWith).toString();
   }


   /**
      <P>What is the first array index containing an int <I>not</I> equal to element zero?</P>

      <P>This is useful in unit tests that tests multiple versions of the same function, when you want to ensure that each returns the same value.</P>

      @param  a_int  The int array to analyze.  May not be null or equal to zero elements in length.  Element zero may not be null.
      @return  <B>-1</B>  If a_int.length is one element in length, or every element in the array is equal.
      <BR>The <B>array index</B>  representing the first element in a_int whose value is different than element zero.  Will definitely be greater than zero.
    **/
   public final int getIdxNEToLmnt0(String[] a_string)  {
      try  {
         for(int i = 1; i < a_string.length; i++)  {
            try  {
               if(!a_string[0].equals(a_string[i]))  {
                  return i;
               }
            }  catch(NullPointerException npx)  {
               if(a_string.length == 0)  {
                  throwAX("getIdxNEToLmnt0:  a_string.length equals zero.");
               }  else  {
                  throwAX("getIdxNEToLmnt0:  a_string[0] is null.");
               }
            }
         }
      }  catch(NullPointerException npx)  {
         throwAX("getIdxNEToLmnt0:  a_string is null.");
      }

      return -1;
   }

   /**
      <P>Create an SOBString from the String.</P>

      @return  <CODE><A HREF="~JD~getSOBS(s,s,s)~EJD~">getSOBS</A>(s_tr, <A HREF="#sUS">sUS</A> + ".s_tr", s_callingClsFnc)</CODE>
    **/
   public final SOBString getSOBS(String s_tr, String s_callingClsFnc)  {
      return getSOBS(s_tr, "s_tr", s_callingClsFnc);
   }

   /**
      <P>Create an SOBString from the String.</P>

      @param  s_tr  The String to create a new SOBString with.  May not be null.
      @param  s_sDescription  The descriptive name of s_tr, for potential error messages.
      @param  s_callingClsFnc  The function from which the potential error message should appear as if it is coming from.
      @return  <CODE>(new <A HREF="~JD~ss#ss(s)~EJD~">SOBString</A>(s_tr))</CODE>
    **/
   public final SOBString getSOBS(String s_tr, String s_sDescription, String s_callingClsFnc)  {
      try  {
         return new SOBString(s_tr);
      }  catch(NullPointerException npx)  {
         throwAX(s_callingClsFnc + ":  " + s_sDescription + " is null.");
      }

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


   /**
      <P>Create an SOBStringBuffer from the String.</P>

      @return  <CODE><A HREF="~JD~getSOBSB(s,s,s)~EJD~">getSOBSB</A>(s_tr, "s_tr", s_callingClsFnc)</CODE>
    **/
   public final SOBStringBuffer getSOBSB(String s_tr, String s_callingClsFnc)  {
      return getSOBSB(s_tr, "s_tr", s_callingClsFnc);
   }
   /**
      <P>Create an SOBStringBuffer from the String.</P>

      @param  s_tr  The String to create a new SOBStringBuffer with.  May not be null.
      @param  s_sDescription  The descriptive name of s_tr, for potential error messages.
      @param  s_callingClsFnc  The function from which the potential error message should appear as if it is coming from.
      @return  <CODE>(new <A HREF="~JD~ssb#ssb(s)~EJD~">SOBStringBuffer</A>(s_tr))</CODE>
    **/
   public final SOBStringBuffer getSOBSB(String s_tr, String s_sDescription, String s_callingClsFnc)  {
      try  {
         return (new SOBStringBuffer(s_tr));
      }  catch(NullPointerException npx)  {
         throwAX(s_callingClsFnc + ":  " + s_sDescription + " is null.");
      }

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



   /**
      <P>Get an array of SOBStrings from the array of strings.</P>

      @param  a_string  The array of strings to create an array of SOBStrings from.
      @return  <B>null</B>  If a_string is null.
      <BR>An <B>array of SOBStrings</B> where each element has contents equalling that in the corresponding member of a_string.  <B>Note:</B>  If a_string[X] is null then the X-th element in the returned array is also null (it is not possible to have the contents of an SOBString equal null).
    **/
   public final SOBString[] getAOSOBS(String[] a_string)  {
      if(a_string == null)  {
         return null;
      }

      SOBString[] ass = new SOBString[a_string.length];
      for(int i = 0; i < a_string.length; i++)  {
         if(a_string[i] == null)  {
            ass[i] = null;

         }  else  {
            ass[i] = new SOBString(a_string[i].toString());
         }
      }

      return ass;
   }

   /**
      <P>Get an array of SOBStringBuffers from the array of strings.</P>

      @param  a_string  The array of strings to create an array of SOBStringBuffers from.
      @return  <B>null</B>  If a_string is null.
      <BR>An <B>array of SOBStringBuffers</B> where each element has contents equalling that in the corresponding member of a_string.  <B>Note:</B>  If a_string[X] is null then the X-th element in the returned array is also null (it is not possible to have the contents of an SOBStringBuffer equal null).
    **/
   public final SOBStringBuffer[] getAOSOBSB(String[] a_string)  {
      if(a_string == null)  {
         return null;
      }

      SOBStringBuffer[] assb = new SOBStringBuffer[a_string.length];
      for(int i = 0; i < a_string.length; i++)  {
         if(a_string[i] == null)  {
            assb[i] = null;

         }  else  {
            assb[i] = new SOBStringBuffer(a_string[i]);
         }
      }

      return assb;
   }
}