Added ToInvariantString extension method overloads

Classes implementing the IFormattable interface indicates that they can be converted to a string representation using a specified format. The first overload therefore takes an instance of IFormattable and a second parameter for the format.

From .NET 7 and up, .NET features the StringSyntaxAttribute class, that can be used to specify the available format for the "format" parameter, which then can improve the intellisense. Additional extension method overloads for DateTime, DateTimeOffset and TimeSpan are added as well.

The extension method overloads are added for all of the current target frameworks. Since StringSyntaxAttribute is only supported from .NET 7 and up, Skybrud.Essentials adds an internal StringSyntaxAttribute class to also support older target frameworks. This should then - in theory - also allow better intellisense for those target frameworks.

Author: abjerner

src/Skybrud.Essentials/StringSyntaxAttribute.cs

@@ -0,0 +1,58 @@
+#if !NET7_0_OR_GREATER
+
+// ReSharper disable CheckNamespace
+
+namespace System.Diagnostics.CodeAnalysis;
+
+/// <summary>Specifies the syntax used in a string.</summary>
+/// <see>
+///     <cref>https://github.com/dotnet/runtime/blob/main/src/libraries/System.Private.CoreLib/src/System/Diagnostics/CodeAnalysis/StringSyntaxAttribute.cs</cref>
+/// </see>
+[AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Field | AttributeTargets.Property)]
+internal sealed class StringSyntaxAttribute(string syntax) : Attribute {
+
+    /// <summary>Gets the identifier of the syntax used.</summary>
+    public string Syntax { get; } = syntax;
+
+    /// <summary>Optional arguments associated with the specific syntax employed.</summary>
+    public object?[] Arguments { get; } = [];
+
+    /// <summary>The syntax identifier for strings containing composite formats for string formatting.</summary>
+    public const string CompositeFormat = nameof(CompositeFormat);
+
+    /// <summary>The syntax identifier for strings containing date format specifiers.</summary>
+    public const string DateOnlyFormat = nameof(DateOnlyFormat);
+
+    /// <summary>The syntax identifier for strings containing date and time format specifiers.</summary>
+    public const string DateTimeFormat = nameof(DateTimeFormat);
+
+    /// <summary>The syntax identifier for strings containing <see cref="Enum"/> format specifiers.</summary>
+    public const string EnumFormat = nameof(EnumFormat);
+
+    /// <summary>The syntax identifier for strings containing <see cref="Guid"/> format specifiers.</summary>
+    public const string GuidFormat = nameof(GuidFormat);
+
+    /// <summary>The syntax identifier for strings containing JavaScript Object Notation (JSON).</summary>
+    public const string Json = nameof(Json);
+
+    /// <summary>The syntax identifier for strings containing numeric format specifiers.</summary>
+    public const string NumericFormat = nameof(NumericFormat);
+
+    /// <summary>The syntax identifier for strings containing regular expressions.</summary>
+    public const string Regex = nameof(Regex);
+
+    /// <summary>The syntax identifier for strings containing time format specifiers.</summary>
+    public const string TimeOnlyFormat = nameof(TimeOnlyFormat);
+
+    /// <summary>The syntax identifier for strings containing <see cref="TimeSpan"/> format specifiers.</summary>
+    public const string TimeSpanFormat = nameof(TimeSpanFormat);
+
+    /// <summary>The syntax identifier for strings containing URIs.</summary>
+    public const string Uri = nameof(Uri);
+
+    /// <summary>The syntax identifier for strings containing XML.</summary>
+    public const string Xml = nameof(Xml);
+
+}
+
+#endif

src/Skybrud.Essentials/Strings/Extensions/StringExtensions.cs

@@ -507,6 +507,50 @@ public static void Split(this string? value, char[] separators, [NotNullIfNotNul
             return value is null ? null : string.Format(CultureInfo.InvariantCulture, "{0}", value);
         }
 
+        /// <summary>
+        /// Returns a culture invariant string representation of the specified <paramref name="value"/> formatted using <paramref name="format"/>.
+        /// </summary>
+        /// <param name="value">The value to convert.</param>
+        /// <param name="format">The format to be used when converting <paramref name="value"/>.</param>
+        /// <returns>A culture invariant string representation of <paramref name="value"/>.</returns>
+        [return: NotNullIfNotNull(nameof(value))]
+        public static string? ToInvariantString(this IFormattable? value, string format) {
+            return value is null ? null : string.Format(CultureInfo.InvariantCulture, format, value);
+        }
+
+        /// <summary>
+        /// Returns a culture invariant string representation of the specified <paramref name="value"/> formatted using <paramref name="format"/>.
+        /// </summary>
+        /// <param name="value">The <see cref="DateTime"/> value to convert.</param>
+        /// <param name="format">The format to be used when converting <paramref name="value"/>.</param>
+        /// <returns>A culture invariant string representation of <paramref name="value"/>.</returns>
+        [return: NotNullIfNotNull(nameof(value))]
+        public static string? ToInvariantString(this DateTime? value, [StringSyntax(StringSyntaxAttribute.DateTimeFormat)] string format) {
+            return value is null ? null : string.Format(CultureInfo.InvariantCulture, format, value);
+        }
+
+        /// <summary>
+        /// Returns a culture invariant string representation of the specified <paramref name="value"/> formatted using <paramref name="format"/>.
+        /// </summary>
+        /// <param name="value">The <see cref="DateTimeOffset"/> value to convert.</param>
+        /// <param name="format">The format to be used when converting <paramref name="value"/>.</param>
+        /// <returns>A culture invariant string representation of <paramref name="value"/>.</returns>
+        [return: NotNullIfNotNull(nameof(value))]
+        public static string? ToInvariantString(this DateTimeOffset? value, [StringSyntax(StringSyntaxAttribute.DateTimeFormat)] string format) {
+            return value is null ? null : string.Format(CultureInfo.InvariantCulture, format, value);
+        }
+
+        /// <summary>
+        /// Returns a culture invariant string representation of the specified <paramref name="value"/> formatted using <paramref name="format"/>.
+        /// </summary>
+        /// <param name="value">The <see cref="TimeSpan"/> value to convert.</param>
+        /// <param name="format">The format to be used when converting <paramref name="value"/>.</param>
+        /// <returns>A culture invariant string representation of <paramref name="value"/>.</returns>
+        [return: NotNullIfNotNull(nameof(value))]
+        public static string? ToInvariantString(this TimeSpan? value, [StringSyntax(StringSyntaxAttribute.TimeSpanFormat)] string format) {
+            return value is null ? null : string.Format(CultureInfo.InvariantCulture, format, value);
+        }
+
     }
 
 }