/*
   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.util;
   import xbn.XBNObject;

/**
   <P>Random functions to analyze and manipulate ints.</P>

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

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

   /**
      <P>Is the number between min and max, but not equal to either bound?.  If so, return true.  Otherwise return false.</P>

      <P>Equal to <CODE><A HREF="~JD~isInRange(i,i,b,i,b)~EJD~">isInRange</A>(i_number, (i_min + 1), true, (i_max - 1), true)</CODE></P>
    **/
   public final boolean isBetween(int i_number, int i_min, int i_max)  {
      return isInRange(i_number, (i_min + 1), true, (i_max - 1), true);
   }

   /**
      <P>Is the number between min and max, or equal to one of the bounds?.  If so, return true.  Otherwise return false.</P>

      <P>Equal to <CODE><A HREF="~JD~isInRange(i,i,b,i,b)~EJD~">isInRange</A>(i_number, i_min, true, i_max, true)</CODE></P>
    **/
   public final boolean isBetweenInclusive(int i_number, int i_min, int i_max)  {
      return isInRange(i_number, i_min, true, i_max, true);
   }

   /**
      <P>Are the bounds for this range valid?</P>

      <P>Equal to <CODE><A HREF="~JD~areRangeBoundsValid(i,b,i,b,b)~EJD~">areRangeBoundsValid</A>(i_min, true, i_max, true, true)</CODE></P>
    **/
   public final boolean areRangeBoundsValid(int i_min, int i_max)  {
      return areRangeBoundsValid(i_min, true, i_max, true, true);
   }

   /**
      <P>Are the bounds for this range valid?</P>

      <P>Equal to <CODE><A HREF="~JD~areRangeBoundsValid(i,b,i,b,b)~EJD~">areRangeBoundsValid</A>(i_min, b_nfrcMin, i_max, b_nfrcMax, true)</CODE></P>
    **/
   public final boolean areRangeBoundsValid(int i_min, boolean b_nfrcMin, int i_max, boolean b_nfrcMax)  {
      return areRangeBoundsValid(i_min, b_nfrcMin, i_max, b_nfrcMax, true);
   }


   /**
      <P>Are the bounds for this range valid?</P>

      @param  i_min  The minimum bound of the range.  Only used if b_nfrcMin is "true".
      @param  b_nfrcMin  If "true", then i_min is used.  If "false", i_min is ignored.
      @param  i_max  The maximum bound of the range.  Only used if b_nfrcMax is "true".
      @param  b_nfrcMax  If "true", then i_max is used.  If "false", i_max is ignored.
      @param  b_actuallyCheck  If "true" then <I>do</I> check these bounds, and return true/false based on their validity.  If "false", exit the function immediately (and return true).  This is needed for external code that can guarantee that the bounds are valid, and don't want to redundantly check each time that <A HREF="~JD~isInRange(i,i,b,i,b)~EJD~">isInRange</A> is called.
      @return <B>true</B> <UL>
         <LI>If b_actuallyCheck is false.</LI>
         <LI>If b_nfrcMin or b_nfrcMax are false.</LI>
         <LI>If both b_nfrcMin and b_nfrcMax are true, and i_min is less than or equal to i_max.</LI>
      </UL>
      <BR><B>false</B> Under any other conditions.
    **/
   public final boolean areRangeBoundsValid(int i_min, boolean b_nfrcMin, int i_max, boolean b_nfrcMax, boolean b_actuallyCheck)  {
      if(!b_actuallyCheck)  {
         return true;
      }

      if(!b_nfrcMin  ||  !b_nfrcMax)  {
         //Since one or both of the bounds are not being
         //enforced, these bounds are valid.
         return true;
      }

      //Both bounds are being enforced.  If i_min is greater
      //than i_max, then bad (false).  Otherwise, i_min is equal to
      //or less than i_max (good:  true).

      return (i_min <= i_max);
   }


   /**
      <P>Is the number in the range?</P>

      <P>Equal to <CODE><A HREF="~JD~isInRange(i,i,b,i,b,b)~EJD~">isInRange</A>(i_number, i_min, b_nfrcMin, i_max, b_nfrcMax, true)</CODE></P>
    **/
   public final boolean isInRange(int i_number, int i_min, boolean b_nfrcMin, int i_max, boolean b_nfrcMax)  {
      return isInRange(i_number, i_min, b_nfrcMin, i_max, b_nfrcMax, true);
   }


   /**
      <P>Is the number in the range?</P>

      @param  i_number  The number to analyze.
      @param i_min  The minimum bound of the range.  If...<UL>
         <LI>...b_nfrcMin is true and b_nfrcMax is false, this may be any value.</LI>
         <LI>...b_nfrcMin is true and b_nfrcMax is true, this must be less than or equal to i_max.</LI>
         <LI>...b_nfrcMin is false, this value is ignored.</LI>
      </UL>
      @param  b_nfrcMin  If "true", then i_min is used.  If "false", i_min is ignored.
      @param i_max  The maximum bound of the range.  If...<UL>
         <LI>...b_nfrcMin is false and b_nfrcMax is true, this may be any value.</LI>
         <LI>...b_nfrcMin is true and b_nfrcMax is true, this must be greater than or equal to i_min.</LI>
         <LI>...b_nfrcMax is false, this value is ignored.</LI>
      </UL>
      @param  b_nfrcMax  If "true", then i_max is used.  If "false", i_max is ignored.
      @param  b_validateRange  If "true" then validate the range (with <A HREF="~JD~areRangeBoundsValid(i,b,i,b,b)~EJD~">areRangeBoundsValid</A>) before analyzing i_number.  If the bounds are bad, throw an <A HREF="~JD~ax~EJD~">AssertException</A>.  If "false", then it is expected that the range has been validated before this function is called.  Use at your own risk, as unpredictable results may occur.
      @return <CODE>(<A HREF="~JD~isGTOEMin(i,i,b)~EJD~">isGTOEMin</A>(i_number, i_min, b_nfrcMin)  &amp;&amp;  <A HREF="~JD~isLTOEMax(i,i,b)~EJD~">isLTOEMax</A>(i_number, i_min, b_nfrcMin))</CODE>.
    **/
   public final boolean isInRange(int i_number, int i_min, boolean b_nfrcMin, int i_max, boolean b_nfrcMax, boolean b_validateRange)  {
      if(!areRangeBoundsValid(i_min, b_nfrcMin, i_max, b_nfrcMax, b_validateRange))  {
         //They want to validate the range, and the range is
         //bad.

         throwAX("setRange:  Illegal range.  b_nfrcMin and b_nfrcMax are both true (are both enforced), but i_min is greater than i_max.");
      }

      return (isGTOEMin(i_number, i_min, b_nfrcMin)  &&  isLTOEMax(i_number, i_max, b_nfrcMax));
   }


   /**
      <P>Is the number greater than or equal to the minimum-possible value?</P>

      @param  i_number  The number to analyze.
      @param  i_min  If b_nfrcMin is "true", this may be any number.  If b_nfrcMin is "false" this is ignored.
      @return  <B>true</B>  <UL>
         <LI>If b_nfrcMin is false.</LI>
         <LI>If b_nfrcMin is true, and i_number is greater than or equal to i_min.</LI>
      </UL>
      <BR><B>false</B>  If b_nfrcMin is true and i_number is less than i_min.
    **/
   public final boolean isGTOEMin(int i_number, int i_min, boolean b_nfrcMin)  {
      if(!b_nfrcMin)  {
         //No matter what, the number is valid.
         return true;
      }

      //The minimum bound is being enforced.

      return i_number >= i_min;
   }


   /**
      <P>Is the number less than or equal to the maimum-possible value?</P>

      @param  i_number  The number to analyze.
      @param  i_max  If b_nfrcMax is "true", this may be any number.  If b_nfrcMax is "false" this is ignored.
      @return  <B>true</B>  <UL>
         <LI>If b_nfrcMax is false.</LI>
         <LI>If b_nfrcMax is true, and i_number is less than or equal to i_max.</LI>
      </UL>

      <BR><B>false</B>  If b_nfrcMax is true and i_number is greater than i_max.
    **/
   public final boolean isLTOEMax(int i_number, int i_max, boolean b_nfrcMax)  {
      if(!b_nfrcMax)  {
         //No matter what, this is a valid value.
         return true;
      }

      //The maximum bound is being enforced.

      return i_number <= i_max;
   }


   /**
      <P>How many digits in length is the provided number?</P>

      <P>An alternative method for determining the number of digits is to convert the number to a string, and then get the string's length (although you need to anticipate the possible dash, with negative numbers):</P>

      <PRE>((new <A HREF="~JD~I#I(i)~EJD~">Integer</A>(i_number)).<A HREF="~JD~I~EJD~#toString()">toString</A>()).<A HREF="~JD~s~EJD~#length()">length</A>()</PRE>

      <P><FONT SIZE="-1"><I>This was an intriguing thing for me to figure out.  The answer to "how many digits does my number contain" is "how many times can you divide ten into it?..plus one".  Take a look at the code.</I></FONT></P>

      @param  i_number  The number you want to know the amount of digits in.  Trailing zeros (zeros on the left side of the number) are ignored, however, the number zero is considered a one-digit number.
      @return  The number of digits in i_number.  For example:<UL>
         <LI><B>10:</B>  Returns <B>2</B>.</LI>
         <LI><B>-94:</B>  Returns <B>2</B>.</LI>
         <LI><B>000037:</B>  Returns <B>2</B>.</LI>
         <LI><B>0:</B>  Returns <B>1</B></LI>
         <LI><B>687482:</B>  Returns <B>6</B></LI>
      </UL>
    **/
   public int getDigitLength(int i_number)  {
      //How many digits does this number contain?  It contains at least one.
      int iDigits = 1;

      if(i_number < 0)  {
         //The number is less than zero.  The below divide-by-ten
         //will never work unless we positive-ize it.
         i_number = (i_number * -1);
      }

      //A temporary variable that holds the value of the divide-by-ten
      //answer.  We don't care what the value is, as long as it's
      //GTOET 10.
      int iAnswerTEMP = i_number;

      while(iAnswerTEMP >= 10)  {
         //There's another digit.
         iAnswerTEMP = iAnswerTEMP / 10;
         iDigits++;
      }

      return iDigits;
   }


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

      <P><FONT SIZE="-1"><I>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.</I></FONT></P>

      @param  a_int  The int array to analyze.  May not be null or equal to zero elements in length.
      @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.
    **/
   public final int getIdxNEToLmnt0(int[] a_int)  {
      try  {
         for(int i = 1; i < a_int.length; i++)  {
            if(a_int[0] != a_int[i])  {
               return i;
            }
         }
      }  catch(NullPointerException npx)  {
         throwAX("getIdxNEToLmnt0:  a_int is null.");
      }

      return -1;
   }
}