/*
   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;
/**
   <P>Base class of "wrappers" for Strings and StringBuffers, to prevent duplication of functions used by both.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/string/StringOrBuffer.java">StringOrBuffer.java</A>. &nbsp;<B>Unit tests:</B> &nbsp;xbn_junit.<A HREF="../../../CODE/xbn_junit/string/JUTStringOrBuffer.java">JUTStringOrBuffer.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 abstract class StringOrBuffer extends XBNObject  {

   /**
      <P>Does this StringOrBuffer contain a String?</P>

      @return <B>true</B>  If this StringOrBuffer contains a string.
      <BR><B>false</B>  If it contains a StringBuffer.
    **/
   public abstract boolean isString();

   /**
      <P>Does this StringOrBuffer contain a StringBuffer?</P>

      @return <CODE>!<A HREF="#isString()">isString</A>()</CODE>
    **/
   public final boolean isStringBuffer()  {
      return !isString();
   }

   /**
      <P>How long is this StringOrBuffer?</P>

      @return  A number greater-than-or-equal-to zero, representing the number of characters.
    **/
   public abstract int length();

   /**
      <P>Are there zero characters in this StringOrBuffer?</P>

      @return  <CODE>(<A HREF="#length()">length</A>() == 0)</CODE>
    **/
   public final boolean isEmpty()  {
      return (length() == 0);
   }

   /**
      <P>Is the search string found at index 0?</P>

      @param  s_toSearchFor  The string to search at index zero for.  May not be null or zero characters in length.
      @return  <B>true</B>  If characters 0..[s_toSearchFor.length()] in the StringOrBuffer are equal to the corresponding characters in s_toSearchFor, with none missing.
      <BR><B>false</B>  If not.
    **/
   public abstract boolean startsWith(String s_toSearchFor);

   /**
      <P>Is the search string found at the end of the StringOrBuffer?</P>

      @param  s_toSearchFor  The string that should be searched for, at the end of the StringOrBuffer.  May not be null or zero characters in length.
      @return  <B>true</B>  If every character starting at (<A HREF="#length()">length</A>() - s_toSearchFor.length()) in the StringOrBuffer are equal to the corresponding characters in s_toSearchFor, with none missing.
      <BR><B>false</B>  If not.
    **/
   public abstract boolean endsWith(String s_toSearchFor);

   /**
      <P>Get the value of this StringOrBuffer, after trimming whitespace from the ends.  This does not alter the internally-held value.</P>
    **/
   public abstract String getTrimmed();

   /**
      <P>Trim whitespace from the value of this StringOrBuffer.  Unlike the java.lang.String version of this function, this does not return anything, but rather just trims the internally-held value.  See <a href="#getTrimmed()">getTrimmed</a>().</P>
    **/
   public abstract void trim();

   /**
      <P>Get the character located at the requested array index.</P>

      @param  i_dx  The array index of the character you want.  Must range 0..<CODE>[<A HREF="#length()">length</A>() - 1]</CODE>, inclusive.
    **/
   public abstract char charAt(int i_dx);

   /**
      <P>Append a string onto the end (right).</P>

      @param  s_toAppend  The string to append.
    **/
   public abstract void append(String s_toAppend);

   /**
      <P>Append a string to the start.</P>

      @param  s_toAppend  The string to append.
    **/
   public abstract void appendToLeft(String s_toAppend);

   /**
      <P>Insert a string.</P>

      @param  i_dx  The array index at which s_toInsert should be inserted.  Must range 0..<CODE>[<A HREF="#length()">length</A>() - 1]</CODE>, inclusive.
      @param  s_toInsert  The string to insert.
    **/
   public abstract void insert(int i_dx, String s_toInsert);

   /**
      <P>Append a character onto the end (right).</P>

      @param  s_toAppend  The character to insert.
    **/
   public abstract void append(char c_toAppend);

   /**
      <P>Append a character to the start.</P>

      @param  c_toAppend  The character to insert.
    **/
   public abstract void appendToLeft(char c_toAppend);

   /**
      <P>Insert a character.</P>

      @param  i_dx  The array index at which c_toInsert should be inserted.  Must range 0..<CODE>[<A HREF="#length()">length</A>() - 1]</CODE>, inclusive.
      @param  c_toInsert  The character to insert.
    **/
   public abstract void insert(int i_dx, char c_toInsert);

   /**
      <P>Delete a character.</P>

      @param  i_dx  The array index containing the character to delete.  Must range 0..<CODE>[<A HREF="#length()">length</A>() - 1]</CODE>, inclusive.
    **/
   public abstract void deleteCharAt(int i_dx);

   /**
      <P>Delete a range of characters.</P>

      @param  i_idxLeft  The array index of the left-most character to be deleted.  Must range 0..<CODE>[<A HREF="#length()">length</A>() - 1]</CODE>, inclusive, and must be less than or equal to i_idxAfterRight.
      @param  i_idxAfterRight  The array index <I>after</I> the right-most to be retrieved.  Must be between i_idxLeft and length, inclusive.
    **/
   public abstract void delete(int i_idxLeft, int i_idxAfterRight);

   /**
      <P>Set the length.</P>

      @param  i_newLength  The desired length.  If less than <A HREF="#length()">length</A>, then every character at and after (array index) i_newLength is deleted.  If greater than length, then spaces are appended to the right hand side until the new length is achieved.
    **/
   public abstract void setLength(int i_newLength);

   /**
      <P>Get a range of characters starting at the requested index.</P>

      <P>This returns the same thing as <CODE><A HREF="~JD~substring(i,i)~EJD~">substring</A>(i_idxLeft, (<A HREF="#length()">length</A>() - 1))</CODE></P>

      @param  i_idxLeft  The array index of the left-most character to be retrieved.  Must range 0..<CODE>[length() - 1]</CODE>, inclusive, and must be less than or equal to i_idxAfterRight.
    **/
   public abstract String substring(int i_idxLeft);

   /**
      <P>Get a range of characters.</P>

      <P>See <A HREF="~JD~substring(i)~EJD~">substring</A>.</P>

      @param  i_idxLeft  The array index of the left-most character to be retrieved.  Must range 0..<CODE>[<A HREF="#length()">length</A>() - 1]</CODE>, inclusive, and must be less than or equal to i_idxAfterRight.
      @param  i_idxAfterRight  The array index <I>after</I> the right-most to be retrieved.  Must be between i_idxLeft and length, inclusive.
    **/
   public abstract String substring(int i_idxLeft, int i_idxAfterRight);

   /**
      <P>Delete all characters.</P>

      <P>Equal to  <CODE><A HREF="~JD~setLength(i)~EJD~">setLength</A>(0)</CODE></P>
    **/
   public final void deleteAll()  {
      setLength(0);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~indexOf(s,i)~EJD~">indexOf</A>(s_toSearchFor, 0)</CODE>
    **/
   public final int indexOf(String s_toSearchFor)  {
      return indexOf(s_toSearchFor, 0);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~indexOf(s,i,i)~EJD~">indexOf</A>(s_toSearchFor, i_idxLeft, <a href="#length()">length</a>())</CODE>
    **/
   public final int indexOf(String s_toSearchFor, int i_idxLeft)  {
      return indexOf(s_toSearchFor, i_idxLeft, length());
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~indexOf(s,i,i,b)~EJD~">indexOf</A>(s_toSearchFor, i_idxLeft, i_idxAfterRight, true)</CODE>
    **/
   public final int indexOf(String s_toSearchFor, int i_idxLeft, int i_idxAfterRight)  {
      return indexOf(s_toSearchFor, i_idxLeft, i_idxAfterRight, true);
   }

   /**
      <P>Get the array index of the left-most occurance of the search string.</P>

      @param  s_toSearchFor  The string to search for..  May not be null or zero characters in length.
      @param  i_idxLeft  The array index of the left-most (first) character to search.  Must be between 0 and (<A HREF="#length()">length</A>() - 1), inclusive.
      @param  i_idxAfterRight  The array index of the first character <I>after</I> the end of the search area.  Must be between i_idxLeft and length, inclusive.
      @param  b_bounded  If true, then the search string must be fully contained between i_idxLeft (inclusive) and i_idxAfterRight (exclusive).  If false, the search string must <I>start</I> between i_idxLeft and i_idxAfterRight, but the search string may exceed i_idxAfterRight (as long as it exists fully in the string as a whole).
      @return  A <B>number between i_idxLeft and (i_idxAfterRight - 1)</B> referring to the first character in the left-most occurance of the search string.
      <BR><B>-1</B>  If the search string is not found

      <H4>Examples</H4>

      <P>Assume the value of <I>this</I> StringOrBuffer is <B><CODE>"abcdef"</CODE></B> and <CODE>s_toSearchFor</CODE> is <B><CODE>"bcde"</CODE></B></P>

      <P><TABLE ALIGN="center" BORDER="1" CELLSPACING="0" CELLPADDING="3" WIDTH="60%" BGCOLOR="#EEEEEE"><TR ALIGN="left" VALIGN="middle">
         <TD><B><CODE>i_idxLeft</CODE></B></TD>
         <TD><B><CODE>i_idxAfterRight</CODE></B></TD>
         <TD><B><CODE>b_bounded</CODE></B></TD>
         <TD><B>RETURNED INT</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>0</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD><CODE>length()</CODE></TD>
         <TD>true</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>1</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>1</TD>
         <TD>false</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>1</TD>
         <TD>1</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>1</TD>
         <TD>1</TD>
         <TD>false</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>3</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>3</TD>
         <TD>false</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>2</TD>
         <TD><CODE>length()</CODE></TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>2</TD>
         <TD><CODE>length()</CODE></TD>
         <TD>false</TD>
         <TD><B>-1</B></TD>
      </TR></TABLE></P>
    **/
   public final int indexOf(String s_toSearchFor, int i_idxLeft, int i_idxAfterRight, boolean b_bounded)  {
      return indexOf(true, "i", s_toSearchFor, i_idxLeft, i_idxAfterRight, b_bounded);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i)~EJD~">lastIndexOf</A>(s_toSearchFor, <a href="#length()">length</a>())</CODE>
    **/
   public final int lastIndexOf(String s_toSearchFor)  {
      return lastIndexOf(s_toSearchFor, length());
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i,b)~EJD~">lastIndexOf</A>(s_toSearchFor, i_idxAfterRight, true)</CODE>
    **/
   public final int lastIndexOf(String s_toSearchFor, int i_idxAfterRight)  {
      return lastIndexOf(s_toSearchFor, i_idxAfterRight, true);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i,i,b)~EJD~">lastIndexOf</A>(s_toSearchFor, 0, i_idxAfterRight, b_bounded)</CODE>
    **/
   public final int lastIndexOf(String s_toSearchFor, int i_idxAfterRight, boolean b_bounded)  {
      return lastIndexOf(s_toSearchFor, 0, i_idxAfterRight, b_bounded);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i,i,b)~EJD~">lastIndexOf</A>(s_toSearchFor, i_idxLeft, i_idxAfterRight, true)</CODE>
    **/
   public final int lastIndexOf(String s_toSearchFor, int i_idxLeft, int i_idxAfterRight)  {
      return lastIndexOf(s_toSearchFor, i_idxLeft, i_idxAfterRight, true);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @param  s_toSearchFor  The string to search for.  May not be null or zero characters in length.
      @param  i_idxLeft  The array index of the left-most (first) character to search.  Must be between 0 and (<A HREF="#length()">length</A>() - 1), inclusive.
      @param  i_idxAfterRight  The array index of the first character <I>after</I> the end of the search area.  Must be between i_idxLeft and length, inclusive.
      @param  b_bounded  If true, then the search string must be fully contained between i_idxLeft (inclusive) and i_idxAfterRight (exclusive).  If false, the search string must <I>start</I> between i_idxLeft and i_idxAfterRight, but the search string may exceed i_idxAfterRight (as long as it exists fully in the string as a whole).  <I>Note:  The default behavior of <CODE>java.lang.<A HREF="~JD~s~EJD~">String</A>.<A HREF="~JD~s#lastIndexOf(s,i)~EJD~">lastIndexOf</A>(s,i)</CODE> is for the search to <B>not</B> be bounded (as if this were equal to false).</I>
      @return  A <B>number between i_idxLeft and (i_idxAfterRight - 1)</B> referring to the first character in the left-most occurance of the search string.
      <BR><B>-1</B>  If the search string does not exist completely between the search bounds.

      <H4>Examples</H4>

      <P>Assume the value of <I>this</I> StringOrBuffer is <B><CODE>"abcdef"</CODE></B> and <CODE>s_toSearchFor</CODE> is <B><CODE>"bcde"</CODE></B></P>

      <P><TABLE ALIGN="center" BORDER="1" CELLSPACING="0" CELLPADDING="3" WIDTH="60%" BGCOLOR="#EEEEEE"><TR ALIGN="left" VALIGN="middle">
         <TD><B><CODE>i_idxLeft</CODE></B></TD>
         <TD><B><CODE>i_idxAfterRight</CODE></B></TD>
         <TD><B><CODE>b_bounded</CODE></B></TD>
         <TD><B>RETURNED INT</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>0</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD><CODE>length()</CODE></TD>
         <TD>true</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>1</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>1</TD>
         <TD>false</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>1</TD>
         <TD>1</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>1</TD>
         <TD>1</TD>
         <TD>false</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>3</TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>0</TD>
         <TD>3</TD>
         <TD>false</TD>
         <TD><B>1</B></TD>
      </TR><TR>
         <TD>2</TD>
         <TD><CODE>length()</CODE></TD>
         <TD>true</TD>
         <TD><B>-1</B></TD>
      </TR><TR>
         <TD>2</TD>
         <TD><CODE>length()</CODE></TD>
         <TD>false</TD>
         <TD><B>-1</B></TD>
      </TR></TABLE></P>
    **/
   public final int lastIndexOf(String s_toSearchFor, int i_idxLeft, int i_idxAfterRight, boolean b_bounded)  {
      return indexOf(false, "lastI", s_toSearchFor, i_idxLeft, i_idxAfterRight, b_bounded);
   }


   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~indexOf(s)~EJD~">indexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>())</CODE>
    **/
   public final int indexOf(char c_toSearchFor)  {
      return indexOf((new Character(c_toSearchFor)).toString());
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~indexOf(s,i)~EJD~">indexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>())</CODE>
    **/
   public final int indexOf(char c_toSearchFor, int i_idxLeft)  {
      return indexOf((new Character(c_toSearchFor)).toString(), i_idxLeft);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~indexOf(s,i,i)~EJD~">indexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>(), i_idxLeft, i_idxAfterRight)</CODE>
    **/
   public final int indexOf(char c_toSearchFor, int i_idxLeft, int i_idxAfterRight)  {
      return indexOf((new Character(c_toSearchFor)).toString(), i_idxLeft, i_idxAfterRight);
   }

   /**
      <P>Get the array index of the left-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i,i)~EJD~">lastIndexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>(), i_idxLeft, i_idxAfterRight)</CODE>
    **/
   public final int indexOf(char c_toSearchFor, int i_idxLeft, int i_idxAfterRight, boolean b_bounded)  {
      return indexOf(true, "i", (new Character(c_toSearchFor)).toString(), i_idxLeft, i_idxAfterRight, b_bounded);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s)~EJD~">lastIndexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>())</CODE>
    **/
   public final int lastIndexOf(char c_toSearchFor)  {
      return lastIndexOf((new Character(c_toSearchFor)).toString());
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i)~EJD~">lastIndexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>(), i_idxAfterRight)</CODE>
    **/
   public final int lastIndexOf(char c_toSearchFor, int i_idxAfterRight)  {
      return lastIndexOf((new Character(c_toSearchFor)).toString(), i_idxAfterRight);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i,i,b)~EJD~">lastIndexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>(), i_idxAfterRight, b_bounded)</CODE>
    **/
   public final int lastIndexOf(char c_toSearchFor, int i_idxAfterRight, boolean b_bounded)  {
      return lastIndexOf((new Character(c_toSearchFor)).toString(), i_idxAfterRight, b_bounded);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i,i,b)~EJD~">lastIndexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>(), i_idxLeft, i_idxAfterRight)</CODE>
    **/
   public final int lastIndexOf(char c_toSearchFor, int i_idxLeft, int i_idxAfterRight)  {
      return lastIndexOf((new Character(c_toSearchFor)).toString(), i_idxLeft, i_idxAfterRight);
   }

   /**
      <P>Get the array index of the right-most occurance of the search string.</P>

      @return  <CODE><A HREF="~JD~lastIndexOf(s,i,i,b)~EJD~">lastIndexOf</A>((new <A HREF="~JD~C#C(c)~EJD~">Character</A>(c_toSearchFor)).<A HREF="~JD~C~EJD~#toString">toString</A>(), i_idxLeft, i_idxAfterRight)</CODE>
    **/
   public final int lastIndexOf(char c_toSearchFor, int i_idxLeft, int i_idxAfterRight, boolean b_bounded)  {
      return indexOf(false, "lastI", (new Character(c_toSearchFor)).toString(), i_idxLeft, i_idxAfterRight, b_bounded);
   }


   /**
      <P>Is the search string found at the specific array index?</P>

      @param  s_toSearchFor  What to search for.  May not be null or zero characters in length.
      @param  i_dx  The array index at which s_toSearchFor should begin.  Must be between zero and (<A HREF="#length()">length</A>() - 1), inclusive.
      @return  <B>true</B>  If s_toSearchFor, as a whole, was found at i_dx
      <BR><B>false</B>  If not.
    **/
   public final boolean isStringAt(String s_toSearchFor, int i_dx)  {
      try  {
         if(s_toSearchFor.length() < 1)  {
            throwAX("isStringAt:  s_toSearchFor is zero in length.");
         }
      }  catch(NullPointerException npx)  {
         throwAX("isStringAt:  s_toSearchFor is null.");
      }

      try  {
         if(charAt(i_dx) != s_toSearchFor.charAt(0))  {
            return false;
         }
      }  catch(IndexOutOfBoundsException ioobx)  {
         throwAX("isStringAt:  i_dx (" + i_dx + ") is invalid for this SOBStringBuffer (length being " + length() + ").");
      }

      for(int i = 1; i < s_toSearchFor.length(); i++)  {
         if(length() <= (i_dx + i)  ||
               charAt(i_dx + i) != s_toSearchFor.charAt(i))  {
            return false;
         }
      }

      //Every character starting at charAt(i_dx) is equal to
      //every character in s_toSearchFor.
      return true;
   }

   private void crashIfBadBounds(String s_funcPrefix, int i_idxLeft, int i_idxAfterRight)  {
      if(i_idxLeft < 0)  {
         throwAX(s_funcPrefix + "ndexOf:   i_idxLeft (" + i_idxLeft + ") is less than zero.");
      }

      if(i_idxAfterRight > length())  {
         throwAX(s_funcPrefix + "ndexOf:   i_idxAfterRight (" + i_idxAfterRight + ") is greater than length() (" + length() + ").");
      }

      if(i_idxLeft > i_idxAfterRight)  {
         throwAX(s_funcPrefix + "ndexOf:   i_idxLeft (" + i_idxLeft + ") is greater than or equal to i_idxAfterRight (" + i_idxAfterRight + ").");
      }
   }

   private int indexOf(boolean b_firstLast, String s_funcPrefix, String s_toSearchFor, int i_idxLeft, int i_idxAfterRight, boolean b_bounded)  {
      crashIfBadBounds(s_funcPrefix, i_idxLeft, i_idxAfterRight);
      int iRightBound = -1;

      if(b_bounded)  {
         //Bounded.
         iRightBound = i_idxAfterRight;
      }  else  {
         //Not bounded.
         iRightBound = length();
      }

      try  {
         if((iRightBound - i_idxLeft) < s_toSearchFor.length())  {
            //The search string is too large to even fit in the
            //search area.
            return -1;
         }  else  {
            //It can fit, as long as it starts somewhere between
            //i_idxLeft and...
            iRightBound = (iRightBound - s_toSearchFor.length());

            if(iRightBound > i_idxAfterRight)  {
               iRightBound = i_idxAfterRight;
            }
         }
      }  catch(NullPointerException npx)  {
         throwAX(s_funcPrefix + "ndexOf:  s_toSearchFor is null.");
      }


      int iIdx = -1;
      int iIncrement = -1;

      if(b_firstLast)  {
         //indexOf.  Go left to right.
         iIdx = i_idxLeft;
         iIncrement = 1;
      }  else  {
         //lastIndexOf.  Go right to left.
         iIdx = iRightBound;
         iIncrement = -1;
      }

      while(true)  {
         if(b_firstLast)  {
            if(iIdx > iRightBound)  {
               break;
            }
         }  else if(iIdx < i_idxLeft)  {
            break;
         }

         if(isStringAt(s_toSearchFor, iIdx))  {
            return iIdx;
         }

         //Increment if indexOf, decrement if lastIndexOf
         iIdx += iIncrement;
      }

      //The search string was not found in the search area.
      return -1;
   }
}