Add wxDateTime::GetWeekBasedYear().

It was just added as a private function to implement %V format specifier
support, just extract and document it as it could possibly be useful in its
own right.

See #11857.

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

docs/changes.txt

@@ -36,6 +36,7 @@ All:
 - Add wxInt64 support to wxText{Input,Output}Stream (Alexander Bezzubikov).
 - Define wxOVERRIDE as override for supporting compilers (Thomas Goyne).
 - Allow specifying custom comparator for wxSortedArrayString (Catalin Raceanu).
+- Add wxDateTime::GetWeekBasedYear().
 
 Unix:
 

include/wx/datetime.h

@@ -760,6 +760,9 @@ public:
         // invalid)
     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
                                const TimeZone& tz = Local) const;
+        // get the year to which the number returned from GetWeekOfYear()
+        // belongs
+    int GetWeekBasedYear(const TimeZone& tz = Local) const;
         // get the week number since the month start (1..5, 0 if date is
         // invalid)
     wxDateTime_t GetWeekOfMonth(WeekFlags flags = Monday_First,

interface/wx/datetime.h

@@ -576,6 +576,25 @@ public:
     */
     WeekDay GetWeekDay(const TimeZone& tz = Local) const;
 
+    /**
+        Returns the year to which the week containing this date belongs.
+
+        The value returned by this function is the same as the year, except,
+        possibly, for a few days at the very beginning and very end of the year
+        if they belong to a week which is mostly (i.e. at least 4 days) is in
+        another year in which case that other (previous or next) year is
+        returned.
+
+        For example, January 1 in 2015 belongs to the first year of 2015, hence
+        GetWeekOfYear() for it returns 1 and this function returns 2015.
+        However January 1 in 2016 belongs to the last week of 2015 according to
+        ISO 8601 standard rules and so GetWeekOfYear() returns 53 and this
+        function returns 2015, although GetYear() returns 2016.
+
+        @since 3.1.0
+    */
+    int GetWeekBasedYear(const TimeZone& tz) const;
+
     /**
         Returns the ordinal number of the week in the month (in 1-5 range).
 
@@ -597,6 +616,8 @@ public:
         The function depends on the week start convention specified by the @a flags
         argument but its results for @c Sunday_First are not well-defined as the
         ISO definition quoted above applies to the weeks starting on Monday only.
+
+        @see GetWeekBasedYear()
     */
     wxDateTime_t GetWeekOfYear(WeekFlags flags = Monday_First,
                                const TimeZone& tz = Local) const;

src/common/datetime.cpp

@@ -1946,6 +1946,28 @@ wxDateTime::GetWeekOfYear(wxDateTime::WeekFlags flags, const TimeZone& tz) const
     return (wxDateTime::wxDateTime_t)week;
 }
 
+int wxDateTime::GetWeekBasedYear(const TimeZone& tz) const
+{
+    const wxDateTime::Tm tm = GetTm(tz);
+
+    int year = tm.year;
+
+    // The week-based year can only be different from the normal year for few
+    // days in the beginning and the end of the year.
+    if ( tm.yday > 361 )
+    {
+        if ( GetWeekOfYear(Monday_First, tz) == 1 )
+            year++;
+    }
+    else if ( tm.yday < 5 )
+    {
+        if ( GetWeekOfYear(Monday_First, tz) == 53 )
+            year--;
+    }
+
+    return year;
+}
+
 wxDateTime::wxDateTime_t wxDateTime::GetWeekOfMonth(wxDateTime::WeekFlags flags,
                                                     const TimeZone& tz) const
 {

src/common/datetimefmt.cpp

@@ -271,30 +271,6 @@ GetWeekDayFromName(wxString::const_iterator& p,
     return wd;
 }
 
-// return the year of the Monday of the week containing the given date
-int
-GetWeekBasedYear(const wxDateTime& dt)
-{
-    const wxDateTime::Tm tm = dt.GetTm();
-
-    int year = tm.year;
-
-    // The week-based year can only be different from the normal year for few
-    // days in the beginning and the end of the year.
-    if ( tm.yday > 361 )
-    {
-        if ( dt.GetWeekOfYear() == 1 )
-            year++;
-    }
-    else if ( tm.yday < 5 )
-    {
-        if ( dt.GetWeekOfYear() == 53 )
-            year--;
-    }
-
-    return year;
-}
-
 // parses string starting at given iterator using the specified format and,
 // optionally, a fall back format (and optionally another one... but it stops
 // there, really)
@@ -623,11 +599,11 @@ wxString wxDateTime::Format(const wxString& formatp, const TimeZone& tz) const
                     break;
 
                 case wxT('g'):      // 2-digit week-based year
-                    res += wxString::Format(fmt, GetWeekBasedYear(*this) % 100);
+                    res += wxString::Format(fmt, GetWeekBasedYear() % 100);
                     break;
 
                 case wxT('G'):       // week-based year with century
-                    res += wxString::Format(fmt, GetWeekBasedYear(*this));
+                    res += wxString::Format(fmt, GetWeekBasedYear());
                     break;
 
                 case wxT('H'):       // hour in 24h format (00-23)