深入理解 Humanizer 的 ByteSizeUnitSystem显式字节单位体系的解析与格式化指南【免费下载链接】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 中ByteSizeUnitSystem枚举展开系统讲解Legacy、DecimalSi、BinaryIec三种字节单位体系的设计动机、底层单位表与进位规则并结合源码与测试用例完整演示Format、FormatFullWords、ParseWithUnitSystem及配套扩展方法的实际用法帮助你为 .NET 应用精确控制字节容量的显示与解析行为。一、ByteSizeUnitSystem 是什么Humanizer.ByteSizeUnitSystem是 Humanizer 库中用于显式选择字节单位体系的枚举。在默认Legacy模式下Humanizer 的ByteSize沿用其历史上形成的混合单位习惯KB 到 TB 按二进制1024进位而 PB、EB 则按十进制1000进位当用户希望输出严格遵循 SI 十进制或 IEC 二进制标准时就需要通过该枚举显式指定单位体系。枚举完整定义如下源码位置public enum ByteSizeUnitSystem { /// summary /// Uses Humanizers established mixed units: binary KB through TB and decimal PB and EB. /// /summary Legacy 0, /// summary /// Uses decimal SI units where each successive unit is 1000 times the previous unit. /// /summary DecimalSi 1, /// summary /// Uses binary IEC units where each successive unit is 1024 times the previous unit. /// /summary BinaryIec 2 }三个成员的语义是本文的核心骨架成员数值单位符号相邻单位倍率语义Legacy0KB/MB/GB/TB二进制PB/EB十进制混合KB 起 1024PB 起 1000保留 Humanizer 既有的解析与格式化行为DecimalSi1kB/MB/GB/TB/PB/EB1000十进制 SI 单位每级为上一级的 1000 倍BinaryIec2KiB/MiB/GiB/TiB/PiB1024二进制 IEC 单位每级为上一级的 1024 倍与 DataUnit 的关系ByteSizeUnitSystem决定“采用哪套单位表”而具体的单位常量则由DataUnit枚举承载。从 DataUnit.cs 可以看到DataUnit在原有Bit、Byte、Kilobyte等 13 个成员之后追加了 6 个十进制 SI 单位DecimalKilobyte 13到DecimalExabyte 18和 5 个二进制 IEC 单位BinaryKibibyte 19到BinaryPebibyte 23专门服务于显式单位体系的格式化。测试PreservesLegacyLayoutValuesAndDefaults也验证了DataUnit前 13 个成员的数值顺序保持不变确保 Legacy 行为不被破坏。二、三种单位体系的行为差异1. Legacy向后兼容的混合单位Legacy是默认值0它直接委托给 Humanizer 的既有 API。从 ByteSize.cs 的实现可以看到public readonly string Format(ByteSizeUnitSystem unitSystem, string? format null, IFormatProvider? formatProvider null) unitSystem ByteSizeUnitSystem.Legacy ? ToString(format, formatProvider) : FormatWithUnitSystem(unitSystem, format, formatProvider, toSymbol: true); public readonly string FormatFullWords(ByteSizeUnitSystem unitSystem, string? format null, IFormatProvider? formatProvider null) unitSystem ByteSizeUnitSystem.Legacy ? ToFullWords(format, formatProvider) : FormatWithUnitSystem(unitSystem, format, formatProvider, toSymbol: false);即传入Legacy时Format等价于ToStringFormatFullWords等价于ToFullWords。测试文件 ByteSizeUnitSystemTests.cs 中的LegacySystemEntryPointsDelegateToExistingApis用断言逐一确认了Format、FormatFullWords、HumanizeWithUnitSystem、HumanizeCompositeWithUnitSystem、HumanizeWithUnitSystemByteRate以及ParseWithUnitSystem/TryParseWithUnitSystem在 Legacy 下与原 API 输出完全一致。Legacy 的混合行为可从常量定义看出BytesInKilobyte 1024、BytesInMegabyte 1048576等为二进制而BytesInExabyte 1000000000000000000十进制。其典型输出如1 KBByteSize.FromBytes(1024).ToString()。2. DecimalSi十进制 SI 单位DecimalSi采用国际单位制SI前缀每级单位为上一级的1000 倍。对应常量ByteSize.cspublic const long BytesInDecimalKilobyte 1000; public const long BytesInDecimalMegabyte 1000000; public const long BytesInDecimalGigabyte 1000000000; public const long BytesInDecimalTerabyte 1000000000000; public const long BytesInDecimalPetabyte 1000000000000000; public const long BytesInDecimalExabyte 1000000000000000000;其单位表定义ByteSize.csstatic readonly SystemUnit[] DecimalUnits [ new(BytesInDecimalExabyte, EB, DataUnit.DecimalExabyte), new(BytesInDecimalPetabyte, PB, DataUnit.DecimalPetabyte), new(BytesInDecimalTerabyte, TB, DataUnit.DecimalTerabyte), new(BytesInDecimalGigabyte, GB, DataUnit.DecimalGigabyte), new(BytesInDecimalMegabyte, MB, DataUnit.DecimalMegabyte), new(BytesInDecimalKilobyte, kB, DataUnit.DecimalKilobyte) ];注意十进制体系下千字节的规范符号是小写kBISO 80000 推荐形式而 MB 及以上保持大写。与之配套的工厂方法包括FromDecimalKilobytes、FromDecimalMegabytes等。3. BinaryIec二进制 IEC 单位BinaryIec采用 IEC 60027-2 二进制前缀kibi、mebi、gibi……每级为上一级的1024 倍符号为KiB、MiB、GiB、TiB、PiB。单位表ByteSize.csstatic readonly SystemUnit[] BinaryUnits [ new(BytesInPebibyte, PiB, DataUnit.BinaryPebibyte), new(BytesInTebibyte, TiB, DataUnit.BinaryTebibyte), new(BytesInGibibyte, GiB, DataUnit.BinaryGibibyte), new(BytesInMebibyte, MiB, DataUnit.BinaryMebibyte), new(BytesInKibibyte, KiB, DataUnit.BinaryKibibyte) ];二进制体系没有 EB 对应物IEC 体系中 Exbi 未纳入 Humanizer 的单位表因此当传入未定义单位时如Format(ByteSizeUnitSystem.BinaryIec, 0 EiB)会抛出FormatException——这一点由测试RejectsAmbiguousOrUnknownExplicitSystems明确验证。三、符号匹配与大小写规则原文档的 Remarks 部分是理解这套 API 的关键其中两条规则在源码与测试中均有印证SI/IEC 前缀符号大小写不敏感对于DecimalSi和BinaryIec显式解析器与格式令牌选择器在匹配带前缀的单位符号时不区分大小写。测试ParsesOnlySelectedSystemTokens验证了1 kB和1 KB在DecimalSi下都能解析为 1000 字节且输出统一采用规范大小写canonical casing。b与B保持大小写敏感b表示 bit位B表示 byte字节两者含义不同不能混淆。ByteSize.BitSymbol b、ByteSize.ByteSymbol BByteSize.cs。测试ExplicitSystemsUseCanonicalBaseUnitSymbols断言ByteSize.FromBits(1).Format(unitSystem, 0 b, culture)输出1 b而字节格式化输出1 B往返解析均保持一致。因此格式字符串中0.0 MB与0.0 mb效果相同都输出规范MB但0 B与0 b分别代表字节与位绝不可混用。FormatWithUnitSystem中的ReplaceFormatToken机制负责定位格式串中的单位令牌并替换为规范符号或本地化词。四、显式格式化 API 实战1. 自动单位选择FormatFormat(ByteSizeUnitSystem, string?, IFormatProvider?)是显式体系下最常用的格式化入口。当格式串中不包含单位令牌时系统会根据数值自动选择最合适的单位并携带进位。测试FormatsAutomaticSystemBoundaries给出了非常直观的边界对照// DecimalSi每 1000 进位 ByteSize.FromBytes(999).Format(ByteSizeUnitSystem.DecimalSi); // 999 B ByteSize.FromBytes(1000).Format(ByteSizeUnitSystem.DecimalSi); // 1 kB ByteSize.FromBytes(1024).Format(ByteSizeUnitSystem.DecimalSi); // 1.02 kB // BinaryIec每 1024 进位 ByteSize.FromBytes(1000).Format(ByteSizeUnitSystem.BinaryIec); // 1000 B ByteSize.FromBytes(1024).Format(ByteSizeUnitSystem.BinaryIec); // 1 KiB ByteSize.FromBytes(1048576).Format(ByteSizeUnitSystem.BinaryIec); // 1 MiB同一字节数 1024 在两个体系下分别显示为1.02 kB与1 KiB这正是 SI 与 IEC 标准差异的直接体现。自动进位还会考虑格式化精度测试PromotesAutomaticUnitsUsingTheRequestedPrecision显示ByteSize.FromBytes(999.6).Format(ByteSizeUnitSystem.DecimalSi, 0)输出1 kB因为精度为 0 时显示值达到 1000 向上进位而格式化为0.000时则输出999.600 kB。进位循环ByteSize.cs通过systemRadixDecimalSi 为 1000BinaryIec 为 1024判断Math.Abs(displayedValue) systemRadix时向上一级单位推进直到显示值落在当前单位范围内。2. 显式单位令牌在格式串中指定单位在格式串中显式写出单位符号即可固定输出单位如ByteSize.FromBytes(1001001).Format(ByteSizeUnitSystem.DecimalSi, 0.000000 MB); // 1.001001 MB ByteSize.FromDecimalMegabytes(1).Format(ByteSizeUnitSystem.DecimalSi); // 1 MB但需要注意一个格式串中至多允许一个未被引号/转义保护的、不同种类的单位令牌且所选令牌必须属于当前单位体系ByteSize.FromBytes(1).Format(ByteSizeUnitSystem.BinaryIec, 0 EiB)抛FormatExceptionEiB 不在 BinaryUnits 表中ByteSize.FromDecimalMegabytes(1).Format(ByteSizeUnitSystem.DecimalSi, 0 MB kB)抛FormatException同时出现两个不同令牌ByteSize.FromBytes(1).Format(ByteSizeUnitSystem.DecimalSi, 0 B b)抛FormatExceptionB 与 b 被视为不同令牌。以上行为由测试RejectsAmbiguousOrUnknownExplicitSystems完整覆盖。若需在格式串中放置单位样式的字面文本可用单引号引用0 MiB kB或反斜杠转义0 \M\i\B此时它们只是普通文本不参与单位匹配——测试IgnoresQuotedAndEscapedUnitLikeLiterals验证了这一点。3. 组合单位HumanizeCompositeWithUnitSystem当需要像 1 MB 1 kB 1 B 这样的拆分显示时使用HumanizeCompositeWithUnitSystem扩展ByteSizeExtensions.csByteSize.FromBytes(1001001) .HumanizeCompositeWithUnitSystem(ByteSizeUnitSystem.DecimalSi, precision: 3); // 1 MB 1 kB 1 B ByteSize.FromBytes(-1049601) .HumanizeCompositeWithUnitSystem(ByteSizeUnitSystem.BinaryIec, precision: 3); // -1 MiB 1 KiB 1 B该扩展支持precision最多组合的级数、separator分隔符、toWords是否用全称词等参数非 Legacy 体系下会校验unitSystem必须落在DecimalSi到BinaryIec区间否则抛ArgumentOutOfRangeException。4. 传输速率ByteRate.HumanizeWithUnitSystem对ByteRate如 1 MB/s同样可以指定单位体系ByteRate.csByteSize.FromDecimalMegabytes(1) .Per(TimeSpan.FromSeconds(1)) .HumanizeWithUnitSystem(ByteSizeUnitSystem.DecimalSi); // 1 MB/s ByteSize.FromMebibytes(1) .Per(TimeSpan.FromSeconds(1)) .HumanizeWithUnitSystem(ByteSizeUnitSystem.BinaryIec); // 1 MiB/s测试FormatsExplicitUnitsWordsCompositeAndRates对上述行为做了断言且ProvidesGeneratedSystemUnitsForEveryShippedLocale验证了每个已发布区域设置ShippedLocales下符号与全称输出的一致性。5. 全称输出FormatFullWordsFormatFullWords将单位符号替换为本地化的完整单词如1 megabyte、法语1 mégaoctet、简体中文2 二进制拍字节适用于面向终端用户的自然语言展示。测试UsesReviewedLocaleOwnedUnitWords覆盖了 el、he、ig、ku、my、so、zh-Hans、zh-Hant、zu-ZA 等多个区域设置ByteSize.FromDecimalMegabytes(1).FormatFullWords(ByteSizeUnitSystem.DecimalSi); // 1 megabyte ByteSize.FromBytes(count * ByteSize.BytesInDecimalKilobyte) .FormatFullWords(ByteSizeUnitSystem.DecimalSi, 0.## kB, culture); // 如 0 kilooctetfr全称模式的词形变化依据显示计数displayed count而非原始字节数测试FullWordsUseDecoratedDisplayedCount、EnglishExactFullWordsPluralizeZeroAndFractionalOther、ExactFullWordsUseCanonicalOneCategory分别验证了百分比/千分比、零与小数、以及复数分类CLDR下的正确输出。五、显式解析 API 实战与格式化对应解析侧提供了三组入口ByteSize.cspublic static ByteSize ParseWithUnitSystem(string s, ByteSizeUnitSystem unitSystem, IFormatProvider? formatProvider null); public static bool TryParseWithUnitSystem(string? s, ByteSizeUnitSystem unitSystem, out ByteSize result); public static bool TryParseWithUnitSystem(string? s, ByteSizeUnitSystem unitSystem, IFormatProvider? formatProvider, out ByteSize result); public static bool TryParseSpanWithUnitSystem(ReadOnlySpanchar s, ByteSizeUnitSystem unitSystem, out ByteSize result); public static bool TryParseSpanWithUnitSystem(ReadOnlySpanchar s, ByteSizeUnitSystem unitSystem, IFormatProvider? formatProvider, out ByteSize result);解析规则要点只接受当前体系内的令牌TryParseWithUnitSystem(1 MB, ByteSizeUnitSystem.BinaryIec, out _)返回false1 MiB在DecimalSi下同样失败测试RejectsAmbiguousOrUnknownExplicitSystems。前缀大小写不敏感、b/B敏感1 kB与1 KB在DecimalSi下都解析为 1000 字节1 b解析为 1 位1 B解析为 1 字节测试ExplicitSystemsUseCanonicalBaseUnitSymbols。精确位数与边界ParseWithUnitSystem(9007199254740993.0 b, ...)能精确还原9_007_199_254_740_993位超过2^53的整数值也能精确保留但非整数的位如1.1 b会解析失败超出long范围的位数值同样失败测试ParsesIntegralFixedPointBitsExactly、ParsesExactBitRange。科学计数法支持1.5E001 b这样的输出往返但指数为负产生小数位时不接受测试ParsesScientificExplicitOutput。非法体系值传入未定义的枚举值如(ByteSizeUnitSystem)99会抛ArgumentOutOfRangeException。解析遵循传入的IFormatProvider的数字格式。测试ExplicitParsingUsesCurrentMutableNumberFormat演示了将NegativeSign设为~、小数分隔符设为,后~1_500,5 MB可正确解析为-1500.5兆字节ByteSizeUnitSystemCurrentCultureTestsfi 文化也验证了默认 provider 下的往返一致性。六、典型应用场景与选型建议结合以上 API 行为可以给出如下工程实践建议网络带宽、存储容量与外部系统对接当数据来源遵循 SI 惯例如云厂商账单通常以十进制计量时选择DecimalSi配合FromDecimalMegabytes等工厂方法避免 1024/1000 换算偏差。操作系统、内存等底层资源展示二进制语义更符合硬件寻址习惯选择BinaryIec输出KiB/MiB/GiB可避免 1 GB 1000MB 还是 1024MB 的歧义。保持既有输出不变迁移存量代码时使用Legacy或直接使用原有的ToString/ToFullWords/Humanize测试PreservesLegacyLayoutValuesAndDefaults与LegacySystemEntryPointsDelegateToExistingApis保证了零行为差异。面向多语言用户使用FormatFullWords配合目标CultureInfo单位词由各区域设置的本地化短语表如 Locales 下的 yml 数据经 SourceGenerator 生成的LocalePhraseTable驱动测试ProvidesGeneratedSystemUnitsForEveryShippedLocale遍历全部已发布区域设置验证了完整覆盖。七、API 使用注意事项速查格式串中未引号/转义保护的单位令牌至多一个种类且必须属于当前单位体系否则抛FormatException。bbit与Bbyte始终大小写敏感其他 SI/IEC 前缀符号大小写不敏感输出统一为规范大小写。BinaryIec体系不支持 EB无 Exbi 级单位DecimalSi的千字节符号规范为小写kB。Legacy分支直接委托原有 API不会抛FormatException也不做令牌体系校验适合兼容旧输出。非 Legacy 体系下传入未定义枚举值会抛ArgumentOutOfRangeException解析失败体系不匹配、数值越界、非法位数时Try*返回false而非抛出异常。延伸阅读ByteSizeUnitSystem的完整使用上下文可参见 ByteSize 结构体文档含全部十进制/二进制常量、属性与工厂方法、ByteSizeExtensions 扩展文档HumanizeWithUnitSystem、HumanizeCompositeWithUnitSystem等以及 ByteRate 文档速率格式化单元测试 ByteSizeUnitSystemTests.cs 提供了 40 余组针对边界、精度、多文化场景的断言是理解行为细节的最佳参考。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考