TaiwanUtilities 1.1.9

🇹🇼 TaiwanUtilities

台灣專用 .NET 工具庫，涵蓋郵遞區號查詢、中文數字轉換、民國日期、證號驗證與中文髒話過濾。

dotnet add package TaiwanUtilities

✨ 核心功能

• 🏠 郵遞區號查詢 — 內嵌全台 80,000+ 筆投遞規則，支援 3+3 碼精確查詢與地址解析
• 🔢 中文數字轉換 — 中文大小寫數字與 decimal 之間的解析與格式化
• 📅 民國日期 — 支援中文日期時間解析、國定假日查詢，可隱含轉換為 DateTime
• ✅ 證號驗證 — 身分證、統編、自然人憑證、手機條碼、捐贈碼
• 🤬 中文髒話過濾 — 三層語言學架構，支援閩南語與國語，低誤判率

🎯 相容性

🏠 郵遞區號 ZipCode

內嵌中華郵政全台 80,000+ 筆投遞規則，查詢引擎採用記憶體內預載 + SQLite 雙層架構，首次查詢自動預熱，後續查詢在微秒級完成。

using TaiwanUtilities;

// 查詢郵遞區號
var result = ZipCode.Find("台北市信義區市府路1號");
// result.ZipCode: "110204"
// result.ResultType: ExactMatch

// 地址解析
var addr = PostalAddress.Parse("台北市信義區市府路1號5樓之3");
// addr.City: "臺北市"
// addr.District: "信義區"
// addr.Road: "市府路"
// addr.Number: 1
// addr.Floor: "5"
// addr.SubFloor: 3

// 自動完成建議
var suggestions = ZipCode.GetSuggestions("台北市信義區市府", maxResults: 5);

// 地址驗證
var validation = ZipCode.ValidateAddress("台北市信義區市府路1號");
// validation.IsValid: true

// 取得投遞規則
var rules = ZipCode.GetDeliveryRules("台北市信義區市府路");

🔢 中文數字 ChineseDecimal

中文大小寫數字與 decimal 之間的解析與格式化，涵蓋繁體/簡體大小寫及全形/半形數字。

using TaiwanUtilities;

// 解析中文數字
decimal value = ChineseDecimal.Parse("貳千參陸九"); // 2369

// 格式化為中文大寫
string upper = value.ToString("TW"); // 貳仟參佰陸拾玖

// 格式化為中文小寫
string lower = value.ToString("tw"); // 二千三百六十九

📅 民國日期 RocDateTime

支援中文日期時間解析，可隱含轉換為 DateTime / DateTimeOffset，支援民國前紀年。 內嵌行政院公告之國定假日資料（民國 87 年至今），支援執行時自動更新最新行事曆。

using TaiwanUtilities;

RocDateTime a = new DateTime(2025, 10, 24);  // 114年10月24日
RocDateTime b = new DateTime(1908, 6, 9);    // 民前4年6月9日

// 國定假日查詢
RocHoliday holiday = a.Holiday;
// holiday.IsHoliday: true
// holiday.Description: "光復節補假"

// 格式化
string s1 = a.ToString("年月日 時分秒");  // 一百一十四年十月二十四日 〇時〇分〇秒
string s2 = a.ToString("g");              // 114/10/24 00:00:00

// 手動新增假日
RocHolidayDataSet.Add(
    new RocDateTime(114, 12, 25),
    new RocHoliday(true, HolidayRole.All, "聖誕節"));

假日資料自動更新

RocHolidayDataSet 採用三層資料查詢機制：手動增刪 > 執行時更新 > 編譯時嵌入。 支援從遠端（GitHub Release / data.gov.tw）或本地 CSV 檔案更新，API 設計與 PostalDatabase 一致。

// 從遠端更新（自動判斷當前年與下一年）
await RocHolidayDataSet.UpdateAsync();

// 從本地 CSV 檔案更新
await RocHolidayDataSet.UpdateFromAsync("holidays.csv");

// 從串流更新
await RocHolidayDataSet.UpdateFromStreamAsync(stream);

// 重置回嵌入資料
RocHolidayDataSet.Reload();

<details> <summary>格式字串對照表</summary>

</details>

✅ 格式驗證

支援多種台灣常用證號的格式驗證。

using TaiwanUtilities;

// 身分證字號
NationalIdentificationCardNumber.Validate("Y190290172"); // true

// 營利事業統一編號
BusinessAdministrationNumber.Validate("12345675"); // true

// 自然人憑證號碼
CitizenDigitalCertificateNumber.Validate("AB12345678901234"); // true

// 電子發票手機條碼
ElectronicInvoiceMobileBarCode.Validate("2134567"); // true

// 電子發票捐贈碼
ElectronicInvoiceDonateCode.Validate("2134567"); // true

🤬 中文髒話 ChineseProfanity

台味滿滿的中文髒話過濾器，基於三層語言學架構（罵人、性器官、排泄物）實作。 支援閩南語、國語及常見變體，低誤判率。

using TaiwanUtilities;

// 偵測
ChineseProfanity.Censor("幹你娘都是說說的而已"); // true

// 取代
ChineseProfanity.Replace("幹你娘都是說說的而已，屌你老母", '*');
// ***都是說說的而已，****

// 語境理解（不誤判）
ChineseProfanity.Censor("這串葡萄誰寫的？程式寫這樣乾脆別寫了"); // false

📁 專案結構

TaiwanUtilities/
├── src/TaiwanUtilities/          # 主要程式庫
│   ├── ChineseDecimal/           # 中文數字模組
│   ├── ChineseProfanity/         # 中文髒話過濾模組
│   ├── Postal/                   # 郵遞區號模組
│   ├── RocDateTime/              # 民國日期模組
│   └── Validators/               # 證號驗證模組
├── test/TaiwanUtilities.UnitTests/
├── tools/postal/                 # 郵遞區號工具
│   └── Postal.Builder/           # 資料庫建立工具
└── docs/                         # 技術文件

🛠️ 開發

# 建置
dotnet build src/TaiwanUtilities/

# 測試
dotnet test test/TaiwanUtilities.UnitTests/

# 發布新版本
git tag v1.2.0 && git push origin v1.2.0

📄 授權

MIT License

🙏 感謝

• 郵遞區號資料來源：中華郵政，採用政府資料開放授權條款
• 國定假日資料來源：行政院，採用政府資料開放授權條款
• 身分證驗證原始版本：enylin/taiwan-id-validator（MIT 授權）

此儲存庫基於「取之於社群，回饋於社群」的愛與信念而存在 ❤️