/*
   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>Defines the legal range for an integer.  See <A HREF="Range.html">Range</A>.</P>

   <P><CODE><I><B>Source code:</B> &nbsp;<A HREF="../../../CODE/xbn/util/RangeConfig.java">RangeConfig.java</A>. &nbsp;<B>Unit tests:</B> &nbsp;xbn_junit.<A HREF="../../../CODE/xbn_junit/util/JUTRangeConfig.java">JUTRangeConfig.java</A>.</I></CODE></P>

   <P>There are four elements of a range:<UL>
      <LI>Minimum bound (<A HREF="#getMin()">getMin</A>):  The lowest value allowed.  Only used when isMinEnforced is true.</LI>
      <LI><A HREF="#isMinEnforced()">isMinEnforced</A>:  Determines whether or not the minimum bound should be used or ignored.</LI>
      <LI>Maximum bound (<A HREF="#getMax()">getMax</A>):  The highest value allowed.  Only used when isMaxEnforced is true.</LI>
      <LI><A HREF="#isMaxEnforced()">isMaxEnforced</A>:  Determines whether or not the maximum bound should be used or ignored.</LI>
   </UL></P>

   <h3>Inclusive and Exclusive</h3>

   <P>A range is always inclusive.  That is, a number is considered legal when the value is between the minimum and maximum bounds <I>or equal</I> to them.  If you need your range to be exclusive, then set the minimum bound to (minimum bound + 1) and maximum bound to (maximum bound - 1).</P>

   @version  0.9b
   @author  Jeff Epstein, <A HREF="http://sourceforge.net/projects/xbnjava">http://sourceforge.net/projects/xbnjava</A>.
 **/
public class RangeConfig extends XBNObject  {
   private UtilInt uInt = new UtilInt();

   private int iMin = -1;
   private boolean bEnforceMin = false;

   private int iMax = -1;
   private boolean bEnforceMax = false;


   /**
      <P>Create a, completely unrestricted, RangeConfig object.</P>

      <P>Equal to <CODE><A HREF="~JD~rc(i,b,i,b)~EJD~">RangeConfig</A>(-1, false, -1, false)</CODE></P>
    **/
   public RangeConfig()  {
      this(-1, false, -1, false);
   }


   /**
      <P>Create a RangeConfig.</P>

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


   /**
      <P>Create a RangeConfig.</P>

      <P>All parameters must be valid according to <A HREF="UtilInt.html">UtilInt</A>.<A HREF="~JD~utili#areRangeBoundsValid(i,b,i,b,b)~EJD~">areRangeBoundsValid</A>(i_min, b_nfrcMin, i_max, b_nfrcMax, true)</P>

      @param  i_min  The minimum bound.  See <A HREF="#getMin()">getMin</A>.
      @param  b_nfrcMin  The minimum bound.  See <A HREF="#isMinEnforced()">isMinEnforced</A>.
      @param  i_max  The minimum bound.  See <A HREF="#getMax()">getMax</A>.
      @param  b_nfrcMax  The minimum bound.  See <A HREF="#isMaxEnforced()">isMaxEnforced</A>.
    **/
   public RangeConfig(int i_min, boolean b_nfrcMin, int i_max, boolean b_nfrcMax)  {
      if(!uInt.areRangeBoundsValid(i_min, b_nfrcMin, i_max, b_nfrcMax, true))  {
         throwAX("constructor:  Illegal range.  b_nfrcMin and b_nfrcMax are both true (read:  are both enforced), but i_min is greater than i_max.");
      }

      //The range is legal.

      iMin = i_min;
      bEnforceMin = b_nfrcMin;
      iMax = i_max;
      bEnforceMax = b_nfrcMax;
   }

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

      @param  range_config  The range config to copy.  May not be null.
    **/
   public RangeConfig(RangeConfig range_config)  {
      try  {
         iMin = range_config.iMin;
      }  catch(NullPointerException npx)  {
         throwAX("constructor:  range_config is null.");
      }

      bEnforceMin = range_config.bEnforceMin;
      iMax = range_config.iMax;
      bEnforceMax = range_config.bEnforceMax;
   }


   /**
      <P>Is the minimum bound enforced?</P>

      @return  <B>b_nfrcMin</B> exactly as provided to the <A HREF="~JD~rc(i,b,i,b)~EJD~">constructor</A>.
    **/
   public final boolean isMinEnforced()  {
      return bEnforceMin;
   }

   /**
      <P>Is the maximum bound enforced?</P>

      @return  <B>b_nfrcMax</B> exactly as provided to the <A HREF="~JD~rc(i,b,i,b)~EJD~">constructor</A>.
    **/
   public final boolean isMaxEnforced()  {
      return bEnforceMax;
   }

   /**
      <P>What is the minimum legal value for this range?</P>

      @return  <B>i_min</B> exactly as provided to the <A HREF="~JD~rc(i,b,i,b)~EJD~">constructor</A>.
    **/
   public final int getMin()  {
      return iMin;
   }

   /**
      <P>What is the maximum legal value for this range?</P>

      @return  <B>i_max</B> exactly as provided to the <A HREF="~JD~rc(i,b,i,b)~EJD~">constructor</A>.
    **/
   public final int getMax()  {
      return iMax;
   }

   /**
      <P>Is the potential value valid for this Range?</P>

      <P>Equal to <CODE><A HREF="~JD~utili~EJD~">UtilInt</A>.<A HREF="~JD~utili#isInRange(i,i,b,i,b,b)~EJD~">isInRange</A>(i_potential, <A HREF="#getMin()">getMin</A>(), <A HREF="#isMinEnforced()">isMinEnforced</A>(), <A HREF="#getMax()">getMax</A>(), <A HREF="#isMaxEnforced()">isMaxEnforced</A>(), false)</CODE></P>
    **/
   public final boolean isValid(int i_potential)  {
      return uInt.isInRange(i_potential, getMin(), isMinEnforced(), getMax(), isMaxEnforced(), false);
   }


   /**
      <P>Are there any restrictions imposed by this RCLength?</P>

      @return  <CODE>(<A HREF="#isMinEnforced()">isMinEnforced</A>()  ||  <A HREF="#isMaxEnforced()">isMaxEnforced</A>())</CODE>
    **/
   public boolean isRestricted()  {
      return (isMinEnforced()  ||  isMaxEnforced());
   }

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

      <P>Equal to <CODE><A HREF="#toString(boolean)">toString</A>(true)</CODE></P>
    **/
   public String toString()  {
      return toString(true);
   }


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

      @param  b_className  If true, display the class name at the beginning of the returned string.  If false, don't.
    **/
   public String toString(boolean b_className)  {
      if(!isRestricted())  {
         return this.getClass().getName() + ":  UNRESTRICTED";
      }

      //Something is being enforced.

      String sMinEnforced = "not enforced";

      if(isMinEnforced())  {
         sMinEnforced = "enforced";
      }

      String sMaxEnforced = "not enforced";

      if(isMaxEnforced())  {
         sMaxEnforced = "enforced";
      }

      String sCN = sES;
      if(b_className)  {
         sCN = this.getClass().getName() + ":  ";
      }

      return sCN + "getMin()=" + getMin() + " (" + sMinEnforced + "), getMax()=" + getMax() + " (" + sMaxEnforced + ")";
   }
}