Humanizer ByteSize 结构体深度解析：.NET 字节大小的完整 API 与源码实现

开发工具【免费下载链接】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 库中的ByteSize是一个不可变结构体负责把多少字节这一原始数值转换为人类可读的形式如10.5 KB、1 byte并支持单位换算、算术运算、比较排序与字符串解析。本文基于 Humanizer 2.13.14 版本站点中的ByteSizeAPI 参考文档结合当前仓库中 src/Humanizer/Bytes/ByteSize.cs 的源码实现与 tests/Humanizer.Tests/Bytes/ 下的测试用例完整覆盖该结构体的构造器、常量字段、属性、方法与运算符帮助你在项目中直接、可靠地使用这套字节大小处理能力。结构体定义与接口契约ByteSize表示一个字节大小值Represents a byte size value它是一个值类型同时实现四个 .NET 标准接口public struct ByteSize : IComparableByteSize, IEquatableByteSize, IComparable, IFormattable接口提供的能力IComparableByteSizeCompareTo(ByteSize)强类型比较可用于OrderBy排序IEquatableByteSizeEquals(ByteSize)精确相等判断配合运算符IComparableCompareTo(object)兼容旧版集合 API如ArrayList.SortIFormattableToString(string, IFormatProvider)支持自定义数字格式与文化感知格式化从源码结构看src/Humanizer/Bytes/ByteSize.cs该结构体以double byteSize作为主构造函数参数C# 主构造语法内部把字节数向上取整后缓存为long型的Bits因此位Bits是精度的最终锚点相等性、哈希与比较全部基于Bits计算Equals/GetHashCode/比较运算符public readonly bool Equals(ByteSize value) Bits value.Bits; public readonly override int GetHashCode() Bits.GetHashCode();这一设计意味着ByteSize.FromBytes(1.5)的Bits是12Math.Ceiling(1.5 * 8)Equals比较的其实是位级别的一致性而非字节小数。构造器ByteSize(double) 构造函数public ByteSize(double byteSize);参数byteSize为System.Double表示以字节为单位的数值。所有From*工厂方法最终都会经过这个构造器例如FromKilobytes(1.5)等价于new ByteSize(1.5 * 1024)FromKilobytes 实现。CreatingTests 验证了构造行为例如用1099511627776字节构造后Kilobytes为1073741824、Gigabytes为1024、Terabytes为1var result new ByteSize(1099511627776); Assert.Equal(8.796093022208e12, result.Bits); Assert.Equal(1024, result.Gigabytes); Assert.Equal(1, result.Terabytes);静态工厂方法From* 系列方法参数语义ByteSize.FromBits(long)位数new(value / 8.0)位数先换算为字节ByteSize.FromBytes(double)字节数直接构造ByteSize.FromKilobytes(double)KB 数value * 1024字节ByteSize.FromMegabytes(double)MB 数value * 1048576字节ByteSize.FromGigabytes(double)GB 数value * 1073741824字节ByteSize.FromTerabytes(double)TB 数value * 1099511627776字节测试中的换算依据CreatingTestsvar result ByteSize.FromBits(8); // Bits 8, Bytes 1 var kb ByteSize.FromKilobytes(1.5); // Bytes 1536, Kilobytes 1.5 var mb ByteSize.FromMegabytes(1.5); // Bytes 1572864常量字段单位名、符号与换算因子ByteSize暴露两组字符串常量——单位全称Bit、Byte、Kilobyte…与符号BitSymbol、ByteSymbol…以及一组表示换算因子的long常量public const long BitsInByte 8; public const long BytesInKilobyte 1024; public const long BytesInMegabyte 1048576; // 1024^2 public const long BytesInGigabyte 1073741824; // 1024^3 public const long BytesInTerabyte 1099511627776; // 1024^4 public const string BitSymbol b; public const string ByteSymbol B; public const string KilobyteSymbol KB; public const string MegabyteSymbol MB; public const string GigabyteSymbol GB; public const string TerabyteSymbol TB;换算因子表明2.13.14 版本的格式化与格式化解析采用每级 1024 倍的二进制约定KB 到 TB这在 ByteSize.cs 的常量定义中可以确认。当前仓库主分支在此基础上又补充了 PB/EB、十进制 SIkB/MB/…与 IEC 二进制KiB/MiB/…常量并引入ByteSizeUnitSystem枚举来显式选择单位体系ByteSizeUnitSystem.cs如果你面向 2.13.14 版本编程上文 API 文档列出的就是全部可用面。此外还有两个边界实例字段类型取值ByteSize.MaxValuestatic readonly ByteSizeFromBits(long.MaxValue)约 9.2 EB 位域上限ByteSize.MinValuestatic readonly ByteSizeFromBits(long.MinValue)MinValue与MaxValue之所以由位数而非字节数推导正是因为结构体的存储与相等判断都锚定在long Bits上源码。属性单位换算属性属性类型计算方式Bitslong(long)Math.Ceiling(byteSize * 8)向上取整Bytesdouble原始字节数KilobytesdoubleBytes / 1024MegabytesdoubleBytes / 1048576GigabytesdoubleBytes / 1073741824TerabytesdoubleBytes / 1099511627776最大整数单位三件套这三个属性是格式化输出的核心它们共同回答这个值用哪个单位表达时数值 1属性类型说明LargestWholeNumberValuedouble以选定的最大整数单位表达的数值LargestWholeNumberSymbolstring该单位的本地化符号如KBLargestWholeNumberFullWordstring该单位的本地化全称如kilobyte从 GetLargestWholeNumberSymbol 的源码 看选择逻辑是逐级向下判断Math.Abs(X) 1用绝对值是为了正确处理负数命中后交给Configurator.GetFormatter(culture)做本地化——也就是说单位词本身是支持多语言的例如法语文化下会得到Ko而非KB。同名方法GetLargestWholeNumberSymbol(IFormatProvider)与GetLargestWholeNumberFullWord(IFormatProvider)允许显式指定格式化提供者。算术方法与运算符Add* 方法族每个单位对应一个加法方法均返回新的ByteSize值类型语义不可变public ByteSize Add(ByteSize bs); // Bytes bs.Bytes public ByteSize AddBits(long value); public ByteSize AddBytes(double value); public ByteSize AddKilobytes(double value); public ByteSize AddMegabytes(double value); public ByteSize AddGigabytes(double value); public ByteSize AddTerabytes(double value); public ByteSize Subtract(ByteSize bs); // Bytes - bs.Bytes实现上AddBits等方法就是委托给运算符源码this FromBits(value)。ArithmeticTests 用位、字节、KB、MB、GB、TB 逐级验证了FromX(2).AddX(2)恰好等于对应单位的 4 倍例如FromGigabytes(2).AddGigabytes(2)后Gigabytes 4。运算符总览运算符签名行为(ByteSize, ByteSize)字节数相加-二元(ByteSize, ByteSize)字节数相减-一元(ByteSize)取负字节数(ByteSize)加 1 字节--(ByteSize)减 1 字节/!(ByteSize, ByteSize)基于Bits比较(ByteSize, ByteSize)基于Bits比较运算符直接操作Bytes或Bits源码注意类增量运算按 1 字节步进而非 1 位。比较与相等性public int CompareTo(ByteSize other); // 强类型比较返回负/0/正 public int CompareTo(object obj); // 非 ByteSize 抛 ArgumentException public bool Equals(ByteSize value); public override bool Equals(object value); public override int GetHashCode();CompareTo(object)对非ByteSize对象抛出ArgumentException(Object is not a ByteSize)源码。由于排序、相等、哈希全部落在Bits上new ByteSize(0) 1 byte 的 /--结果、MaxValue MinValue等边界情况的行为也被 ArithmeticTests 固定两者相加得到Bytes 0且ToString()为0 b。字符串格式化ToString 与 ToFullWords默认格式化public override string ToString();官方语义把当前值转换为字符串所选用的度量前缀bit、byte、kilo、mega、giga、tera是使对应数值 1 的最大单位。默认数字格式为0.##最多两位小数。ToStringTests 给出可复现的输出ByteSize.FromKilobytes(10.5).ToString() // 10.5 KB ByteSize.FromKilobytes(10.501).ToString() // 10.5 KB默认 0.## 舍入 ByteSize.FromBytes(10).ToString(##.#### B) // 10 B ByteSize.FromKilobytes(10).ToString(##.#### KB) // 10 KB ByteSize.FromBits(10).ToString(##.#### b) // 10 b带格式串的 ToStringpublic string ToString(string format); public string ToString(string format, IFormatProvider provider); public string ToString(IFormatProvider provider);格式串规则可结合 ToString(format, provider) 实现 理解format为null或G时回落到默认0.##格式串中出现某个单位符号如KB、MB、TB、B、b时强制按该单位换算输出例如FromTerabytes(10).ToString(0.0 TB)得到10.0 TB格式串中不含单位符号时仍按最大整数单位规则选择单位例如FromMegabytes(.5).ToString(#.#)得到512 KB负值同理为-512 KBB与b的大小写判断是敏感的源码注释 Byte and Bit symbol look must be case-sensitiveByteSize.cs避免与格式串中的其他字母冲突。ToStringTests 覆盖了这些路径包括小数精度FromKilobytes(10.1234).ToString(#.#### KB)输出10.1234 KB。ToFullWords全称输出public string ToFullWords(string format null, IFormatProvider provider null);语义与ToString相同但单位使用本地化全称kilobyte、gigabyte…而非符号。ToFullWordsTests 同时验证了单复数ByteSize.FromBits(1).ToFullWords() // 1 bit ByteSize.FromBits(2).ToFullWords() // 2 bits ByteSize.FromBytes(1).ToFullWords() // 1 byte ByteSize.FromBytes(10).ToFullWords()// 10 bytes单复数与本地化词形由格式化器Configurator注册的文化格式化器提供因此切换CultureInfo即可得到对应语言的全称。解析Parse 与 TryParsepublic static ByteSize Parse(string s); public static ByteSize Parse(string s, IFormatProvider formatProvider); public static bool TryParse(string s, out ByteSize result); public static bool TryParse(string s, IFormatProvider formatProvider, out ByteSize result);解析输入形如1020KB、100.5MB数值部分按文化感知的NumberStyles允许小数点、千位分隔符、前导符号解析单位部分取 1~3 个字符并匹配B、KB、MB、GB、TB、b等符号失败时Parse抛出FormatExceptionTryParse返回false且result为default。文化支持是解析的核心能力ParsingTests 展示了de文化下2000,01KB、2.000,01KB都能正确解析为 2000.01 KB也支持自定义NumberFormatInfo如用_作小数分隔符、−作负号var numberFormat new NumberFormatInfo { NumberDecimalSeparator _, NumberGroupSeparator ;, NegativeSign −, }; ByteSize.TryParse(−2;000_01KB, numberFormat, out var result); // FromKilobytes(-2000.01)从 TryParse 源码 可以看到解析器会把文化的数字分隔符、千位分隔符与正负号收集为特殊字符集合来切分数字与单位因此多字符分隔符如阿拉伯文化的分隔符也能正确处理——TryParseWithArabicCulture测试ParsingTests验证了ar文化下0 b、100KB均能解析成功。无效输入的判定边界同样被测试固化ParsingTests空串、纯数字1000缺单位、KB缺数字、1000.5b部分位数为非法输入、1000KBB坏后缀均返回false而Parse对应抛出FormatException。典型用法速查using Humanizer; var size ByteSize.FromGigabytes(1.5); size.ToString(); // 1.5 GB size.ToString(0.00 MB); // 强制 MB1536.00 MB size.ToFullWords(); // 1.5 gigabytes size.AddMegabytes(512); // 新实例2048 MB size ByteSize.FromBytes(10); // 运算符等价于 Add ByteSize.Parse(1020KB); // 1020 KB ByteSize.TryParse(3.5 MB, out var parsed); // true, parsed FromMegabytes(3.5) var ordered new[] { size, ByteSize.FromKilobytes(3) } .OrderBy(x x); // IComparableByteSize关键事实依据索引内容证据位置接口声明与构造器src/Humanizer/Bytes/ByteSize.cs换算常量与单位符号src/Humanizer/Bytes/ByteSize.csFrom* 工厂方法src/Humanizer/Bytes/ByteSize.cs最大整数单位选择逻辑src/Humanizer/Bytes/ByteSize.cs格式化含单位 token 匹配src/Humanizer/Bytes/ByteSize.csAdd*/运算符实现src/Humanizer/Bytes/ByteSize.csTryParse/Parse 文化解析src/Humanizer/Bytes/ByteSize.cs构造/换算测试tests/Humanizer.Tests/Bytes/CreatingTests.cs格式化输出测试tests/Humanizer.Tests/Bytes/ToStringTests.cs、ToFullWordsTests.cs解析与测试矩阵tests/Humanizer.Tests/Bytes/ParsingTests.cs算术与边界测试tests/Humanizer.Tests/Bytes/ArithmeticTests.cs适用前提说明本文的 API 面以 Humanizer 2.13.14 版本站点文档为基准当前仓库主分支的ByteSize已扩展了 PB/EB、十进制 SI 与 IEC 二进制单位及Format/ParseWithUnitSystem等显式单位体系 API见 ByteSizeUnitSystem.cs 与 ByteSizeUnitSystemTests.cs且Legacy体系保持了本文所述既有行为。面向 2.13.14 版本使用时请以该版本文档列出的成员为准升级后新增 API 可按仓库当前源码继续查阅。赞分享开发工具【免费下载链接】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点击查看免费下载相关推荐如何快速入门ysoserial修改版10分钟掌握反序列化利用基础如何快速入门ysoserial修改版10分钟掌握反序列化利用基础 ysoserial修改版是一款专注于反序列化漏洞利用的工具通过优化 ysoserial.pHumanizer ByteSizeExtensions 深度解析从数值类型构建并人性化格式化 ByteSizeHumanizer ByteSizeExtensions 深度解析从数值类型构建并人性化格式化 ByteSize 本篇以 Humanizer 2.13.14开发工具如何使用Flume高性能多生产者多消费者通道的完整指南如何使用Flume高性能多生产者多消费者通道的完整指南 Flume是一个安全且快速的多生产者多消费者通道库专为Rust语言设计。它提供了高效的消息传递机制上一篇5个关键步骤在Windows 10/11上构建完整Android子系统从安装到优化的全面指南下一篇4步掌握PyAutoCAD从环境搭建到AutoCAD自动化全攻略创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考