ByteSize

ByteSize is a utility class that makes byte size representation in code easier by removing ambiguity of the value being represented.

ByteSize is to bytes what System.TimeSpan is to time.

Development

• Install .NET Core SDK
• Build: dotnet build
• Test: dotnet test

v2 Breaking Changes

Ratio Changes (HUGE BREAKING CHANGE)

By default ByteSize now assumes 1 KB == 1000 B and 1 KiB == 1024 B to adhere to the IEC and NIST standards (https://en.wikipedia.org/wiki/Binary_prefix). In version 1 ByteSize assumed 1 KB == 1024 B, that means if you're upgrading from v1, you'll see differences in values.

When you upgrade an existing application to v2 your existing code will be using the decimal representation of bytes (i.e. 1 KB == 1000 B). If the difference in calculation is not material to your application, you don't need to change anything.

However, if you want to use 1 KiB == 1024 B, then you'll need to change all ByteSize calls to the respective method. For example, calls to ByteSize.FromKiloByte need to be changed to ByteSize.FromKibiByte.

Lastly, ByteSize no longer supports the ratio of 1 KB == 1024 B. Note this is kilobytes to bytes. The only ratio of 1 == 1024 is kibibytes to bytes.

Other Breaking Changes

• Renamed property LargestWholeNumberSymbol and LargestWholeNumberValue to LargestWholeNumberDecimalSymbol and LargestWholeNumberDecimalValue respectively.
• Drop support for all platforms exceptnetstandard1.0 and net45.

Usage

ByteSize adheres to the IEC standard, see this Wikipedia article. That means ByteSize assumes:

• Decimal representation: 1 kilobyte = 1000 bytes with 2 letter abbrevations b, B,KB, MB, GB, TB, PB.
• Binary representation: 1 kibibyte = 1024 bytes with 3 letter abbrevations b, B,KiB, MiB, GiB, TiB, PiB.

ByteSize manages conversion of the values internally and provides methods to create and retrieve the values as needed. See the examples below.

Example

Without ByteSize:

doublemaxFileSizeMBs=1.5;// I need it in KBs and KiBs!varkilobytes=maxFileSizeMBs*1000;// 1500varkibibytes=maxFileSizeMBs*1024;// 1536

With ByteSize:

varmaxFileSize=ByteSize.FromMegaBytes(1.5);// I have it in KBs and KiBs!!maxFileSize.KiloBytes;// 1500maxFileSize.KibiBytes;// 1464.84376

ByteSize behaves like any other struct backed by a numerical value allowing arithmetic operations between two objects.

// AddvarmonthlyUsage=ByteSize.FromGigaBytes(10);varcurrentUsage=ByteSize.FromMegaBytes(512);ByteSizetotal=monthlyUsage+currentUsage;total.Add(ByteSize.FromKiloBytes(10));total.AddGigaBytes(10);// Subtractvardelta=total.Subtract(ByteSize.FromKiloBytes(10));delta=delta-ByteSize.FromGigaBytes(100);delta=delta.AddMegaBytes(-100);// Multiplevarmultiple=ByteSize.FromBytes(4)*ByteSize.FromBytes(2);// 8// Dividevardivide=ByteSize.FromBytes(16)/ByteSize.FromBytes(8);// 2

Constructors

You can create a ByteSize object from bits, bytes, kilobytes, megabytes, gigabytes, and terabytes.

newByteSize(15);// Constructor takes in bits (long)newByteSize(1.5);// ... or bytes (double)// Static ConstructorsByteSize.FromBits(10);// Same as constructorByteSize.FromBytes(1.5);// Same as constructor// Decimal: 1 KB = 1000 BByteSize.FromKiloBytes(1.5);ByteSize.FromMegaBytes(1.5);ByteSize.FromGigaBytes(1.5);ByteSize.FromTeraBytes(1.5);// Binary: 1 KiB = 1024 BByteSize.FromKibiBytes(1.5);ByteSize.FromMebiBytes(1.5);ByteSize.FromGibiBytes(1.5);ByteSize.FromTebiBytes(1.5);

Properties

A ByteSize object contains representations in:

• bits, bytes
• kilobytes, megabytes, gigabytes, and terabytes
• kibibytes, mebibytes, gibibytes, and tebibytes

varmaxFileSize=ByteSize.FromKiloBytes(10);maxFileSize.Bits;// 80000maxFileSize.Bytes;// 10000// DecimalmaxFileSize.KiloBytes;// 10maxFileSize.MegaBytes;// 0.01maxFileSize.GigaBytes;// 1E-05maxFileSize.TeraBytes;// 1E-08// BinarymaxFileSize.KibiBytes;// 9.765625maxFileSize.MebiBytes;// 0.0095367431640625maxFileSize.GibiBytes;// 9.31322574615479E-06maxFileSize.TebiBytes;// 9.09494701772928E-09

A ByteSize object also contains four properties that represent the largest whole number symbol and value.

varmaxFileSize=ByteSize.FromKiloBytes(10);maxFileSize.LargestWholeNumberDecimalSymbol;// "KB"maxFileSize.LargestWholeNumberDecimalValue;// 10maxFileSize.LargestWholeNumberBinarySymbol;// "KiB"maxFileSize.LargestWholeNumberBinaryValue;// 9.765625

String Representation

By default a ByteSize object uses the decimal value for string representation.

All string operations are localized to use the number decimal separator of the culture set in Thread.CurrentThread.CurrentCulture.

ToString

ByteSize comes with a handy ToString method that uses the largest metric prefix whose value is greater than or equal to 1.

// By default the decimal values are usedByteSize.FromBits(7).ToString();// 7 bByteSize.FromBits(8).ToString();// 1 BByteSize.FromKiloBytes(.5).ToString();// 500 BByteSize.FromKiloBytes(999).ToString();// 999 KBByteSize.FromKiloBytes(1000).ToString();// 1 MBByteSize.FromGigabytes(.5).ToString();// 500 MBByteSize.FromGigabytes(1000).ToString();// 1 TB// BinaryByteSize.Parse("1.55 kb").ToString("kib");// 1.51 kib

Formatting

The ToString method accepts a single string parameter to format the output. The formatter can contain the symbol of the value to display.

• Base: b, B
• Decimal: KB, MB, GB, TB
• Binary: KiB, MiB, GiB, TiB

The formatter uses the built in double.ToString method.

The default number format is 0.## which rounds the number to two decimal places and outputs only 0 if the value is 0.

You can include symbol and number formats.

varb=ByteSize.FromKiloBytes(10.505);// Default number format is 0.##b.ToString("KB");// 10.52 KBb.ToString("MB");// .01 MBb.ToString("b");// 86057 b// Default symbol is the largest metric prefix value >= 1b.ToString("#.#");// 10.5 KB// All valid values of double.ToString(string format) are acceptableb.ToString("0.0000");// 10.5050 KBb.ToString("000.00");// 010.51 KB// You can include number format and symbolsb.ToString("#.#### MB");// .0103 MBb.ToString("0.00 GB");// 0 GBb.ToString("#.## B");// 10757.12 B// ByteSize object of value 0varzeroBytes=ByteSize.FromKiloBytes(0);zeroBytes.ToString();// 0 bzeroBytes.ToString("0 kb");// 0 kbzeroBytes.ToString("0.## mb");// 0 mb

Parsing

ByteSize has a Parse and TryParse method similar to other base classes.

Like other TryParse methods, ByteSize.TryParse returns boolean value indicating whether or not the parsing was successful. If the value is parsed it is output to the out parameter supplied.

ByteSizeoutput;ByteSize.TryParse("1.5mb",outoutput);ByteSize.TryParse("1.5mib",outoutput);// InvalidByteSize.Parse("1.5 b");// Can't have partial bits// ValidByteSize.Parse("5b");ByteSize.Parse("1.55B");ByteSize.Parse("1.55KB");ByteSize.Parse("1.55 kB ");// Spaces are trimmedByteSize.Parse("1.55 kb");ByteSize.Parse("1.55 MB");ByteSize.Parse("1.55 mB");ByteSize.Parse("1.55 mb");ByteSize.Parse("1.55 GB");ByteSize.Parse("1.55 gB");ByteSize.Parse("1.55 gib");ByteSize.Parse("1.55 TiB");ByteSize.Parse("1.55 tiB");ByteSize.Parse("1.55 tib");ByteSize.Parse("1,55 kib");// de-DE culture

Author and License

Omar Khudeira (http://omar.io)

Copyright (c) 2013-2022 Omar Khudeira. All rights reserved.

Released under MIT License (see LICENSE file).