Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2014 The Android Open Source Project |
| 3 | * |
| 4 | * Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | * you may not use this file except in compliance with the License. |
| 6 | * You may obtain a copy of the License at |
| 7 | * |
| 8 | * http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | * |
| 10 | * Unless required by applicable law or agreed to in writing, software |
| 11 | * distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | * See the License for the specific language governing permissions and |
| 14 | * limitations under the License. |
| 15 | */ |
| 16 | |
| 17 | package android.util; |
| 18 | |
| 19 | import static com.android.internal.util.Preconditions.*; |
| 20 | |
Igor Murashkin | 3c40a04 | 2014-04-22 15:05:50 -0700 | [diff] [blame] | 21 | import android.hardware.camera2.utils.HashCodeHelpers; |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 22 | |
| 23 | /** |
| 24 | * Immutable class for describing the range of two numeric values. |
| 25 | * <p> |
| 26 | * A range (or "interval") defines the inclusive boundaries around a contiguous span of |
| 27 | * values of some {@link Comparable} type; for example, |
| 28 | * "integers from 1 to 100 inclusive." |
| 29 | * </p> |
| 30 | * <p> |
Gopalakrishnan Nallasamy | ad1c854 | 2019-01-02 14:22:09 -0800 | [diff] [blame] | 31 | * All ranges are bounded, and the left side of the range is always {@code <=} |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 32 | * the right side of the range. |
| 33 | * </p> |
| 34 | * |
| 35 | * <p>Although the implementation itself is immutable, there is no restriction that objects |
| 36 | * stored must also be immutable. If mutable objects are stored here, then the range |
| 37 | * effectively becomes mutable. </p> |
| 38 | */ |
| 39 | public final class Range<T extends Comparable<? super T>> { |
| 40 | /** |
| 41 | * Create a new immutable range. |
| 42 | * |
| 43 | * <p> |
| 44 | * The endpoints are {@code [lower, upper]}; that |
| 45 | * is the range is bounded. {@code lower} must be {@link Comparable#compareTo lesser or equal} |
| 46 | * to {@code upper}. |
| 47 | * </p> |
| 48 | * |
| 49 | * @param lower The lower endpoint (inclusive) |
| 50 | * @param upper The upper endpoint (inclusive) |
| 51 | * |
| 52 | * @throws NullPointerException if {@code lower} or {@code upper} is {@code null} |
| 53 | */ |
| 54 | public Range(final T lower, final T upper) { |
| 55 | mLower = checkNotNull(lower, "lower must not be null"); |
| 56 | mUpper = checkNotNull(upper, "upper must not be null"); |
| 57 | |
| 58 | if (lower.compareTo(upper) > 0) { |
| 59 | throw new IllegalArgumentException("lower must be less than or equal to upper"); |
| 60 | } |
| 61 | } |
| 62 | |
| 63 | /** |
| 64 | * Create a new immutable range, with the argument types inferred. |
| 65 | * |
| 66 | * <p> |
| 67 | * The endpoints are {@code [lower, upper]}; that |
| 68 | * is the range is bounded. {@code lower} must be {@link Comparable#compareTo lesser or equal} |
| 69 | * to {@code upper}. |
| 70 | * </p> |
| 71 | * |
| 72 | * @param lower The lower endpoint (inclusive) |
| 73 | * @param upper The upper endpoint (inclusive) |
| 74 | * |
| 75 | * @throws NullPointerException if {@code lower} or {@code upper} is {@code null} |
| 76 | */ |
| 77 | public static <T extends Comparable<? super T>> Range<T> create(final T lower, final T upper) { |
| 78 | return new Range<T>(lower, upper); |
| 79 | } |
| 80 | |
| 81 | /** |
| 82 | * Get the lower endpoint. |
| 83 | * |
| 84 | * @return a non-{@code null} {@code T} reference |
| 85 | */ |
| 86 | public T getLower() { |
| 87 | return mLower; |
| 88 | } |
| 89 | |
| 90 | /** |
| 91 | * Get the upper endpoint. |
| 92 | * |
| 93 | * @return a non-{@code null} {@code T} reference |
| 94 | */ |
| 95 | public T getUpper() { |
| 96 | return mUpper; |
| 97 | } |
| 98 | |
| 99 | /** |
Igor Murashkin | 007bfb1 | 2014-06-05 18:02:22 -0700 | [diff] [blame] | 100 | * Checks if the {@code value} is within the bounds of this range. |
| 101 | * |
Lajos Molnar | b1a236b | 2014-07-11 00:54:50 -0700 | [diff] [blame] | 102 | * <p>A value is considered to be within this range if it's {@code >=} |
| 103 | * the lower endpoint <i>and</i> {@code <=} the upper endpoint (using the {@link Comparable} |
| 104 | * interface.)</p> |
Igor Murashkin | 007bfb1 | 2014-06-05 18:02:22 -0700 | [diff] [blame] | 105 | * |
| 106 | * @param value a non-{@code null} {@code T} reference |
| 107 | * @return {@code true} if the value is within this inclusive range, {@code false} otherwise |
| 108 | * |
| 109 | * @throws NullPointerException if {@code value} was {@code null} |
| 110 | */ |
Lajos Molnar | b1a236b | 2014-07-11 00:54:50 -0700 | [diff] [blame] | 111 | public boolean contains(T value) { |
Igor Murashkin | 007bfb1 | 2014-06-05 18:02:22 -0700 | [diff] [blame] | 112 | checkNotNull(value, "value must not be null"); |
| 113 | |
| 114 | boolean gteLower = value.compareTo(mLower) >= 0; |
| 115 | boolean lteUpper = value.compareTo(mUpper) <= 0; |
| 116 | |
| 117 | return gteLower && lteUpper; |
| 118 | } |
| 119 | |
| 120 | /** |
Lajos Molnar | b1a236b | 2014-07-11 00:54:50 -0700 | [diff] [blame] | 121 | * Checks if another {@code range} is within the bounds of this range. |
| 122 | * |
| 123 | * <p>A range is considered to be within this range if both of its endpoints |
| 124 | * are within this range.</p> |
| 125 | * |
| 126 | * @param range a non-{@code null} {@code T} reference |
| 127 | * @return {@code true} if the range is within this inclusive range, {@code false} otherwise |
| 128 | * |
| 129 | * @throws NullPointerException if {@code range} was {@code null} |
| 130 | */ |
| 131 | public boolean contains(Range<T> range) { |
| 132 | checkNotNull(range, "value must not be null"); |
| 133 | |
| 134 | boolean gteLower = range.mLower.compareTo(mLower) >= 0; |
| 135 | boolean lteUpper = range.mUpper.compareTo(mUpper) <= 0; |
| 136 | |
| 137 | return gteLower && lteUpper; |
| 138 | } |
| 139 | |
| 140 | /** |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 141 | * Compare two ranges for equality. |
| 142 | * |
| 143 | * <p>A range is considered equal if and only if both the lower and upper endpoints |
| 144 | * are also equal.</p> |
| 145 | * |
| 146 | * @return {@code true} if the ranges are equal, {@code false} otherwise |
| 147 | */ |
| 148 | @Override |
Igor Murashkin | 007bfb1 | 2014-06-05 18:02:22 -0700 | [diff] [blame] | 149 | public boolean equals(Object obj) { |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 150 | if (obj == null) { |
| 151 | return false; |
Igor Murashkin | 007bfb1 | 2014-06-05 18:02:22 -0700 | [diff] [blame] | 152 | } else if (this == obj) { |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 153 | return true; |
Igor Murashkin | 007bfb1 | 2014-06-05 18:02:22 -0700 | [diff] [blame] | 154 | } else if (obj instanceof Range) { |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 155 | @SuppressWarnings("rawtypes") |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 156 | Range other = (Range) obj; |
| 157 | return mLower.equals(other.mLower) && mUpper.equals(other.mUpper); |
| 158 | } |
| 159 | return false; |
| 160 | } |
| 161 | |
| 162 | /** |
Lajos Molnar | b1a236b | 2014-07-11 00:54:50 -0700 | [diff] [blame] | 163 | * Clamps {@code value} to this range. |
| 164 | * |
| 165 | * <p>If the value is within this range, it is returned. Otherwise, if it |
| 166 | * is {@code <} than the lower endpoint, the lower endpoint is returned, |
| 167 | * else the upper endpoint is returned. Comparisons are performed using the |
| 168 | * {@link Comparable} interface.</p> |
| 169 | * |
| 170 | * @param value a non-{@code null} {@code T} reference |
| 171 | * @return {@code value} clamped to this range. |
| 172 | */ |
| 173 | public T clamp(T value) { |
| 174 | checkNotNull(value, "value must not be null"); |
| 175 | |
| 176 | if (value.compareTo(mLower) < 0) { |
| 177 | return mLower; |
| 178 | } else if (value.compareTo(mUpper) > 0) { |
| 179 | return mUpper; |
| 180 | } else { |
| 181 | return value; |
| 182 | } |
| 183 | } |
| 184 | |
| 185 | /** |
| 186 | * Returns the intersection of this range and another {@code range}. |
| 187 | * <p> |
| 188 | * E.g. if a {@code <} b {@code <} c {@code <} d, the |
| 189 | * intersection of [a, c] and [b, d] ranges is [b, c]. |
| 190 | * As the endpoints are object references, there is no guarantee |
| 191 | * which specific endpoint reference is used from the input ranges:</p> |
| 192 | * <p> |
| 193 | * E.g. if a {@code ==} a' {@code <} b {@code <} c, the |
| 194 | * intersection of [a, b] and [a', c] ranges could be either |
| 195 | * [a, b] or ['a, b], where [a, b] could be either the exact |
| 196 | * input range, or a newly created range with the same endpoints.</p> |
| 197 | * |
| 198 | * @param range a non-{@code null} {@code Range<T>} reference |
| 199 | * @return the intersection of this range and the other range. |
| 200 | * |
| 201 | * @throws NullPointerException if {@code range} was {@code null} |
| 202 | * @throws IllegalArgumentException if the ranges are disjoint. |
| 203 | */ |
| 204 | public Range<T> intersect(Range<T> range) { |
| 205 | checkNotNull(range, "range must not be null"); |
| 206 | |
| 207 | int cmpLower = range.mLower.compareTo(mLower); |
| 208 | int cmpUpper = range.mUpper.compareTo(mUpper); |
| 209 | |
| 210 | if (cmpLower <= 0 && cmpUpper >= 0) { |
| 211 | // range includes this |
| 212 | return this; |
| 213 | } else if (cmpLower >= 0 && cmpUpper <= 0) { |
| 214 | // this inludes range |
| 215 | return range; |
| 216 | } else { |
| 217 | return Range.create( |
| 218 | cmpLower <= 0 ? mLower : range.mLower, |
| 219 | cmpUpper >= 0 ? mUpper : range.mUpper); |
| 220 | } |
| 221 | } |
| 222 | |
| 223 | /** |
| 224 | * Returns the intersection of this range and the inclusive range |
| 225 | * specified by {@code [lower, upper]}. |
| 226 | * <p> |
| 227 | * See {@link #intersect(Range)} for more details.</p> |
| 228 | * |
| 229 | * @param lower a non-{@code null} {@code T} reference |
| 230 | * @param upper a non-{@code null} {@code T} reference |
| 231 | * @return the intersection of this range and the other range |
| 232 | * |
| 233 | * @throws NullPointerException if {@code lower} or {@code upper} was {@code null} |
| 234 | * @throws IllegalArgumentException if the ranges are disjoint. |
| 235 | */ |
| 236 | public Range<T> intersect(T lower, T upper) { |
| 237 | checkNotNull(lower, "lower must not be null"); |
| 238 | checkNotNull(upper, "upper must not be null"); |
| 239 | |
| 240 | int cmpLower = lower.compareTo(mLower); |
| 241 | int cmpUpper = upper.compareTo(mUpper); |
| 242 | |
| 243 | if (cmpLower <= 0 && cmpUpper >= 0) { |
| 244 | // [lower, upper] includes this |
| 245 | return this; |
| 246 | } else { |
| 247 | return Range.create( |
| 248 | cmpLower <= 0 ? mLower : lower, |
| 249 | cmpUpper >= 0 ? mUpper : upper); |
| 250 | } |
| 251 | } |
| 252 | |
| 253 | /** |
| 254 | * Returns the smallest range that includes this range and |
| 255 | * another {@code range}. |
| 256 | * <p> |
| 257 | * E.g. if a {@code <} b {@code <} c {@code <} d, the |
| 258 | * extension of [a, c] and [b, d] ranges is [a, d]. |
| 259 | * As the endpoints are object references, there is no guarantee |
| 260 | * which specific endpoint reference is used from the input ranges:</p> |
| 261 | * <p> |
| 262 | * E.g. if a {@code ==} a' {@code <} b {@code <} c, the |
| 263 | * extension of [a, b] and [a', c] ranges could be either |
| 264 | * [a, c] or ['a, c], where ['a, c] could be either the exact |
| 265 | * input range, or a newly created range with the same endpoints.</p> |
| 266 | * |
| 267 | * @param range a non-{@code null} {@code Range<T>} reference |
| 268 | * @return the extension of this range and the other range. |
| 269 | * |
| 270 | * @throws NullPointerException if {@code range} was {@code null} |
| 271 | */ |
| 272 | public Range<T> extend(Range<T> range) { |
| 273 | checkNotNull(range, "range must not be null"); |
| 274 | |
| 275 | int cmpLower = range.mLower.compareTo(mLower); |
| 276 | int cmpUpper = range.mUpper.compareTo(mUpper); |
| 277 | |
| 278 | if (cmpLower <= 0 && cmpUpper >= 0) { |
| 279 | // other includes this |
| 280 | return range; |
| 281 | } else if (cmpLower >= 0 && cmpUpper <= 0) { |
| 282 | // this inludes other |
| 283 | return this; |
| 284 | } else { |
| 285 | return Range.create( |
| 286 | cmpLower >= 0 ? mLower : range.mLower, |
| 287 | cmpUpper <= 0 ? mUpper : range.mUpper); |
| 288 | } |
| 289 | } |
| 290 | |
| 291 | /** |
| 292 | * Returns the smallest range that includes this range and |
| 293 | * the inclusive range specified by {@code [lower, upper]}. |
| 294 | * <p> |
| 295 | * See {@link #extend(Range)} for more details.</p> |
| 296 | * |
| 297 | * @param lower a non-{@code null} {@code T} reference |
| 298 | * @param upper a non-{@code null} {@code T} reference |
| 299 | * @return the extension of this range and the other range. |
| 300 | * |
| 301 | * @throws NullPointerException if {@code lower} or {@code |
| 302 | * upper} was {@code null} |
| 303 | */ |
| 304 | public Range<T> extend(T lower, T upper) { |
| 305 | checkNotNull(lower, "lower must not be null"); |
| 306 | checkNotNull(upper, "upper must not be null"); |
| 307 | |
| 308 | int cmpLower = lower.compareTo(mLower); |
| 309 | int cmpUpper = upper.compareTo(mUpper); |
| 310 | |
| 311 | if (cmpLower >= 0 && cmpUpper <= 0) { |
| 312 | // this inludes other |
| 313 | return this; |
| 314 | } else { |
| 315 | return Range.create( |
| 316 | cmpLower >= 0 ? mLower : lower, |
| 317 | cmpUpper <= 0 ? mUpper : upper); |
| 318 | } |
| 319 | } |
| 320 | |
| 321 | /** |
| 322 | * Returns the smallest range that includes this range and |
| 323 | * the {@code value}. |
| 324 | * <p> |
| 325 | * See {@link #extend(Range)} for more details, as this method is |
| 326 | * equivalent to {@code extend(Range.create(value, value))}.</p> |
| 327 | * |
| 328 | * @param value a non-{@code null} {@code T} reference |
| 329 | * @return the extension of this range and the value. |
| 330 | * |
| 331 | * @throws NullPointerException if {@code value} was {@code null} |
| 332 | */ |
| 333 | public Range<T> extend(T value) { |
| 334 | checkNotNull(value, "value must not be null"); |
| 335 | return extend(value, value); |
| 336 | } |
| 337 | |
| 338 | /** |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 339 | * Return the range as a string representation {@code "[lower, upper]"}. |
| 340 | * |
| 341 | * @return string representation of the range |
| 342 | */ |
| 343 | @Override |
| 344 | public String toString() { |
| 345 | return String.format("[%s, %s]", mLower, mUpper); |
| 346 | } |
| 347 | |
| 348 | /** |
| 349 | * {@inheritDoc} |
| 350 | */ |
| 351 | @Override |
| 352 | public int hashCode() { |
Eino-Ville Talvala | 0819c75 | 2015-06-17 11:34:41 -0700 | [diff] [blame] | 353 | return HashCodeHelpers.hashCodeGeneric(mLower, mUpper); |
Igor Murashkin | b3a78b2 | 2014-04-17 14:01:13 -0700 | [diff] [blame] | 354 | } |
| 355 | |
| 356 | private final T mLower; |
| 357 | private final T mUpper; |
| 358 | }; |