ByteSize 2.1.2

dotnet add package ByteSize --version 2.1.2
NuGet\Install-Package ByteSize -Version 2.1.2
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="ByteSize" Version="2.1.2" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add ByteSize --version 2.1.2
#r "nuget: ByteSize, 2.1.2"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install ByteSize as a Cake Addin
#addin nuget:?package=ByteSize&version=2.1.2

// Install ByteSize as a Cake Tool
#tool nuget:?package=ByteSize&version=2.1.2

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.

Stable nuget

Development

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 except netstandard1.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:

double maxFileSizeMBs = 1.5;

// I need it in KBs and KiBs!
var kilobytes = maxFileSizeMBs * 1000; // 1500
var kibibytes = maxFileSizeMBs * 1024; // 1536

With ByteSize:

var maxFileSize = ByteSize.FromMegaBytes(1.5);

// I have it in KBs and KiBs!!
maxFileSize.KiloBytes;  // 1500
maxFileSize.KibiBytes;  // 1464.84376

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

// Add
var monthlyUsage = ByteSize.FromGigaBytes(10);
var currentUsage = ByteSize.FromMegaBytes(512);
ByteSize total = monthlyUsage + currentUsage;

total.Add(ByteSize.FromKiloBytes(10));
total.AddGigaBytes(10);

// Subtract
var delta = total.Subtract(ByteSize.FromKiloBytes(10));
delta = delta - ByteSize.FromGigaBytes(100);
delta = delta.AddMegaBytes(-100);

// Multiple
var multiple = ByteSize.FromBytes(4) * ByteSize.FromBytes(2); // 8

// Divide
var divide = ByteSize.FromBytes(16) / ByteSize.FromBytes(8); // 2

Constructors

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

new ByteSize(15);            // Constructor takes in bits (long)
new ByteSize(1.5);           // ... or bytes (double)

// Static Constructors
ByteSize.FromBits(10);       // Same as constructor
ByteSize.FromBytes(1.5);     // Same as constructor

// Decimal: 1 KB = 1000 B
ByteSize.FromKiloBytes(1.5);
ByteSize.FromMegaBytes(1.5);
ByteSize.FromGigaBytes(1.5);
ByteSize.FromTeraBytes(1.5);

// Binary: 1 KiB = 1024 B
ByteSize.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
var maxFileSize = ByteSize.FromKiloBytes(10);

maxFileSize.Bits;      // 80000
maxFileSize.Bytes;     // 10000

// Decimal
maxFileSize.KiloBytes; // 10
maxFileSize.MegaBytes; // 0.01
maxFileSize.GigaBytes; // 1E-05
maxFileSize.TeraBytes; // 1E-08

// Binary
maxFileSize.KibiBytes; // 9.765625
maxFileSize.MebiBytes; // 0.0095367431640625
maxFileSize.GibiBytes; // 9.31322574615479E-06
maxFileSize.TebiBytes; // 9.09494701772928E-09

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

var maxFileSize = ByteSize.FromKiloBytes(10);

maxFileSize.LargestWholeNumberDecimalSymbol; // "KB"
maxFileSize.LargestWholeNumberDecimalValue;  // 10
maxFileSize.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 used
ByteSize.FromBits(7).ToString();         // 7 b
ByteSize.FromBits(8).ToString();         // 1 B
ByteSize.FromKiloBytes(.5).ToString();   // 500 B
ByteSize.FromKiloBytes(999).ToString();  // 999 KB
ByteSize.FromKiloBytes(1000).ToString(); // 1 MB
ByteSize.FromGigabytes(.5).ToString();   // 500 MB
ByteSize.FromGigabytes(1000).ToString(); // 1 TB

// Binary
ByteSize.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.

var b = ByteSize.FromKiloBytes(10.505);

// Default number format is 0.##
b.ToString("KB");         // 10.52 KB
b.ToString("MB");         // .01 MB
b.ToString("b");          // 86057 b

// Default symbol is the largest metric prefix value >= 1
b.ToString("#.#");        // 10.5 KB

// All valid values of double.ToString(string format) are acceptable
b.ToString("0.0000");     // 10.5050 KB
b.ToString("000.00");     // 010.51 KB

// You can include number format and symbols
b.ToString("#.#### MB");  // .0103 MB
b.ToString("0.00 GB");    // 0 GB
b.ToString("#.## B");     // 10757.12 B

// ByteSize object of value 0
var zeroBytes = ByteSize.FromKiloBytes(0); 
zeroBytes.ToString();           // 0 b
zeroBytes.ToString("0 kb");     // 0 kb
zeroBytes.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.

ByteSize output;
ByteSize.TryParse("1.5mb", out output);
ByteSize.TryParse("1.5mib", out output);

// Invalid
ByteSize.Parse("1.5 b");   // Can't have partial bits

// Valid
ByteSize.Parse("5b");
ByteSize.Parse("1.55B");
ByteSize.Parse("1.55KB");
ByteSize.Parse("1.55 kB "); // Spaces are trimmed
ByteSize.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).

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 was computed.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard1.0 is compatible.  netstandard1.1 was computed.  netstandard1.2 was computed.  netstandard1.3 was computed.  netstandard1.4 was computed.  netstandard1.5 was computed.  netstandard1.6 was computed.  netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net45 is compatible.  net451 was computed.  net452 was computed.  net46 was computed.  net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Universal Windows Platform uap was computed.  uap10.0 was computed. 
Windows Phone wp8 was computed.  wp81 was computed.  wpa81 was computed. 
Windows Store netcore was computed.  netcore45 was computed.  netcore451 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (21)

Showing the top 5 NuGet packages that depend on ByteSize:

Package Downloads
FenixAlliance.ACL.Dependencies

Application Component for the Alliance Business Suite.

Zen.Base

A fluid, seamless middleware.

Sucrose.Orleans.Persistence.Redis

Package Description

Relativity.Transfer.SDK

Relativity Transfer SDK allows performing high-throughput transfers of files from and to Relativity environment.

HASS.Agent.Shared

Shared functions and models for the HASS.Agent platform.

GitHub repositories (28)

Showing the top 5 popular GitHub repositories that depend on ByteSize:

Repository Stars
files-community/Files
Building the best file manager for Windows
jenius-apps/ambie
An app that uses white noise, nature sounds, and focus features to boost your productivity.
PixiEditor/PixiEditor
PixiEditor is a lightweight pixel art editor made with .NET 7
ProtonVPN/win-app
Official ProtonVPN Windows app
WOA-Project/WOA-Deployer-Rpi
WOA Deployer for Raspberry Pi
Version Downloads Last updated
2.1.2 261,485 1/14/2024
2.1.1 2,724,673 11/6/2021
2.1.0 5,030,520 9/3/2021
2.0.0 1,105,351 1/14/2020
1.3.0 600,737 1/22/2017
1.2.5 1,270 1/21/2017
1.2.4 3,345 11/25/2016
1.2.3 7,387 11/10/2016
1.2.2 1,685 10/28/2016
1.2.1 20,895 7/23/2016
1.2.0 2,333 6/18/2016
1.1.3 1,589 6/18/2016
1.1.2 3,346 3/22/2016
1.1.1 2,735 12/13/2015
1.1.0 17,991 8/20/2015
1.0.0 6,164 5/30/2015

- Add strong name support

View all release notes at https://github.com/omar/ByteSize/blob/master/CHANGELOG.md.