EsUtil.Helper.ZenHanConverter 2.0.0

ZenHanConverter ユーザー利用仕様書

概要

• 全角・半角・カタカナ/ひらがな・記号などの相互変換を提供するユーティリティです。
• 変換定義は CSV からコード生成され、ConvertPairs/EntryRecord オブジェクトとして高速に扱えます。
• 入力を正規化してから変換する複合メソッド (ToHan, ToZenWithKatakana など) を備え、アプリケーションの文字幅統一やデータクレンジングに利用できます。

インストール

NuGet.org から

dotnet add package EsUtil.Helper.ZenHanConverter

• NuGet ギャラリー: https://www.nuget.org/packages/EsUtil.Helper.ZenHanConverter
• パッケージ名: EsUtil.Helper.ZenHanConverter

GitHub Packages から

GitHub Packages は認証が必要なため、事前にソースと資格情報を登録します。

# USERNAME は GitHub のユーザー名、TOKEN は read:packages 権限を持つ PAT を指定します
dotnet nuget add source --username USERNAME --password TOKEN --store-password-in-clear-text --name github "https://nuget.pkg.github.com/tomokuni/index.json"

dotnet add package EsUtil.Helper.ZenHanConverter

• GitHub Packages: https://github.com/tomokuni/EsUtil.Helper.ZenHanConverter/pkgs/nuget/EsUtil.Helper.ZenHanConverter
• 初回公開時の可視性は Private です。他のユーザーが利用する場合は、パッケージ設定から可視性を変更してください。
• GitHub Packages を併用すると、NuGet が全ソースへ問い合わせる都合で稀に 403 が出ることがあります。その場合は nuget.config の Package Source Mapping でソースを振り分けてください。

対応環境

• .NET 10 以上（ライブラリ本体。C# 14 で実装）
• OS に依存しないため、Windows / Linux / macOS のいずれでも動作します。
• テストはライブラリと同じ net10.0 を対象に実行しています。

リリースビルド での ベンチマーク結果

1000 文字の混合テキスト（英数字・全角/半角カナ・ひらがな・記号）を 10,000 回ループ処理した際の実行時間計測結果です（.NET 10 / Release / x64）。

※ ToHan は変換対象のパターンが最も多く (GroupOf.Ascii + GroupOf.Kana の全域)、正規表現のマッチング負荷が高いため相対的に時間を要します。 ※ ToNormalize は正規化のみのため最も高速です。

変換できる文字とカテゴリ

• 数字: ０～９ ↔ 0～9
• 英字: 全角/半角の大文字・小文字 Ａ～Ｚ、ａ～ｚ ↔ A～Z、a～z
• 記号: 括弧類、クォート類、区切り記号、算術/比較記号、＼/\\/￥/¥/スペース など
• カタカナ/ひらがな: 清音・濁音・半濁音・小書き文字を全角/半角で相互変換。゛/゜ 長音 ー、中点 ・、句読点 、 。 も対応
• ケース変換: 全角・半角それぞれの大文字⇔小文字
• カナの結合: 分離した全角カナ (カ+゛ 等) を合成 (GroupOf.Kana.Kata.ComposeMap / GroupOf.Kana.Hira.ComposeMap)。半角化 (ToHan 系) で分離した半角カナが得られます
• 特殊ケース: 細かな空白（ノーブレークスペース等）を通常スペースへ、各種ダッシュをハイフンへ正規化

主な API 詳説

ToHan・ToZen 系と ToUpper/ToLowerCase は内部で ToNormalize を適用します。 ToNormalize のカナ合成は 全角カナ同士 / 全角+半角濁点 が対象で、半角カナ同士 (ｶ+ﾞ) は変化しません。

拡張メンバー（文字列に直接チェーンできる API）

上記の表のメソッドは、C# 14 の拡張メンバーとして 文字列のインスタンス メソッドと同じ形でも呼び出せます。 using EsUtil.Helper.ZenHanConverter; を記述するだけで利用できます。

using EsUtil.Helper.ZenHanConverter;

// 静的 API の代わりに、文字列から直接チェーンできる
var han = "ＡＢＣ１２３　カナ。".ToHan();                          // "ABC123 ｶﾅ｡"
var zen = "ABC123 ｶﾀｶﾅ かな".ToZenWithKatakana();               // "ＡＢＣ１２３　カタカナ　かな"
var normalized = "カ゛\u00A0\u2010".ToNormalize();              // "ガ -"

// ペア集合への拡張
var isEmpty = GroupOf.Ascii.ToHanMap.IsEmpty;                    // false
var pairs = new[] { ("◎", "○"), ("○", "◯") }.ToConvertPairs();

使い方サンプル

using EsUtil.Helper.ZenHanConverter;

// 正規化（特殊空白→U+0020、各種ダッシュ→U+002D、分離した全角カナの合成）
var normalized = ZenHanConverter.ToNormalize("カ゛\u00A0\u2010"); // "ガ -"

// 半角カナは ToNormalize の合成対象外（変化しない）
var notNormalized = ZenHanConverter.ToNormalize("ｶﾞ"); // "ｶﾞ"

// 全カテゴリを半角へ
var han = ZenHanConverter.ToHan("ＡＢＣ１２３　カナ。"); // "ABC123 ｶﾅ｡"

// 全角で統一（半角カナは全角カタカナ、ひらがなはそのまま）
var zenKata = ZenHanConverter.ToZenWithKatakana("ABC123 ｶﾀｶﾅ かな"); // "ＡＢＣ１２３　カタカナ　かな"

// 半角カナを全角ひらがなへ（全角カタカナはそのまま）
var zenHira = ZenHanConverter.ToZenWithHiragana("ABC123 ｶﾀｶﾅ カナ"); // "ＡＢＣ１２３　かたかな　カナ"

// 数字・英字・記号のみ半角化
var hanAscii = ZenHanConverter.ToHanOnlyAscii("ＡＢＣ１２３ カナ"); // "ABC123 カナ"

// 数字・英字・記号のみ全角化（半角スペースも全角スペースへ）
var zenAscii = ZenHanConverter.ToZenOnlyAscii("ABC123 カナ"); // "ＡＢＣ１２３　カナ"

// ひらがな/カタカナとかな記号を半角化
var hanKana = ZenHanConverter.ToHanOnlyKana("カナかな。ー"); // "ｶﾅｶﾅ｡ｰ"

// カタカナとかな記号のみ半角化（ひらがなはそのまま）
var hanKata = ZenHanConverter.ToHanOnlyKatakana("カナかな。ー"); // "ｶﾅかな｡ｰ"

// 半角カナを全角カタカナへ
var zenKataOnlyKata = ZenHanConverter.ToZenOnlyKatakana("カナかな ｶﾀｶﾅ"); // "カナかな カタカナ"

// ひらがな+半角カナを全角カタカナへ
var zenKataOnlyKana = ZenHanConverter.ToZenKatakanaOnlyKana("かな ｶﾅ"); // "カナ カナ"

// カタカナ（全/半）をひらがなへ
var zenHiraOnlyKana = ZenHanConverter.ToZenHiraganaOnlyKana("カナ ｶﾅ"); // "かな かな"

// 英字を大文字へ（全角/半角対応）
var upper = ZenHanConverter.ToUpperCase("abc ａｂｃ"); // "ABC ＡＢＣ"

// 英字を小文字へ（全角/半角対応）
var lower = ZenHanConverter.ToLowerCase("ABC ＡＢＣ"); // "abc ａｂｃ"

// タブを半角スペースへ
var tabs = ZenHanConverter.ConvertTabToSpace("\tABC\t"); // " ABC "

// バックスラッシュを半角円記号へ
var yen = ZenHanConverter.ConvertBackslashToHanYen(@"\"); // "¥"

// ConvertPairs で任意の組合せを構築
var pairs = new ConvertPairs([( "◎", "○" ), ( "○", "◯" )]);
var chained = pairs.ChainMerge(new ConvertPairs([( "◯", "●" )]));
var result = chained.Convert("◎○◯"); // "○●◯"

変換定義の直接利用

• 主な API では対応しない細かな変換を行う場合、GroupOf / NameOf クラス経由で定義済みの変換ペア (ConvertPairs) を取得できます。
• GroupOf はグループ単位、NameOf は定義単位でアクセスできます（詳細は「定義済みエントリ一覧」を参照）。

定義グループ (GroupOf)

GroupOf 静的クラス以下にカテゴリごとに分類されたプロパティが定義されています。

これらを通して、さらに細かい単位のマップ (IEnumerable<(string Source, string Target)>) にアクセス可能です。 例: GroupOf.Ascii.ToHanMap, GroupOf.Kana.ToZenMap, GroupOf.Kana.Kata.ComposeMap など。

ConvertPairs の使い方と変換方法

定義済みエントリ一覧 (GroupOf / NameOf)

GroupOf クラスおよび NameOf クラスでアクセス可能な定義一覧です。 GroupOf.{カテゴリ}.{グループ} で ConvertPairs を、NameOf.{カテゴリ}.{定義名} で個別の定義を取得できます。 いずれも EsUtil.Helper.ZenHanConverter 名前空間に属します。

GroupOf の階層

各ノードには変換方向ごとの ConvertPairs プロパティ (ToHanMap / ToZenMap / ToUpperMap / ToLowerMap / ComposeMap / ToAsciiMap / FromAsciiMap / ToHiraMap / ToKataMap / ToASpaceMap / ToAHyphenMap / ToSpaceFromTabMap / ToYenFromBslashMap / ToBslashFromYenMap) が定義されています。

NameOf の階層

NameOf.Ascii の記号名一覧

パフォーマンス向上施策

• Regex/辞書キャッシュ: ConcurrentDictionary でコンパイル済み Regex とマッピングをキャッシュし、再生成を回避。
• 先勝ち辞書化: 同一 Source は初出のみ採用し、決定性と無駄な上書きを防止。
• Unicode デコード先行: EntryRecord 生成時に U+XXXX を実体化し、実行時オーバーヘッドを削減。
• null/空の早期スキップ: 変換不要ケースで早期 return し、Regex.Replace 呼び出しを抑制。
• 不変コレクション共有: ImmutableList を使い副作用を排除、スレッドセーフに高速アクセス。
• 連鎖変換の辞書化: ConvertPairs.Chain では第2段を Source ごとにグルーピングし、連結判定を O(1) に高速化。

ライセンス

本リポジトリの LICENSE を参照してください。