/*
   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.String.  See <A HREF="~JD~s~EJD~">String</A>.</P>

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

   private String s = null;

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

      @param  s_tr  May not be null.
    **/
   public SOBString(String s_tr)  {
      throwAXIfNull(s_tr, "s_tr", sCNSTR);
      s = s_tr;
   }

   /**
      <P>Get the String.</P>

      @return  The internally-held String.
    **/
   public final String getString()  {
      return s;
   }

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

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

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

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

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

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

      <P>Sets the internally-held string to <CODE>[internally-held string].<A HREF="~JD~s~EJD~#trim()">trim</A>()</CODE></P>
    **/
   public final void trim()  {
      s = s.trim();
   }


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

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

      <P>This executes
         <BR>&nbsp; &nbsp;<CODE>[The internal string] += s_toAppend</CODE></P>
    **/
   public final void append(String s_toAppend)  {
      s += s_toAppend;
   }

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

      <P>Equal to  <CODE>[The internal string] = [The internal string] + s_toAppend</CODE></P>
    **/
   public final void appendToLeft(String s_toAppend)  {
      s = s_toAppend + s;
   }

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

      <P>Equal to  <CODE>[The internal string] = [The internal string].<A HREF="~JD~s#substring(i,i)~EJD~">substring</A>(0, i_dx) + s_toInsert + [The internal string].substring(i_dx, s.<A HREF="~JD~s~EJD~#length()">length</A>())</CODE></P>
    **/
   public final void insert(int i_dx, String s_toInsert)  {
      s = s.substring(0, i_dx) + s_toInsert + s.substring(i_dx, s.length());
   }

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

      <P>This executes
         <BR>&nbsp; &nbsp;<CODE>[The internal string] += c_toAppend</CODE></P>
    **/
   public final void append(char c_toAppend)  {
      s += c_toAppend;
   }

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

      <P>Equal to  <CODE>[The internal string] = [The internal string] + c_toAppend</CODE></P>
    **/
   public final void appendToLeft(char c_toAppend)  {
      s = c_toAppend + s;
   }

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

      <P>Equal to  <CODE>[The internal string] = [The internal string].<A HREF="~JD~s#substring(i,i)~EJD~">substring</A>(0, i_dx) + c_toInsert + [The internal string].substring(i_dx, s.<A HREF="~JD~s~EJD~#length()">length</A>()())</CODE></P>
    **/
   public final void insert(int i_dx, char c_toInsert)  {
      s = s.substring(0, i_dx) + c_toInsert + s.substring(i_dx, s.length());
   }

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

      <P>Equal to  <CODE>[The internal string] = [The internal string].<A HREF="~JD~s#substring(i,i)~EJD~">substring</A>(0, i_dx) + [The internal string].substring((i_dx + 1), s.<A HREF="~JD~s~EJD~#length()">length</A>()())</CODE></P>
    **/
   public final void deleteCharAt(int i_dx)  {
      s = s.substring(0, i_dx) + s.substring((i_dx + 1), s.length());
   }

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

      <P>Equal to  <CODE>[The internal string] = [The internal string].<A HREF="~JD~s#substring(i,i)~EJD~">substring</A>(0, i_dx) + [The internal string].substring(i_idxAfterRight, s.<A HREF="~JD~s~EJD~#length()">length</A>()())</CODE></P>
    **/
   public final void delete(int i_idxLeft, int i_idxAfterRight)  {
      s = s.substring(0, i_idxLeft) + s.substring(i_idxAfterRight, s.length());
   }

   //OVERRIDES sob
   public final void setLength(int i_newLength)  {
      if(i_newLength >= length())  {
         StringBuffer sb = new StringBuffer(sES);
         sb.setLength(i_newLength - length());
         s += sb.toString();

      }  else  {
         s = s.substring(0, i_newLength);
      }
   }

   /**
      @return  <CODE><A HREF="#getString()">getString</A>().<A HREF="~JD~s#startsWith(s)~EJD~">startsWith</A>(s_toSearchFor)</CODE>
    **/
   public final boolean startsWith(String s_toSearchFor)  {
      return getString().startsWith(s_toSearchFor);
   }


   /**
      @return  <CODE><A HREF="#getString()">getString</A>().<A HREF="~JD~s#endsWith(s)~EJD~">endsWith</A>(s_toSearchFor)</CODE>
    **/
   public final boolean endsWith(String s_toSearchFor)  {
      return getString().endsWith(s_toSearchFor);
   }

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

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