OpenShot Library | libopenshot-audio 0.2.0
juce_Range.h
1
2/** @weakgroup juce_core-maths
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/** A general-purpose range object, that simply represents any linear range with
32 a start and end point.
33
34 Note that when checking whether values fall within the range, the start value is
35 considered to be inclusive, and the end of the range exclusive.
36
37 The templated parameter is expected to be a primitive integer or floating point
38 type, though class types could also be used if they behave in a number-like way.
39
40 @tags{Core}
41*/
42template <typename ValueType>
43class Range
44{
45public:
46 //==============================================================================
47 /** Constructs an empty range. */
48 JUCE_CONSTEXPR Range() = default;
49
50 /** Constructs a range with given start and end values. */
51 JUCE_CONSTEXPR Range (const ValueType startValue, const ValueType endValue) noexcept
52 : start (startValue), end (jmax (startValue, endValue))
53 {
54 }
55
56 /** Constructs a copy of another range. */
57 JUCE_CONSTEXPR Range (const Range&) = default;
58
59 /** Copies another range object. */
60 Range& operator= (const Range&) = default;
61
62 /** Returns the range that lies between two positions (in either order). */
63 JUCE_CONSTEXPR static Range between (const ValueType position1, const ValueType position2) noexcept
64 {
65 return position1 < position2 ? Range (position1, position2)
66 : Range (position2, position1);
67 }
68
69 /** Returns a range with a given start and length. */
70 static Range withStartAndLength (const ValueType startValue, const ValueType length) noexcept
71 {
72 jassert (length >= ValueType());
73 return Range (startValue, startValue + length);
74 }
75
76 /** Returns a range with the specified start position and a length of zero. */
77 JUCE_CONSTEXPR static Range emptyRange (const ValueType start) noexcept
78 {
79 return Range (start, start);
80 }
81
82 //==============================================================================
83 /** Returns the start of the range. */
84 JUCE_CONSTEXPR inline ValueType getStart() const noexcept { return start; }
85
86 /** Returns the length of the range. */
87 JUCE_CONSTEXPR inline ValueType getLength() const noexcept { return end - start; }
88
89 /** Returns the end of the range. */
90 JUCE_CONSTEXPR inline ValueType getEnd() const noexcept { return end; }
91
92 /** Returns true if the range has a length of zero. */
93 JUCE_CONSTEXPR inline bool isEmpty() const noexcept { return start == end; }
94
95 //==============================================================================
96 /** Changes the start position of the range, leaving the end position unchanged.
97 If the new start position is higher than the current end of the range, the end point
98 will be pushed along to equal it, leaving an empty range at the new position.
99 */
100 void setStart (const ValueType newStart) noexcept
101 {
102 start = newStart;
103 if (end < newStart)
104 end = newStart;
105 }
106
107 /** Returns a range with the same end as this one, but a different start.
108 If the new start position is higher than the current end of the range, the end point
109 will be pushed along to equal it, returning an empty range at the new position.
110 */
111 JUCE_CONSTEXPR Range withStart (const ValueType newStart) const noexcept
112 {
113 return Range (newStart, jmax (newStart, end));
114 }
115
116 /** Returns a range with the same length as this one, but moved to have the given start position. */
117 JUCE_CONSTEXPR Range movedToStartAt (const ValueType newStart) const noexcept
118 {
119 return Range (newStart, end + (newStart - start));
120 }
121
122 /** Changes the end position of the range, leaving the start unchanged.
123 If the new end position is below the current start of the range, the start point
124 will be pushed back to equal the new end point.
125 */
126 void setEnd (const ValueType newEnd) noexcept
127 {
128 end = newEnd;
129 if (newEnd < start)
130 start = newEnd;
131 }
132
133 /** Returns a range with the same start position as this one, but a different end.
134 If the new end position is below the current start of the range, the start point
135 will be pushed back to equal the new end point.
136 */
137 JUCE_CONSTEXPR Range withEnd (const ValueType newEnd) const noexcept
138 {
139 return Range (jmin (start, newEnd), newEnd);
140 }
141
142 /** Returns a range with the same length as this one, but moved to have the given end position. */
143 JUCE_CONSTEXPR Range movedToEndAt (const ValueType newEnd) const noexcept
144 {
145 return Range (start + (newEnd - end), newEnd);
146 }
147
148 /** Changes the length of the range.
149 Lengths less than zero are treated as zero.
150 */
151 void setLength (const ValueType newLength) noexcept
152 {
153 end = start + jmax (ValueType(), newLength);
154 }
155
156 /** Returns a range with the same start as this one, but a different length.
157 Lengths less than zero are treated as zero.
158 */
159 JUCE_CONSTEXPR Range withLength (const ValueType newLength) const noexcept
160 {
161 return Range (start, start + newLength);
162 }
163
164 /** Returns a range which has its start moved down and its end moved up by the
165 given amount.
166 @returns The returned range will be (start - amount, end + amount)
167 */
168 JUCE_CONSTEXPR Range expanded (ValueType amount) const noexcept
169 {
170 return Range (start - amount, end + amount);
171 }
172
173 //==============================================================================
174 /** Adds an amount to the start and end of the range. */
175 inline Range operator+= (const ValueType amountToAdd) noexcept
176 {
177 start += amountToAdd;
178 end += amountToAdd;
179 return *this;
180 }
181
182 /** Subtracts an amount from the start and end of the range. */
183 inline Range operator-= (const ValueType amountToSubtract) noexcept
184 {
185 start -= amountToSubtract;
186 end -= amountToSubtract;
187 return *this;
188 }
189
190 /** Returns a range that is equal to this one with an amount added to its
191 start and end.
192 */
193 JUCE_CONSTEXPR Range operator+ (const ValueType amountToAdd) const noexcept
194 {
195 return Range (start + amountToAdd, end + amountToAdd);
196 }
197
198 /** Returns a range that is equal to this one with the specified amount
199 subtracted from its start and end. */
200 JUCE_CONSTEXPR Range operator- (const ValueType amountToSubtract) const noexcept
201 {
202 return Range (start - amountToSubtract, end - amountToSubtract);
203 }
204
205 JUCE_CONSTEXPR bool operator== (Range other) const noexcept { return start == other.start && end == other.end; }
206 JUCE_CONSTEXPR bool operator!= (Range other) const noexcept { return start != other.start || end != other.end; }
207
208 //==============================================================================
209 /** Returns true if the given position lies inside this range.
210 When making this comparison, the start value is considered to be inclusive,
211 and the end of the range exclusive.
212 */
213 JUCE_CONSTEXPR bool contains (const ValueType position) const noexcept
214 {
215 return start <= position && position < end;
216 }
217
218 /** Returns the nearest value to the one supplied, which lies within the range. */
219 ValueType clipValue (const ValueType value) const noexcept
220 {
221 return jlimit (start, end, value);
222 }
223
224 /** Returns true if the given range lies entirely inside this range. */
225 JUCE_CONSTEXPR bool contains (Range other) const noexcept
226 {
227 return start <= other.start && end >= other.end;
228 }
229
230 /** Returns true if the given range intersects this one. */
231 JUCE_CONSTEXPR bool intersects (Range other) const noexcept
232 {
233 return other.start < end && start < other.end;
234 }
235
236 /** Returns the range that is the intersection of the two ranges, or an empty range
237 with an undefined start position if they don't overlap. */
238 JUCE_CONSTEXPR Range getIntersectionWith (Range other) const noexcept
239 {
240 return Range (jmax (start, other.start),
241 jmin (end, other.end));
242 }
243
244 /** Returns the smallest range that contains both this one and the other one. */
245 JUCE_CONSTEXPR Range getUnionWith (Range other) const noexcept
246 {
247 return Range (jmin (start, other.start),
248 jmax (end, other.end));
249 }
250
251 /** Returns the smallest range that contains both this one and the given value. */
252 JUCE_CONSTEXPR Range getUnionWith (const ValueType valueToInclude) const noexcept
253 {
254 return Range (jmin (valueToInclude, start),
255 jmax (valueToInclude, end));
256 }
257
258 /** Returns a given range, after moving it forwards or backwards to fit it
259 within this range.
260
261 If the supplied range has a greater length than this one, the return value
262 will be this range.
263
264 Otherwise, if the supplied range is smaller than this one, the return value
265 will be the new range, shifted forwards or backwards so that it doesn't extend
266 beyond this one, but keeping its original length.
267 */
268 Range constrainRange (Range rangeToConstrain) const noexcept
269 {
270 const ValueType otherLen = rangeToConstrain.getLength();
271 return getLength() <= otherLen
272 ? *this
273 : rangeToConstrain.movedToStartAt (jlimit (start, end - otherLen, rangeToConstrain.getStart()));
274 }
275
276 /** Scans an array of values for its min and max, and returns these as a Range. */
277 static Range findMinAndMax (const ValueType* values, int numValues) noexcept
278 {
279 if (numValues <= 0)
280 return Range();
281
282 const ValueType first (*values++);
283 Range r (first, first);
284
285 while (--numValues > 0) // (> 0 rather than >= 0 because we've already taken the first sample)
286 {
287 const ValueType v (*values++);
288
289 if (r.end < v) r.end = v;
290 if (v < r.start) r.start = v;
291 }
292
293 return r;
294 }
295
296private:
297 //==============================================================================
298 ValueType start{}, end{};
299};
300
301} // namespace juce
302
303/** @}*/
A general-purpose range object, that simply represents any linear range with a start and end point.
Definition juce_Range.h:44
static Range withStartAndLength(const ValueType startValue, const ValueType length) noexcept
Returns a range with a given start and length.
Definition juce_Range.h:70
void setEnd(const ValueType newEnd) noexcept
Changes the end position of the range, leaving the start unchanged.
Definition juce_Range.h:126
Range constrainRange(Range rangeToConstrain) const noexcept
Returns a given range, after moving it forwards or backwards to fit it within this range.
Definition juce_Range.h:268
JUCE_CONSTEXPR Range withEnd(const ValueType newEnd) const noexcept
Returns a range with the same start position as this one, but a different end.
Definition juce_Range.h:137
JUCE_CONSTEXPR Range getIntersectionWith(Range other) const noexcept
Returns the range that is the intersection of the two ranges, or an empty range with an undefined sta...
Definition juce_Range.h:238
JUCE_CONSTEXPR Range expanded(ValueType amount) const noexcept
Returns a range which has its start moved down and its end moved up by the given amount.
Definition juce_Range.h:168
JUCE_CONSTEXPR Range withStart(const ValueType newStart) const noexcept
Returns a range with the same end as this one, but a different start.
Definition juce_Range.h:111
JUCE_CONSTEXPR ValueType getStart() const noexcept
Returns the start of the range.
Definition juce_Range.h:84
JUCE_CONSTEXPR Range operator+(const ValueType amountToAdd) const noexcept
Returns a range that is equal to this one with an amount added to its start and end.
Definition juce_Range.h:193
JUCE_CONSTEXPR Range movedToEndAt(const ValueType newEnd) const noexcept
Returns a range with the same length as this one, but moved to have the given end position.
Definition juce_Range.h:143
JUCE_CONSTEXPR bool contains(const ValueType position) const noexcept
Returns true if the given position lies inside this range.
Definition juce_Range.h:213
JUCE_CONSTEXPR Range operator-(const ValueType amountToSubtract) const noexcept
Returns a range that is equal to this one with the specified amount subtracted from its start and end...
Definition juce_Range.h:200
JUCE_CONSTEXPR Range withLength(const ValueType newLength) const noexcept
Returns a range with the same start as this one, but a different length.
Definition juce_Range.h:159
JUCE_CONSTEXPR bool isEmpty() const noexcept
Returns true if the range has a length of zero.
Definition juce_Range.h:93
JUCE_CONSTEXPR Range()=default
Constructs an empty range.
ValueType clipValue(const ValueType value) const noexcept
Returns the nearest value to the one supplied, which lies within the range.
Definition juce_Range.h:219
JUCE_CONSTEXPR ValueType getLength() const noexcept
Returns the length of the range.
Definition juce_Range.h:87
static Range findMinAndMax(const ValueType *values, int numValues) noexcept
Scans an array of values for its min and max, and returns these as a Range.
Definition juce_Range.h:277
Range operator+=(const ValueType amountToAdd) noexcept
Adds an amount to the start and end of the range.
Definition juce_Range.h:175
JUCE_CONSTEXPR Range(const ValueType startValue, const ValueType endValue) noexcept
Constructs a range with given start and end values.
Definition juce_Range.h:51
JUCE_CONSTEXPR bool intersects(Range other) const noexcept
Returns true if the given range intersects this one.
Definition juce_Range.h:231
static JUCE_CONSTEXPR Range between(const ValueType position1, const ValueType position2) noexcept
Returns the range that lies between two positions (in either order).
Definition juce_Range.h:63
void setLength(const ValueType newLength) noexcept
Changes the length of the range.
Definition juce_Range.h:151
void setStart(const ValueType newStart) noexcept
Changes the start position of the range, leaving the end position unchanged.
Definition juce_Range.h:100
Range & operator=(const Range &)=default
Copies another range object.
JUCE_CONSTEXPR Range(const Range &)=default
Constructs a copy of another range.
JUCE_CONSTEXPR bool contains(Range other) const noexcept
Returns true if the given range lies entirely inside this range.
Definition juce_Range.h:225
Range operator-=(const ValueType amountToSubtract) noexcept
Subtracts an amount from the start and end of the range.
Definition juce_Range.h:183
JUCE_CONSTEXPR Range getUnionWith(Range other) const noexcept
Returns the smallest range that contains both this one and the other one.
Definition juce_Range.h:245
JUCE_CONSTEXPR Range getUnionWith(const ValueType valueToInclude) const noexcept
Returns the smallest range that contains both this one and the given value.
Definition juce_Range.h:252
static JUCE_CONSTEXPR Range emptyRange(const ValueType start) noexcept
Returns a range with the specified start position and a length of zero.
Definition juce_Range.h:77
JUCE_CONSTEXPR ValueType getEnd() const noexcept
Returns the end of the range.
Definition juce_Range.h:90
JUCE_CONSTEXPR Range movedToStartAt(const ValueType newStart) const noexcept
Returns a range with the same length as this one, but moved to have the given start position.
Definition juce_Range.h:117