Make wxDateTime::Tm::yday public and document it.

There doesn't seem any reason to allow access to all the other struct Tm
fields but not yday so make it public, fill it in correctly when creating Tm
without using its ctor from struct tm and document struct Tm itself including
its yday field.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@65649 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

include/wx/datetime.h

@@ -462,7 +462,9 @@ public:
         //     instead of modifying the member fields directly!
     struct WXDLLIMPEXP_BASE Tm
     {
-        wxDateTime_t msec, sec, min, hour, mday;
+        wxDateTime_t msec, sec, min, hour,
+                     mday,  // Day of the month in 1..31 range.
+                     yday;  // Day of the year in 0..365 range.
         Month mon;
         int year;
 
@@ -497,9 +499,10 @@ public:
         // the timezone we correspond to
         TimeZone m_tz;
 
-        // these values can't be accessed directly because they're not always
+        // This value can only be accessed via GetWeekDay() and not directly
-        // computed and we calculate them on demand
+        // because it's not always computed when creating this object and may
-        wxDateTime_t wday, yday;
+        // need to be calculated on demand.
+        wxDateTime_t wday;
     };
 
     // static methods

interface/wx/datetime.h

@@ -244,6 +244,42 @@ public:
     };
 
 
+    /**
+        Contains broken down date-time representation.
+
+        This struct is analogous to standard C <code>struct tm</code> and uses
+        the same, not always immediately obvious, conventions for its members:
+        notably its mon and mday fields count from 0 while yday counts from 1.
+     */
+    struct Tm
+    {
+        wxDateTime_t msec,  ///< Number of milliseconds.
+                     sec,   ///< Seconds in 0..59 (60 with leap seconds) range.
+                     min,   ///< Minutes in 0..59 range.
+                     hour,  ///< Hours since midnight in 0..23 range.
+                     mday,  ///< Day of the month in 1..31 range.
+                     yday;  ///< Day of the year in 0..365 range.
+        Month mon;          ///< Month, as an enumerated constant.
+        int year;           ///< Year.
+
+        /**
+            Check if the given date/time is valid (in Gregorian calendar).
+
+            Return @false if the components don't correspond to a correct date.
+         */
+        bool IsValid() const;
+
+        /**
+            Return the week day corresponding to this date.
+
+            Unlike the other fields, the week day is not always available and
+            so must be accessed using this method as it is computed on demand
+            when it is called.
+         */
+        WeekDay GetWeekDay();
+    };
+
+
     /**
         @name Constructors, Assignment Operators and Setters
 

src/common/datetime.cpp

@@ -1616,6 +1616,7 @@ wxDateTime::Tm wxDateTime::GetTm(const TimeZone& tz) const
     // construct Tm from these values
     Tm tm;
     tm.year = (int)year;
+    tm.yday = (wxDateTime_t)(dayOfYear - 1); // use C convention for day number
     tm.mon = (Month)(month - 1); // algorithm yields 1 for January, not 0
     tm.mday = (wxDateTime_t)day;
     tm.msec = (wxDateTime_t)(timeOnly % 1000);