Add string.Truncate(int charCount) and string.TruncateBytes(int byteCount, Encoding?)

PowerKit.Tests/Extensions/StringExtensionsTests.cs

@@ -1,3 +1,4 @@
+using System.Text;
 using FluentAssertions;
 using PowerKit.Extensions;
 using Xunit;
@@ -137,4 +138,33 @@ public void Truncate_Test()
         "hello".Truncate(5).Should().Be("hello");
         "hello".Truncate(3).Should().Be("hel");
     }
+
+    [Fact]
+    public void TruncateBytes_Test()
+    {
+        // ASCII-only (1 byte per char with UTF-8)
+        "hello".TruncateBytes(10, Encoding.UTF8).Should().Be("hello");
+        "hello".TruncateBytes(5, Encoding.UTF8).Should().Be("hello");
+        "hello".TruncateBytes(3, Encoding.UTF8).Should().Be("hel");
+        "hello".TruncateBytes(0, Encoding.UTF8).Should().Be("");
+
+        // Multi-byte characters (é = 2 bytes in UTF-8)
+        "héllo".TruncateBytes(6, Encoding.UTF8).Should().Be("héllo");
+        "héllo".TruncateBytes(5, Encoding.UTF8).Should().Be("héll");
+        "héllo".TruncateBytes(4, Encoding.UTF8).Should().Be("hél");
+        "héllo".TruncateBytes(3, Encoding.UTF8).Should().Be("hé");
+        "héllo".TruncateBytes(2, Encoding.UTF8).Should().Be("h");
+        "héllo".TruncateBytes(1, Encoding.UTF8).Should().Be("h");
+
+        // Emoji (𝄞 = 4 bytes in UTF-8, encoded as a surrogate pair in C#)
+        "a𝄞b".TruncateBytes(5, Encoding.UTF8).Should().Be("a𝄞");
+        "a𝄞b".TruncateBytes(4, Encoding.UTF8).Should().Be("a");
+        "a𝄞b".TruncateBytes(1, Encoding.UTF8).Should().Be("a");
+
+        // Default encoding is UTF-8
+        "héllo".TruncateBytes(4, null).Should().Be("hél");
+
+        // Non-UTF-8 encoding
+        "hello".TruncateBytes(3, Encoding.ASCII).Should().Be("hel");
+    }
 }

PowerKit/Extensions/StringExtensions.cs

@@ -171,5 +171,37 @@ public SecureString ToSecureString()
         /// Truncates the string to the specified maximum number of characters.
         /// </summary>
         public string Truncate(int charCount) => str.Length > charCount ? str[..charCount] : str;
+
+        /// <summary>
+        /// Truncates the string so that its encoded byte length does not exceed the specified maximum.
+        /// Uses the provided encoding, or UTF-8 if <paramref name="encoding"/> is <c>null</c>.
+        /// </summary>
+        public string TruncateBytes(int byteCount, Encoding? encoding = null)
+        {
+            var enc = encoding ?? Encoding.UTF8;
+
+            if (enc.GetByteCount(str) <= byteCount)
+                return str;
+
+            var chars = str.ToCharArray();
+            var lo = 0;
+            var hi = chars.Length;
+
+            while (lo < hi)
+            {
+                var mid = lo + (hi - lo + 1) / 2;
+                if (enc.GetByteCount(chars, 0, mid) <= byteCount)
+                    lo = mid;
+                else
+                    hi = mid - 1;
+            }
+
+            // If the cut point landed right after a high surrogate (its paired low surrogate
+            // was not included), step back to avoid returning a string with an unpaired surrogate.
+            if (lo > 0 && char.IsHighSurrogate(chars[lo - 1]))
+                lo--;
+
+            return str[..lo];
+        }
     }
 }