feat(Converter): add HexConverter/BinConverter static class (#544)

* feat: 增加 HexConverter 类

* test: 增加单元测试

* refactor: 更新 HexConveter 文档注释

* feat: 增加 BinConverter 转换器

* doc: 更新文档

* test: 更新单元测试

* chore: bump version 9.0.2

Author: ArgoZhang

src/extensions/BootstrapBlazor.Socket/BootstrapBlazor.Socket.csproj

@@ -1,7 +1,7 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <Version>9.0.1</Version>
+    <Version>9.0.2</Version>
   </PropertyGroup>
 
   <PropertyGroup>

src/extensions/BootstrapBlazor.Socket/DataConverter/BinConverter.cs

@@ -0,0 +1,59 @@
+// Copyright (c) BootstrapBlazor & Argo Zhang (argo@live.ca). All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+// Website: https://www.blazor.zone or https://argozhang.github.io/
+
+using System.Text;
+
+namespace BootstrapBlazor.Components.DataConverter;
+
+/// <summary>
+/// 二进制 与 Byte 数组转换方法
+/// </summary>
+public static class BinConverter
+{
+    /// <summary>
+    /// 将 byte[] 转为 二进制字符串
+    /// <para>Converts a byte array to its hexadecimal string representation.</para>
+    /// </summary>
+    /// <param name="bytes">The byte array to convert.</param>
+    /// <param name="separator"></param>
+    /// <returns>A string containing the hexadecimal representation of the byte array.</returns>
+    public static string ToString(byte[]? bytes, string? separator = "-")
+    {
+        if (bytes == null || bytes.Length == 0)
+        {
+            return string.Empty;
+        }
+
+        return string.Join(separator, bytes.Select(i => Convert.ToString(i, 2).PadLeft(8, '0')));
+    }
+
+    /// <summary>
+    /// 将字符串转换为字节数组
+    /// </summary>
+    /// <param name="str"></param>
+    /// <param name="separator"></param>
+    /// <param name="options"></param>
+    /// <returns></returns>
+    public static byte[] ToBytes(string str, string? separator = null, StringSplitOptions options = StringSplitOptions.None)
+    {
+        // 把 str 内的 separator 符号替换掉
+        if (!string.IsNullOrEmpty(separator))
+        {
+            str = string.Join("", str.Split(separator, options).Select(i => i.PadLeft(8, '0')));
+        }
+
+        // 把 Hex 形式的 str 转化为 byte[]
+        if (str.Length % 8 != 0)
+        {
+            throw new ArgumentException("The raw string cannot have an odd number of digits. 参数 str 位数不正确无法转化为 二进制字节数组", nameof(str));
+        }
+
+        var bytes = new byte[str.Length / 8];
+        for (var i = 0; i < bytes.Length; i++)
+        {
+            bytes[i] = Convert.ToByte(str.Substring(i * 8, 8), 2);
+        }
+        return bytes;
+    }
+}

src/extensions/BootstrapBlazor.Socket/DataConverter/HexConverter.cs

@@ -0,0 +1,70 @@
+// Copyright (c) BootstrapBlazor & Argo Zhang (argo@live.ca). All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+// Website: https://www.blazor.zone or https://argozhang.github.io/
+
+using System.Text;
+
+namespace BootstrapBlazor.Components.DataConverter;
+
+/// <summary>
+/// 十六进制 与 Byte 数组转换方法
+/// </summary>
+public static class HexConverter
+{
+    /// <summary>
+    /// 将 byte[] 转为 16 进制字符串
+    /// <para>Converts a byte array to its hexadecimal string representation.</para>
+    /// </summary>
+    /// <param name="bytes">The byte array to convert.</param>
+    /// <param name="separator"></param>
+    /// <returns>A string containing the hexadecimal representation of the byte array.</returns>
+    public static string ToString(byte[]? bytes, string? separator = "-")
+    {
+        if (bytes == null || bytes.Length == 0)
+        {
+            return string.Empty;
+        }
+
+        if (separator == "-")
+        {
+            return BitConverter.ToString(bytes);
+        }
+
+        var sb = new StringBuilder(bytes.Length * 3);
+        foreach (var b in bytes)
+        {
+            sb.Append(b.ToString("X2"));
+            sb.Append(separator);
+        }
+        return sb.ToString(0, sb.Length - 1);
+    }
+
+    /// <summary>
+    /// 将字符串转换为字节数组
+    /// </summary>
+    /// <param name="str"></param>
+    /// <param name="separator"></param>
+    /// <param name="options"></param>
+    /// <returns></returns>
+    public static byte[] ToBytes(string str, string? separator = null, StringSplitOptions options = StringSplitOptions.None)
+    {
+        // 把 str 内的 delimiter 符号替换掉
+        if (!string.IsNullOrEmpty(separator))
+        {
+            str = string.Join("", str.Split(separator, options));
+        }
+
+        // 把 Hex 形式的 str 转化为 byte[]
+        if (str.Length % 2 != 0)
+        {
+            throw new ArgumentException("The raw string cannot have an odd number of digits. 参数 str 位数不正确无法转化为 16 进制字节数组", nameof(str));
+        }
+
+        var bytes = new byte[str.Length / 2];
+        for (var i = 0; i < bytes.Length; i++)
+        {
+            bytes[i] = Convert.ToByte(str.Substring(i * 2, 2), 16);
+        }
+        return bytes;
+    }
+}

test/UnitTestTcpSocket/BinConverterTest.cs

@@ -0,0 +1,57 @@
+// Copyright (c) BootstrapBlazor & Argo Zhang (argo@live.ca). All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+// Website: https://www.blazor.zone or https://argozhang.github.io/
+
+using BootstrapBlazor.Components.DataConverter;
+
+namespace UnitTestTcpSocket;
+
+public class BinConverterTest
+{
+    [Fact]
+    public void ToHexString_Null()
+    {
+        var actual = BinConverter.ToString(null);
+        Assert.Equal(string.Empty, actual);
+
+        actual = BinConverter.ToString([]);
+        Assert.Equal(string.Empty, actual);
+    }
+
+    [Fact]
+    public void ToBinString_Ok()
+    {
+        var data = new byte[] { 0x1A, 0x02 };
+        var actual = BinConverter.ToString(data);
+        Assert.Equal("00011010-00000010", actual);
+
+        actual = BinConverter.ToString(data, " ");
+        Assert.Equal("00011010 00000010", actual);
+    }
+
+    [Fact]
+    public void ToHexString_Exception()
+    {
+        var data = "00011010-00000010";
+        var ex = Assert.ThrowsAny<ArgumentException>(() => BinConverter.ToBytes(data));
+        Assert.NotNull(ex);
+    }
+
+    [Fact]
+    public void ToBytes_Ok()
+    {
+        var excepted = new byte[] { 0x1A, 0x02 };
+
+        var data = "00011010-00000010";
+        var actual = BinConverter.ToBytes(data, "-");
+        Assert.Equal(excepted, actual);
+
+        data = "00011010 00000010";
+        actual = BinConverter.ToBytes(data, " ");
+        Assert.Equal(excepted, actual);
+
+        data = "0001101000000010";
+        actual = BinConverter.ToBytes(data);
+        Assert.Equal(excepted, actual);
+    }
+}

test/UnitTestTcpSocket/HexConverterTest.cs

@@ -0,0 +1,57 @@
+// Copyright (c) BootstrapBlazor & Argo Zhang (argo@live.ca). All rights reserved.
+// Licensed under the Apache License, Version 2.0. See License.txt in the project root for license information.
+// Website: https://www.blazor.zone or https://argozhang.github.io/
+
+using BootstrapBlazor.Components.DataConverter;
+
+namespace UnitTestTcpSocket;
+
+public class HexConverterTest
+{
+    [Fact]
+    public void ToHexString_Null()
+    {
+        var actual = HexConverter.ToString(null);
+        Assert.Equal(string.Empty, actual);
+
+        actual = HexConverter.ToString([]);
+        Assert.Equal(string.Empty, actual);
+    }
+
+    [Fact]
+    public void ToHexString_Exception()
+    {
+        var data = "1A021304FE1";
+        var ex = Assert.ThrowsAny<ArgumentException>(() => HexConverter.ToBytes(data));
+        Assert.NotNull(ex);
+    }
+
+    [Fact]
+    public void ToHexString_Ok()
+    {
+        var data = new byte[] { 0x1A, 0x02, 0x13, 0x04, 0xFE };
+        var actual = HexConverter.ToString(data);
+        Assert.Equal("1A-02-13-04-FE", actual);
+
+        actual = HexConverter.ToString(data, " ");
+        Assert.Equal("1A 02 13 04 FE", actual);
+    }
+
+    [Fact]
+    public void ToBytes_Ok()
+    {
+        var excepted = new byte[] { 0x1A, 0x02, 0x13, 0x04, 0xFE };
+
+        var data = "1A021304FE";
+        var actual = HexConverter.ToBytes(data);
+        Assert.Equal(excepted, actual);
+
+        data = "1A-02-13-04-FE";
+        actual = HexConverter.ToBytes(data, "-");
+        Assert.Equal(excepted, actual);
+
+        data = "1A 02 13 04 FE";
+        actual = HexConverter.ToBytes(data, " ");
+        Assert.Equal(excepted, actual);
+    }
+}