2017 © Pedro Peláez
 

library byte-formatter

Formats byte values as human-readable strings.

image

scriptfusion/byte-formatter

Formats byte values as human-readable strings.

  • Saturday, February 4, 2017
  • by Bilge
  • Repository
  • 2 Watchers
  • 36 Stars
  • 15,241 Installations
  • PHP
  • 5 Dependents
  • 0 Suggesters
  • 0 Forks
  • 3 Open issues
  • 8 Versions
  • 6 % Grown

The README.md

ByteFormatter

Latest version Total downloads Build status Test coverage ![Code style][Style image], (*1)

ByteFormatter formats byte values as human-readable strings. An appropriate exponent is calculated automatically such that the value never exceeds the base. For example, in base 1024, format(1023) gives 1023 B but format(1024) gives 1 KiB instead of 1024 B., (*2)

Usage

By default, bytes are divided using Base::BINARY into multiples of 1024., (*3)

(new ByteFormatter)->format(0x80000);

512 KiB, (*4)

Bytes can be divided into multiples of 1000 by specifying Base::DECIMAL as the base., (*5)

(new ByteFormatter)->setBase(Base::DECIMAL)->format(500000);

500 KB, (*6)

Precision

By default, all values are rounded to the nearest integer., (*7)

(new ByteFormatter)->format(0x80233);

513 KiB, (*8)

Increasing the default precision with setPrecision() allows the specified number of digits after the decimal point., (*9)

(new ByteFormatter)->setPrecision(2)->format(0x80233);

512.55 KiB, (*10)

Increasing the precision will increase the maximum digits allowed but the formatter will only display as many as needed., (*11)

(new ByteFormatter)->setPrecision(2)->format(0x80200);

512.5 KiB, (*12)

Automatic precision scaling can be disabled if this behaviour is undesired., (*13)

(new ByteFormatter)->setPrecision(2)->disableAutomaticPrecision()->format(0x80200);

512.50 KiB, (*14)

The default precision can be overridden by passing the second argument to format()., (*15)

(new ByteFormatter)->setPrecision(2)->format(0x80233, 4);

512.5498 KiB, (*16)

Output format

The format can be changed by calling setFormat() which takes a string format parameter. The default format is '%v %u'. Occurrences of %v and %u in the format string will be replaced with the calculated value and units respectively., (*17)

(new ByteFormatter)->setFormat('%v%u')->format(0x80000);

512KiB, (*18)

Fixed exponent

One of the main benefits of the formatter is an appropriate exponent is calculated automatically, however it is also possible to fix the exponent to a specific value using setFixedExponent()., (*19)

(new ByteFormatter)->setFixedExponent(1)->format(1024 * 1024);

1024 KiB, (*20)

Normally we would expect the above example to output 1 MiB but because the exponent is locked to 1 the output will always be in KiB. Consult the following table to see how exponents map to symbols., (*21)

Exponent Symbol
0 B
1 K
2 M
3 G
4 T
5 P
6 E
7 Z
8 Y

Unit customization

Units are provided by decorators extending UnitDecorator. Two implementations are provided: the default SymbolDecorator and an optional NameDecorator., (*22)

Unit decorators receive the base of the formatter when asked to decorate a value so that different units can be returned for different bases. For example, the default decorator outputs KiB in base 1024 for 210 < bytes < 220 but outputs KB in base 1000 for 1000 < bytes < 1000000. This behaviour can be suppressed by callingSymbolDecorator::setSuffix() with the desired SymbolDecorator suffix constant to prevent units changing when the base is changed. Decorators also receive the exponent and scaled byte value., (*23)

Symbol decorator

SymbolDecorator is the default unit decorator and returns units like B, KB, MB, etc. The symbol's suffix can be changed using one of the class constants from the following table., (*24)

Constant B K M G T P E Z Y
SUFFIX_NONE K M G T P E Z Y
SUFFIX_METRIC B KB MB GB TB PB EB ZB YB
SUFFIX_IEC B KiB MiB GiB TiB PiB EiB ZiB YiB

The following example uses base 1024 but displays the metric suffix, like Windows Explorer., (*25)

(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_METRIC)))
    ->format(0x80000)

512 KB, (*26)

If you prefer terse notation the suffix may be removed with SUFFIX_NONE., (*27)

(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE)))
    ->format(0x80000)

512 K, (*28)

Note that no unit is displayed for bytes when the suffix is disabled. If this is undesired, byte units can be forced with SymbolDecorator::alwaysShowUnit()., (*29)

(new ByteFormatter(new SymbolDecorator(SymbolDecorator::SUFFIX_NONE)))
    ->format(512)

512, (*30)

(new ByteFormatter(
    (new SymbolDecorator(SymbolDecorator::SUFFIX_NONE))
        ->alwaysShowUnit()
))
    ->format(512)

512 B, (*31)

Name decorator

NameDecorator can be used to replace the default decorator and returns units like byte, kilobyte, megabyte, etc., (*32)

(new ByteFormatter(new NameDecorator))
    ->format(0x80000)

512 kibibytes, (*33)

Using decimal base:, (*34)

(new ByteFormatter(new NameDecorator))
    ->setBase(Base::DECIMAL)
    ->format(500000)

500 kilobytes, (*35)

Testing

This library is fully unit tested. Run the tests with composer test from the command line. All examples in this document can be found in DocumentationTest., (*36)

The Versions

04/02 2017

dev-master

9999999-dev

Formats byte values as human-readable strings.

  Sources   Download

MIT

The Requires

 

The Development Requires

by Avatar Bilge

04/01 2016

3.2.0

3.2.0.0

Formats byte values as human-readable strings.

  Sources   Download

MIT

The Requires

  • php >=5.5

 

The Development Requires

by Avatar Bilge

02/01 2016

3.1.1

3.1.1.0

Formats byte values as human-readable strings.

  Sources   Download

MIT

The Requires

  • php >=5.5

 

The Development Requires

by Avatar Bilge

01/01 2016

3.1.0

3.1.0.0

Formats byte values as human-readable strings.

  Sources   Download

MIT

The Requires

  • php >=5.5

 

The Development Requires

by Avatar Bilge

30/12 2015

3.0.0

3.0.0.0

Formats byte values as human-readable strings.

  Sources   Download

MIT

The Requires

  • php >=5.5

 

The Development Requires

by Avatar Bilge

28/12 2015

2.0.1

2.0.1.0

Formats byte values as human-readable strings.

  Sources   Download

MIT

The Requires

  • php >=5.5

 

The Development Requires

by Avatar Bilge

08/04 2014

2.0.0

2.0.0.0

Formats byte values as human-readable strings.

  Sources   Download

The Requires

  • php >=5.5

 

The Development Requires

by Avatar Bilge

08/04 2014

1.0.0

1.0.0.0

Formats byte values as human-readable strings.

  Sources   Download

The Requires

  • php >=5.5

 

The Development Requires

by Avatar Bilge