feat: add WithOffset and DateTimeOffsetBuilder

Source/aweXpect.Chronology/DateBuilder.cs

@@ -44,4 +44,7 @@ public static implicit operator DateOnly(DateBuilder builder)
 
 	internal DateTimeBuilder Add(TimeSpan time)
 		=> new(_value + time);
+
+	internal DateTimeOffsetBuilder SetOffset(TimeSpan offset)
+		=> new(new DateTimeOffset(_value, offset));
 }

Source/aweXpect.Chronology/DateTimeBuilder.cs

@@ -4,8 +4,8 @@ namespace aweXpect.Chronology;
 
 #if NET8_0_OR_GREATER
 /// <summary>
-///     A builder that allows implicit cast to <see cref="DateTime" />, <see cref="DateOnly" /> and <see cref="TimeOnly" />
-///     .
+///     A builder that allows implicit cast to <see cref="DateTime" />, <see cref="DateOnly" />
+///     and <see cref="TimeOnly" />.
 /// </summary>
 #else
 /// <summary>
@@ -52,4 +52,7 @@ public static implicit operator TimeOnly(DateTimeBuilder builder)
 
 	internal DateTimeBuilder SpecifyKind(DateTimeKind kind)
 		=> new(DateTime.SpecifyKind(_value, kind));
+
+	internal DateTimeOffsetBuilder SetOffset(TimeSpan offset)
+		=> new(new DateTimeOffset(_value, offset));
 }

Source/aweXpect.Chronology/DateTimeOffsetBuilder.cs

@@ -0,0 +1,58 @@
+using System;
+
+namespace aweXpect.Chronology;
+
+#if NET8_0_OR_GREATER
+/// <summary>
+///     A builder that allows implicit cast to <see cref="DateTimeOffset" />, <see cref="DateTime" />,
+///     <see cref="DateOnly" /> and <see cref="TimeOnly" />.
+/// </summary>
+#else
+/// <summary>
+///     A builder that allows implicit cast to <see cref="DateTimeOffset" /> and <see cref="DateTime" />.
+/// </summary>
+#endif
+public readonly struct DateTimeOffsetBuilder(DateTimeOffset value)
+{
+	private readonly DateTimeOffset _value = value;
+
+	/// <summary>
+	///     Implicitly casts the <see cref="DateTimeBuilder" /> to a <see cref="DateTime" />.
+	/// </summary>
+	public static implicit operator DateTime(DateTimeOffsetBuilder builder)
+		=> builder._value.DateTime;
+
+	/// <summary>
+	///     Implicitly casts the <see cref="DateTimeBuilder" /> to a <see cref="DateTimeOffset" />.
+	/// </summary>
+	public static implicit operator DateTimeOffset(DateTimeOffsetBuilder builder)
+		=> builder._value;
+
+#if NET8_0_OR_GREATER
+	/// <summary>
+	///     Implicitly casts the <see cref="DateTimeBuilder" /> to a <see cref="DateOnly" />.
+	/// </summary>
+	public static implicit operator DateOnly(DateTimeOffsetBuilder builder)
+		=> DateOnly.FromDateTime(builder._value.DateTime);
+#endif
+
+#if NET8_0_OR_GREATER
+	/// <summary>
+	///     Implicitly casts the <see cref="DateTimeBuilder" /> to a <see cref="TimeOnly" />.
+	/// </summary>
+	public static implicit operator TimeOnly(DateTimeOffsetBuilder builder)
+		=> TimeOnly.FromDateTime(builder._value.DateTime);
+#endif
+
+	/// <summary>
+	///     Adds a <see cref="TimeSpan" /> to the <see cref="DateTime" />.
+	/// </summary>
+	public static DateTimeOffsetBuilder operator +(DateTimeOffsetBuilder builder, TimeSpan time)
+		=> new(builder._value + time);
+
+	/// <summary>
+	///     Subtracts a <see cref="TimeSpan" /> from the <see cref="DateTime" />.
+	/// </summary>
+	public static DateTimeOffsetBuilder operator -(DateTimeOffsetBuilder builder, TimeSpan time)
+		=> new(builder._value - time);
+}

Source/aweXpect.Chronology/DateTimeOffsetExtensions.cs

@@ -0,0 +1,34 @@
+using System;
+
+namespace aweXpect.Chronology;
+
+/// <summary>
+///     Extension methods for creating <see cref="DateTimeOffset" />.
+/// </summary>
+/// <example>
+///     Instead of <c>new DateTime(2024, 24, 12, 14, 30, 0, TimeSpan.FromHours(2))</c><br />
+///     you can write <c>24.December(2024).At(14, 30).WithOffset(2.Hours())</c>.
+/// </example>
+public static class DateTimeOffsetExtensions
+{
+	/// <summary>
+	///     Creates a <see cref="DateTimeOffset" /> that uses the <paramref name="dateTime" />
+	///     with the given <paramref name="offset" />.
+	/// </summary>
+	public static DateTimeOffsetBuilder WithOffset(this DateBuilder dateTime, TimeSpan offset)
+		=> dateTime.SetOffset(offset);
+
+	/// <summary>
+	///     Creates a <see cref="DateTimeOffset" /> that uses the <paramref name="dateTime" />
+	///     with the given <paramref name="offset" />.
+	/// </summary>
+	public static DateTimeOffsetBuilder WithOffset(this DateTimeBuilder dateTime, TimeSpan offset)
+		=> dateTime.SetOffset(offset);
+
+	/// <summary>
+	///     Creates a <see cref="DateTimeOffset" /> that uses the <paramref name="dateTime" />
+	///     with the given <paramref name="offset" />.
+	/// </summary>
+	public static DateTimeOffsetBuilder WithOffset(this DateTime dateTime, TimeSpan offset)
+		=> new(new DateTimeOffset(dateTime, offset));
+}

Tests/aweXpect.Chronology.Api.Tests/Expected/aweXpect.Chronology_net8.0.txt

@@ -52,6 +52,22 @@ namespace aweXpect.Chronology
         public static aweXpect.Chronology.DateBuilder October(this int day, int year) { }
         public static aweXpect.Chronology.DateBuilder September(this int day, int year) { }
     }
+    public readonly struct DateTimeOffsetBuilder
+    {
+        public DateTimeOffsetBuilder(System.DateTimeOffset value) { }
+        public static System.DateTime op_Implicit(aweXpect.Chronology.DateTimeOffsetBuilder builder) { }
+        public static System.DateTimeOffset op_Implicit(aweXpect.Chronology.DateTimeOffsetBuilder builder) { }
+        public static System.DateOnly op_Implicit(aweXpect.Chronology.DateTimeOffsetBuilder builder) { }
+        public static System.TimeOnly op_Implicit(aweXpect.Chronology.DateTimeOffsetBuilder builder) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder operator +(aweXpect.Chronology.DateTimeOffsetBuilder builder, System.TimeSpan time) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder operator -(aweXpect.Chronology.DateTimeOffsetBuilder builder, System.TimeSpan time) { }
+    }
+    public static class DateTimeOffsetExtensions
+    {
+        public static aweXpect.Chronology.DateTimeOffsetBuilder WithOffset(this System.DateTime dateTime, System.TimeSpan offset) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder WithOffset(this aweXpect.Chronology.DateBuilder dateTime, System.TimeSpan offset) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder WithOffset(this aweXpect.Chronology.DateTimeBuilder dateTime, System.TimeSpan offset) { }
+    }
     public readonly struct TimeSpanBuilder
     {
         public TimeSpanBuilder(System.TimeSpan value) { }

Tests/aweXpect.Chronology.Api.Tests/Expected/aweXpect.Chronology_netstandard2.0.txt

@@ -47,6 +47,20 @@ namespace aweXpect.Chronology
         public static aweXpect.Chronology.DateBuilder October(this int day, int year) { }
         public static aweXpect.Chronology.DateBuilder September(this int day, int year) { }
     }
+    public readonly struct DateTimeOffsetBuilder
+    {
+        public DateTimeOffsetBuilder(System.DateTimeOffset value) { }
+        public static System.DateTime op_Implicit(aweXpect.Chronology.DateTimeOffsetBuilder builder) { }
+        public static System.DateTimeOffset op_Implicit(aweXpect.Chronology.DateTimeOffsetBuilder builder) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder operator +(aweXpect.Chronology.DateTimeOffsetBuilder builder, System.TimeSpan time) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder operator -(aweXpect.Chronology.DateTimeOffsetBuilder builder, System.TimeSpan time) { }
+    }
+    public static class DateTimeOffsetExtensions
+    {
+        public static aweXpect.Chronology.DateTimeOffsetBuilder WithOffset(this System.DateTime dateTime, System.TimeSpan offset) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder WithOffset(this aweXpect.Chronology.DateBuilder dateTime, System.TimeSpan offset) { }
+        public static aweXpect.Chronology.DateTimeOffsetBuilder WithOffset(this aweXpect.Chronology.DateTimeBuilder dateTime, System.TimeSpan offset) { }
+    }
     public readonly struct TimeSpanBuilder
     {
         public TimeSpanBuilder(System.TimeSpan value) { }

Tests/aweXpect.Chronology.Tests/DateTimeOffsetBuilderTests.cs

@@ -0,0 +1,74 @@
+namespace aweXpect.Chronology.Tests;
+
+public sealed class DateTimeOffsetBuilderTests
+{
+	[Fact]
+	public async Task MinusOperator_ShouldSubtractTimeSpan()
+	{
+		DateTimeOffsetBuilder expected = 23.March(2024).At(10, 00).WithOffset(2.Hours());
+		DateTimeOffsetBuilder builder = new(23.March(2024).At(12, 00).WithOffset(2.Hours()));
+
+		DateTime result = builder - 2.Hours();
+
+		await That(result).Should().Be(expected);
+	}
+
+	[Fact]
+	public async Task PlusOperator_ShouldAddTimeSpan()
+	{
+		DateTimeOffsetBuilder expected = 23.March(2024).At(14, 00).WithOffset(2.Hours());
+		DateTimeOffsetBuilder builder = new(23.March(2024).At(12, 00).WithOffset(2.Hours()));
+
+		DateTime result = builder + 2.Hours();
+
+		await That(result).Should().Be(expected);
+	}
+
+	[Fact]
+	public async Task ImplicitOperator_ShouldConvertToDateTime()
+	{
+		DateTime expected = new(2024, 03, 23, 12, 13, 14);
+		DateTimeOffsetBuilder builder = new(23.March(2024).At(12, 13, 14).WithOffset(2.Hours()));
+
+		DateTime result = builder;
+
+		await That(result).Should().Be(expected);
+	}
+
+	[Fact]
+	public async Task ImplicitOperator_ShouldConvertToDateTimeOffset()
+	{
+		DateTimeOffset expected = new(2024, 03, 23, 12, 13, 14, TimeSpan.FromHours(2));
+		DateTimeOffsetBuilder builder = new(23.March(2024).At(12, 13, 14).WithOffset(2.Hours()));
+
+		DateTimeOffset result = builder;
+
+		await That(result).Should().Be(expected);
+	}
+
+#if NET8_0_OR_GREATER
+	[Fact]
+	public async Task ImplicitOperator_ShouldConvertToDateOnly()
+	{
+		DateOnly expected = new(2024, 03, 23);
+		DateTimeOffsetBuilder builder = new(23.March(2024).At(12, 13, 14).WithOffset(2.Hours()));
+
+		DateOnly result = builder;
+
+		await That(result).Should().Be(expected);
+	}
+#endif
+
+#if NET8_0_OR_GREATER
+	[Fact]
+	public async Task ImplicitOperator_ShouldConvertToTimeOnly()
+	{
+		TimeOnly expected = new(12, 13, 14);
+		DateTimeOffsetBuilder builder = new(23.March(2024).At(12, 13, 14).WithOffset(2.Hours()));
+
+		TimeOnly result = builder;
+
+		await That(result).Should().Be(expected);
+	}
+#endif
+}

Tests/aweXpect.Chronology.Tests/DateTimeOffsetExtensions.WithOffsetTests.cs

@@ -0,0 +1,40 @@
+namespace aweXpect.Chronology.Tests;
+
+public sealed class DateTimeOffsetExtensions
+{
+	public sealed class WithOffsetTests
+	{
+		[Fact]
+		public async Task WithDateTime_ShouldApplyOffset()
+		{
+			DateTimeOffset expected = new(2024, 12, 24, 21, 0, 0, TimeSpan.FromHours(7.5));
+			DateTime dateTime = 24.December(2024).At(21, 0);
+
+			DateTimeOffset result = dateTime.WithOffset(7.5.Hours());
+
+			await That(result).Should().Be(expected);
+		}
+
+		[Fact]
+		public async Task WithDateTimeBuilder_ShouldApplyOffset()
+		{
+			DateTimeOffset expected = new(2024, 12, 24, 21, 0, 0, TimeSpan.FromHours(7.5));
+			DateTimeBuilder dateTime = 24.December(2024).At(21, 0);
+
+			DateTimeOffset result = dateTime.WithOffset(7.5.Hours());
+
+			await That(result).Should().Be(expected);
+		}
+
+		[Fact]
+		public async Task WithDateBuilder_ShouldApplyOffset()
+		{
+			DateTimeOffset expected = new(2024, 12, 24, 0, 0, 0, TimeSpan.FromHours(7.5));
+			DateBuilder dateTime = 24.December(2024);
+
+			DateTimeOffset result = dateTime.WithOffset(7.5.Hours());
+
+			await That(result).Should().Be(expected);
+		}
+	}
+}