开发工具【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址https://gitcode.com/gh_mirrors/hu/Humanizer点击查看免费下载本篇技术指南以 Humanizer 库 OrdinalizeExtensions 的 API 参考文档为主体系统讲解如何将数字转换为序数形式如1st、2nd、3rd深入剖析其在当前仓库中的源码实现、语法性别GrammaticalGender支持、区域性CultureInfo本地化机制以及 64 位整数扩展。读完本文你将掌握Ordinalize全系列重载的用法、底层IOrdinalizer插件化架构以及如何利用它输出符合巴西葡萄牙语、西班牙语等语言习惯的序数文本。什么是序数化Ordinalize序数ordinal number用于表示在有序序列中的位置例如英文中的1st、2nd、3rd、4th。Humanizer 的OrdinalizeExtensions静态类为int、long和string类型提供了同名的扩展方法Ordinalize用于把一个数字变成序数字符串。它是 Humanizer 众多人性化字符串功能Humanize、Dehumanize、ToQuantity等中的一员位于 src/Humanizer/OrdinalizeExtensions.cs。public static class OrdinalizeExtensions { public static string Ordinalize(this int number); public static string Ordinalize(this string numberString); // ... 更多重载 }根据 src/Humanizer/OrdinalizeExtensions.cs 中的类注释序数化只接受整数值如果调用方持有小数必须先自行选择并执行显式的取整与类型转换策略再调用Ordinalize。基础用法int 与 string 两个入口原 API 文档列出两类接收者receiver的Ordinalize重载int与string。两者在语义上等价——将数字转为序数文本区别仅在于输入类型。方法签名参数说明返回string Ordinalize(this int number)number要被序数化的整数stringstring Ordinalize(this string numberString)numberString以字符串形式表示的数字string从源码看int重载的默认实现OrdinalizeExtensions.cs会委托给带CultureInfo的重载public static string Ordinalize(this int number) number.Ordinalize(CultureInfo.CurrentCulture);而string重载OrdinalizeExtensions.cs则直接调用全局默认序数化器public static string Ordinalize(this string numberString) Configurator.Ordinalizer.Convert(int.Parse(numberString), NormalizeOrdinalNumberString(numberString));即先通过int.Parse把字符串解析为整数再交给配置好的IOrdinalizer完成转换。在英文环境下实际输出由英语序数化器基于ModuloSuffixOrdinalizer的取模后缀规则决定1.Ordinalize(); // 1st 2.Ordinalize(); // 2nd 3.Ordinalize(); // 3rd 4.Ordinalize(); // 4th 11.Ordinalize(); // 11th —— 注意不是 11st 21.Ordinalize(); // 21st 101.Ordinalize(); // 101st这些结果与测试用例 tests/Humanizer.Tests/OrdinalizeTests.cs 中的[InlineData]断言完全一致例如1 → 1st、11 → 11th、21 → 21st、101 → 101st。语法性别GrammaticalGender参数原文档明确指出Ordinalize的多个重载接受Humanizer.GrammaticalGender参数并特别强调其用于**巴西葡萄牙语Brazilian Portuguese**区域1.Ordinalize(GrammaticalGender.Masculine) - 1º 1.Ordinalize(GrammaticalGender.Feminine) - 1ªGrammaticalGender是一个三值枚举src/Humanizer/GrammaticalGender.csMasculine阳性Feminine阴性Neuter中性// 巴西葡萄牙语 1.Ordinalize(GrammaticalGender.Masculine); // 1º 1.Ordinalize(GrammaticalGender.Feminine); // 1ª 1.Ordinalize(GrammaticalGender.Masculine); // 1º 1.Ordinalize(GrammaticalGender.Feminine); // 1ª源码中性别相关的重载OrdinalizeExtensions.cs会将参数透传给IOrdinalizer.Convert(int, string, GrammaticalGender)而巴西葡萄牙语的序数化器正是基于 SuffixOrdinalizer 实现——该类接收三个性别后缀并在Convert中按性别选择后缀SuffixOrdinalizer.csreturn numberString gender switch { GrammaticalGender.Feminine feminineSuffix, // ª GrammaticalGender.Neuter neuterSuffix, _ masculineSuffix // º };CultureInfo 参数与本地化机制原文档中多个重载接受System.Globalization.CultureInfo culture参数其语义为指定用于序数化的区域性若传入null则使用当前线程的 UI 文化current threads UI culture。从实现看culture为null时实际回落逻辑OrdinalizeExtensions.cs为var resolvedCulture culture ?? CultureInfo.CurrentCulture; return Configurator.Ordinalizers.ResolveForCulture(culture) .Convert(ParseOrdinalNumber(numberString, resolvedCulture), ...);这里的关键是Configurator.Ordinalizers—— 一个LocaliserRegistryIOrdinalizer类型的注册表src/Humanizer/Configuration/Configurator.cs。它由 OrdinalizerRegistry 构建默认回退到DefaultOrdinalizer原样返回输入文本随后通过源代码生成器Source Generator按 locale 注册各语言的专用序数化器。DefaultOrdinalizersrc/Humanizer/Localisation/Ordinalizers/DefaultOrdinalizer.cs本身是一个什么都不做的基类public virtual string Convert(long number, string numberString) numberString;各区域语言通过继承它来覆盖行为。从 OrdinalizerProfileCatalogInput.cs 可见源生成器支持三种序数化器类型suffix固定性别后缀如巴西葡萄牙语的º/ª对应SuffixOrdinalizermodulo-suffix按数字取模规则选择后缀如英语的st/nd/rd/th对应 ModuloSuffixOrdinalizernumber-word-suffix基于数字单词的后缀形式。以英语为例ModuloSuffixOrdinalizer的后缀选择遵循严格优先级ModuloSuffixOrdinalizer.cs先检查最后两位数区间规则再查精确数值映射然后查后两位后缀表最后回退到末位数字后缀表与默认后缀。这正是11th、12th、13th不同于1st、2nd、3rd的底层原因11-13的末位1、2、3被精确映射覆盖为th。显式指定文化的示例// 指定文化与当前线程文化无关 1.Ordinalize(new System.Globalization.CultureInfo(pt-BR), Humanizer.GrammaticalGender.Feminine); // 1ª 1.Ordinalize(new System.Globalization.CultureInfo(en-US)); // 1st文化相关的数字格式化细节Ordinalize在内部还会根据文化格式化数字本身OrdinalizeExtensions.cs对正数若该文化的NumberFormat.NativeDigits是标准 ASCII 数字UsesInvariantDigits为true则用不变文化格式化否则使用该文化自身的数字格式例如某些语言的原生数字字符。负数则额外比对文化的负号与NumberNegativePattern以决定是否直接用不变文化输出。这些数字格式化配置按文化名缓存在ConcurrentDictionarystring, OrdinalNumberFormatting中OrdinalizeExtensions.cs避免每次调用重复构建。全系列重载一览综合原 API 文档与 src/Humanizer/OrdinalizeExtensions.csOrdinalize的完整重载矩阵如下均返回string接收者参数组合int number()/(WordForm)/(CultureInfo?)/(CultureInfo?, WordForm)/(GrammaticalGender)/(GrammaticalGender, WordForm)/(GrammaticalGender, CultureInfo?)/(GrammaticalGender, CultureInfo?, WordForm)string numberString同上 8 种组合long number同上 8 种组合其中WordForm用于区分缩写与完整词形。例如西班牙语源码注释中的示例OrdinalizeExtensions.cs1.Ordinalize(WordForm.Abbreviation) - 1.er // 如 Vivo en el 1.er piso我住在一楼 1.Ordinalize(WordForm.Normal) - 1.º // 如 Fui el 1º de mi promoción我是班里第一名 1.Ordinalize(GrammaticalGender.Feminine, WordForm.Normal) - 1.ª注意原 API 文档生成的版本中string接收者仅收录了int/string两类long重载在源码中同样完整存在OrdinalizeExtensions.cs并通过ILongOrdinalizer接口提供原生 64 位支持详见下文。底层架构IOrdinalizer 与 64 位支持Ordinalize之所以能做到多语言、多形式输出是因为它完全委托给可插拔的序数化器接口src/Humanizer/Localisation/Ordinalizers/IOrdinalizer.cspublic interface IOrdinalizer { string Convert(int number, string numberString); string Convert(int number, string numberString, WordForm wordForm); string Convert(int number, string numberString, GrammaticalGender gender); string Convert(int number, string numberString, GrammaticalGender gender, WordForm wordForm); } public interface ILongOrdinalizer : IOrdinalizer { string Convert(long number, string numberString); // ... 对应的 WordForm / gender 重载 }ILongOrdinalizer用于支持超出int范围的 64 位值。在long重载的ConvertOrdinalizer辅助方法中OrdinalizeExtensions.cs如果注册的序数化器实现了ILongOrdinalizer则直接传入long否则尝试把值安全收缩到int若超出范围则抛出NotSupportedException: The registered ordinalizer {type} does not support 64-bit values.这意味着在默认的英语环境下long.MaxValue.Ordinalize()可以正常工作DefaultOrdinalizer及其派生类实现了ILongOrdinalizer但若你通过 Configurator 注册了一个仅实现IOrdinalizer的自定义序数化器超大long值会抛出上述异常——这是扩展自定义序数化器时需要注意的边界。另外string重载在解析与归一化上做了两层处理OrdinalizeExtensions.csParseOrdinalNumber按指定文化解析int.Parse(numberString, culture)NormalizeOrdinalNumberString剔除字符串中的 Unicode格式类字符UnicodeCategory.Format如不可见的控制/格式符保证传入IOrdinalizer的字符串干净一致。测试验证与可靠性仓库提供了详尽的测试用例来锁定Ordinalize行为。tests/Humanizer.Tests/OrdinalizeTests.cs 通过[Theory][InlineData]覆盖了大量输入-输出对例如int系列0→0th、1→1st、2→2nd、3→3rd、4→4th、11→11th、21→21st、101→101st等以及string系列的同构断言。运行测试即可验证dotnet test tests/Humanizer.Tests/Humanizer.Tests.csproj --filter FullyQualifiedName~Ordinalize实用注意事项小结只接受整数Ordinalize的语义限定于整数值类注释明确说明见 OrdinalizeExtensions.cs小数需自行取整后再调用。culture为null时按源码实现而非原文档措辞实际使用CultureInfo.CurrentCulture当前线程文化作为回落值。默认文化行为int/long的无参数重载均委托给CultureInfo.CurrentCulture版本因此输出随线程当前文化变化。性别只对特定语言生效GrammaticalGender主要影响巴西葡萄牙语1º/1ª等区分性别的语言对英语等无性别后缀的语言性别参数通常被忽略SuffixOrdinalizer按性别选择而英语的ModuloSuffixOrdinalizer不感知性别。自定义序数化器可通过Configurator.Ordinalizers注册新的IOrdinalizer/ILongOrdinalizer实现来扩展若注册项仅实现 32 位接口注意 64 位大数会抛NotSupportedException。借助这套 API你可以在极少的代码量下输出符合多种语言习惯的序数文本——从英文的1st/2nd/3rd/4th到巴西葡萄牙语的1º/1ª再到西班牙语的1.er/1.º无需手写任何规则分支。赞分享开发工具【免费下载链接】HumanizerHumanizer meets all your .NET needs for manipulating and displaying strings, enums, dates, times, timespans, numbers and quantities项目地址https://gitcode.com/gh_mirrors/hu/Humanizer点击查看免费下载相关推荐Humanizer 序数化扩展OrdinalizeExtensions完全指南从 1st/2nd/3rd 到多语言序数输出Humanizer 序数化扩展OrdinalizeExtensions完全指南从 1st/2nd/3rd 到多语言序数输出 OrdinalizeExten开发工具Humanizer 序数化扩展OrdinalizeExtensions完全指南从 1st/2nd/3rd 到多语言、多性别的序数格式化Humanizer 序数化扩展OrdinalizeExtensions完全指南从 1st/2nd/3rd 到多语言、多性别的序数格式化 Ordinaliz开发工具Humanizer OrdinalizeExtensions 序数化完全指南从 1st 到多语言序数输出Humanizer OrdinalizeExtensions 序数化完全指南从 1st 到多语言序数输出 导读 本文以 Humanizer 项目中的 Ordi开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考