|
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401 |
- /*
- ==============================================================================
-
- This file is part of the JUCE library.
- Copyright (c) 2016 - ROLI Ltd.
-
- Permission is granted to use this software under the terms of the ISC license
- http://www.isc.org/downloads/software-support-policy/isc-license/
-
- Permission to use, copy, modify, and/or distribute this software for any
- purpose with or without fee is hereby granted, provided that the above
- copyright notice and this permission notice appear in all copies.
-
- THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH REGARD
- TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
- FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT,
- OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
- USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
- TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE
- OF THIS SOFTWARE.
-
- -----------------------------------------------------------------------------
-
- To release a closed-source product which uses other parts of JUCE not
- licensed under the ISC terms, commercial licenses are available: visit
- www.juce.com for more information.
-
- ==============================================================================
- */
-
- #ifndef JUCE_TIME_H_INCLUDED
- #define JUCE_TIME_H_INCLUDED
-
-
- //==============================================================================
- /**
- Holds an absolute date and time.
-
- Internally, the time is stored at millisecond precision.
-
- @see RelativeTime
- */
- class JUCE_API Time
- {
- public:
- //==============================================================================
- /** Creates a Time object.
-
- This default constructor creates a time of midnight Jan 1st 1970 UTC, (which is
- represented internally as 0ms).
-
- To create a time object representing the current time, use getCurrentTime().
-
- @see getCurrentTime
- */
- Time() noexcept;
-
- /** Creates a time based on a number of milliseconds.
-
- To create a time object set to the current time, use getCurrentTime().
-
- @param millisecondsSinceEpoch the number of milliseconds since the unix
- 'epoch' (midnight Jan 1st 1970 UTC).
- @see getCurrentTime, currentTimeMillis
- */
- explicit Time (int64 millisecondsSinceEpoch) noexcept;
-
- /** Creates a time from a set of date components.
-
- @param year the year, in 4-digit format, e.g. 2004
- @param month the month, in the range 0 to 11
- @param day the day of the month, in the range 1 to 31
- @param hours hours in 24-hour clock format, 0 to 23
- @param minutes minutes 0 to 59
- @param seconds seconds 0 to 59
- @param milliseconds milliseconds 0 to 999
- @param useLocalTime if true, assume input is in this machine's local timezone
- if false, assume input is in UTC.
- */
- Time (int year,
- int month,
- int day,
- int hours,
- int minutes,
- int seconds = 0,
- int milliseconds = 0,
- bool useLocalTime = true) noexcept;
-
- /** Creates a copy of another Time object. */
- Time (const Time& other) noexcept;
-
- /** Destructor. */
- ~Time() noexcept;
-
- /** Copies this time from another one. */
- Time& operator= (const Time& other) noexcept;
-
- //==============================================================================
- /** Returns a Time object that is set to the current system time.
-
- This may not be monotonic, as the system time can change at any moment.
- You should therefore not use this method for measuring time intervals.
-
- @see currentTimeMillis
- */
- static Time JUCE_CALLTYPE getCurrentTime() noexcept;
-
- /** Returns the time as a number of milliseconds.
- @returns the number of milliseconds this Time object represents, since
- midnight Jan 1st 1970 UTC.
- @see getMilliseconds
- */
- int64 toMilliseconds() const noexcept { return millisSinceEpoch; }
-
- /** Returns the year (in this machine's local timezone).
- A 4-digit format is used, e.g. 2004.
- */
- int getYear() const noexcept;
-
- /** Returns the number of the month (in this machine's local timezone).
- The value returned is in the range 0 to 11.
- @see getMonthName
- */
- int getMonth() const noexcept;
-
- /** Returns the name of the month (in this machine's local timezone).
- @param threeLetterVersion if true, it'll be a 3-letter abbreviation, e.g. "Jan"; if false
- it'll return the long form, e.g. "January"
- @see getMonth
- */
- String getMonthName (bool threeLetterVersion) const;
-
- /** Returns the day of the month (in this machine's local timezone).
- The value returned is in the range 1 to 31.
- */
- int getDayOfMonth() const noexcept;
-
- /** Returns the number of the day of the week (in this machine's local timezone).
- The value returned is in the range 0 to 6 (0 = sunday, 1 = monday, etc).
- */
- int getDayOfWeek() const noexcept;
-
- /** Returns the number of the day of the year (in this machine's local timezone).
- The value returned is in the range 0 to 365.
- */
- int getDayOfYear() const noexcept;
-
- /** Returns the name of the weekday (in this machine's local timezone).
- @param threeLetterVersion if true, it'll return a 3-letter abbreviation, e.g. "Tue"; if
- false, it'll return the full version, e.g. "Tuesday".
- */
- String getWeekdayName (bool threeLetterVersion) const;
-
- /** Returns the number of hours since midnight (in this machine's local timezone).
- This is in 24-hour clock format, in the range 0 to 23.
- @see getHoursInAmPmFormat, isAfternoon
- */
- int getHours() const noexcept;
-
- /** Returns true if the time is in the afternoon (in this machine's local timezone).
- @returns true for "PM", false for "AM".
- @see getHoursInAmPmFormat, getHours
- */
- bool isAfternoon() const noexcept;
-
- /** Returns the hours in 12-hour clock format (in this machine's local timezone).
- This will return a value 1 to 12 - use isAfternoon() to find out
- whether this is in the afternoon or morning.
- @see getHours, isAfternoon
- */
- int getHoursInAmPmFormat() const noexcept;
-
- /** Returns the number of minutes, 0 to 59 (in this machine's local timezone). */
- int getMinutes() const noexcept;
-
- /** Returns the number of seconds, 0 to 59. */
- int getSeconds() const noexcept;
-
- /** Returns the number of milliseconds, 0 to 999.
-
- Unlike toMilliseconds(), this just returns the position within the
- current second rather than the total number since the epoch.
-
- @see toMilliseconds
- */
- int getMilliseconds() const noexcept;
-
- /** Returns true if the local timezone uses a daylight saving correction. */
- bool isDaylightSavingTime() const noexcept;
-
- //==============================================================================
- /** Returns a 3-character string to indicate the local timezone. */
- String getTimeZone() const noexcept;
-
- /** Returns the local timezone offset from UTC in seconds. */
- int getUTCOffsetSeconds() const noexcept;
-
- /** Returns a string to indicate the offset of the local timezone from UTC.
- @returns "+XX:XX", "-XX:XX" or "Z"
- @param includeDividerCharacters whether to include or omit the ":" divider in the string
- */
- String getUTCOffsetString (bool includeDividerCharacters) const;
-
- //==============================================================================
- /** Returns a string version of this date and time, using this machine's local timezone.
-
- For a more powerful way of formatting the date and time, see the formatted() method.
-
- @param includeDate whether to include the date in the string
- @param includeTime whether to include the time in the string
- @param includeSeconds if the time is being included, this provides an option not to include
- the seconds in it
- @param use24HourClock if the time is being included, sets whether to use am/pm or 24
- hour notation.
- @see formatted
- */
- String toString (bool includeDate,
- bool includeTime,
- bool includeSeconds = true,
- bool use24HourClock = false) const noexcept;
-
- /** Converts this date/time to a string with a user-defined format.
-
- This uses the C strftime() function to format this time as a string. To save you
- looking it up, these are the escape codes that strftime uses (other codes might
- work on some platforms and not others, but these are the common ones):
-
- - %a is replaced by the locale's abbreviated weekday name.
- - %A is replaced by the locale's full weekday name.
- - %b is replaced by the locale's abbreviated month name.
- - %B is replaced by the locale's full month name.
- - %c is replaced by the locale's appropriate date and time representation.
- - %d is replaced by the day of the month as a decimal number [01,31].
- - %H is replaced by the hour (24-hour clock) as a decimal number [00,23].
- - %I is replaced by the hour (12-hour clock) as a decimal number [01,12].
- - %j is replaced by the day of the year as a decimal number [001,366].
- - %m is replaced by the month as a decimal number [01,12].
- - %M is replaced by the minute as a decimal number [00,59].
- - %p is replaced by the locale's equivalent of either a.m. or p.m.
- - %S is replaced by the second as a decimal number [00,61].
- - %U is replaced by the week number of the year (Sunday as the first day of the week) as a decimal number [00,53].
- - %w is replaced by the weekday as a decimal number [0,6], with 0 representing Sunday.
- - %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.
- - %x is replaced by the locale's appropriate date representation.
- - %X is replaced by the locale's appropriate time representation.
- - %y is replaced by the year without century as a decimal number [00,99].
- - %Y is replaced by the year with century as a decimal number.
- - %Z is replaced by the timezone name or abbreviation, or by no bytes if no timezone information exists.
- - %% is replaced by %.
-
- @see toString
- */
- String formatted (const String& format) const;
-
- //==============================================================================
- /** Returns a fully described string of this date and time in ISO-8601 format
- (using the local timezone).
-
- @param includeDividerCharacters whether to include or omit the "-" and ":"
- dividers in the string
- */
- String toISO8601 (bool includeDividerCharacters) const;
-
- /** Parses an ISO-8601 string and returns it as a Time. */
- static Time fromISO8601 (StringRef iso8601) noexcept;
-
- //==============================================================================
- /** Tries to set the computer's clock.
-
- @returns true if this succeeds, although depending on the system, the
- application might not have sufficient privileges to do this.
- */
- bool setSystemTimeToThisTime() const;
-
- //==============================================================================
- /** Returns the name of a day of the week.
-
- @param dayNumber the day, 0 to 6 (0 = sunday, 1 = monday, etc)
- @param threeLetterVersion if true, it'll return a 3-letter abbreviation, e.g. "Tue"; if
- false, it'll return the full version, e.g. "Tuesday".
- */
- static String getWeekdayName (int dayNumber, bool threeLetterVersion);
-
- /** Returns the name of one of the months.
-
- @param monthNumber the month, 0 to 11
- @param threeLetterVersion if true, it'll be a 3-letter abbreviation, e.g. "Jan"; if false
- it'll return the long form, e.g. "January"
- */
- static String getMonthName (int monthNumber, bool threeLetterVersion);
-
- //==============================================================================
- // Static methods for getting system timers directly..
-
- /** Returns the current system time.
-
- Returns the number of milliseconds since midnight Jan 1st 1970 UTC.
-
- Should be accurate to within a few millisecs, depending on platform,
- hardware, etc.
- */
- static int64 currentTimeMillis() noexcept;
-
- /** Returns the number of millisecs since a fixed event (usually system startup).
-
- This returns a monotonically increasing value which it unaffected by changes to the
- system clock. It should be accurate to within a few millisecs, depending on platform,
- hardware, etc.
-
- Being a 32-bit return value, it will of course wrap back to 0 after 2^32 seconds of
- uptime, so be careful to take that into account. If you need a 64-bit time, you can
- use currentTimeMillis() instead.
-
- @see getApproximateMillisecondCounter
- */
- static uint32 getMillisecondCounter() noexcept;
-
- /** Returns the number of millisecs since a fixed event (usually system startup).
-
- This has the same function as getMillisecondCounter(), but returns a more accurate
- value, using a higher-resolution timer if one is available.
-
- @see getMillisecondCounter
- */
- static double getMillisecondCounterHiRes() noexcept;
-
- /** Waits until the getMillisecondCounter() reaches a given value.
-
- This will make the thread sleep as efficiently as it can while it's waiting.
- */
- static void waitForMillisecondCounter (uint32 targetTime) noexcept;
-
- /** Less-accurate but faster version of getMillisecondCounter().
-
- This will return the last value that getMillisecondCounter() returned, so doesn't
- need to make a system call, but is less accurate - it shouldn't be more than
- 100ms away from the correct time, though, so is still accurate enough for a
- lot of purposes.
-
- @see getMillisecondCounter
- */
- static uint32 getApproximateMillisecondCounter() noexcept;
-
- //==============================================================================
- // High-resolution timers..
-
- /** Returns the current high-resolution counter's tick-count.
-
- This is a similar idea to getMillisecondCounter(), but with a higher
- resolution.
-
- @see getHighResolutionTicksPerSecond, highResolutionTicksToSeconds,
- secondsToHighResolutionTicks
- */
- static int64 getHighResolutionTicks() noexcept;
-
- /** Returns the resolution of the high-resolution counter in ticks per second.
-
- @see getHighResolutionTicks, highResolutionTicksToSeconds,
- secondsToHighResolutionTicks
- */
- static int64 getHighResolutionTicksPerSecond() noexcept;
-
- /** Converts a number of high-resolution ticks into seconds.
-
- @see getHighResolutionTicks, getHighResolutionTicksPerSecond,
- secondsToHighResolutionTicks
- */
- static double highResolutionTicksToSeconds (int64 ticks) noexcept;
-
- /** Converts a number seconds into high-resolution ticks.
-
- @see getHighResolutionTicks, getHighResolutionTicksPerSecond,
- highResolutionTicksToSeconds
- */
- static int64 secondsToHighResolutionTicks (double seconds) noexcept;
-
- /** Returns a Time based on the value of the __DATE__ macro when this module was compiled */
- static Time getCompilationDate();
-
- private:
- //==============================================================================
- int64 millisSinceEpoch;
- };
-
- //==============================================================================
- /** Compares two Time objects. */
- JUCE_API bool operator== (Time time1, Time time2) noexcept;
- /** Compares two Time objects. */
- JUCE_API bool operator!= (Time time1, Time time2) noexcept;
- /** Compares two Time objects. */
- JUCE_API bool operator< (Time time1, Time time2) noexcept;
- /** Compares two Time objects. */
- JUCE_API bool operator<= (Time time1, Time time2) noexcept;
- /** Compares two Time objects. */
- JUCE_API bool operator> (Time time1, Time time2) noexcept;
- /** Compares two Time objects. */
- JUCE_API bool operator>= (Time time1, Time time2) noexcept;
-
-
- #endif // JUCE_TIME_H_INCLUDED
|