OpenShot Library | libopenshot-audio 0.2.0
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
27namespace 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{
42public:
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
376private:
377 //==============================================================================
378 int64 millisSinceEpoch = 0;
379};
380
381//==============================================================================
382/** Adds a RelativeTime to a Time. */
383JUCE_API Time operator+ (Time time, RelativeTime delta) noexcept;
384/** Adds a RelativeTime to a Time. */
385JUCE_API Time operator+ (RelativeTime delta, Time time) noexcept;
386
387/** Subtracts a RelativeTime from a Time. */
388JUCE_API Time operator- (Time time, RelativeTime delta) noexcept;
389/** Returns the relative time difference between two times. */
390JUCE_API const RelativeTime operator- (Time time1, Time time2) noexcept;
391
392/** Compares two Time objects. */
393JUCE_API bool operator== (Time time1, Time time2) noexcept;
394/** Compares two Time objects. */
395JUCE_API bool operator!= (Time time1, Time time2) noexcept;
396/** Compares two Time objects. */
397JUCE_API bool operator< (Time time1, Time time2) noexcept;
398/** Compares two Time objects. */
399JUCE_API bool operator<= (Time time1, Time time2) noexcept;
400/** Compares two Time objects. */
401JUCE_API bool operator> (Time time1, Time time2) noexcept;
402/** Compares two Time objects. */
403JUCE_API bool operator>= (Time time1, Time time2) noexcept;
404
405} // namespace juce
406
407/** @}*/
A relative measure of time.
A simple class for holding temporary references to a string literal or String.
The JUCE String class!
Definition juce_String.h:43
Holds an absolute date and time.
Definition juce_Time.h:41
Time()=default
Creates a Time object.
#define JUCE_API
This macro is added to all JUCE public class declarations.