| /* | |
| * 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.annotation.Nullable; | |
| 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(@Nullable 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; | |
| } |