/*
   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;

/**
   <P>A StringOrBuffer that wraps around a java.lang.StringBuffer.  See <A HREF="~JD~sb~EJD~">StringBuffer</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/string/SOBStringBuffer.java">SOBStringBuffer.java</A>. &nbsp;<B>Unit tests:</B> &nbsp;See the unit tests for <A HREF="~JD~sob~EJD~">StringOrBuffer</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 SOBStringBuffer extends StringOrBuffer  {
   private final TCInvisible tci = new TCInvisible();

   private StringBuffer sb = null;

   /**
      <P>Create an SOBStringBuffer.</P>

      @param  s_tr  May not be null.
    **/
   public SOBStringBuffer(String s_tr)  {
      //This try block is  only necessary to protect against
      //new SOBStringBuffer((String)null).  Without the casting,
      //the compiler would throw an "ambiguous invocation"
      //error.
      try  {
         sb = new StringBuffer(s_tr);
      }  catch(NullPointerException npx)  {
         throwAX("constructor:  s_tr is null.");
      }
   }

   /**
      <P>Create an SOBStringBuffer.</P>

      @param  str_buffer  The StringBuffer to wrap around.  May not be null.
    **/
   public SOBStringBuffer(StringBuffer str_buffer)  {
      //throwAXIfNull is  only necessary to protect against
      //new SOBStringBuffer((StringBuffer)null).  Without the
      //casting, the compiler would throw an "ambiguous
      //invocation" error.
      throwAXIfNull(str_buffer, "str_buffer", sCNSTR);
      sb = str_buffer;
   }


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

      @return  The internally-held StringBuffer.
    **/
   public final StringBuffer getStringBuffer()  {
      return sb;
   }

   /**
      @return  <B>false</B>
    **/
   public final boolean isString()  {
      return false;
   }

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

      @return  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb~EJD~#toString()">toString</A>()</CODE>
    **/
   public final String toString()  {
      return getStringBuffer().toString();
   }


   /**
      <P>Trim whitespace from the value of this StringOrBuffer.</P>

      <P>Equal to <CODE>[<A HREF="~JD~tci~EJD~">TCInvisible</A>].<A HREF="~JD~tc~EJD~">trim</A>(<a href="#getStringBuffer()">getStringBuffer</a>())</CODE></P>
    **/
   public final void trim()  {
      tci.trim(getStringBuffer());
   }


   /**
      @return  <CODE><a href="#getStringBuffer()">getStringBuffer</a>().<A HREF="~JD~sb~EJD~#toString()">toString</A>().<A HREF="~JD~s~EJD~#trim()">trim</A>()</CODE>
    **/
   public final String getTrimmed()  {
      return getStringBuffer().toString().trim();
   }


   /**
      @return  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#charAt(i)~EJD~">charAt</A>(i_dx)</CODE>
    **/
   public final char charAt(int i_dx)  {
      return getStringBuffer().charAt(i_dx);
   }

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

      <P>First executes
         <BR>&nbsp; &nbsp;<CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#append(s)~EJD~">append</A>(s_toAppend)</CODE></P>
    **/
   public final void append(String s_toAppend)  {
      getStringBuffer().append(s_toAppend);
   }

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

      <P>Equal to  <CODE><A HREF="~JD~insert(i,s)~EJD~">insert</A>(0, s_toAppend)</CODE></P>
    **/
   public final void appendToLeft(String s_toAppend)  {
      insert(0, s_toAppend);
   }

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

      <P>Equal to  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#insert(i,s)~EJD~">insert</A>(i_dx, s_toInsert)</CODE></P>
    **/
   public final void insert(int i_dx, String s_toInsert)  {
      getStringBuffer().insert(i_dx, s_toInsert);
   }

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

      <P>First executes
         <BR>&nbsp; &nbsp;<CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#append(c)~EJD~">append</A>(c_toAppend)</CODE></P>
      @return <I>This</I> <CODE>SOBStringBuffer</CODE> (as a <CODE>StringOrBuffer</CODE>).
    **/
   public final void append(char c_toAppend)  {
      getStringBuffer().append(c_toAppend);
   }

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

      <P>Equal to  <CODE><A HREF="~JD~insert(i,c)~EJD~">insert</A>(0, c_toAppend)</CODE></P>
    **/
   public final void appendToLeft(char c_toAppend)  {
      insert(0, c_toAppend);
   }

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

      <P>Equal to  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#insert(i,c)~EJD~">insert</A>(i_dx, c_toInsert)</CODE></P>
    **/
   public final void insert(int i_dx, char c_toInsert)  {
      getStringBuffer().insert(i_dx, c_toInsert);
   }

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

      <P>Equal to  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#deleteCharAt(i)~EJD~">deleteCharAt</A>(i_dx)</CODE></P>
    **/
   public final void deleteCharAt(int i_dx)  {
      getStringBuffer().deleteCharAt(i_dx);
   }

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

      <P>Equal to  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#delete(i,i)~EJD~">delete</A>(i_idxLeft, i_idxAfterRight)</CODE></P>
    **/
   public final void delete(int i_idxLeft, int i_idxAfterRight)  {
      getStringBuffer().delete(i_idxLeft, i_idxAfterRight);
   }

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

      <P>Equal to  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#setLength(i)~EJD~">setLength</A>(i_newLength)</CODE></P>
    **/
   public final void setLength(int i_newLength)  {
      getStringBuffer().setLength(i_newLength);
   }

   /**
      @return  <CODE><A HREF="~JD~sob#isStringAt(s,i)~EJD~">isStringAt</A>(s_toSearchFor, 0)</CODE>  If s_toSearchFor.<A HREF="~JD~s~EJD~#length()">length</A> is greater than or equal to <A HREF="#length()">length</A>.
      <BR><B>false</B>  If s_toSearchFor.length is less than length.
    **/
   public final boolean startsWith(String s_toSearchFor)  {
      try  {
         if(length() < s_toSearchFor.length())  {
            return false;
         }

      }  catch(NullPointerException npx)  {
         throwAXIfNull(s_toSearchFor, "s_toSearchFor", "startsWith");
      }

      return isStringAt(s_toSearchFor, 0);
   }


   /**
      @return  <CODE><A HREF="~JD~sob#isStringAt(s,i)~EJD~">isStringAt</A>(s_toSearchFor, (<A HREF="#length()">length</A>() - s_toSearchFor.<A HREF="~JD~s~EJD~#length()">length</A>()))</CODE>  If s_toSearchFor.length is greater than or equal to <A HREF="#length()">length</A>.
      <BR><B>false</B>  If s_toSearchFor.length is less than length.
    **/
   public final boolean endsWith(String s_toSearchFor)  {
      try  {
         if(length() < s_toSearchFor.length())  {
            return false;
         }

      }  catch(NullPointerException npx)  {
         throwAXIfNull(s_toSearchFor, "s_toSearchFor", "endsWith");
      }

      return isStringAt(s_toSearchFor, (length() - s_toSearchFor.length()));
   }

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

   /**
      @return  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#substring(i)~EJD~">substring</A>(i_idxLeft)</CODE>
    **/
   public final String substring(int i_idxLeft)  {
      return getStringBuffer().substring(i_idxLeft);
   }

   /**
      @return  <CODE><A HREF="#getStringBuffer()">getStringBuffer</A>().<A HREF="~JD~sb#substring(i,i)~EJD~">substring</A>(i_idxLeft, i_idxAfterRight)</CODE>
    **/
   public final String substring(int i_idxLeft, int i_idxAfterRight)  {
      return getStringBuffer().substring(i_idxLeft, i_idxAfterRight);
   }
}