Added DateTimeExtensions.

CHANGELOG.md

@@ -9,6 +9,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Nothing yet.
 
+## [1.18.0] - 2024-07-30
+
+### Added
+
+- `DateTimeExtensions`.
+
+### Fixed
+
+- Upgraded NuGet package.
+
 ## [1.17.0] - 2024-06-06
 
 ### Changed
@@ -211,7 +221,8 @@ Nothing yet.
 
 - Implemented StringExtensions.
 
-[unreleased]: https://github.com/Logitar/Logitar.NET/compare/v1.17.0...HEAD
+[unreleased]: https://github.com/Logitar/Logitar.NET/compare/v1.18.0...HEAD
+[1.18.0]: https://github.com/Logitar/Logitar.NET/compare/v1.17.0...v1.18.0
 [1.17.0]: https://github.com/Logitar/Logitar.NET/compare/v1.16.0...v1.17.0
 [1.16.0]: https://github.com/Logitar/Logitar.NET/compare/v1.15.0...v1.16.0
 [1.15.0]: https://github.com/Logitar/Logitar.NET/compare/v1.14.0...v1.15.0

src/Logitar/DateTimeExtensions.cs

@@ -0,0 +1,28 @@
+namespace Logitar;
+
+/// <summary>
+/// Provides extension methods for <see cref="DateTime"/> instances.
+/// </summary>
+public static class DateTimeExtensions
+{
+  /// <summary>
+  /// Converts the specified date and time as universal (UTC).
+  /// </summary>
+  /// <param name="value">The date and time to convert.</param>
+  /// <returns>The date and time as universal (UTC).</returns>
+  /// <exception cref="ArgumentException">The date time kind is no supported.</exception>
+  public static DateTime AsUniversalTime(this DateTime value) => value.Kind switch
+  {
+    DateTimeKind.Local => value.ToUniversalTime(),
+    DateTimeKind.Unspecified => DateTime.SpecifyKind(value, DateTimeKind.Utc),
+    DateTimeKind.Utc => value,
+    _ => throw new ArgumentException($"The date time kind '{value.Kind}' is not supported.", nameof(value)),
+  };
+
+  /// <summary>
+  /// Converts the specified date and time as an ISO 8601 string.
+  /// </summary>
+  /// <param name="value">The date and time to convert.</param>
+  /// <returns>The string representation.</returns>
+  public static string ToISOString(this DateTime value) => value.AsUniversalTime().ToString("O", CultureInfo.InvariantCulture);
+}

src/Logitar/Logitar.csproj

@@ -15,14 +15,14 @@
     <PackageReadmeFile>README.md</PackageReadmeFile>
     <RepositoryType>git</RepositoryType>
     <RepositoryUrl>https://github.com/Logitar/Logitar.NET</RepositoryUrl>
-    <AssemblyVersion>6.2.0.0</AssemblyVersion>
+    <AssemblyVersion>6.3.0.0</AssemblyVersion>
     <FileVersion>$(AssemblyVersion)</FileVersion>
     <PackageLicenseFile>LICENSE</PackageLicenseFile>
     <PackageRequireLicenseAcceptance>True</PackageRequireLicenseAcceptance>
-    <Version>6.2.0</Version>
+    <Version>6.3.0</Version>
     <NeutralLanguage>en-CA</NeutralLanguage>
     <GenerateDocumentationFile>True</GenerateDocumentationFile>
-    <PackageReleaseNotes>Now targeting .NET Standard 2.1.</PackageReleaseNotes>
+    <PackageReleaseNotes>Added DateTimeExtensions and upgraded NuGet.</PackageReleaseNotes>
     <PackageTags>logitar net framework</PackageTags>
     <PackageProjectUrl>https://github.com/Logitar/Logitar.NET/tree/dev/src/Logitar</PackageProjectUrl>
   </PropertyGroup>
@@ -36,7 +36,7 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="System.Text.Json" Version="8.0.3" />
+    <PackageReference Include="System.Text.Json" Version="8.0.4" />
   </ItemGroup>
 
   <ItemGroup>
@@ -56,6 +56,7 @@
 
   <ItemGroup>
     <Using Include="System.Collections" />
+    <Using Include="System.Globalization" />
     <Using Include="System.Text.Json" />
   </ItemGroup>
 

tests/Logitar.UnitTests/DateTimeExtensionsTests.cs

@@ -0,0 +1,50 @@
+namespace Logitar;
+
+[Trait(Traits.Category, Categories.Unit)]
+public class DateTimeExtensionsTests
+{
+  [Fact(DisplayName = "AsUniversalTime: it should return a local DateTime as universal (UTC).")]
+  public void AsUniversalTime_it_should_return_a_local_DateTime_as_universal_UTC()
+  {
+    DateTime value = DateTime.Now;
+    Assert.Equal(value.ToUniversalTime(), value.AsUniversalTime());
+  }
+
+  [Fact(DisplayName = "AsUniversalTime: it should return an unspecified DateTime as universal (UTC) with the same date and time.")]
+  public void AsUniversalTime_it_should_return_an_unspecified_DateTime_as_universal_UTC_with_the_same_date_and_time()
+  {
+    DateTime value = new(2024, 5, 21, 20, 7, 53);
+    DateTime expected = new(2024, 5, 21, 20, 7, 53, DateTimeKind.Utc);
+    Assert.Equal(expected, value.AsUniversalTime());
+  }
+
+  [Fact(DisplayName = "AsUniversalTime: it should return the original universal (UTC) DateTime.")]
+  public void AsUniversalTime_it_should_return_the_original_universal_UTC_DateTime()
+  {
+    DateTime value = DateTime.UtcNow;
+    Assert.Equal(value, value.AsUniversalTime());
+  }
+
+  [Fact(DisplayName = "ToISOString: it should return the correct string representation (local).")]
+  public void ToISOString_it_should_return_the_correct_string_representation_local()
+  {
+    DateTime value = new(2024, 5, 21, 16, 7, 53, DateTimeKind.Local);
+    string expected = value.ToUniversalTime().ToISOString();
+    Assert.Equal(expected, value.ToISOString());
+  }
+
+  [Fact(DisplayName = "ToISOString: it should return the correct string representation (unspecified).")]
+  public void ToISOString_it_should_return_the_correct_string_representation_unspecified()
+  {
+    DateTime value = new(2024, 5, 21, 16, 7, 53);
+    string expected = DateTime.SpecifyKind(value, DateTimeKind.Utc).ToISOString();
+    Assert.Equal(expected, value.ToISOString());
+  }
+
+  [Fact(DisplayName = "ToISOString: it should return the correct string representation (UTC).")]
+  public void ToISOString_it_should_return_the_correct_string_representation_UTC()
+  {
+    DateTime value = new(2024, 5, 21, 16, 7, 53, DateTimeKind.Utc);
+    Assert.Equal("2024-05-21T16:07:53.0000000Z", value.ToISOString());
+  }
+}