Added Customizable suffix sets (allowing non-standard units) and Added Additional helpers for formatting with alignment/padding

Author: AndrewMorgan1

src/ByteFlow/ByteFlow/HumanBytesExtensions.cs

@@ -7,35 +7,26 @@ namespace ByteFlow
     /// <summary>
     /// Provides extension methods for converting between raw byte counts and human-readable sizes.
     /// Supports both IEC (binary: KiB, MiB, GiB) and SI (decimal: KB, MB, GB) unit standards,
-    /// and allows culture-aware formatting and parsing.
+    /// allows culture-aware formatting and parsing, and supports custom suffix sets.
     /// </summary>
     public static class HumanBytesExtensions
     {
         /// <summary>
         /// Converts a number of bytes into a human-readable string using either
-        /// SI (decimal: KB, MB, GB) or IEC (binary: KiB, MiB, GiB) units.
+        /// SI (decimal: KB, MB, GB) or IEC (binary: KiB, MiB, GiB) units,
+        /// or a custom suffix set if provided.
         /// </summary>
-        /// <param name="bytes">The size in bytes.</param>
-        /// <param name="decimalPlaces">Number of decimal places to display.</param>
-        /// <param name="standard">Whether to use SI (base 1000) or IEC (base 1024) units.</param>
-        /// <param name="formatProvider">
-        /// The culture to use for formatting (e.g. decimal separator). 
-        /// Defaults to <see cref="CultureInfo.InvariantCulture"/>.
-        /// </param>
-        /// <returns>
-        /// A formatted string such as "1.23 MB" (SI, en-US) or "1,23 MB" (SI, de-DE).
-        /// </returns>
-        /// <exception cref="ArgumentOutOfRangeException">Thrown if <paramref name="bytes"/> is negative.</exception>
         public static string ToHumanBytes(
             this long bytes,
             int decimalPlaces = 2,
             UnitStandard standard = UnitStandard.IEC,
-            IFormatProvider formatProvider = null)
+            IFormatProvider formatProvider = null,
+            (string Symbol, double Factor)[] customSuffixes = null)
         {
             if (bytes < 0)
                 throw new ArgumentOutOfRangeException(nameof(bytes), "Value must be non-negative.");
 
-            var suffixes = standard == UnitStandard.SI ? SiSuffixes : IecSuffixes;
+            var suffixes = customSuffixes ?? (standard == UnitStandard.SI ? SiSuffixes : IecSuffixes);
 
             if (bytes == 0)
                 return $"0 {suffixes[0].Symbol}";
@@ -57,28 +48,37 @@ public static string ToHumanBytes(
         }
 
         /// <summary>
-        /// Parses a human-readable size string (e.g. "2.5 GB" or "2,5 GiB") back into bytes,
-        /// using either SI (decimal) or IEC (binary) interpretation.
+        /// Converts a number of bytes into a human-readable string,
+        /// padded to a given width for alignment.
+        /// </summary>
+        public static string ToHumanBytesAligned(
+            this long bytes,
+            int decimalPlaces = 2,
+            UnitStandard standard = UnitStandard.IEC,
+            int width = 10,
+            char paddingChar = ' ',
+            IFormatProvider formatProvider = null,
+            (string Symbol, double Factor)[] customSuffixes = null)
+        {
+            var s = ToHumanBytes(bytes, decimalPlaces, standard, formatProvider, customSuffixes);
+            return s.PadLeft(width, paddingChar);
+        }
+
+        /// <summary>
+        /// Parses a human-readable size string back into bytes,
+        /// using either SI (decimal), IEC (binary), or a custom suffix set if provided.
         /// </summary>
-        /// <param name="input">The input string, e.g. "1 KB", "1 KiB", "2.5 MB".</param>
-        /// <param name="standard">Whether to interpret units as SI (base 1000) or IEC (base 1024).</param>
-        /// <param name="formatProvider">
-        /// The culture to use for parsing (e.g. decimal separator).
-        /// Defaults to <see cref="CultureInfo.InvariantCulture"/>.
-        /// </param>
-        /// <returns>The size in bytes.</returns>
-        /// <exception cref="ArgumentNullException">Thrown if <paramref name="input"/> is null or whitespace.</exception>
-        /// <exception cref="FormatException">Thrown if the input string cannot be parsed.</exception>
         public static long ToBytes(
             this string input,
             UnitStandard standard = UnitStandard.IEC,
-            IFormatProvider formatProvider = null)
+            IFormatProvider formatProvider = null,
+            (string Symbol, double Factor)[] customSuffixes = null)
         {
             if (string.IsNullOrWhiteSpace(input))
                 throw new ArgumentNullException(nameof(input));
 
             input = input.Trim();
-            var suffixes = standard == UnitStandard.SI ? SiSuffixes : IecSuffixes;
+            var suffixes = customSuffixes ?? (standard == UnitStandard.SI ? SiSuffixes : IecSuffixes);
 
             foreach (var (symbol, factor) in suffixes.OrderByDescending(s => s.Symbol.Length))
             {
@@ -101,11 +101,7 @@ public static long ToBytes(
 
         /// <summary>
         /// Safely parses a human-readable string into bytes.
-        /// Returns <c>true</c> if parsing succeeds; otherwise <c>false</c>.
         /// </summary>
-        /// <param name="input">The input string.</param>
-        /// <param name="result">The parsed byte value if successful, or 0 otherwise.</param>
-        /// <returns><c>true</c> if parsing was successful; otherwise <c>false</c>.</returns>
         public static bool TryParseHumanBytes(this string input, out long result)
         {
             try
@@ -121,25 +117,19 @@ public static bool TryParseHumanBytes(this string input, out long result)
         }
 
         /// <summary>
-        /// Safely parses a human-readable string into bytes, using either SI (decimal) or IEC (binary) units.
+        /// Safely parses a human-readable string into bytes,
+        /// supporting SI, IEC, or custom suffix sets.
         /// </summary>
-        /// <param name="input">The input string (e.g. "1 KB", "1 KiB", "2.5 MB").</param>
-        /// <param name="result">The parsed byte value if successful, or 0 otherwise.</param>
-        /// <param name="standard">Whether to interpret units as SI (base 1000) or IEC (base 1024).</param>
-        /// <param name="formatProvider">
-        /// The culture to use for parsing (e.g. decimal separator).
-        /// Defaults to <see cref="CultureInfo.InvariantCulture"/>.
-        /// </param>
-        /// <returns><c>true</c> if parsing was successful; otherwise <c>false</c>.</returns>
         public static bool TryParseHumanBytes(
             this string input,
             out long result,
             UnitStandard standard = UnitStandard.IEC,
-            IFormatProvider formatProvider = null)
+            IFormatProvider formatProvider = null,
+            (string Symbol, double Factor)[] customSuffixes = null)
         {
             try
             {
-                result = input.ToBytes(standard, formatProvider);
+                result = input.ToBytes(standard, formatProvider, customSuffixes);
                 return true;
             }
             catch
@@ -149,7 +139,7 @@ public static bool TryParseHumanBytes(
             }
         }
 
-        // --- Unit suffix definitions ---
+        // --- Default suffix definitions ---
 
         private static readonly (string Symbol, double Factor)[] SiSuffixes =
         {

tests/ByteFlow.Tests/HumanBytesExtensionsTests.cs

@@ -36,6 +36,21 @@ public void ToHumanBytes_ShouldRespectCulture()
             Assert.Equal("1,23 MB", result);
         }
 
+        [Fact]
+        public void ToHumanBytes_ShouldSupportCustomSuffixes()
+        {
+            var custom = new[] { ("X", 1d), ("KX", 1000d), ("MX", 1000000d) };
+            string result = 2000L.ToHumanBytes(2, UnitStandard.SI, null, custom);
+            Assert.Equal("2.00 KX", result);
+        }
+
+        [Fact]
+        public void ToHumanBytesAligned_ShouldPadCorrectly()
+        {
+            string result = 1234L.ToHumanBytesAligned(2, UnitStandard.SI, width: 12, paddingChar: '_');
+            Assert.Equal("_____1.23 KB", result); // 5 underscores, total length 12
+        }
+
         [Fact]
         public void ToHumanBytes_ShouldThrowOnNegativeInput()
         {
@@ -85,6 +100,14 @@ public void ToBytes_ShouldParseAccordingToCulture(string input, long expected, s
             Assert.Equal(expected, result);
         }
 
+        [Fact]
+        public void ToBytes_ShouldSupportCustomSuffixes()
+        {
+            var custom = new[] { ("X", 1d), ("KX", 1000d), ("MX", 1000000d) };
+            long result = "2 KX".ToBytes(UnitStandard.SI, null, custom);
+            Assert.Equal(2000, result);
+        }
+
         [Fact]
         public void ToBytes_InvalidString_ShouldThrow()
         {
@@ -148,7 +171,6 @@ public void ToBytes_InputWithoutSuffix_ShouldThrow()
         public void TryParseHumanBytes_DefaultOverload_ShouldReturnTrue()
         {
             bool success = "1 KiB".TryParseHumanBytes(out long result);
-
             Assert.True(success);
             Assert.Equal(1024, result); // uses default IEC
         }
@@ -157,7 +179,6 @@ public void TryParseHumanBytes_DefaultOverload_ShouldReturnTrue()
         public void TryParseHumanBytes_DefaultOverload_ShouldReturnFalseOnInvalid()
         {
             bool success = "invalid".TryParseHumanBytes(out long result);
-
             Assert.False(success);
             Assert.Equal(0, result);
         }
@@ -182,6 +203,16 @@ public void TryParseHumanBytes_ShouldRespectCulture()
             Assert.Equal((long)(2.5 * 1024 * 1024), result);
         }
 
+        [Fact]
+        public void TryParseHumanBytes_ShouldSupportCustomSuffixes()
+        {
+            var custom = new[] { ("X", 1d), ("KX", 1000d) };
+            bool success = "5 KX".TryParseHumanBytes(out long result, UnitStandard.SI, null, custom);
+
+            Assert.True(success);
+            Assert.Equal(5000, result);
+        }
+
         [Theory]
         [InlineData("1 XB", UnitStandard.SI)]
         [InlineData("ten MB", UnitStandard.SI)]
@@ -209,5 +240,16 @@ public void RoundTrip_BytesToHumanAndBack_ShouldBeConsistent(long original, Unit
             long parsed = human.ToBytes(standard);
             Assert.Equal(original, parsed);
         }
+
+        [Fact]
+        public void RoundTrip_WithCustomSuffixes_ShouldBeConsistent()
+        {
+            var custom = new[] { ("X", 1d), ("KX", 1000d), ("MX", 1000000d) };
+            long original = 5000;
+            string human = original.ToHumanBytes(2, UnitStandard.SI, null, custom);
+            long parsed = human.ToBytes(UnitStandard.SI, null, custom);
+
+            Assert.Equal(original, parsed);
+        }
     }
 }