feat: add value converters and extensions for DateTime, string, and file size; enhance length and math conversions

Author: jamesmcroft

.github/workflows/docs.yml

@@ -16,6 +16,9 @@ on:
     - .github/workflows/docs.yml
   workflow_dispatch:
 
+permissions:
+  contents: write
+
 jobs:
   generate-docs:
 
@@ -38,8 +41,7 @@ jobs:
       run: dotnet tool install -g docfx
 
     - name: Restore projects
-      run: dotnet restore
-      working-directory: src
+      run: dotnet restore MADE.NET.sln
 
     - name: Build DocFX site
       working-directory: docs

docs/articles/features/data-converters.md

@@ -58,6 +58,30 @@ These can be used to convert any type to another. Whatever data conversion you t
 
 If there is a common value converter you think is missing from MADE.NET, [raise a tracking item on GitHub](https://github.com/MADE-Apps/MADE.NET/issues/new/choose) and we'll get it implemented.
 
+## Converting strings to enums using the StringToEnumValueConverter
+
+The `MADE.Data.Converters.StringToEnumValueConverter<TEnum>` converts between string values and enum types. It supports case-insensitive matching by default.
+
+```csharp
+var converter = new StringToEnumValueConverter<DayOfWeek>();
+
+DayOfWeek day = converter.Convert("Monday"); // DayOfWeek.Monday
+string name = converter.ConvertBack(DayOfWeek.Friday); // "Friday"
+```
+
+Set `IgnoreCase` to `false` if you need exact case matching. The converter throws `InvalidDataConversionException` if the string cannot be parsed as the target enum type.
+
+## Converting DateTime to Unix timestamps using the DateTimeToUnixTimestampValueConverter
+
+The `MADE.Data.Converters.DateTimeToUnixTimestampValueConverter` converts between `DateTime` and Unix timestamps (seconds since 1970-01-01 UTC).
+
+```csharp
+var converter = new DateTimeToUnixTimestampValueConverter();
+
+long timestamp = converter.Convert(new DateTime(2024, 1, 1, 0, 0, 0, DateTimeKind.Utc));
+DateTime dateTime = converter.ConvertBack(timestamp);
+```
+
 ## DateTime extensions
 
 The `MADE.Data.Converters.Extensions.DateTimeExtensions` class provides a comprehensive set of extensions for working with `DateTime` values:
@@ -84,6 +108,18 @@ The `MADE.Data.Converters.Extensions.StringExtensions` class provides extensions
 - `ToFloat()` / `ToNullableFloat()` - Parses a string to a float.
 - `ToDouble()` / `ToNullableDouble()` - Parses a string to a double.
 - `ToBoolean()` - Parses a string to a boolean.
+- `ToSlug()` - Converts a string to a URL-friendly slug by removing diacritics, replacing non-alphanumeric characters with hyphens, and lowercasing.
+
+```csharp
+string slug = "Hello World! Cafe\u0301".ToSlug(); // "hello-world-cafe"
+```
+
+## TimeSpan extensions
+
+The `MADE.Data.Converters.Extensions.TimeSpanExtensions` class provides extensions for working with `TimeSpan` values:
+
+- `ToHumanReadableString()` - Converts a TimeSpan to a human-readable string such as "2 hours 30 minutes".
+- `TotalWeeks()` - Gets the total number of whole weeks in a TimeSpan.
 
 ## Boolean extensions
 
@@ -96,11 +132,28 @@ string result = isActive.ToFormattedString("Active", "Inactive"); // "Active"
 
 ## Math extensions
 
-The `MADE.Data.Converters.Extensions.MathExtensions` class provides extensions for common mathematic expressions including `ToRadians` to convert a degrees value to radians.
+The `MADE.Data.Converters.Extensions.MathExtensions` class provides extensions for common mathematic expressions:
+
+- `ToRadians()` - Converts a degrees value to radians.
+- `ToDegrees()` - Converts a radians value to degrees.
 
 ## Length extensions
 
 The `MADE.Data.Converters.Extensions.LengthExtensions` class provides extensions for converting length values:
 
 - `ToMeters()` - Converts a value from miles to meters.
 - `ToMiles()` - Converts a value from meters to miles.
+- `KilometersToMeters()` / `ToKilometers()` - Converts between kilometers and meters.
+- `FeetToMeters()` / `ToFeet()` - Converts between feet and meters.
+- `InchesToMeters()` / `ToInches()` - Converts between inches and meters.
+
+## File size extensions
+
+The `MADE.Data.Converters.Extensions.FileSizeExtensions` class provides extensions for converting byte values to human-readable file size strings:
+
+- `ToHumanReadableFileSize()` - Converts a byte count to a string such as "1.50 MB" or "256 B".
+
+```csharp
+long bytes = 1_572_864;
+string size = bytes.ToHumanReadableFileSize(); // "1.50 MB"
+```

docs/articles/intro.md

@@ -66,10 +66,14 @@ It includes features such as:
 
 - BooleanToStringValueConverter, a value converter for converting `bool` values to configurable `String` representations, with the capability to convert back.
 - DateTimeToStringValueConverter, a value converter that takes a `DateTime` string format parameter to convert a `DateTime` value to a `String`, with the capability to convert back.
-- DateTimeExtensions, a collection of useful extensions for interacting with `DateTime` values including `ToCurrentAge` (to get an age in years based on a given date from today), `StartOfDay`/`EndOfDay`, `StartOfWeek`/`EndOfWeek`, `StartOfMonth`/`EndOfMonth`, `StartOfYear`/`EndOfYear`, and `ToNearestHour`.
-- MathExtensions, a collection of extensions for common mathematic expressions including `ToRadians` (to convert a degrees value to radians).
-- StringExtensions, a collection of extensions for manipulating `String` values such as `ToTitleCase`, `ToDefaultCase`, `Truncate`, `ToBase64`, `FromBase64`, `ToInt`, `ToBoolean`, `ToFloat`, and `ToDouble`.
-- LengthExtensions, for converting length values such as `ToMeters` and `ToMiles`.
+- StringToEnumValueConverter, a generic value converter for converting between `String` and any `Enum` type with case-insensitive matching.
+- DateTimeToUnixTimestampValueConverter, a value converter between `DateTime` and Unix timestamps.
+- DateTimeExtensions, a collection of useful extensions for interacting with `DateTime` values including `ToCurrentAge`, `StartOfDay`/`EndOfDay`, `StartOfWeek`/`EndOfWeek`, `StartOfMonth`/`EndOfMonth`, `StartOfYear`/`EndOfYear`, and `ToNearestHour`.
+- TimeSpanExtensions, providing `ToHumanReadableString` and `TotalWeeks`.
+- MathExtensions, providing `ToRadians` and `ToDegrees` for angle conversions.
+- StringExtensions, a collection of extensions for manipulating `String` values such as `ToTitleCase`, `ToDefaultCase`, `Truncate`, `ToBase64`, `FromBase64`, `ToSlug`, `ToInt`, `ToBoolean`, `ToFloat`, and `ToDouble`.
+- LengthExtensions, for converting between miles, meters, kilometers, feet, and inches.
+- FileSizeExtensions, for converting byte counts to human-readable file size strings.
 - BooleanExtensions, for formatting `bool` values to custom string representations with `ToFormattedString`.
 
 <span class="button">

src/MADE.Data.Converters/DateTimeToUnixTimestampValueConverter.cs

@@ -0,0 +1,46 @@
+// MADE Apps licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using MADE.Data.Converters.Constants;
+
+namespace MADE.Data.Converters;
+
+/// <summary>
+/// Defines a value converter from <see cref="DateTime"/> to a Unix timestamp represented as a <see cref="long"/>.
+/// </summary>
+public class DateTimeToUnixTimestampValueConverter : IValueConverter<DateTime, long>
+{
+    /// <summary>
+    /// Converts the <paramref name="value">value</paramref> to a Unix timestamp in seconds.
+    /// </summary>
+    /// <param name="value">
+    /// The <see cref="DateTime"/> value to convert.
+    /// </param>
+    /// <param name="parameter">
+    /// The optional parameter used to help with conversion.
+    /// </param>
+    /// <returns>
+    /// The Unix timestamp in seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+    /// </returns>
+    public long Convert(DateTime value, object? parameter = default)
+    {
+        return (long)(value.ToUniversalTime() - DateTimeConstants.UnixEpoch).TotalSeconds;
+    }
+
+    /// <summary>
+    /// Converts a Unix timestamp in seconds back to a <see cref="DateTime"/> in UTC.
+    /// </summary>
+    /// <param name="value">
+    /// The Unix timestamp in seconds to convert.
+    /// </param>
+    /// <param name="parameter">
+    /// The optional parameter used to help with conversion.
+    /// </param>
+    /// <returns>
+    /// The converted <see cref="DateTime"/> in UTC.
+    /// </returns>
+    public DateTime ConvertBack(long value, object? parameter = default)
+    {
+        return DateTimeConstants.UnixEpoch.AddSeconds(value);
+    }
+}

src/MADE.Data.Converters/Extensions/FileSizeExtensions.cs

@@ -0,0 +1,49 @@
+// MADE Apps licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace MADE.Data.Converters.Extensions;
+
+/// <summary>
+/// Defines a collection of extensions for converting byte values to human-readable file size representations.
+/// </summary>
+public static class FileSizeExtensions
+{
+    private static readonly string[] SizeUnits = { "B", "KB", "MB", "GB", "TB", "PB", "EB" };
+
+    /// <summary>
+    /// Converts a byte count to a human-readable file size string using binary units (1 KB = 1024 bytes).
+    /// </summary>
+    /// <param name="bytes">The byte count to convert.</param>
+    /// <param name="decimalPlaces">The number of decimal places to display. Default is 2.</param>
+    /// <returns>A human-readable file size string such as "1.50 MB" or "256 B".</returns>
+    public static string ToHumanReadableFileSize(this long bytes, int decimalPlaces = 2)
+    {
+        if (bytes < 0)
+        {
+            return $"-{(-bytes).ToHumanReadableFileSize(decimalPlaces)}";
+        }
+
+        if (bytes == 0)
+        {
+            return "0 B";
+        }
+
+        int unitIndex = (int)Math.Floor(Math.Log(bytes, 1024));
+        unitIndex = Math.Min(unitIndex, SizeUnits.Length - 1);
+
+        double size = bytes / Math.Pow(1024, unitIndex);
+
+        return $"{size.ToString($"F{decimalPlaces}")} {SizeUnits[unitIndex]}";
+    }
+
+    /// <summary>
+    /// Converts a byte count to a human-readable file size string using binary units (1 KB = 1024 bytes).
+    /// </summary>
+    /// <param name="bytes">The byte count to convert.</param>
+    /// <param name="decimalPlaces">The number of decimal places to display. Default is 2.</param>
+    /// <returns>A human-readable file size string such as "1.50 MB" or "256 B".</returns>
+    public static string ToHumanReadableFileSize(this double bytes, int decimalPlaces = 2)
+    {
+        return ((long)bytes).ToHumanReadableFileSize(decimalPlaces);
+    }
+}

src/MADE.Data.Converters/Extensions/LengthExtensions.cs

@@ -8,14 +8,23 @@ namespace MADE.Data.Converters.Extensions;
 /// </summary>
 public static class LengthExtensions
 {
+    private const double MetersPerMile = 1609.344;
+    private const double MilesPerMeter = 1.0 / MetersPerMile;
+    private const double MetersPerKilometer = 1000.0;
+    private const double KilometersPerMeter = 1.0 / MetersPerKilometer;
+    private const double MetersPerFoot = 0.3048;
+    private const double FeetPerMeter = 1.0 / MetersPerFoot;
+    private const double MetersPerInch = 0.0254;
+    private const double InchesPerMeter = 1.0 / MetersPerInch;
+
     /// <summary>
     /// Converts a distance measured in miles to a distance measured in meters.
     /// </summary>
     /// <param name="miles">The miles to convert to meters.</param>
     /// <returns>The meters that represent the miles.</returns>
     public static double ToMeters(this double miles)
     {
-        return miles * 1609.344;
+        return miles * MetersPerMile;
     }
 
     /// <summary>
@@ -25,6 +34,66 @@ public static double ToMeters(this double miles)
     /// <returns>The miles that represent the meters.</returns>
     public static double ToMiles(this double meters)
     {
-        return meters / 1609.344;
+        return meters * MilesPerMeter;
+    }
+
+    /// <summary>
+    /// Converts a distance measured in kilometers to a distance measured in meters.
+    /// </summary>
+    /// <param name="kilometers">The kilometers to convert to meters.</param>
+    /// <returns>The meters that represent the kilometers.</returns>
+    public static double KilometersToMeters(this double kilometers)
+    {
+        return kilometers * MetersPerKilometer;
+    }
+
+    /// <summary>
+    /// Converts a distance measured in meters to a distance measured in kilometers.
+    /// </summary>
+    /// <param name="meters">The meters to convert to kilometers.</param>
+    /// <returns>The kilometers that represent the meters.</returns>
+    public static double ToKilometers(this double meters)
+    {
+        return meters * KilometersPerMeter;
+    }
+
+    /// <summary>
+    /// Converts a distance measured in feet to a distance measured in meters.
+    /// </summary>
+    /// <param name="feet">The feet to convert to meters.</param>
+    /// <returns>The meters that represent the feet.</returns>
+    public static double FeetToMeters(this double feet)
+    {
+        return feet * MetersPerFoot;
+    }
+
+    /// <summary>
+    /// Converts a distance measured in meters to a distance measured in feet.
+    /// </summary>
+    /// <param name="meters">The meters to convert to feet.</param>
+    /// <returns>The feet that represent the meters.</returns>
+    public static double ToFeet(this double meters)
+    {
+        return meters * FeetPerMeter;
+    }
+
+    /// <summary>
+    /// Converts a distance measured in inches to a distance measured in meters.
+    /// </summary>
+    /// <param name="inches">The inches to convert to meters.</param>
+    /// <returns>The meters that represent the inches.</returns>
+    public static double InchesToMeters(this double inches)
+    {
+        return inches * MetersPerInch;
+    }
+
+    /// <summary>
+    /// Converts a distance measured in meters to a distance measured in inches.
+    /// </summary>
+    /// <param name="meters">The meters to convert to inches.</param>
+    /// <returns>The inches that represent the meters.</returns>
+    public static double ToInches(this double meters)
+    {
+        return meters * InchesPerMeter;
     }
 }

src/MADE.Data.Converters/Extensions/MathExtensions.cs

@@ -21,4 +21,18 @@ public static double ToRadians(this double degrees)
     {
         return degrees * (System.Math.PI / 180);
     }
+
+    /// <summary>
+    /// Converts a radians value to a degrees value.
+    /// </summary>
+    /// <param name="radians">
+    /// The radians value to convert.
+    /// </param>
+    /// <returns>
+    /// The converted value as degrees.
+    /// </returns>
+    public static double ToDegrees(this double radians)
+    {
+        return radians * (180 / System.Math.PI);
+    }
 }

src/MADE.Data.Converters/Extensions/StringExtensions.cs

@@ -2,8 +2,10 @@
 // See the LICENSE file in the project root for more information.
 
 using System;
+using System.Globalization;
 using System.IO;
 using System.Text;
+using System.Text.RegularExpressions;
 using System.Threading.Tasks;
 
 namespace MADE.Data.Converters.Extensions;
@@ -269,4 +271,46 @@ public static double ToDouble(this string value)
         bool parsed = double.TryParse(value, out double doubleValue);
         return parsed ? doubleValue : null;
     }
+
+    /// <summary>
+    /// Converts a string to a URL-friendly slug by removing diacritics, replacing non-alphanumeric characters with hyphens, and lowercasing.
+    /// </summary>
+    /// <param name="value">The value to convert to a slug.</param>
+    /// <returns>A URL-friendly slug string.</returns>
+    public static string ToSlug(this string value)
+    {
+        if (string.IsNullOrWhiteSpace(value))
+        {
+            return string.Empty;
+        }
+
+        // Normalize to decompose characters (e.g., e with accent -> e + combining accent)
+        string normalized = value.Normalize(NormalizationForm.FormD);
+
+        // Remove non-spacing marks (diacritics/accents)
+        var stripped = new StringBuilder();
+        foreach (char c in normalized)
+        {
+            if (CharUnicodeInfo.GetUnicodeCategory(c) != UnicodeCategory.NonSpacingMark)
+            {
+                stripped.Append(c);
+            }
+        }
+
+        string result = stripped.ToString().Normalize(NormalizationForm.FormC);
+
+        // Lowercase
+        result = result.ToLowerInvariant();
+
+        // Replace non-alphanumeric characters with hyphens
+        result = Regex.Replace(result, @"[^a-z0-9\s-]", string.Empty);
+
+        // Replace whitespace and multiple hyphens with a single hyphen
+        result = Regex.Replace(result, @"[\s-]+", "-");
+
+        // Trim leading and trailing hyphens
+        result = result.Trim('-');
+
+        return result;
+    }
 }