DateBuilder that allows DateOnly building too

Src/FluentAssertions/Common/ObjectExtensions.cs

@@ -19,15 +19,20 @@ internal static class ObjectExtensions
             // CompareNumerics is only relevant for numerics boxed in an object.
             return (actual, expected) => actual is null
                 ? expected is null
-                : expected is not null && EqualityComparer<T>.Default.Equals(actual, expected);
+                : expected is not null && Compare(actual, expected);
         }
 
         return (actual, expected) => actual is null
             ? expected is null
             : expected is not null
-            && (EqualityComparer<T>.Default.Equals(actual, expected) || CompareNumerics(actual, expected));
+            && (Compare(actual, expected) || CompareNumerics(actual, expected));
     }
 
+    // Both ways, because sometimes expected can compare to actual but not vice versa.
+    private static bool Compare<T>(T actual, T expected)
+        => EqualityComparer<T>.Default.Equals(actual, expected)
+        || EqualityComparer<T>.Default.Equals(expected, actual);
+
     private static bool CompareNumerics(object actual, object expected)
     {
         Type expectedType = expected.GetType();

Src/FluentAssertions/Extensions/DateBuilder.cs

@@ -0,0 +1,125 @@
+#nullable enable
+
+using System;
+using System.Diagnostics;
+using System.Diagnostics.CodeAnalysis;
+using System.Globalization;
+
+namespace FluentAssertions.Extensions;
+
+/// <summary>A date builder that implicitly casts both to a date only and a date time.</summary>
+public readonly partial struct DateBuilder : IEquatable<DateBuilder>
+{
+    [DebuggerBrowsable(DebuggerBrowsableState.Never)]
+    private readonly DateTime date;
+
+    /// <summary>Initializes a new instance of the <see cref="DateBuilder"/> struct.</summary>
+    internal DateBuilder(int year, int month, int day)
+        => date = new DateTime(year, month, day, 00, 00, 00, DateTimeKind.Unspecified);
+
+    /// <summary>
+    /// Returns a new <see cref="DateTimeOffset"/> value without an offset.
+    /// </summary>
+    public DateTimeOffset AsOffset() => WithOffset(0.Hours());
+
+    /// <summary>
+    /// Returns a new <see cref="DateTimeOffset"/> value with specified offset.
+    /// </summary>
+    public DateTimeOffset WithOffset(TimeSpan offset) => new(date, offset);
+
+    /// <inheritdoc />
+    public override string ToString() => date.ToString("yyyy-MM-dd", CultureInfo.InvariantCulture);
+
+    /// <inheritdoc />
+    public override int GetHashCode() => date.GetHashCode();
+
+    /// <inheritdoc />
+    public override bool Equals([NotNullWhen(true)] object? obj)
+        => (obj is DateBuilder builder && Equals(builder))
+#if NET6_0_OR_GREATER
+        || (obj is DateTime dateTime && Equals(dateTime))
+        || (obj is DateOnly dateOnly && Equals(dateOnly));
+#else
+        || (obj is DateTime dateTime && Equals(dateTime));
+#endif
+
+    /// <inheritdoc />
+    public bool Equals(DateBuilder other) => date.Equals(other.date);
+
+    /// <summary>True if both <see cref="DateBuilder"/>s represent the same date.</summary>
+    public static bool operator ==(DateBuilder left, DateBuilder right)
+        => left.Equals(right);
+
+    /// <summary>False if both <see cref="DateBuilder"/>s represent the same date.</summary>
+    public static bool operator !=(DateBuilder left, DateBuilder right)
+        => !(left == right);
+}
+
+/// <summary>Contains <see cref="DateTime"/> related logic.</summary>
+public readonly partial struct DateBuilder : IEquatable<DateTime>
+{
+    /// <summary>
+    /// Returns a new <see cref="DateTime"/> value for the <paramref name="time"/>.
+    /// </summary>
+    public DateTime At(TimeSpan time) => date.Date + time;
+
+    /// <summary>
+    /// Returns a new <see cref="DateTime"/> value for time with the specified
+    /// <paramref name="hours"/>, <paramref name="minutes"/> and optionally <paramref name="seconds"/>.
+    /// </summary>
+    public DateTime At(int hours, int minutes, int seconds = 0, int milliseconds = 0,
+        int microseconds = 0, int nanoseconds = 0)
+    {
+        if (microseconds is < 0 or > 999)
+        {
+            throw new ArgumentOutOfRangeException(nameof(microseconds), "Valid values are between 0 and 999");
+        }
+
+        if (nanoseconds is < 0 or > 999)
+        {
+            throw new ArgumentOutOfRangeException(nameof(nanoseconds), "Valid values are between 0 and 999");
+        }
+
+        var value = new DateTime(date.Year, date.Month, date.Day, hours, minutes, seconds, milliseconds, date.Kind);
+
+        if (microseconds != 0)
+        {
+            value += microseconds.Microseconds();
+        }
+
+        if (nanoseconds != 0)
+        {
+            value += nanoseconds.Nanoseconds();
+        }
+
+        return value;
+    }
+
+    /// <summary>
+    /// Returns a new <see cref="DateTime"/> with the kind set to <see cref="DateTimeKind.Utc"/>.
+    /// </summary>
+    public DateTime AsUtc() => date.AsUtc();
+
+    /// <inheritdoc />
+    public bool Equals(DateTime other) => other.Equals(this);
+
+    /// <summary>Implicitly casts the <see cref="DateBuilder"/> to a <see cref="DateTime"/>.</summary>
+    public static implicit operator DateTime(DateBuilder builder) => builder.date;
+
+    /// <summary>Adds a <see cref="TimeSpan"/> to the <see cref="DateTime"/>.</summary>
+    public static DateTime operator +(DateBuilder builder, TimeSpan time) => builder.At(+time);
+}
+
+#if NET6_0_OR_GREATER
+
+/// <summary>Contains <see cref="DateOnly"/> related logic.</summary>
+public readonly partial struct DateBuilder : IEquatable<DateOnly>
+{
+    /// <inheritdoc />
+    public bool Equals(DateOnly other) => other.Equals(this);
+
+    /// <summary>Implicitly casts the <see cref="DateBuilder"/> to a <see cref="DateOnly"/>.</summary>
+    public static implicit operator DateOnly(DateBuilder builder) => DateOnly.FromDateTime(builder.date);
+}
+
+#endif

Src/FluentAssertions/Extensions/FluentDateTimeExtensions.cs

@@ -1,6 +1,5 @@
 using System;
 using System.Diagnostics;
-using FluentAssertions.Common;
 
 namespace FluentAssertions.Extensions;
 
@@ -23,111 +22,111 @@ namespace FluentAssertions.Extensions;
 public static class FluentDateTimeExtensions
 {
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month January.
     /// </summary>
-    public static DateTime January(this int day, int year)
+    public static DateBuilder January(this int day, int year)
     {
-        return new DateTime(year, 1, day);
+        return new DateBuilder(year, 1, day);
     }
 
     /// <summary>
     /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month February.
     /// </summary>
-    public static DateTime February(this int day, int year)
+    public static DateBuilder February(this int day, int year)
     {
-        return new DateTime(year, 2, day);
+        return new DateBuilder(year, 2, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month March.
     /// </summary>
-    public static DateTime March(this int day, int year)
+    public static DateBuilder March(this int day, int year)
     {
-        return new DateTime(year, 3, day);
+        return new DateBuilder(year, 3, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month April.
     /// </summary>
-    public static DateTime April(this int day, int year)
+    public static DateBuilder April(this int day, int year)
     {
-        return new DateTime(year, 4, day);
+        return new DateBuilder(year, 4, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month May.
     /// </summary>
-    public static DateTime May(this int day, int year)
+    public static DateBuilder May(this int day, int year)
     {
-        return new DateTime(year, 5, day);
+        return new DateBuilder(year, 5, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month June.
     /// </summary>
-    public static DateTime June(this int day, int year)
+    public static DateBuilder June(this int day, int year)
     {
-        return new DateTime(year, 6, day);
+        return new DateBuilder(year, 6, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month July.
     /// </summary>
-    public static DateTime July(this int day, int year)
+    public static DateBuilder July(this int day, int year)
     {
-        return new DateTime(year, 7, day);
+        return new DateBuilder(year, 7, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month August.
     /// </summary>
-    public static DateTime August(this int day, int year)
+    public static DateBuilder August(this int day, int year)
     {
-        return new DateTime(year, 8, day);
+        return new DateBuilder(year, 8, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month September.
     /// </summary>
-    public static DateTime September(this int day, int year)
+    public static DateBuilder September(this int day, int year)
     {
-        return new DateTime(year, 9, day);
+        return new DateBuilder(year, 9, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month October.
     /// </summary>
-    public static DateTime October(this int day, int year)
+    public static DateBuilder October(this int day, int year)
     {
-        return new DateTime(year, 10, day);
+        return new DateBuilder(year, 10, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month November.
     /// </summary>
-    public static DateTime November(this int day, int year)
+    public static DateBuilder November(this int day, int year)
     {
-        return new DateTime(year, 11, day);
+        return new DateBuilder(year, 11, day);
     }
 
     /// <summary>
-    /// Returns a new <see cref="DateTime"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
+    /// Returns a new <see cref="DateBuilder"/> value for the specified <paramref name="day"/> and <paramref name="year"/>
     /// in the month December.
     /// </summary>
-    public static DateTime December(this int day, int year)
+    public static DateBuilder December(this int day, int year)
     {
-        return new DateTime(year, 12, day);
+        return new DateBuilder(year, 12, day);
     }
 
     /// <summary>
@@ -306,8 +305,5 @@ public static DateTimeOffset AddMicroseconds(this DateTimeOffset self, long micr
     /// Returns new <see cref="DateTimeOffset"/> that uses <paramref name="self"/>
     /// as its datetime and <paramref name="offset"/> as its offset.
     /// </summary>
-    public static DateTimeOffset WithOffset(this DateTime self, TimeSpan offset)
-    {
-        return self.ToDateTimeOffset(offset);
-    }
+    public static DateTimeOffset WithOffset(this DateTime self, TimeSpan offset) => new(self, offset);
 }

Tests/FluentAssertions.Equivalency.Specs/AssertionRuleSpecs.cs

@@ -150,9 +150,9 @@ public void When_a_nested_property_is_equal_based_on_equality_comparer_it_should
     public void When_a_nested_property_is_unequal_based_on_equality_comparer_it_should_throw()
     {
         // Arrange
-        var subject = new { Timestamp = 22.March(2020) };
+        var subject = new { Timestamp = 22.March(2020).AsUtc() };
 
-        var expectation = new { Timestamp = 1.January(2021) };
+        var expectation = new { Timestamp = 1.January(2021).AsUtc() };
 
         // Act
         Action act = () => subject.Should().BeEquivalentTo(expectation,