I have tried here to change to juce_Time docs to be more specific about the timezones of inputs and outputs. Also I believe the "-" makes a list on Doxygen.
diff --git a/modules/juce_core/time/juce_Time.h b/modules/juce_core/time/juce_Time.h
index a2bdb3a..614b24e 100644
--- a/modules/juce_core/time/juce_Time.h
+++ b/modules/juce_core/time/juce_Time.h
@@ -44,7 +44,7 @@ public:
//==============================================================================
/** Creates a Time object.
- This default constructor creates a time of 1st January 1970, (which is
+ 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().
@@ -55,19 +55,16 @@ public:
/** Creates a time based on a number of milliseconds.
- The internal millisecond count is set to 0 (1st January 1970). To create a
- time object set to the current time, use getCurrentTime().
+ 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).
+ 'epoch' (midnight Jan 1st 1970 UTC).
@see getCurrentTime, currentTimeMillis
*/
explicit Time (int64 millisecondsSinceEpoch) noexcept;
/** Creates a time from a set of date components.
- The timezone is assumed to be whatever the system is using as its locale.
-
@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
@@ -75,8 +72,8 @@ public:
@param minutes minutes 0 to 59
@param seconds seconds 0 to 59
@param milliseconds milliseconds 0 to 999
- @param useLocalTime if true, encode using the current machine's local time; if
- false, it will always work in GMT.
+ @param useLocalTime if true, assume input is in machine's local timezone
+ if false, assume input is in UTC.
*/
Time (int year,
int month,
@@ -109,25 +106,25 @@ public:
/** Returns the time as a number of milliseconds.
@returns the number of milliseconds this Time object represents, since
- midnight jan 1st 1970.
+ midnight Jan 1st 1970 UTC.
@see getMilliseconds
*/
int64 toMilliseconds() const noexcept { return millisSinceEpoch; }
- /** Returns the year.
+ /** Returns the year in local timezone.
A 4-digit format is used, e.g. 2004.
*/
int getYear() const noexcept;
- /** Returns the number of the month.
+ /** Returns the number of the month in local timezone.
The value returned is in the range 0 to 11.
@see getMonthName
*/
int getMonth() const noexcept;
- /** Returns the name of the month.
+ /** Returns the name of the month in 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"
@@ -135,29 +132,29 @@ public:
*/
String getMonthName (bool threeLetterVersion) const;
- /** Returns the day of the month.
+ /** Returns the day of the month in 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.
+ /** Returns the number of the day of the week in 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.
+ /** Returns the number of the day of the year in local timezone.
The value returned is in the range 0 to 365.
*/
int getDayOfYear() const noexcept;
- /** Returns the name of the weekday.
+ /** Returns the name of the weekday in 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.
+ /** Returns the number of hours since midnight in local timezone.
This is in 24-hour clock format, in the range 0 to 23.
@@ -165,7 +162,7 @@ public:
*/
int getHours() const noexcept;
- /** Returns true if the time is in the afternoon.
+ /** Returns true if the time is in the afternoon in local timezone.
So it returns true for "PM", false for "AM".
@@ -173,7 +170,7 @@ public:
*/
bool isAfternoon() const noexcept;
- /** Returns the hours in 12-hour clock format.
+ /** Returns the hours in 12-hour clock format in local timezone.
This will return a value 1 to 12 - use isAfternoon() to find out
whether this is in the afternoon or morning.
@@ -182,7 +179,7 @@ public:
*/
int getHoursInAmPmFormat() const noexcept;
- /** Returns the number of minutes, 0 to 59. */
+ /** Returns the number of minutes, 0 to 59 in local timezone. */
int getMinutes() const noexcept;
/** Returns the number of seconds, 0 to 59. */
@@ -204,7 +201,7 @@ public:
String getTimeZone() const noexcept;
//==============================================================================
- /** Quick way of getting a string version of a date and time.
+ /** Quick way of getting a string version of a date and time in local timezone.
For a more powerful way of formatting the date and time, see the formatted() method.
@@ -227,28 +224,28 @@ public:
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 %.
+ - %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
*/
@@ -269,7 +266,7 @@ public:
bool setSystemTimeToThisTime() const;
//==============================================================================
- /** Returns the name of a day of the week.
+ /** Returns the name of a day of the week in local timezone.
@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
@@ -277,7 +274,7 @@ public:
*/
static String getWeekdayName (int dayNumber, bool threeLetterVersion);
- /** Returns the name of one of the months.
+ /** Returns the name of one of the months in local timezone.
@param monthNumber the month, 0 to 11
@param threeLetterVersion if true, it'll be a 3-letter abbreviation, e.g. "Jan"; if false
@@ -290,7 +287,7 @@ public:
/** Returns the current system time.
- Returns the number of milliseconds since midnight jan 1st 1970.
+ Returns the number of milliseconds since midnight Jan 1st 1970 UTC.
Should be accurate to within a few millisecs, depending on platform,
hardware, etc.
Commit available on GitHub also https://github.com/hm1992/JUCE/commit/769d75044b4ceac5e18f0da2e6302ae77217b8d8