From 2fb3eb77dd38f365c5f4c5fb20176516187e09a4 Mon Sep 17 00:00:00 2001
From: Oliver Booth <me@olivr.me>
Date: Tue, 5 Jul 2022 21:26:45 +0100
Subject: [PATCH] Add DateTime(Offset).GetIso8601WeekOfYear

---
 CHANGELOG.md                              |  1 +
 X10D/src/Time/DateTimeExtensions.cs       | 27 +++++++++++++++++++++++
 X10D/src/Time/DateTimeOffsetExtensions.cs | 19 ++++++++++++++++
 3 files changed, 47 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 03386e6..08dccfb 100644
--- a/CHANGELOG.md
+++ b/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)`
diff --git a/X10D/src/Time/DateTimeExtensions.cs b/X10D/src/Time/DateTimeExtensions.cs
index f06a4f0..3210aa5 100644
--- a/X10D/src/Time/DateTimeExtensions.cs
+++ b/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>
diff --git a/X10D/src/Time/DateTimeOffsetExtensions.cs b/X10D/src/Time/DateTimeOffsetExtensions.cs
index e30560b..eeb8a67 100644
--- a/X10D/src/Time/DateTimeOffsetExtensions.cs
+++ b/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>