💾💿 DataSizeUnits

Convert and format data size units (bits, bytes, kilobits, kilobytes, and others).

Installation

This is a .NET Standard 2.0 library, and can be depended upon in projects which target at least .NET 5, .NET Core 2.0, or .NET Framework 4.6.1.

dotnet package add DataSizeUnits

Features

• Convert between many units of digital information, including bits, bytes, and their higher-order units (kilobits and kilobytes and the rest, up to and including quettabits and quettabytes)

  • 150 Mbit → 17.8 MByte

    double sizeInMegabytes = new DataSize(150, DataSizeUnit.Megabit).AsUnit(DataSizeUnit.Megabyte);
    // sizeInMegabytes == 17.8

  • 1 MB → 1024 kB

    // if you want to convert to a smaller unit with an integral quantity, AsUnitExact avoids floating-point imprecision
    BigInteger kilobytesIn1Megabyte = new DataSize(1, DataSizeUnit.Megabyte).AsUnitExact(DataSizeUnit.Kilobyte);
    // kilobytesIn1Megabyte = 1024

• Normalize a number of bytes to an automatically-selected unit based on its magnitude

  • 2,097,152 bytes → 2 MB

    (double quantity, DataSizeUnit unit) normalized = new DataSize(2_097_152).AsAutomaticUnit();
    // normalized.quantity == 2.0
    // normalized.unit == DataSizeUnit.Megabyte

  • 2,097,152 bytes → 16.78 mbit

    normalized = new DataSize(2_097_152).AsAutomaticUnit(true); // pass true to get bits units instead of bytes
    // normalized.quantity == 16.78
    // normalized.unit == DataSizeUnit.Megabit

  • The unit will be automatically selected so the value is greater than or equal to 1 of that unit, and less than 1 of the next largest unit. For example, 2,097,152 bytes is greater than or equal to 1 MB and less than 1 GB, so it is normalized to 2 MB.

• Parse data sizes

  • 1.5 MB → 1,572,864 bytes

    DataSize parsed = DataSize.Parse("1.5 MB");
    // parsed.Bytes == 1572864

• Parse and format unit names and abbreviations

  • Megabyte, MByte, mebibyte, MiB, MB, and M are all megabytes

    DataSizeUnit? unit = DataSizeUnit.Parse("MB");
    // unit == DataSizeUnit.Megabyte

  • Abbreviations for each unit are of the short, case-sensitive forms.

    string abbreviation = DataSizeUnit.Terabyte.ToAbbreviation();
    // abbreviation == "TB"

    string iecAbbreviation = DataSizeUnit.Terabyte.ToAbbreviation(true); // pass true for the IEC abbreviations (kibibyte, etc.)
    // iecAbbreviation == "TiB"

  • Get the unit names in JEDEC (TB) or IEC (TiB) variants.

    string name = DataSizeUnit.Terabyte.ToName();
    // name == "terabyte"

    string iecName = DataSizeUnit.Terabyte.ToName(true); // pass true for the IEC names (kibibyte, etc.)
    // iecName == "tebibyte"

• Format bytes as a string with different unit and precision options

  • Automatic precision from culture, automatic byte-based unit

    string formatted = new DataSize(1572864).ToString();
    // formatted == "1.50 MB"

  • Automatic precision, manual unit

    formatted = new DataSize(1572864).ToString(DataSizeUnit.Kilobyte);
    // formatted == "1,536.00 kB"

  • Manual precision, automatic unit

    formatted = new DataSize(1572864).ToString(1);
    // formatted == "1.5 MB"

  • Automatic precision, automatic bit-based unit

    formatted = new DataSize(1572864).ToString(true);
    // formatted == "12.58 mb"

• Serialize and deserialize to and from bits

  • JSON (System.Text.Json or Newtonsoft.Json)

    { "filename": "example.txt", "size": 8192 }

  • XML (XmlSerializer)

    <?xml version="1.0" encoding="utf-8"?>
    <MyFile>
        <Filename>example.txt</Filename>
        <Size bits="8192" />
    </MyFile>

Migration

You can read the Migration article in the repository wiki to learn about breaking changes between major version upgrades.