juce_Time Comments / Docs improvements [PULL REQUEST]


#1

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


#2

Thanks for all this Harry - I need to devote some time to your time stuff, and will look at it either over the weekend or monday..


#3

Hi Jules,

Thanks for looking at it. All the changes I have made are in that github fork. If you need anything else I am happy to help.


#4

Hey Harry - I've added this functionality, though rewrote it a bit. I've added some unit-tests that seem to work but you might want to make sure I've not broken anything!


#5

This looks good. I just have a few things:

* I think this change (https://github.com/hm1992/JUCE/commit/8a0f4135e1bd4c9d705227a8f34db121cffcd869) should go in to avoid an assertion in visual studio in Time::formatted.

* In ISO8601 "2016-02-16T15:03:57:999Z" is not correct but "2016-02-16T15:03:57,999Z" or "2016-02-16T15:03:57.999Z" is. Milliseconds are fractions of seconds rather than another element. "20160216T150357999Z" is not correct either, it must be "20160216T150357.999Z" or "20160216T150357,999Z". (https://en.wikipedia.org/wiki/ISO_8601#Times)

* I think (I posted this in a separate thread to avoid cross-threading http://www.juce.com/forum/topic/time-and-2038-problem) that you should consider widening the "isBeyond1970to2030Range" and "if (year < 1971 || year >= 2038" to cover a wider area on platforms which support it.


#6

Ah, I see.. ok, will make it parse the fractional part.

For the MSVC thing, you commented that it was 9999AD but used 8099 in the code - which is right?


#7

It is 0AD to 9999AD which is tm_year (from 1900) of -1900 to 8099.

The year 9999 seems to work, the year 10000 does not as far as formatted is concerned.


#8

Gotcha.