介紹 DotNet 庫 - Viyi.Strings

邊城發表於2021-11-28

Viyi.Strings 是一個 .NET 庫，支援 .Net Standard 2.0 和 .Net 5。從名字就能看出來，這個庫的主要目的是解決對字串和文字的一些操作。總的來說，Viyi.Strings 目前的版本提供瞭如下一些功能：

  • 基於文字的編/解碼，支援 Base64 和 Hex（十六進位制）編/解碼，但不止於此；
  • 提供擴充套件方法對空字串和空白字串進行快速處理；
  • 提供字串大小寫轉換框架，並預設提供了 camelCase、PascalCase、kebab-case 和 snake_case 轉換方法；
  • 在整數和字串之間進行 2~36 進位制轉換，即便只想用 16 進位制，也會很方便；
  • 擴充套件對布林值的解析，允許 on/off、yes/no，允許靈活地自定義轉換；
  • 若有其他需求，歡迎在 Issue 中提出並討論
如何安裝？

Viyi.Strings 庫已經發布到 NuGet，可以從 NuGet 快速安裝。

基於文字的編/解碼框架

Viyi.String 庫的 Viyi.Strings.Codec名稱空間下提供了基於文字的編/解碼框架。該名稱空間下，不僅提供了 Base64 和 Hex 等常用編/解碼方式，還提供了統一的編/解碼介面設計，為在某些場景下統一替換編/解碼方式提供便利。除此之外，該名稱空間下還提供了便於使用的擴充套件方法。

快速 Base64/Hex 編/解碼

Viyi.Stings.Codec.Base64 名稱空間對 byte[] 提供了 EncodeBase64() 和 DeocdeBase64() 系列擴充套件方法，可以迅速地在 byte[] 和 Base64 字串之間進行編解碼轉換：

// 隨機產生 20 位元組資料
byte[] data = new byte[20];
Random r = new Random();
r.NextBytes(data);

string base64;
Console.WriteLine("不加引數：");
Console.WriteLine(base64 = data.EncodeBase64());
// 輸出：RdFVrmsY45kkFKkUULem1LfCP6Y=

Compare(data, base64.DecodeBase64());  // 完全匹配

Console.WriteLine("指定行寬為 16：");
Console.WriteLine(base64 = data.EncodeBase64(16));
// 輸出：RdFVrmsY45kkFKkU
// 輸出：ULem1LfCP6Y=

Compare(data, base64.DecodeBase64());  // 完全匹配

甚至，如果 Base64 缺少最後的 = 號也是可以解碼成功的，因為 = 號本來就是表示的空資料。

Console.WriteLine(base64 = data.EncodeBase64());
Compare(data, base64.DecodeBase64());  // 完全匹配

// 根據上面示例，base64 最後一個字元是 = 號，去掉之後再解碼
Compare(data, base64.Substring(0, base64.Length - 1).DecodeBase64()); // 完全匹配

上面演示了 Base64 通過擴充套件方法快速進行編/解碼。按 Hex（十六進位制）編解碼也類似，只是需要使用 Viyi.Strings.Codec.Hex 名稱空間。

完整的 Base64/Hex 編/解碼

擴充套件方法只是為 byte[] 和 string 型別分別提供了快捷的編/解碼方式。如果需要複雜一點的編/解碼，比如對 Stream 進行編/解碼，可以使用 Encoder 和 Decoder。通過 Viyi.String.Codec.TextCodec 類可以拿到預置的 Base64Codec 和 HexCodec 物件，他們都實現了 ITextCodec 介面，可以

  • 使用 CreateEncoder() 建立對應的編碼器物件，用於對位元組資料進行編碼
  • 使用 CreateDecoder() 建立對應的解碼器物件，用於對字串資料進行解碼

比如，想對將二進位制檔案 data.bin 中的資料轉換成十六進位制輸出到 data_hexdump.txt 中，可以用這樣的程式碼完成：

var hexEncoder = TextCodec.Hex.CreateEncoder(
    // 選項屬性只讀，需要使用建造者模式來構建
    CodecOptions.Create()
        // 配置換行：每行 16 位元組，也就是 32 個十六進位制字元
        .SetLineWidth(16 * 2)
        .Build()
);

using Stream inStream = File.OpenRead("data.bin");
using StreamWriter writer = new StreamWriter("data_hexdump.txt");
hexEncoder.Encode(writer, inStream);

如果編碼結果不想寫入檔案，而是儲存在字串中，使用使用 StringWriter 作為輸出，也可以使用 Encode 的另一個過載：

string hex = hexEncoder.Encode(inStream);

更多關於編/解碼的內容，可以閱讀：文字編碼和解碼 (Viyi.Strings.Codec))

命名風格（大小寫）轉換

在多端、多語言、多技術聯合實現應用軟體/服務的大環境下，想要保持各部分遵從各自的語法和資料規範，對命名進行不同的風格轉換就很有必要，也很常用。

Viyi.Strings 在 Viyi.Strings.CaseConverters 名稱空間中提供了對命名風格轉換在框架地，並預設提供了 camelCase、PascalCase、kebab-case 和 snake_case 的轉換工具。這些工具類都實現了 ICaseConverter 介面，方便必要時進行快速選擇或替換。

同時，在 Viyi.Strings 名稱空間中，也提供了對 string 的擴充套件方法進行處理呼叫。比如：

Console.WriteLine("Hello James Fan".KebabCase());
// 輸出：hello-james-fan

如果需要了解更多相關內容，可以閱讀：命名風格轉換 CaseConvert

空字串和空白字串

這部分功能主要是擴充套件 string 在處理空字串 "" 和空白字串（僅含空白字元的字串）的能力。

舉例來說，我們知道如果某字串是 null 就把它變成預設的 "default_value" 可以這麼寫：

s = s ?? "default_value";
// 或者 s ??= "default_value";

但是，如果想判斷某字串是空字串時進行替換，不使用 Viyi.Strgins 擴充套件的情況下需要這樣寫：

// 如果是 null 或空字串則替換為預設內容
s = string.IsNullOrEmpty(s) ? "default_value" : s;

// 如果僅空白字串替換為預設內容，null 不變
s = string.IsNullOrWhiteSpace(s) ? "" : s;

但使用擴充套件就方便多了：

// 如果是 null 或空字串則替換為預設內容
s = s.EmptyAs("default_value");

// 如果僅空白字串替換為預設內容，null 和 "" 不變
s = s?.SpacesAs("");

不需要使用三目運算子，在複雜表示式中使用更簡潔。

另外，還提供了 IsEmpty(this string, true) 和 IsSpaces(this string, true) 用於精確判斷字串僅為空字串空白字串（精確表示 null 算在內）。

更多詳情，請閱讀：空字串和空白字串

解析布林值

.Net 預設的布林解析只能處理 "true" 和 "false"，但實際使用中，像 on/off、yes/no 等也是可以轉換為布林型別資料的。Viyi.Strings 提供了多個 ToBoolean() 過載來實現各種各樣的需求，比如

// 如果 s 是 true，返回 true；s 是 false 返回 false；否則返回 null。
s.ToBoolean(true);

// 與第 1 個引數匹配返回 true；與第 2 個引數匹配返回 false；否則返回 null。
s.ToBoolean("yes", "no");

// 在第一個陣列中返回 true；在第 2 個陣列中返回 false；其它情況返回 null。
s.ToBoolean(new String[] { "yes", "on" }, new String[] { "no", "off" });

// 與第一個引數之後的任意引數匹配，返回第一引數的表示的布林值，否則返回相反值
s.ToBoolean(false, "no", "off", "false", "down");

更多內容請閱讀：解析為布林型別 (bool))

整數的進位制轉換

Viyi.Strings 在 Viyi.Strings.Extensions 名稱空間中提供了 2~32 進位制的轉換工具函式，可以在字串和 int、uint、long、ulong 之間進行進位制轉換。比如

"3ae".ToInt32(16); // 942
"3ae".ToInt32(16).ToString(8); // 1656
(36 + 35).ToString(36); // 1z

更新內容請閱讀：整數的進位制轉換

結語

對 Viyi.Strings 的介紹就到這裡，歡迎有興趣的朋友參與到這個開源工具庫來！

原始碼託管在 Gitee 上：邊城/Viyi.String

相關文章