1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * https://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18 package org.apache.commons.lang3;
19
20 import java.util.stream.LongStream;
21
22 /**
23 * Specializes {@link NumberRange} for {@link Long}s.
24 *
25 * <p>
26 * This class is not designed to interoperate with other NumberRanges
27 * </p>
28 *
29 * @since 3.13.0
30 */
31 public final class LongRange extends NumberRange<Long> {
32
33 private static final long serialVersionUID = 1L;
34
35 /**
36 * Creates a closed range with the specified minimum and maximum values (both inclusive).
37 *
38 * <p>
39 * The range uses the natural ordering of the elements to determine where values lie in the range.
40 * </p>
41 *
42 * <p>
43 * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
44 * </p>
45 *
46 * @param fromInclusive the first value that defines the edge of the range, inclusive.
47 * @param toInclusive the second value that defines the edge of the range, inclusive.
48 * @return the range object, not null.
49 */
50 public static LongRange of(final long fromInclusive, final long toInclusive) {
51 return of(Long.valueOf(fromInclusive), Long.valueOf(toInclusive));
52 }
53
54 /**
55 * Creates a closed range with the specified minimum and maximum values (both inclusive).
56 *
57 * <p>
58 * The range uses the natural ordering of the elements to determine where values lie in the range.
59 * </p>
60 *
61 * <p>
62 * The arguments may be passed in the order (min,max) or (max,min). The getMinimum and getMaximum methods will return the correct values.
63 * </p>
64 *
65 * @param fromInclusive the first value that defines the edge of the range, inclusive.
66 * @param toInclusive the second value that defines the edge of the range, inclusive.
67 * @return the range object, not null.
68 * @throws IllegalArgumentException if either element is null.
69 */
70 public static LongRange of(final Long fromInclusive, final Long toInclusive) {
71 return new LongRange(fromInclusive, toInclusive);
72 }
73
74 /**
75 * Creates a new instance.
76 *
77 * @param number1 the first element, not null
78 * @param number2 the second element, not null
79 * @throws NullPointerException when element1 is null.
80 * @throws NullPointerException when element2 is null.
81 */
82 private LongRange(final Long number1, final Long number2) {
83 super(number1, number2, null);
84 }
85
86 /**
87 * Fits the given value into this range by returning the given value or, if out of bounds, the range minimum if
88 * below, or the range maximum if above.
89 *
90 * <pre>{@code
91 * LongRange range = LongRange.of(16, 64);
92 * range.fit(-9) --> 16
93 * range.fit(0) --> 16
94 * range.fit(15) --> 16
95 * range.fit(16) --> 16
96 * range.fit(17) --> 17
97 * ...
98 * range.fit(63) --> 63
99 * range.fit(64) --> 64
100 * range.fit(99) --> 64
101 * }</pre>
102 *
103 * @param element the element to test.
104 * @return the minimum, the element, or the maximum depending on the element's location relative to the range.
105 * @since 3.19.0
106 */
107 public long fit(final long element) {
108 return super.fit(element).longValue();
109 }
110
111 /**
112 * Returns a sequential ordered {@code LongStream} from {@link #getMinimum()} (inclusive) to {@link #getMaximum()} (inclusive) by an incremental step of
113 * {@code 1}.
114 *
115 * @return a sequential {@code LongStream} for the range of {@code long} elements
116 * @since 3.18.0
117 */
118 public LongStream toLongStream() {
119 return LongStream.rangeClosed(getMinimum(), getMaximum());
120 }
121
122 }