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 21 import android.hardware.camera2.utils.HashCodeHelpers; 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> 31 * All ranges are bounded, and the left side of the range is always {@code >=} 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 /** 100 * Checks if the {@code value} is within the bounds of this range. 101 * 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> 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 */ 111 public boolean contains(T value) { 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 /** 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 /** 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 149 public boolean equals(Object obj) { 150 if (obj == null) { 151 return false; 152 } else if (this == obj) { 153 return true; 154 } else if (obj instanceof Range) { 155 @SuppressWarnings("rawtypes") 156 Range other = (Range) obj; 157 return mLower.equals(other.mLower) && mUpper.equals(other.mUpper); 158 } 159 return false; 160 } 161 162 /** 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 /** 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() { 353 return HashCodeHelpers.hashCodeGeneric(mLower, mUpper); 354 } 355 356 private final T mLower; 357 private final T mUpper; 358 }; 359
