Add DateTime(Offset).GetIso8601WeekOfYear

CHANGELOG.md

@@ -4,6 +4,7 @@
 ### Added
 - X10D: Added `MathUtility.InverseLerp(float, float, float)` and `MathUtility.InverseLerp(double, double, double)`
 - X10D: Added `Circle`, `CircleF`, `Cuboid`, `Ellipse`, `EllipseF`, `Line3D`, `Line`, `LineF`, `Polygon`, `PolygonF`, `Polyhedron`, and `Sphere`, to complement System.Drawing structs such as `Point` and `Rectangle`
+- X10D: Added `DateTime.GetIso8601WeekOfYear()` and `DateTimeOffset.GetIso8601WeekOfYear()`
 - X10D: Added `DirectoryInfo.Clear([bool])`
 - X10D: Added `IList<T>.RemoveRange(Range)`
 - X10D: Added `Point.IsOnLine(LineF)`, `Point.IsOnLine(PointF, PointF)`, and `Point.IsOnLine(Vector2, Vector2)`

X10D/src/Time/DateTimeExtensions.cs

@@ -1,4 +1,5 @@
 using System.Diagnostics.Contracts;
+using System.Globalization;
 using System.Runtime.CompilerServices;
 
 namespace X10D.Time;
@@ -58,6 +59,32 @@ public static class DateTimeExtensions
         return ((DateTimeOffset)value).FirstDayOfMonth().DateTime;
     }
 
+    /// <summary>
+    ///     Gets the ISO-8601 week number of the year for the current date.
+    /// </summary>
+    /// <param name="value">The date whose week number to return.</param>
+    /// <returns>The ISO-8601 week number of the year.</returns>
+    /// <author>Shawn Steele, Microsoft</author>
+    /// <remarks>
+    ///     This implementation is directly inspired from a
+    ///     <a href="https://docs.microsoft.com/en-gb/archive/blogs/shawnste/iso-8601-week-of-year-format-in-microsoft-net">
+    ///         blog post
+    ///     </a>.
+    ///     about this subject.
+    /// </remarks>
+    [Pure]
+    public static int GetIso8601WeekOfYear(this DateTime value)
+    {
+        var calendar = CultureInfo.InvariantCulture.Calendar;
+        DayOfWeek day = calendar.GetDayOfWeek(value);
+        if (day is >= DayOfWeek.Monday and <= DayOfWeek.Wednesday)
+        {
+            value = value.AddDays(3);
+        }
+
+        return calendar.GetWeekOfYear(value, CalendarWeekRule.FirstFourDayWeek, DayOfWeek.Monday);
+    }
+
     /// <summary>
     ///     Returns a value indicating whether the year represented by the current <see cref="DateTime" /> is a leap year.
     /// </summary>

X10D/src/Time/DateTimeOffsetExtensions.cs

@@ -84,6 +84,25 @@ public static class DateTimeOffsetExtensions
         return value.AddDays(1 - value.Day);
     }
 
+    /// <summary>
+    ///     Gets the ISO-8601 week number of the year for the current date.
+    /// </summary>
+    /// <param name="value">The date whose week number to return.</param>
+    /// <returns>The ISO-8601 week number of the year.</returns>
+    /// <author>Shawn Steele, Microsoft</author>
+    /// <remarks>
+    ///     This implementation is directly inspired from a
+    ///     <a href="https://docs.microsoft.com/en-gb/archive/blogs/shawnste/iso-8601-week-of-year-format-in-microsoft-net">
+    ///         blog post
+    ///     </a>.
+    ///     about this subject.
+    /// </remarks>
+    [Pure]
+    public static int GetIso8601WeekOfYear(this DateTimeOffset value)
+    {
+        return value.DateTime.GetIso8601WeekOfYear();
+    }
+
     /// <summary>
     ///     Returns a value indicating whether the year represented by the current <see cref="DateTimeOffset" /> is a leap year.
     /// </summary>