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 
27 namespace 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 */
42 template <typename ValueType>
43 class Range
44 {
45 public:
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 
296 private:
297  //==============================================================================
298  ValueType start{}, end{};
299 };
300 
301 } // namespace juce
302 
303 /** @}*/
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
void setEnd(const ValueType newEnd) noexcept
Changes the end position of the range, leaving the start unchanged.
Definition: juce_Range.h:126
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
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 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
void setLength(const ValueType newLength) noexcept
Changes the length of the range.
Definition: juce_Range.h:151
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
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 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 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 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
Range & operator=(const Range &)=default
Copies another range object.
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
JUCE_CONSTEXPR bool intersects(Range other) const noexcept
Returns true if the given range intersects this one.
Definition: juce_Range.h:231
JUCE_CONSTEXPR Range()=default
Constructs an empty range.
JUCE_CONSTEXPR ValueType getEnd() const noexcept
Returns the end of the range.
Definition: juce_Range.h:90
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
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
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
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
static Range withStartAndLength(const ValueType startValue, const ValueType length) noexcept
Returns a range with a given start and length.
Definition: juce_Range.h:70
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 amountToSubtract) noexcept
Subtracts an amount from the start and end of the range.
Definition: juce_Range.h:183
JUCE_CONSTEXPR ValueType getLength() const noexcept
Returns the length of the range.
Definition: juce_Range.h:87
JUCE_CONSTEXPR bool isEmpty() const noexcept
Returns true if the range has a length of zero.
Definition: juce_Range.h:93
void setStart(const ValueType newStart) noexcept
Changes the start position of the range, leaving the end position unchanged.
Definition: juce_Range.h:100
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 ValueType getStart() const noexcept
Returns the start of the range.
Definition: juce_Range.h:84
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 contains(Range other) const noexcept
Returns true if the given range lies entirely inside this range.
Definition: juce_Range.h:225
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 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
A general-purpose range object, that simply represents any linear range with a start and end point...
Definition: juce_Range.h:43