/*
   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.escape;
   import xbn.XBNObject;
   import xbn.AssertException;
   import xbn.string.StringOrBuffer;
   import xbn.string.UtilString;
   import xbn.string.UtilStringBuffer;

/**
   <P>Base class for escaping or unescaping characters in a string.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../../CODE/xbn/string/escape/EscapeUnescapeString.java">EscapeUnescapeString.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 EscapeUnescapeString extends XBNObject  {
   private UtilString uStr = new UtilString();
   private UtilStringBuffer uSB = new UtilStringBuffer();

   private ESConfig esc = null;

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

      @param  es_config  The configuration.  May not be null.
    **/
   public EscapeUnescapeString(ESConfig es_config)  {
      throwAXIfNull(es_config, "es_config", sCNSTR);
      esc = es_config;
   }

   /**
      <P>Create a full copy of the provided EscapeUnescapeString.</P>

      @param  escape_unescapeString  The object to copy.  May not be null.
    **/
   public EscapeUnescapeString(EscapeUnescapeString escape_unescapeString)  {
      try  {
         esc = new ESConfig(escape_unescapeString.esc);
      }  catch(AssertException ax)  {
         throwAX("constructor:  escape_unescapeString is null.  Original error:  " + ax.toString());
      }
   }

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

      @return <B>es_config</B>  Exactly as provided to the <A HREF="~JD~eus(esc)~EJD~">constructor</A>.
    **/
   public final ESConfig getESConfig()  {
      return esc;
   }

   /**
      <P>Is the character at the requested array index preceded by the escape character?</P>

      @return  <CODE><A HREF="~JD~isEscaped(sob,i)~EJD~">isEscaped</A>([<A HREF="~JD~utils~EJD~">UtilString</A>].<A HREF="~JD~utils#getSOBS(s,s)~EJD~">getSOBSB</A>(s_tr, "isEscaped"), i_dx)</CODE>
    **/
   public final boolean isEscaped(String s_tr, int i_dx)  {
      return isEscaped(uStr.getSOBS(s_tr, "isEscaped"), i_dx);
   }


   /**
      <P>Is the character at the requested array index preceded by the escape character?</P>

      @return  <CODE><A HREF="~JD~isEscaped(sob,i)~EJD~">isEscaped</A>([<A HREF="~JD~utilsb~EJD~">UtilStringBuffer</A>].<A HREF="~JD~utilsb#getSOBSB(sb,s)~EJD~">getSOBSB</A>(str_buffer, "isEscaped"), i_dx)</CODE>
    **/
   public final boolean isEscaped(StringBuffer str_buffer, int i_dx)  {
      return isEscaped(uSB.getSOBSB(str_buffer, "isEscaped"), i_dx);
   }

   /**
      <P>Is the character at the requested array index preceded by the escape character?</P>

      <P>Note that this function does not care if the character is one that <A HREF="~JD~esc#isToBeEscaped(c)~EJD~">should be escaped</A>, just that it is preceded by the <A HREF="~JD~esc~EJD~#getEscapeChar()">escape character</A>.</P>

      <P>Also, take special care when analyzing a character in a string that is being unescaped on the fly.  It is easily possible to confuse things.  For example:<UL>
         <LI>In '<CODE>\\\\z</CODE>', is the very first '<CODE>\\</CODE>' escaped?  No.  Go on.</LI>
         <LI>In '<CODE>\\\\z</CODE>', is the second '<CODE>\\</CODE>' escaped?  Yes.  UnescapeString it by eliminating the first '<CODE>\\</CODE>' and go on.</LI>
         <LI>In '<CODE>\\z</CODE>', is the '<CODE>z</CODE>' escaped?  NO.  It appears to be, but we know better...</LI>
      </UL></P>

      @param  str_orBfr  The string to analyze.  May not be null or zero characters in length.
      @param  i_dx  The array index of the character to analyze for escaped-ness.  Must be between zero and (str_orBfr.<A HREF="~JD~sob~EJD~#length()">length</A>() - 1), inclusive.
      @return  <B>true</B>  If an <I>odd</I> number of escape characters immediately precede <CODE>str_orBfr.<A HREF="~JD~sob#charAt(i)~EJD~">charAt</A>(i_dx)</CODE>.
      <BR><B>false</B>  If an <I>even</I> number (including zero) of escape characters immediately precede <CODE>str_orBfr.charAt(i_dx)</CODE>.
    **/
   public final boolean isEscaped(StringOrBuffer str_orBfr, int i_dx)  {
      if(i_dx == 0)  {
         //No matter what, the first character is not escaped.
         return false;
      }

      char cThis = ' ';
      try  {
         cThis = str_orBfr.charAt(i_dx);
      }  catch(IndexOutOfBoundsException ioobx)  {
         throwAX("isEscaped:  i_dx (" + i_dx + ") is invalid.  str_orBfr.length()=" + str_orBfr.length() + ".");
      }

      //Must be initialized to false.
      boolean bSheLovesMe = false;   //bSheLovesMe == "is escaped"
      int i = (i_dx - 1);
      while(i > -1)  {
         if(str_orBfr.charAt(i) == getESConfig().getEscapeChar())  {
            bSheLovesMe = !bSheLovesMe;

            //If this is the first one found, then it's set to true (false
            //is the initial value, !false is true).  Therefore it is escaped.
            //If this is the second, then it's false.  It's not escaped.
            //If this is the third, then it's true.  It is escaped.
            //If this is the fourth, then it's false.  It's not escaped.
            //If this is the fifth, then it's true.  It is escaped.
            //...
            //
            //An odd number of escape characters before this one means
            //this one is escaped.  An even number of escape characters
            //before this one means this one is not escaped.
            i--;
         }  else  {
            break;
         }
      }

      return bSheLovesMe;   //bSheLovesMe == "is escaped"
   }

   private static final String sGI1U2BE = "getIdx1stUnesc2BEsc";
   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob)~EJD~">getIdx1stUnesc2BEsc</A>([<A HREF="~JD~utils~EJD~">UtilString</A>].<A HREF="~JD~utils#getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, "getIdx1stUnesc2BEsc"))</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(String s_tr)  {
      return getIdx1stUnesc2BEsc(uStr.getSOBSB(s_tr, sGI1U2BE));
   }

   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob,i)~EJD~">getIdx1stUnesc2BEsc</A>([<A HREF="~JD~utils~EJD~">UtilString</A>].<A HREF="~JD~utils#getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, "getIdx1stUnesc2BEsc"), i_idxStart)</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(String s_tr, int i_idxStart)  {
      return getIdx1stUnesc2BEsc(uStr.getSOBSB(s_tr, sGI1U2BE), i_idxStart);
   }

   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob,i,i)~EJD~">getIdx1stUnesc2BEsc</A>([<A HREF="~JD~utils~EJD~">UtilString</A>].<A HREF="~JD~utils#getSOBSB(s,s)~EJD~">getSOBSB</A>(s_tr, "getIdx1stUnesc2BEsc"), i_idxStart, i_idxEnd)</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(String s_tr, int i_idxStart, int i_idxEnd)  {
      return getIdx1stUnesc2BEsc(uStr.getSOBSB(s_tr, sGI1U2BE), i_idxStart, i_idxEnd);
   }

   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob)~EJD~">getIdx1stUnesc2BEsc</A>([<A HREF="~JD~utilsb~EJD~">UtilStringBuffer</A>].<A HREF="~JD~utilsb#getSOBSB(sb,s)~EJD~">getSOBSB</A>(s_tr, "getIdx1stUnesc2BEsc"))</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(StringBuffer str_buffer)  {
      return getIdx1stUnesc2BEsc(uSB.getSOBSB(str_buffer, sGI1U2BE));
   }

   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob,i)~EJD~">getIdx1stUnesc2BEsc</A>([<A HREF="~JD~utilsb~EJD~">UtilStringBuffer</A>].<A HREF="~JD~utilsb#getSOBSB(sb,s)~EJD~">getSOBSB</A>(str_buffer, "getIdx1stUnesc2BEsc"), i_idxStart)</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(StringBuffer str_buffer, int i_idxStart)  {
      return getIdx1stUnesc2BEsc(uSB.getSOBSB(str_buffer, sGI1U2BE), i_idxStart);
   }

   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob,i,i)~EJD~">getIdx1stUnesc2BEsc</A>([<A HREF="~JD~utilsb~EJD~">UtilStringBuffer</A>].<A HREF="~JD~utilsb#getSOBSB(sb,s)~EJD~">getSOBSB</A>(str_buffer, "getIdx1stUnesc2BEsc"), i_idxStart, i_idxEnd)</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(StringBuffer str_buffer, int i_idxStart, int i_idxEnd)  {
      return getIdx1stUnesc2BEsc(uSB.getSOBSB(str_buffer, sGI1U2BE), i_idxStart, i_idxEnd);
   }


   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob,i)~EJD~">getIdx1stUnesc2BEsc</A>(str_orBfr, 0)</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(StringOrBuffer str_orBfr)  {
      return getIdx1stUnesc2BEsc(str_orBfr, 0);
   }

   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      @param  str_orBfr  The StringOrBuffer to analyze.  May not be null.
      @return  <CODE><A HREF="~JD~getIdx1stUnesc2BEsc(sob,i,i)~EJD~">getIdx1stUnesc2BEsc</A>(str_orBfr, i_idxStart, (str_orBfr.<A HREF="~JD~sob~EJD~#length()">length</A>() - 1))</CODE>
    **/
   public final int getIdx1stUnesc2BEsc(StringOrBuffer str_orBfr, int i_idxStart)  {
      try  {
         return getIdx1stUnesc2BEsc(str_orBfr, i_idxStart, (str_orBfr.length() - 1));
      }  catch(NullPointerException npx)  {
         throwAX("getIdx1stUnesc2BEsc:  str_orBfr is null.");
      }

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

   /**
      <P>Get the array index of the first character that <I>should</I> be escaped, but is not.</P>

      <P><I>Note:  Be careful that the value of <CODE>i_idxStart</CODE>/<CODE>i_idxEnd</CODE> (whichever is lower/smaller/more-to-the-left) is the index of a character that <A HREF="~JD~isEscaped(sob,i)~EJD~">is <B>not</B> escaped</A>.  Otherwise, this function will give you inaccurate results.</I></P>

      @param  str_orBfr  The StringBuffer to analyze.  May not be null or zero characters in length.
      @param  i_idxStart  The first array index to analyze.  Must be between zero and (str_orBfr.<A HREF="~JD~sob~EJD~#length()">length</A>() - 1), inclusive.  Note that this may be greater than i_idxEnd, should you want to analyze right to left.
      @param  i_idxEnd  The last array index to analyze.  Must be between zero and (str_orBfr.length() - 1), inclusive.
      @return  The index of the first char found, starting with i_idxStart, that <A HREF="~JD~esc#isToBeEscaped(c)~EJD~">should be escaped</A>, but is not.  If every character that should be escaped, is escaped (or no to-be-escaped characters exist in the line), then <B>-1</B> is returned.
    **/
   public final int getIdx1stUnesc2BEsc(StringOrBuffer str_orBfr, int i_idxStart, int i_idxEnd)  {
      try  {
         int i = i_idxStart;
         if(i_idxStart > i_idxEnd)  {
            for(; i >= i_idxEnd; i--)  {
               char c = str_orBfr.charAt(i);
               if(getESConfig().isToBeEscaped(c)  &&
                     !isEscaped(str_orBfr, i))  {

                  return i;
               }
            }

         }  else  {
            for(; i <= i_idxEnd; i++)  {
               char c = str_orBfr.charAt(i);
               if(getESConfig().isToBeEscaped(c)  &&
                     !isEscaped(str_orBfr, i))  {
                  return i;
               }
            }
         }
      }  catch(NullPointerException npx)  {
         throwAX("getIdx1stUnesc2BEsc:  str_orBfr is null.");
      }  catch(IndexOutOfBoundsException ioobx)  {

         if(str_orBfr.length() < 1)  {
            throwAX("getIdx1stUnesc2BEsc:  str_orBfr is zero characters in length.");
         }

         throwAX("getIdx1stUnesc2BEsc:  str_orBfr is " + str_orBfr.length() + " characters in length, i_idxStart (" + i_idxStart + ") and/or i_idxEnd (" + i_idxEnd + ") are invalid array index bounds.  str_orBfr.length()=" + str_orBfr.length() + ".");
      }

      return -1;
   }
}