CJF.Utilities.Extensions 1.24.432

CJF.Utilities.Extensions

這是一個提供各種 .NET 資料型別擴充方法的函式庫，包含陣列、字串、數值型別、日期時間、列舉、物件等常用的擴充功能。

版本資訊

• 版本: 1.24.432
• 作者: Chen Jaofeng
• 建立日期: 2025-05-17
• 目標框架: .NET 8.0
• 授權: MIT License

主要功能

ArrayExtension (陣列擴充)

• 位元組陣列操作：位元檢查、XOR 運算、型別轉換
• 數值轉換：支援 Big/Little Endian 的各種數值型別轉換
• 陣列工具：複製、比較、字串轉換、16進位輸出
• 加密解密：DES 加密/解密功能
• 編碼轉換：34進位編碼、位元陣列轉換

StringExtension (字串擴充)

• 寬度計算：支援中文字元的顯示寬度計算 (GetDisplayWidth, GetWidth)
• 雙寬度字元檢測：檢查字串是否包含雙寬度字元 (ContainsDoubleWidthChar)
• 格式化：固定長度填充、置中對齊、自動換行 (PadRightFixLength, PadLeftFixLength, PadCenter, PadCenterFixLength, WordWrap)
• 編碼轉換：16進位字串與位元組陣列互轉 (ToByteArray)
• 加密解密：DES 字串加密/解密 (Encrypt, Decrypt)
• 指令解析：命令列參數切割，支援引號處理 (SplitCommand)
• 列舉轉換：字串轉列舉型別 (ToEnum)
• 已過時方法：GetByteCount (建議改用 GetDisplayWidth)

數值型別擴充 (Int16/Int32/Int64/Float/Double)

• 位元陣列轉換：數值轉位元陣列
• 位元組陣列：支援 Big/Little Endian 的位元組陣列取得
• 中文數字：數字轉中文表示（支援一般與金錢格式）

DateTimeExtensions (日期時間擴充)

• 週數計算：月份週數、年度週數
• 日期比較：同週、同月、同年判斷
• 週數操作：增減週數

EnumExtensions (列舉擴充)

• 描述取得：取得 DescriptionAttribute 設定的說明文字
• 屬性存取：取得列舉值的自訂屬性

ObjectExtension (物件擴充)

• 型別檢查：數值、布林、日期時間型別判斷
• 型別轉換：泛型型別轉換，支援布林值的多種格式

ConcurrentBagExtension (並行集合擴充)

• 批次新增：將集合批次加入 ConcurrentBag
• 固定大小佇列：FixedSizedQueue 類別，自動移除超出大小的元素

安裝方式

dotnet add package CJF.Utilities.Extensions

使用範例

陣列操作

using CJF.Utilities.Extensions;

byte[] data = { 0x12, 0x34, 0x56, 0x78 };

// 轉換為 16 進位字串
string hex = data.ToHexString(); // "12 34 56 78"

// 轉換為 32 位元整數 (Big Endian)
int value = data.ToInt32(true);

// XOR 運算
byte[] encrypted = data.Xor(0xFF);

字串操作

using CJF.Utilities.Extensions;

string text = "Hello 世界";

// 取得顯示寬度（中文字為 2，英文為 1）
int width = text.GetDisplayWidth(); // 10

// 固定長度填充
string padded = text.PadRightFixLength(15);

// 16 進位字串轉位元組陣列
byte[] bytes = "48656C6C6F".ToByteArray();

數值操作

using CJF.Utilities.Extensions;

int number = 12345;

// 轉中文數字
string chinese = number.ToChinese(); // "一萬二千三百四十五"

// 轉中文金錢格式
string money = number.ToChinese(true); // "壹萬貳仟參佰肆拾伍"

// 轉位元陣列
bool[] bits = number.ToBitArray();

日期時間操作

using CJF.Utilities.Extensions;

DateTime date = DateTime.Now;

// 取得該月第幾週
int weekOfMonth = date.WeekOfMonth();

// 檢查是否為同一週
bool sameWeek = date.IsSameWeek(DateTime.Today);

// 增加週數
DateTime nextWeek = date.AddWeeks(1);

列舉操作

using CJF.Utilities.Extensions;
using System.ComponentModel;

public enum Status
{
    [Description("進行中")]
    InProgress,
    [Description("已完成")]
    Completed
}

// 取得描述文字
string desc = Status.InProgress.GetDescription(); // "進行中"

// 字串轉列舉
Status? status = "InProgress".ToEnum<Status>();

測試覆蓋

本函式庫包含完整的單元測試，確保所有功能的穩定性和可靠性：

StringExtension 測試覆蓋

• ✅ GetDisplayWidth: 英文、中文、符號、空字串的寬度計算測試
• ✅ GetWidth: 已過時方法的相容性測試
• ✅ ToByteArray: 16進位字串轉換，包含空白處理、奇數長度、無效字元例外測試
• ✅ PadRightFixLength: 右側填充，包含英文、中英混合、截斷、邊界情況測試
• ✅ PadLeftFixLength: 左側填充的各種情境測試
• ✅ PadCenter: 居中填充，包含奇偶長度、中文字元測試
• ✅ PadCenterFixLength: 固定長度居中填充和截斷測試
• ✅ WordWrap: 自動換行，包含英文、中文、邊界情況測試
• ✅ SplitCommand: 指令分割，包含雙引號、單引號、複雜巢狀引號測試
• ✅ Encrypt/Decrypt: 加密解密，包含中文、空字串、無效長度例外測試
• ✅ ToEnum: 列舉轉換，包含有效值、數字、無效值測試
• ✅ ContainsDoubleWidthChar: 雙寬度字元檢測，包含各種語言字元測試
• ✅ GetVisibleChar: 可見字元檢測，包含 ANSI Color 處理
• ✅ GetWords: 支援 ANSI Color 字串處理，包含單詞分割、字元寬度計算測試

測試統計: 20 個測試，20 個通過，0 個跳過，0 個失敗

注意事項

• 部分方法標記為 [Obsolete]，建議使用新的替代方法
• 字串寬度計算支援 Unicode 雙寬度字元，包含中文、日文、韓文等
• 加密功能使用 DES 演算法，僅適用於相容性需求
• 數值轉換支援 Big-Endian 和 Little-Endian 格式
• 所有公開方法都有對應的單元測試保護

版本歷程

1.24.432(2025-08-11)

• 修正 PadRightFixLength 和 PadLeftFixLength 方法，支援 ANSI Color 字串處理
• 新增 GetWords 方法，支援 ANSI Color 字串處理，優化字串顯示寬度計算
• 刪除 GetByteCount 方法
• 刪除 GetWidth 方法
• 修改 GetDisplayWidth 方法，支援 ANSI Color 處理
• 更名 GetDisplayWidth 為 GetWidth
• 新增 GetVisibleChar 方法，支援 ANSI Color 處理
• 新增 GetWords 方法，支援 ANSI Color 字串處理，優化字串顯示寬度計算