OpenShot Library | libopenshot-audio  0.1.9
juce_Time.h
1 
2 /** @weakgroup juce_core-time
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 /**
32  Holds an absolute date and time.
33 
34  Internally, the time is stored at millisecond precision.
35 
36  @see RelativeTime
37 
38  @tags{Core}
39 */
41 {
42 public:
43  //==============================================================================
44  /** Creates a Time object.
45  This default constructor creates a time of midnight Jan 1st 1970 UTC, (which is
46  represented internally as 0ms).
47  To create a time object representing the current time, use getCurrentTime().
48  @see getCurrentTime
49  */
50  Time() = default;
51 
52  /** Creates a time based on a number of milliseconds.
53  To create a time object set to the current time, use getCurrentTime().
54 
55  @param millisecondsSinceEpoch the number of milliseconds since the unix
56  'epoch' (midnight Jan 1st 1970 UTC).
57  @see getCurrentTime, currentTimeMillis
58  */
59  explicit Time (int64 millisecondsSinceEpoch) noexcept;
60 
61  /** Creates a time from a set of date components.
62 
63  @param year the year, in 4-digit format, e.g. 2004
64  @param month the month, in the range 0 to 11
65  @param day the day of the month, in the range 1 to 31
66  @param hours hours in 24-hour clock format, 0 to 23
67  @param minutes minutes 0 to 59
68  @param seconds seconds 0 to 59
69  @param milliseconds milliseconds 0 to 999
70  @param useLocalTime if true, assume input is in this machine's local timezone
71  if false, assume input is in UTC.
72  */
73  Time (int year,
74  int month,
75  int day,
76  int hours,
77  int minutes,
78  int seconds = 0,
79  int milliseconds = 0,
80  bool useLocalTime = true) noexcept;
81 
82  Time (const Time&) = default;
83  ~Time() = default;
84 
85  Time& operator= (const Time&) = default;
86 
87  //==============================================================================
88  /** Returns a Time object that is set to the current system time.
89 
90  This may not be monotonic, as the system time can change at any moment.
91  You should therefore not use this method for measuring time intervals.
92 
93  @see currentTimeMillis
94  */
95  static Time JUCE_CALLTYPE getCurrentTime() noexcept;
96 
97  /** Returns the time as a number of milliseconds.
98  @returns the number of milliseconds this Time object represents, since
99  midnight Jan 1st 1970 UTC.
100  @see getMilliseconds
101  */
102  int64 toMilliseconds() const noexcept { return millisSinceEpoch; }
103 
104  /** Returns the year (in this machine's local timezone).
105  A 4-digit format is used, e.g. 2004.
106  */
107  int getYear() const noexcept;
108 
109  /** Returns the number of the month (in this machine's local timezone).
110  The value returned is in the range 0 to 11.
111  @see getMonthName
112  */
113  int getMonth() const noexcept;
114 
115  /** Returns the name of the month (in this machine's local timezone).
116  @param threeLetterVersion if true, it'll be a 3-letter abbreviation, e.g. "Jan"; if false
117  it'll return the long form, e.g. "January"
118  @see getMonth
119  */
120  String getMonthName (bool threeLetterVersion) const;
121 
122  /** Returns the day of the month (in this machine's local timezone).
123  The value returned is in the range 1 to 31.
124  */
125  int getDayOfMonth() const noexcept;
126 
127  /** Returns the number of the day of the week (in this machine's local timezone).
128  The value returned is in the range 0 to 6 (0 = sunday, 1 = monday, etc).
129  */
130  int getDayOfWeek() const noexcept;
131 
132  /** Returns the number of the day of the year (in this machine's local timezone).
133  The value returned is in the range 0 to 365.
134  */
135  int getDayOfYear() const noexcept;
136 
137  /** Returns the name of the weekday (in this machine's local timezone).
138  @param threeLetterVersion if true, it'll return a 3-letter abbreviation, e.g. "Tue"; if
139  false, it'll return the full version, e.g. "Tuesday".
140  */
141  String getWeekdayName (bool threeLetterVersion) const;
142 
143  /** Returns the number of hours since midnight (in this machine's local timezone).
144  This is in 24-hour clock format, in the range 0 to 23.
145  @see getHoursInAmPmFormat, isAfternoon
146  */
147  int getHours() const noexcept;
148 
149  /** Returns true if the time is in the afternoon (in this machine's local timezone).
150  @returns true for "PM", false for "AM".
151  @see getHoursInAmPmFormat, getHours
152  */
153  bool isAfternoon() const noexcept;
154 
155  /** Returns the hours in 12-hour clock format (in this machine's local timezone).
156  This will return a value 1 to 12 - use isAfternoon() to find out
157  whether this is in the afternoon or morning.
158  @see getHours, isAfternoon
159  */
160  int getHoursInAmPmFormat() const noexcept;
161 
162  /** Returns the number of minutes, 0 to 59 (in this machine's local timezone). */
163  int getMinutes() const noexcept;
164 
165  /** Returns the number of seconds, 0 to 59. */
166  int getSeconds() const noexcept;
167 
168  /** Returns the number of milliseconds, 0 to 999.
169 
170  Unlike toMilliseconds(), this just returns the position within the
171  current second rather than the total number since the epoch.
172 
173  @see toMilliseconds
174  */
175  int getMilliseconds() const noexcept;
176 
177  /** Returns true if the local timezone uses a daylight saving correction. */
178  bool isDaylightSavingTime() const noexcept;
179 
180  //==============================================================================
181  /** Returns a 3-character string to indicate the local timezone. */
182  String getTimeZone() const;
183 
184  /** Returns the local timezone offset from UTC in seconds. */
185  int getUTCOffsetSeconds() const noexcept;
186 
187  /** Returns a string to indicate the offset of the local timezone from UTC.
188  @returns "+XX:XX", "-XX:XX" or "Z"
189  @param includeDividerCharacters whether to include or omit the ":" divider in the string
190  */
191  String getUTCOffsetString (bool includeDividerCharacters) const;
192 
193  //==============================================================================
194  /** Returns a string version of this date and time, using this machine's local timezone.
195 
196  For a more powerful way of formatting the date and time, see the formatted() method.
197 
198  @param includeDate whether to include the date in the string
199  @param includeTime whether to include the time in the string
200  @param includeSeconds if the time is being included, this provides an option not to include
201  the seconds in it
202  @param use24HourClock if the time is being included, sets whether to use am/pm or 24
203  hour notation.
204  @see formatted
205  */
206  String toString (bool includeDate,
207  bool includeTime,
208  bool includeSeconds = true,
209  bool use24HourClock = false) const;
210 
211  /** Converts this date/time to a string with a user-defined format.
212 
213  This uses the C strftime() function to format this time as a string. To save you
214  looking it up, these are the escape codes that strftime uses (other codes might
215  work on some platforms and not others, but these are the common ones):
216 
217  - %a is replaced by the locale's abbreviated weekday name.
218  - %A is replaced by the locale's full weekday name.
219  - %b is replaced by the locale's abbreviated month name.
220  - %B is replaced by the locale's full month name.
221  - %c is replaced by the locale's appropriate date and time representation.
222  - %d is replaced by the day of the month as a decimal number [01,31].
223  - %H is replaced by the hour (24-hour clock) as a decimal number [00,23].
224  - %I is replaced by the hour (12-hour clock) as a decimal number [01,12].
225  - %j is replaced by the day of the year as a decimal number [001,366].
226  - %m is replaced by the month as a decimal number [01,12].
227  - %M is replaced by the minute as a decimal number [00,59].
228  - %p is replaced by the locale's equivalent of either a.m. or p.m.
229  - %S is replaced by the second as a decimal number [00,60].
230  - %U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
231  - %w is replaced by the weekday as a decimal number [0,6], with 0 representing Sunday.
232  - %W is replaced by the week number of the year (Monday as the first day of the week) as a decimal number [00,53]. All days in a new year preceding the first Monday are considered to be in week 0.
233  - %x is replaced by the locale's appropriate date representation.
234  - %X is replaced by the locale's appropriate time representation.
235  - %y is replaced by the year without century as a decimal number [00,99].
236  - %Y is replaced by the year with century as a decimal number.
237  - %Z is replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists.
238  - %% is replaced by %.
239 
240  @see toString
241  */
242  String formatted (const String& format) const;
243 
244  //==============================================================================
245  /** Returns a fully described string of this date and time in ISO-8601 format
246  (using the local timezone).
247 
248  @param includeDividerCharacters whether to include or omit the "-" and ":"
249  dividers in the string
250  */
251  String toISO8601 (bool includeDividerCharacters) const;
252 
253  /** Parses an ISO-8601 string and returns it as a Time. */
254  static Time fromISO8601 (StringRef iso8601);
255 
256  //==============================================================================
257  /** Adds a RelativeTime to this time. */
258  Time& operator+= (RelativeTime delta) noexcept;
259  /** Subtracts a RelativeTime from this time. */
260  Time& operator-= (RelativeTime delta) noexcept;
261 
262  //==============================================================================
263  /** Tries to set the computer's clock.
264 
265  @returns true if this succeeds, although depending on the system, the
266  application might not have sufficient privileges to do this.
267  */
268  bool setSystemTimeToThisTime() const;
269 
270  //==============================================================================
271  /** Returns the name of a day of the week.
272 
273  @param dayNumber the day, 0 to 6 (0 = sunday, 1 = monday, etc)
274  @param threeLetterVersion if true, it'll return a 3-letter abbreviation, e.g. "Tue"; if
275  false, it'll return the full version, e.g. "Tuesday".
276  */
277  static String getWeekdayName (int dayNumber, bool threeLetterVersion);
278 
279  /** Returns the name of one of the months.
280 
281  @param monthNumber the month, 0 to 11
282  @param threeLetterVersion if true, it'll be a 3-letter abbreviation, e.g. "Jan"; if false
283  it'll return the long form, e.g. "January"
284  */
285  static String getMonthName (int monthNumber, bool threeLetterVersion);
286 
287  //==============================================================================
288  // Static methods for getting system timers directly..
289 
290  /** Returns the current system time.
291 
292  Returns the number of milliseconds since midnight Jan 1st 1970 UTC.
293 
294  Should be accurate to within a few millisecs, depending on platform,
295  hardware, etc.
296  */
297  static int64 currentTimeMillis() noexcept;
298 
299  /** Returns the number of millisecs since a fixed event (usually system startup).
300 
301  This returns a monotonically increasing value which is unaffected by changes to the
302  system clock. It should be accurate to within a few millisecs, depending on platform,
303  hardware, etc.
304 
305  Being a 32-bit return value, it will of course wrap back to 0 after 2^32 seconds of
306  uptime, so be careful to take that into account. If you need a 64-bit time, you can
307  use currentTimeMillis() instead.
308 
309  @see getApproximateMillisecondCounter
310  */
311  static uint32 getMillisecondCounter() noexcept;
312 
313  /** Returns the number of millisecs since a fixed event (usually system startup).
314 
315  This has the same function as getMillisecondCounter(), but returns a more accurate
316  value, using a higher-resolution timer if one is available.
317 
318  @see getMillisecondCounter
319  */
320  static double getMillisecondCounterHiRes() noexcept;
321 
322  /** Waits until the getMillisecondCounter() reaches a given value.
323 
324  This will make the thread sleep as efficiently as it can while it's waiting.
325  */
326  static void waitForMillisecondCounter (uint32 targetTime) noexcept;
327 
328  /** Less-accurate but faster version of getMillisecondCounter().
329 
330  This will return the last value that getMillisecondCounter() returned, so doesn't
331  need to make a system call, but is less accurate - it shouldn't be more than
332  100ms away from the correct time, though, so is still accurate enough for a
333  lot of purposes.
334 
335  @see getMillisecondCounter
336  */
337  static uint32 getApproximateMillisecondCounter() noexcept;
338 
339  //==============================================================================
340  // High-resolution timers..
341 
342  /** Returns the current high-resolution counter's tick-count.
343 
344  This is a similar idea to getMillisecondCounter(), but with a higher
345  resolution.
346 
347  @see getHighResolutionTicksPerSecond, highResolutionTicksToSeconds,
348  secondsToHighResolutionTicks
349  */
350  static int64 getHighResolutionTicks() noexcept;
351 
352  /** Returns the resolution of the high-resolution counter in ticks per second.
353 
354  @see getHighResolutionTicks, highResolutionTicksToSeconds,
355  secondsToHighResolutionTicks
356  */
357  static int64 getHighResolutionTicksPerSecond() noexcept;
358 
359  /** Converts a number of high-resolution ticks into seconds.
360 
361  @see getHighResolutionTicks, getHighResolutionTicksPerSecond,
362  secondsToHighResolutionTicks
363  */
364  static double highResolutionTicksToSeconds (int64 ticks) noexcept;
365 
366  /** Converts a number seconds into high-resolution ticks.
367 
368  @see getHighResolutionTicks, getHighResolutionTicksPerSecond,
369  highResolutionTicksToSeconds
370  */
371  static int64 secondsToHighResolutionTicks (double seconds) noexcept;
372 
373  /** Returns a Time based on the value of the __DATE__ macro when this module was compiled */
374  static Time getCompilationDate();
375 
376 private:
377  //==============================================================================
378  int64 millisSinceEpoch = 0;
379 };
380 
381 //==============================================================================
382 /** Adds a RelativeTime to a Time. */
383 JUCE_API Time operator+ (Time time, RelativeTime delta) noexcept;
384 /** Adds a RelativeTime to a Time. */
385 JUCE_API Time operator+ (RelativeTime delta, Time time) noexcept;
386 
387 /** Subtracts a RelativeTime from a Time. */
388 JUCE_API Time operator- (Time time, RelativeTime delta) noexcept;
389 /** Returns the relative time difference between two times. */
390 JUCE_API const RelativeTime operator- (Time time1, Time time2) noexcept;
391 
392 /** Compares two Time objects. */
393 JUCE_API bool operator== (Time time1, Time time2) noexcept;
394 /** Compares two Time objects. */
395 JUCE_API bool operator!= (Time time1, Time time2) noexcept;
396 /** Compares two Time objects. */
397 JUCE_API bool operator< (Time time1, Time time2) noexcept;
398 /** Compares two Time objects. */
399 JUCE_API bool operator<= (Time time1, Time time2) noexcept;
400 /** Compares two Time objects. */
401 JUCE_API bool operator> (Time time1, Time time2) noexcept;
402 /** Compares two Time objects. */
403 JUCE_API bool operator>= (Time time1, Time time2) noexcept;
404 
405 } // namespace juce
406 
407 /** @}*/
#define JUCE_API
This macro is added to all JUCE public class declarations.
A simple class for holding temporary references to a string literal or String.
int64 toMilliseconds() const noexcept
Returns the time as a number of milliseconds.
Definition: juce_Time.h:102
The JUCE String class!
Definition: juce_String.h:42
A relative measure of time.
Holds an absolute date and time.
Definition: juce_Time.h:40