Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

juce_Time.h 17KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401
  1. /*
  2. ==============================================================================
  3. This file is part of the JUCE library.
  4. Copyright (c) 2016 - ROLI Ltd.
  5. Permission is granted to use this software under the terms of the ISC license
  6. http://www.isc.org/downloads/software-support-policy/isc-license/
  7. Permission to use, copy, modify, and/or distribute this software for any
  8. purpose with or without fee is hereby granted, provided that the above
  9. copyright notice and this permission notice appear in all copies.
  10. THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
  11. TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
  12. FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
  13. OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  14. USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
  15. TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
  16. OF THIS SOFTWARE.
  17. -----------------------------------------------------------------------------
  18. To release a closed-source product which uses other parts of JUCE not
  19. licensed under the ISC terms, commercial licenses are available: visit
  20. www.juce.com for more information.
  21. ==============================================================================
  22. */
  23. #ifndef JUCE_TIME_H_INCLUDED
  24. #define JUCE_TIME_H_INCLUDED
  25. //==============================================================================
  26. /**
  27. Holds an absolute date and time.
  28. Internally, the time is stored at millisecond precision.
  29. @see RelativeTime
  30. */
  31. class JUCE_API Time
  32. {
  33. public:
  34. //==============================================================================
  35. /** Creates a Time object.
  36. This default constructor creates a time of midnight Jan 1st 1970 UTC, (which is
  37. represented internally as 0ms).
  38. To create a time object representing the current time, use getCurrentTime().
  39. @see getCurrentTime
  40. */
  41. Time() noexcept;
  42. /** Creates a time based on a number of milliseconds.
  43. To create a time object set to the current time, use getCurrentTime().
  44. @param millisecondsSinceEpoch the number of milliseconds since the unix
  45. 'epoch' (midnight Jan 1st 1970 UTC).
  46. @see getCurrentTime, currentTimeMillis
  47. */
  48. explicit Time (int64 millisecondsSinceEpoch) noexcept;
  49. /** Creates a time from a set of date components.
  50. @param year the year, in 4-digit format, e.g. 2004
  51. @param month the month, in the range 0 to 11
  52. @param day the day of the month, in the range 1 to 31
  53. @param hours hours in 24-hour clock format, 0 to 23
  54. @param minutes minutes 0 to 59
  55. @param seconds seconds 0 to 59
  56. @param milliseconds milliseconds 0 to 999
  57. @param useLocalTime if true, assume input is in this machine's local timezone
  58. if false, assume input is in UTC.
  59. */
  60. Time (int year,
  61. int month,
  62. int day,
  63. int hours,
  64. int minutes,
  65. int seconds = 0,
  66. int milliseconds = 0,
  67. bool useLocalTime = true) noexcept;
  68. /** Creates a copy of another Time object. */
  69. Time (const Time& other) noexcept;
  70. /** Destructor. */
  71. ~Time() noexcept;
  72. /** Copies this time from another one. */
  73. Time& operator= (const Time& other) noexcept;
  74. //==============================================================================
  75. /** Returns a Time object that is set to the current system time.
  76. This may not be monotonic, as the system time can change at any moment.
  77. You should therefore not use this method for measuring time intervals.
  78. @see currentTimeMillis
  79. */
  80. static Time JUCE_CALLTYPE getCurrentTime() noexcept;
  81. /** Returns the time as a number of milliseconds.
  82. @returns the number of milliseconds this Time object represents, since
  83. midnight Jan 1st 1970 UTC.
  84. @see getMilliseconds
  85. */
  86. int64 toMilliseconds() const noexcept { return millisSinceEpoch; }
  87. /** Returns the year (in this machine's local timezone).
  88. A 4-digit format is used, e.g. 2004.
  89. */
  90. int getYear() const noexcept;
  91. /** Returns the number of the month (in this machine's local timezone).
  92. The value returned is in the range 0 to 11.
  93. @see getMonthName
  94. */
  95. int getMonth() const noexcept;
  96. /** Returns the name of the month (in this machine's local timezone).
  97. @param threeLetterVersion if true, it'll be a 3-letter abbreviation, e.g. "Jan"; if false
  98. it'll return the long form, e.g. "January"
  99. @see getMonth
  100. */
  101. String getMonthName (bool threeLetterVersion) const;
  102. /** Returns the day of the month (in this machine's local timezone).
  103. The value returned is in the range 1 to 31.
  104. */
  105. int getDayOfMonth() const noexcept;
  106. /** Returns the number of the day of the week (in this machine's local timezone).
  107. The value returned is in the range 0 to 6 (0 = sunday, 1 = monday, etc).
  108. */
  109. int getDayOfWeek() const noexcept;
  110. /** Returns the number of the day of the year (in this machine's local timezone).
  111. The value returned is in the range 0 to 365.
  112. */
  113. int getDayOfYear() const noexcept;
  114. /** Returns the name of the weekday (in this machine's local timezone).
  115. @param threeLetterVersion if true, it'll return a 3-letter abbreviation, e.g. "Tue"; if
  116. false, it'll return the full version, e.g. "Tuesday".
  117. */
  118. String getWeekdayName (bool threeLetterVersion) const;
  119. /** Returns the number of hours since midnight (in this machine's local timezone).
  120. This is in 24-hour clock format, in the range 0 to 23.
  121. @see getHoursInAmPmFormat, isAfternoon
  122. */
  123. int getHours() const noexcept;
  124. /** Returns true if the time is in the afternoon (in this machine's local timezone).
  125. @returns true for "PM", false for "AM".
  126. @see getHoursInAmPmFormat, getHours
  127. */
  128. bool isAfternoon() const noexcept;
  129. /** Returns the hours in 12-hour clock format (in this machine's local timezone).
  130. This will return a value 1 to 12 - use isAfternoon() to find out
  131. whether this is in the afternoon or morning.
  132. @see getHours, isAfternoon
  133. */
  134. int getHoursInAmPmFormat() const noexcept;
  135. /** Returns the number of minutes, 0 to 59 (in this machine's local timezone). */
  136. int getMinutes() const noexcept;
  137. /** Returns the number of seconds, 0 to 59. */
  138. int getSeconds() const noexcept;
  139. /** Returns the number of milliseconds, 0 to 999.
  140. Unlike toMilliseconds(), this just returns the position within the
  141. current second rather than the total number since the epoch.
  142. @see toMilliseconds
  143. */
  144. int getMilliseconds() const noexcept;
  145. /** Returns true if the local timezone uses a daylight saving correction. */
  146. bool isDaylightSavingTime() const noexcept;
  147. //==============================================================================
  148. /** Returns a 3-character string to indicate the local timezone. */
  149. String getTimeZone() const noexcept;
  150. /** Returns the local timezone offset from UTC in seconds. */
  151. int getUTCOffsetSeconds() const noexcept;
  152. /** Returns a string to indicate the offset of the local timezone from UTC.
  153. @returns "+XX:XX", "-XX:XX" or "Z"
  154. @param includeDividerCharacters whether to include or omit the ":" divider in the string
  155. */
  156. String getUTCOffsetString (bool includeDividerCharacters) const;
  157. //==============================================================================
  158. /** Returns a string version of this date and time, using this machine's local timezone.
  159. For a more powerful way of formatting the date and time, see the formatted() method.
  160. @param includeDate whether to include the date in the string
  161. @param includeTime whether to include the time in the string
  162. @param includeSeconds if the time is being included, this provides an option not to include
  163. the seconds in it
  164. @param use24HourClock if the time is being included, sets whether to use am/pm or 24
  165. hour notation.
  166. @see formatted
  167. */
  168. String toString (bool includeDate,
  169. bool includeTime,
  170. bool includeSeconds = true,
  171. bool use24HourClock = false) const noexcept;
  172. /** Converts this date/time to a string with a user-defined format.
  173. This uses the C strftime() function to format this time as a string. To save you
  174. looking it up, these are the escape codes that strftime uses (other codes might
  175. work on some platforms and not others, but these are the common ones):
  176. - %a is replaced by the locale's abbreviated weekday name.
  177. - %A is replaced by the locale's full weekday name.
  178. - %b is replaced by the locale's abbreviated month name.
  179. - %B is replaced by the locale's full month name.
  180. - %c is replaced by the locale's appropriate date and time representation.
  181. - %d is replaced by the day of the month as a decimal number [01,31].
  182. - %H is replaced by the hour (24-hour clock) as a decimal number [00,23].
  183. - %I is replaced by the hour (12-hour clock) as a decimal number [01,12].
  184. - %j is replaced by the day of the year as a decimal number [001,366].
  185. - %m is replaced by the month as a decimal number [01,12].
  186. - %M is replaced by the minute as a decimal number [00,59].
  187. - %p is replaced by the locale's equivalent of either a.m. or p.m.
  188. - %S is replaced by the second as a decimal number [00,61].
  189. - %U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
  190. - %w is replaced by the weekday as a decimal number [0,6], with 0 representing Sunday.
  191. - %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.
  192. - %x is replaced by the locale's appropriate date representation.
  193. - %X is replaced by the locale's appropriate time representation.
  194. - %y is replaced by the year without century as a decimal number [00,99].
  195. - %Y is replaced by the year with century as a decimal number.
  196. - %Z is replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists.
  197. - %% is replaced by %.
  198. @see toString
  199. */
  200. String formatted (const String& format) const;
  201. //==============================================================================
  202. /** Returns a fully described string of this date and time in ISO-8601 format
  203. (using the local timezone).
  204. @param includeDividerCharacters whether to include or omit the "-" and ":"
  205. dividers in the string
  206. */
  207. String toISO8601 (bool includeDividerCharacters) const;
  208. /** Parses an ISO-8601 string and returns it as a Time. */
  209. static Time fromISO8601 (StringRef iso8601) noexcept;
  210. //==============================================================================
  211. /** Tries to set the computer's clock.
  212. @returns true if this succeeds, although depending on the system, the
  213. application might not have sufficient privileges to do this.
  214. */
  215. bool setSystemTimeToThisTime() const;
  216. //==============================================================================
  217. /** Returns the name of a day of the week.
  218. @param dayNumber the day, 0 to 6 (0 = sunday, 1 = monday, etc)
  219. @param threeLetterVersion if true, it'll return a 3-letter abbreviation, e.g. "Tue"; if
  220. false, it'll return the full version, e.g. "Tuesday".
  221. */
  222. static String getWeekdayName (int dayNumber, bool threeLetterVersion);
  223. /** Returns the name of one of the months.
  224. @param monthNumber the month, 0 to 11
  225. @param threeLetterVersion if true, it'll be a 3-letter abbreviation, e.g. "Jan"; if false
  226. it'll return the long form, e.g. "January"
  227. */
  228. static String getMonthName (int monthNumber, bool threeLetterVersion);
  229. //==============================================================================
  230. // Static methods for getting system timers directly..
  231. /** Returns the current system time.
  232. Returns the number of milliseconds since midnight Jan 1st 1970 UTC.
  233. Should be accurate to within a few millisecs, depending on platform,
  234. hardware, etc.
  235. */
  236. static int64 currentTimeMillis() noexcept;
  237. /** Returns the number of millisecs since a fixed event (usually system startup).
  238. This returns a monotonically increasing value which it unaffected by changes to the
  239. system clock. It should be accurate to within a few millisecs, depending on platform,
  240. hardware, etc.
  241. Being a 32-bit return value, it will of course wrap back to 0 after 2^32 seconds of
  242. uptime, so be careful to take that into account. If you need a 64-bit time, you can
  243. use currentTimeMillis() instead.
  244. @see getApproximateMillisecondCounter
  245. */
  246. static uint32 getMillisecondCounter() noexcept;
  247. /** Returns the number of millisecs since a fixed event (usually system startup).
  248. This has the same function as getMillisecondCounter(), but returns a more accurate
  249. value, using a higher-resolution timer if one is available.
  250. @see getMillisecondCounter
  251. */
  252. static double getMillisecondCounterHiRes() noexcept;
  253. /** Waits until the getMillisecondCounter() reaches a given value.
  254. This will make the thread sleep as efficiently as it can while it's waiting.
  255. */
  256. static void waitForMillisecondCounter (uint32 targetTime) noexcept;
  257. /** Less-accurate but faster version of getMillisecondCounter().
  258. This will return the last value that getMillisecondCounter() returned, so doesn't
  259. need to make a system call, but is less accurate - it shouldn't be more than
  260. 100ms away from the correct time, though, so is still accurate enough for a
  261. lot of purposes.
  262. @see getMillisecondCounter
  263. */
  264. static uint32 getApproximateMillisecondCounter() noexcept;
  265. //==============================================================================
  266. // High-resolution timers..
  267. /** Returns the current high-resolution counter's tick-count.
  268. This is a similar idea to getMillisecondCounter(), but with a higher
  269. resolution.
  270. @see getHighResolutionTicksPerSecond, highResolutionTicksToSeconds,
  271. secondsToHighResolutionTicks
  272. */
  273. static int64 getHighResolutionTicks() noexcept;
  274. /** Returns the resolution of the high-resolution counter in ticks per second.
  275. @see getHighResolutionTicks, highResolutionTicksToSeconds,
  276. secondsToHighResolutionTicks
  277. */
  278. static int64 getHighResolutionTicksPerSecond() noexcept;
  279. /** Converts a number of high-resolution ticks into seconds.
  280. @see getHighResolutionTicks, getHighResolutionTicksPerSecond,
  281. secondsToHighResolutionTicks
  282. */
  283. static double highResolutionTicksToSeconds (int64 ticks) noexcept;
  284. /** Converts a number seconds into high-resolution ticks.
  285. @see getHighResolutionTicks, getHighResolutionTicksPerSecond,
  286. highResolutionTicksToSeconds
  287. */
  288. static int64 secondsToHighResolutionTicks (double seconds) noexcept;
  289. /** Returns a Time based on the value of the __DATE__ macro when this module was compiled */
  290. static Time getCompilationDate();
  291. private:
  292. //==============================================================================
  293. int64 millisSinceEpoch;
  294. };
  295. //==============================================================================
  296. /** Compares two Time objects. */
  297. JUCE_API bool operator== (Time time1, Time time2) noexcept;
  298. /** Compares two Time objects. */
  299. JUCE_API bool operator!= (Time time1, Time time2) noexcept;
  300. /** Compares two Time objects. */
  301. JUCE_API bool operator< (Time time1, Time time2) noexcept;
  302. /** Compares two Time objects. */
  303. JUCE_API bool operator<= (Time time1, Time time2) noexcept;
  304. /** Compares two Time objects. */
  305. JUCE_API bool operator> (Time time1, Time time2) noexcept;
  306. /** Compares two Time objects. */
  307. JUCE_API bool operator>= (Time time1, Time time2) noexcept;
  308. #endif // JUCE_TIME_H_INCLUDED