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
17package android.util;
18
19import static com.android.internal.util.Preconditions.*;
20
21import 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 */
39public 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