range.java

使用java编写的关于通讯及串口编程所必需的类库

/*
 * Randoms.java
 *
 * This is a required part of the com.adaptiveview.ospso package.
 *
 * Copyright (C) 2003 AdaptiveView.com
 * 
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 * 
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 * 
 * You may contact AdaptiveView.com via email at: [e-mail] 
 *
 */

package com.adaptiveview.toolkits.numbers;

/**
 *
 * @author  AdaptiveView.com
 */

public final class Range implements com.adaptiveview.ospso.dmi.DMI_GPL_License {
    
    private static final String MIN_LT_MAX = "Minimum must be less than maximum.";
    private static final double EPSILON    = 0.0000000000000005d;
    
    /** Cannot create a new instance of Randoms */
    private Range() {}
    
    /**Makes a double value fit within a range by "sticking it" to an exceeded boundary
     * (if any) -- for example, the value of 12 is fit into the range 0-to-10 by 
     * setting it to 10.
     *@return a number within the specified range. 
     */
    public static final double constrict(double n, double min, double max) {
        if (n < min) return min;
        if (n > max) return max;
        return n;
    }
    
    /**Makes a double value fit within a range by "sticking it" to an exceeded boundary
     * (if any) -- for example, the value of 12 is fit into the range 0-to-10 by 
     * setting it to 10.
     *@return a number within the specified range. 
     */
    public static final double stick(double n, double min, double max) {
        return constrict(n,min,max);
    }
    
    /**Makes a double value fit within a range by "sticking it" to an exceeded boundary
     * (if any) -- for example, the value of 12 is fit into the range 0-to-10 by 
     * setting it to 10. If <code>withEpsilon</code> is <code>true</code>, the 
     * value is compared against the range boundaries narrowed by the value of 
     * static final field EPSILON.
     *@return a number within the specified range. 
     */
    public static final double constrict(double n, double min, double max, boolean withEpsilon) {
        if (!withEpsilon) return constrict(n,min,max);
        if (n < min + EPSILON) return min;
        if (n > max - EPSILON) return max;
        return n;
    }
    
    /**Makes a double value fit within a range using a "bounce method" -- for example,
     * the value 12 is fit into the range 0-to-10 by repeatedly wrapping it around a
     * continuous <code>0,...,9,10,9,...,1,0,1,...</code> range, yielding a result of 8.
     *@return a number within the specified range. 
     */
    public static final double bounce(double n, double min, double max) {
        if (inRange(n,min,max)) return n;
        double range = max - min;
        double err = (n < min ? min - n : n - max);
        double bounces = Math.floor(Math.abs(err)/range);
        double remainder = err - (bounces * range);
        bounces = bounces % 2.0;
        if (n < min) return (bounces == 0.0 ? min + remainder : max - remainder);
        /* else:  */ return (bounces == 0.0 ? max - remainder : min + remainder);
    }
    
    /**Makes an integer value fit within a range using a "wrap method" -- for example,
     * the value 22 is fit into the range 0-to-10 by repeatedly wrapping it around a
     * continuous <code>0,...,10,0,...,10,0,...</code> range, yielding a result of 2.
     *@return a number within the specified range. 
     */
    public static final int wrap(int n, int min, int max) {
        if (inRange(n,min,max)) return n;
        int range = max - min;
        int err = (n < min ? min - n : n - max);
        int wraps = (int)Math.floor(Math.abs(err)/range);
        int remainder = err - (wraps * range);
        if (n < min) return max - remainder;
        if (n > max) return min + remainder;
        return n;
    }
    
    /**Makes a double value fit within a range using a "wrap method" -- for example,
     * the value 22 is fit into the range 0-to-10 by repeatedly wrapping it around a
     * continuous <code>0,...,10,0,...,10,0,...</code> range, yielding a result of 2.
     *@return a number within the specified range. 
     */
    public static final double wrap(double n, double min, double max) {
        if (inRange(n,min,max)) return n;
        double range = max - min;
        double err = (n < min ? min - n : n - max);
        double wraps = Math.floor(Math.abs(err)/range);
        double remainder = err - (wraps * range);
        if (n < min) return max - remainder;
        if (n > max) return min + remainder;
        return n;
    }
    
    /** Returns true if n is inside range min..max <b>inclusive</b>. */
    public static final boolean inRange(double n, double min, double max) 
           throws IllegalArgumentException {
        if (min > max)
           throw new IllegalArgumentException(MIN_LT_MAX); 
        return ((n >= min) && (n <= max));
    }
    
    /** Returns true if n is inside range min..max <b>inclusive</b>. */
    public static final boolean inRange(int n, int min, int max) 
           throws IllegalArgumentException {
        if (min > max)
           throw new IllegalArgumentException(MIN_LT_MAX); 
        return ((n >= min) && (n <= max));
    }
    
    /** Returns true if n is inside range min..max <b>exclusive</b>. */
    public static final boolean inBounds(double n, double min, double max) 
           throws IllegalArgumentException {
        if (min >= max)
           throw new IllegalArgumentException(MIN_LT_MAX); 
        return ((n > min) && (n < max));
    }
    
}