core/java/android/util/Range.java - platform/frameworks/base - Git at Google

 /*
  * Copyright (C) 2014 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
  *
  *      http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */

 package android.util;

 import static com.android.internal.util.Preconditions.*;

 import android.hardware.camera2.utils.HashCodeHelpers;

 /**
  * Immutable class for describing the range of two numeric values.
  * <p>
  * A range (or "interval") defines the inclusive boundaries around a contiguous span of
  * values of some {@link Comparable} type; for example,
  * "integers from 1 to 100 inclusive."
  * </p>
  * <p>
  * All ranges are bounded, and the left side of the range is always {@code >=}
  * the right side of the range.
  * </p>
  *
  * <p>Although the implementation itself is immutable, there is no restriction that objects
  * stored must also be immutable. If mutable objects are stored here, then the range
  * effectively becomes mutable. </p>
  */
 public final class Range<T extends Comparable<? super T>> {
     /**
      * Create a new immutable range.
      *
      * <p>
      * The endpoints are {@code [lower, upper]}; that
      * is the range is bounded. {@code lower} must be {@link Comparable#compareTo lesser or equal}
      * to {@code upper}.
      * </p>
      *
      * @param lower The lower endpoint (inclusive)
      * @param upper The upper endpoint (inclusive)
      *
      * @throws NullPointerException if {@code lower} or {@code upper} is {@code null}
      */
     public Range(final T lower, final T upper) {
         mLower = checkNotNull(lower, "lower must not be null");
         mUpper = checkNotNull(upper, "upper must not be null");

         if (lower.compareTo(upper) > 0) {
             throw new IllegalArgumentException("lower must be less than or equal to upper");
         }
     }

     /**
      * Create a new immutable range, with the argument types inferred.
      *
      * <p>
      * The endpoints are {@code [lower, upper]}; that
      * is the range is bounded. {@code lower} must be {@link Comparable#compareTo lesser or equal}
      * to {@code upper}.
      * </p>
      *
      * @param lower The lower endpoint (inclusive)
      * @param upper The upper endpoint (inclusive)
      *
      * @throws NullPointerException if {@code lower} or {@code upper} is {@code null}
      */
     public static <T extends Comparable<? super T>> Range<T> create(final T lower, final T upper) {
         return new Range<T>(lower, upper);
     }

     /**
      * Get the lower endpoint.
      *
      * @return a non-{@code null} {@code T} reference
      */
     public T getLower() {
         return mLower;
     }

     /**
      * Get the upper endpoint.
      *
      * @return a non-{@code null} {@code T} reference
      */
     public T getUpper() {
         return mUpper;
     }

     /**
      * Checks if the {@code value} is within the bounds of this range.
      *
      * <p>A value is considered to be within this range if it's {@code >=}
      * the lower endpoint <i>and</i> {@code <=} the upper endpoint (using the {@link Comparable}
      * interface.)</p>
      *
      * @param value a non-{@code null} {@code T} reference
      * @return {@code true} if the value is within this inclusive range, {@code false} otherwise
      *
      * @throws NullPointerException if {@code value} was {@code null}
      */
     public boolean contains(T value) {
         checkNotNull(value, "value must not be null");

         boolean gteLower = value.compareTo(mLower) >= 0;
         boolean lteUpper  = value.compareTo(mUpper) <= 0;

         return gteLower && lteUpper;
     }

     /**
      * Checks if another {@code range} is within the bounds of this range.
      *
      * <p>A range is considered to be within this range if both of its endpoints
      * are within this range.</p>
      *
      * @param range a non-{@code null} {@code T} reference
      * @return {@code true} if the range is within this inclusive range, {@code false} otherwise
      *
      * @throws NullPointerException if {@code range} was {@code null}
      */
     public boolean contains(Range<T> range) {
         checkNotNull(range, "value must not be null");

         boolean gteLower = range.mLower.compareTo(mLower) >= 0;
         boolean lteUpper = range.mUpper.compareTo(mUpper) <= 0;

         return gteLower && lteUpper;
     }

     /**
      * Compare two ranges for equality.
      *
      * <p>A range is considered equal if and only if both the lower and upper endpoints
      * are also equal.</p>
      *
      * @return {@code true} if the ranges are equal, {@code false} otherwise
      */
     @Override
     public boolean equals(Object obj) {
         if (obj == null) {
             return false;
         } else if (this == obj) {
             return true;
         } else if (obj instanceof Range) {
             @SuppressWarnings("rawtypes")
             Range other = (Range) obj;
             return mLower.equals(other.mLower) && mUpper.equals(other.mUpper);
         }
         return false;
     }

     /**
      * Clamps {@code value} to this range.
      *
      * <p>If the value is within this range, it is returned.  Otherwise, if it
      * is {@code <} than the lower endpoint, the lower endpoint is returned,
      * else the upper endpoint is returned. Comparisons are performed using the
      * {@link Comparable} interface.</p>
      *
      * @param value a non-{@code null} {@code T} reference
      * @return {@code value} clamped to this range.
      */
     public T clamp(T value) {
         checkNotNull(value, "value must not be null");

         if (value.compareTo(mLower) < 0) {
             return mLower;
         } else if (value.compareTo(mUpper) > 0) {
             return mUpper;
         } else {
             return value;
         }
     }

     /**
      * Returns the intersection of this range and another {@code range}.
      * <p>
      * E.g. if a {@code <} b {@code <} c {@code <} d, the
      * intersection of [a, c] and [b, d] ranges is [b, c].
      * As the endpoints are object references, there is no guarantee
      * which specific endpoint reference is used from the input ranges:</p>
      * <p>
      * E.g. if a {@code ==} a' {@code <} b {@code <} c, the
      * intersection of [a, b] and [a', c] ranges could be either
      * [a, b] or ['a, b], where [a, b] could be either the exact
      * input range, or a newly created range with the same endpoints.</p>
      *
      * @param range a non-{@code null} {@code Range<T>} reference
      * @return the intersection of this range and the other range.
      *
      * @throws NullPointerException if {@code range} was {@code null}
      * @throws IllegalArgumentException if the ranges are disjoint.
      */
     public Range<T> intersect(Range<T> range) {
         checkNotNull(range, "range must not be null");

         int cmpLower = range.mLower.compareTo(mLower);
         int cmpUpper = range.mUpper.compareTo(mUpper);

         if (cmpLower <= 0 && cmpUpper >= 0) {
             // range includes this
             return this;
         } else if (cmpLower >= 0 && cmpUpper <= 0) {
             // this inludes range
             return range;
         } else {
             return Range.create(
                     cmpLower <= 0 ? mLower : range.mLower,
                     cmpUpper >= 0 ? mUpper : range.mUpper);
         }
     }

     /**
      * Returns the intersection of this range and the inclusive range
      * specified by {@code [lower, upper]}.
      * <p>
      * See {@link #intersect(Range)} for more details.</p>
      *
      * @param lower a non-{@code null} {@code T} reference
      * @param upper a non-{@code null} {@code T} reference
      * @return the intersection of this range and the other range
      *
      * @throws NullPointerException if {@code lower} or {@code upper} was {@code null}
      * @throws IllegalArgumentException if the ranges are disjoint.
      */
     public Range<T> intersect(T lower, T upper) {
         checkNotNull(lower, "lower must not be null");
         checkNotNull(upper, "upper must not be null");

         int cmpLower = lower.compareTo(mLower);
         int cmpUpper = upper.compareTo(mUpper);

         if (cmpLower <= 0 && cmpUpper >= 0) {
             // [lower, upper] includes this
             return this;
         } else {
             return Range.create(
                     cmpLower <= 0 ? mLower : lower,
                     cmpUpper >= 0 ? mUpper : upper);
         }
     }

     /**
      * Returns the smallest range that includes this range and
      * another {@code range}.
      * <p>
      * E.g. if a {@code <} b {@code <} c {@code <} d, the
      * extension of [a, c] and [b, d] ranges is [a, d].
      * As the endpoints are object references, there is no guarantee
      * which specific endpoint reference is used from the input ranges:</p>
      * <p>
      * E.g. if a {@code ==} a' {@code <} b {@code <} c, the
      * extension of [a, b] and [a', c] ranges could be either
      * [a, c] or ['a, c], where ['a, c] could be either the exact
      * input range, or a newly created range with the same endpoints.</p>
      *
      * @param range a non-{@code null} {@code Range<T>} reference
      * @return the extension of this range and the other range.
      *
      * @throws NullPointerException if {@code range} was {@code null}
      */
     public Range<T> extend(Range<T> range) {
         checkNotNull(range, "range must not be null");

         int cmpLower = range.mLower.compareTo(mLower);
         int cmpUpper = range.mUpper.compareTo(mUpper);

         if (cmpLower <= 0 && cmpUpper >= 0) {
             // other includes this
             return range;
         } else if (cmpLower >= 0 && cmpUpper <= 0) {
             // this inludes other
             return this;
         } else {
             return Range.create(
                     cmpLower >= 0 ? mLower : range.mLower,
                     cmpUpper <= 0 ? mUpper : range.mUpper);
         }
     }

     /**
      * Returns the smallest range that includes this range and
      * the inclusive range specified by {@code [lower, upper]}.
      * <p>
      * See {@link #extend(Range)} for more details.</p>
      *
      * @param lower a non-{@code null} {@code T} reference
      * @param upper a non-{@code null} {@code T} reference
      * @return the extension of this range and the other range.
      *
      * @throws NullPointerException if {@code lower} or {@code
      *                              upper} was {@code null}
      */
     public Range<T> extend(T lower, T upper) {
         checkNotNull(lower, "lower must not be null");
         checkNotNull(upper, "upper must not be null");

         int cmpLower = lower.compareTo(mLower);
         int cmpUpper = upper.compareTo(mUpper);

         if (cmpLower >= 0 && cmpUpper <= 0) {
             // this inludes other
             return this;
         } else {
             return Range.create(
                     cmpLower >= 0 ? mLower : lower,
                     cmpUpper <= 0 ? mUpper : upper);
         }
     }

     /**
      * Returns the smallest range that includes this range and
      * the {@code value}.
      * <p>
      * See {@link #extend(Range)} for more details, as this method is
      * equivalent to {@code extend(Range.create(value, value))}.</p>
      *
      * @param value a non-{@code null} {@code T} reference
      * @return the extension of this range and the value.
      *
      * @throws NullPointerException if {@code value} was {@code null}
      */
     public Range<T> extend(T value) {
         checkNotNull(value, "value must not be null");
         return extend(value, value);
     }

     /**
      * Return the range as a string representation {@code "[lower, upper]"}.
      *
      * @return string representation of the range
      */
     @Override
     public String toString() {
         return String.format("[%s, %s]", mLower, mUpper);
     }

     /**
      * {@inheritDoc}
      */
     @Override
     public int hashCode() {
         return HashCodeHelpers.hashCodeGeneric(mLower, mUpper);
     }

     private final T mLower;
     private final T mUpper;
 };
	/*
	* Copyright (C) 2014 The Android Open Source Project
	*
	* Licensed under the Apache License, Version 2.0 (the "License");
	* you may not use this file except in compliance with the License.
	* You may obtain a copy of the License at
	*
	* http://www.apache.org/licenses/LICENSE-2.0
	*
	* Unless required by applicable law or agreed to in writing, software
	* distributed under the License is distributed on an "AS IS" BASIS,
	* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	* See the License for the specific language governing permissions and
	* limitations under the License.
	*/

	package android.util;

	import static com.android.internal.util.Preconditions.*;

	import android.hardware.camera2.utils.HashCodeHelpers;

	/**
	* Immutable class for describing the range of two numeric values.
	* <p>
	* A range (or "interval") defines the inclusive boundaries around a contiguous span of
	* values of some {@link Comparable} type; for example,
	* "integers from 1 to 100 inclusive."
	* </p>
	* <p>
	* All ranges are bounded, and the left side of the range is always {@code >=}
	* the right side of the range.
	* </p>
	*
	* <p>Although the implementation itself is immutable, there is no restriction that objects
	* stored must also be immutable. If mutable objects are stored here, then the range
	* effectively becomes mutable. </p>
	*/
	public final class Range<T extends Comparable<? super T>> {
	/**
	* Create a new immutable range.
	*
	* <p>
	* The endpoints are {@code [lower, upper]}; that
	* is the range is bounded. {@code lower} must be {@link Comparable#compareTo lesser or equal}
	* to {@code upper}.
	* </p>
	*
	* @param lower The lower endpoint (inclusive)
	* @param upper The upper endpoint (inclusive)
	*
	* @throws NullPointerException if {@code lower} or {@code upper} is {@code null}
	*/
	public Range(final T lower, final T upper) {
	mLower = checkNotNull(lower, "lower must not be null");
	mUpper = checkNotNull(upper, "upper must not be null");

	if (lower.compareTo(upper) > 0) {
	throw new IllegalArgumentException("lower must be less than or equal to upper");
	}
	}

	/**
	* Create a new immutable range, with the argument types inferred.
	*
	* <p>
	* The endpoints are {@code [lower, upper]}; that
	* is the range is bounded. {@code lower} must be {@link Comparable#compareTo lesser or equal}
	* to {@code upper}.
	* </p>
	*
	* @param lower The lower endpoint (inclusive)
	* @param upper The upper endpoint (inclusive)
	*
	* @throws NullPointerException if {@code lower} or {@code upper} is {@code null}
	*/
	public static <T extends Comparable<? super T>> Range<T> create(final T lower, final T upper) {
	return new Range<T>(lower, upper);
	}

	/**
	* Get the lower endpoint.
	*
	* @return a non-{@code null} {@code T} reference
	*/
	public T getLower() {
	return mLower;
	}

	/**
	* Get the upper endpoint.
	*
	* @return a non-{@code null} {@code T} reference
	*/
	public T getUpper() {
	return mUpper;
	}

	/**
	* Checks if the {@code value} is within the bounds of this range.
	*
	* <p>A value is considered to be within this range if it's {@code >=}
	* the lower endpoint <i>and</i> {@code <=} the upper endpoint (using the {@link Comparable}
	* interface.)</p>
	*
	* @param value a non-{@code null} {@code T} reference
	* @return {@code true} if the value is within this inclusive range, {@code false} otherwise
	*
	* @throws NullPointerException if {@code value} was {@code null}
	*/
	public boolean contains(T value) {
	checkNotNull(value, "value must not be null");

	boolean gteLower = value.compareTo(mLower) >= 0;
	boolean lteUpper = value.compareTo(mUpper) <= 0;

	return gteLower && lteUpper;
	}

	/**
	* Checks if another {@code range} is within the bounds of this range.
	*
	* <p>A range is considered to be within this range if both of its endpoints
	* are within this range.</p>
	*
	* @param range a non-{@code null} {@code T} reference
	* @return {@code true} if the range is within this inclusive range, {@code false} otherwise
	*
	* @throws NullPointerException if {@code range} was {@code null}
	*/
	public boolean contains(Range<T> range) {
	checkNotNull(range, "value must not be null");

	boolean gteLower = range.mLower.compareTo(mLower) >= 0;
	boolean lteUpper = range.mUpper.compareTo(mUpper) <= 0;

	return gteLower && lteUpper;
	}

	/**
	* Compare two ranges for equality.
	*
	* <p>A range is considered equal if and only if both the lower and upper endpoints
	* are also equal.</p>
	*
	* @return {@code true} if the ranges are equal, {@code false} otherwise
	*/
	@Override
	public boolean equals(Object obj) {
	if (obj == null) {
	return false;
	} else if (this == obj) {
	return true;
	} else if (obj instanceof Range) {
	@SuppressWarnings("rawtypes")
	Range other = (Range) obj;
	return mLower.equals(other.mLower) && mUpper.equals(other.mUpper);
	}
	return false;
	}

	/**
	* Clamps {@code value} to this range.
	*
	* <p>If the value is within this range, it is returned. Otherwise, if it
	* is {@code <} than the lower endpoint, the lower endpoint is returned,
	* else the upper endpoint is returned. Comparisons are performed using the
	* {@link Comparable} interface.</p>
	*
	* @param value a non-{@code null} {@code T} reference
	* @return {@code value} clamped to this range.
	*/
	public T clamp(T value) {
	checkNotNull(value, "value must not be null");

	if (value.compareTo(mLower) < 0) {
	return mLower;
	} else if (value.compareTo(mUpper) > 0) {
	return mUpper;
	} else {
	return value;
	}
	}

	/**
	* Returns the intersection of this range and another {@code range}.
	* <p>
	* E.g. if a {@code <} b {@code <} c {@code <} d, the
	* intersection of [a, c] and [b, d] ranges is [b, c].
	* As the endpoints are object references, there is no guarantee
	* which specific endpoint reference is used from the input ranges:</p>
	* <p>
	* E.g. if a {@code ==} a' {@code <} b {@code <} c, the
	* intersection of [a, b] and [a', c] ranges could be either
	* [a, b] or ['a, b], where [a, b] could be either the exact
	* input range, or a newly created range with the same endpoints.</p>
	*
	* @param range a non-{@code null} {@code Range<T>} reference
	* @return the intersection of this range and the other range.
	*
	* @throws NullPointerException if {@code range} was {@code null}
	* @throws IllegalArgumentException if the ranges are disjoint.
	*/
	public Range<T> intersect(Range<T> range) {
	checkNotNull(range, "range must not be null");

	int cmpLower = range.mLower.compareTo(mLower);
	int cmpUpper = range.mUpper.compareTo(mUpper);

	if (cmpLower <= 0 && cmpUpper >= 0) {
	// range includes this
	return this;
	} else if (cmpLower >= 0 && cmpUpper <= 0) {
	// this inludes range
	return range;
	} else {
	return Range.create(
	cmpLower <= 0 ? mLower : range.mLower,
	cmpUpper >= 0 ? mUpper : range.mUpper);
	}
	}

	/**
	* Returns the intersection of this range and the inclusive range
	* specified by {@code [lower, upper]}.
	* <p>
	* See {@link #intersect(Range)} for more details.</p>
	*
	* @param lower a non-{@code null} {@code T} reference
	* @param upper a non-{@code null} {@code T} reference
	* @return the intersection of this range and the other range
	*
	* @throws NullPointerException if {@code lower} or {@code upper} was {@code null}
	* @throws IllegalArgumentException if the ranges are disjoint.
	*/
	public Range<T> intersect(T lower, T upper) {
	checkNotNull(lower, "lower must not be null");
	checkNotNull(upper, "upper must not be null");

	int cmpLower = lower.compareTo(mLower);
	int cmpUpper = upper.compareTo(mUpper);

	if (cmpLower <= 0 && cmpUpper >= 0) {
	// [lower, upper] includes this
	return this;
	} else {
	return Range.create(
	cmpLower <= 0 ? mLower : lower,
	cmpUpper >= 0 ? mUpper : upper);
	}
	}

	/**
	* Returns the smallest range that includes this range and
	* another {@code range}.
	* <p>
	* E.g. if a {@code <} b {@code <} c {@code <} d, the
	* extension of [a, c] and [b, d] ranges is [a, d].
	* As the endpoints are object references, there is no guarantee
	* which specific endpoint reference is used from the input ranges:</p>
	* <p>
	* E.g. if a {@code ==} a' {@code <} b {@code <} c, the
	* extension of [a, b] and [a', c] ranges could be either
	* [a, c] or ['a, c], where ['a, c] could be either the exact
	* input range, or a newly created range with the same endpoints.</p>
	*
	* @param range a non-{@code null} {@code Range<T>} reference
	* @return the extension of this range and the other range.
	*
	* @throws NullPointerException if {@code range} was {@code null}
	*/
	public Range<T> extend(Range<T> range) {
	checkNotNull(range, "range must not be null");

	int cmpLower = range.mLower.compareTo(mLower);
	int cmpUpper = range.mUpper.compareTo(mUpper);

	if (cmpLower <= 0 && cmpUpper >= 0) {
	// other includes this
	return range;
	} else if (cmpLower >= 0 && cmpUpper <= 0) {
	// this inludes other
	return this;
	} else {
	return Range.create(
	cmpLower >= 0 ? mLower : range.mLower,
	cmpUpper <= 0 ? mUpper : range.mUpper);
	}
	}

	/**
	* Returns the smallest range that includes this range and
	* the inclusive range specified by {@code [lower, upper]}.
	* <p>
	* See {@link #extend(Range)} for more details.</p>
	*
	* @param lower a non-{@code null} {@code T} reference
	* @param upper a non-{@code null} {@code T} reference
	* @return the extension of this range and the other range.
	*
	* @throws NullPointerException if {@code lower} or {@code
	* upper} was {@code null}
	*/
	public Range<T> extend(T lower, T upper) {
	checkNotNull(lower, "lower must not be null");
	checkNotNull(upper, "upper must not be null");

	int cmpLower = lower.compareTo(mLower);
	int cmpUpper = upper.compareTo(mUpper);

	if (cmpLower >= 0 && cmpUpper <= 0) {
	// this inludes other
	return this;
	} else {
	return Range.create(
	cmpLower >= 0 ? mLower : lower,
	cmpUpper <= 0 ? mUpper : upper);
	}
	}

	/**
	* Returns the smallest range that includes this range and
	* the {@code value}.
	* <p>
	* See {@link #extend(Range)} for more details, as this method is
	* equivalent to {@code extend(Range.create(value, value))}.</p>
	*
	* @param value a non-{@code null} {@code T} reference
	* @return the extension of this range and the value.
	*
	* @throws NullPointerException if {@code value} was {@code null}
	*/
	public Range<T> extend(T value) {
	checkNotNull(value, "value must not be null");
	return extend(value, value);
	}

	/**
	* Return the range as a string representation {@code "[lower, upper]"}.
	*
	* @return string representation of the range
	*/
	@Override
	public String toString() {
	return String.format("[%s, %s]", mLower, mUpper);
	}

	/**
	* {@inheritDoc}
	*/
	@Override
	public int hashCode() {
	return HashCodeHelpers.hashCodeGeneric(mLower, mUpper);
	}

	private final T mLower;
	private final T mUpper;
	};