Added significant figure formatting.

Author: Bilge

.github/workflows/Tests.yaml

@@ -3,6 +3,7 @@ name: Tests
 on:
   push:
   pull_request:
+  workflow_dispatch:
   schedule:
     - cron: 0 6 * * *
 

README.md

@@ -45,8 +45,7 @@ Increasing the default precision with `setPrecision()` allows the specified numb
 ```
 > 512.55 KiB
 
-Increasing the precision will increase the maximum digits allowed but the formatter will only display as many as
-needed.
+Increasing the precision will increase the maximum digits allowed, but the formatter will only display as many as needed.
 
 ```php
 (new ByteFormatter)->setPrecision(2)->format(0x80200);
@@ -67,6 +66,28 @@ The default precision can be overridden by passing the second argument to `forma
 ```
 > 512.5498 KiB
 
+Significant figures
+-------------------
+
+Formatting by the specified number of significant figures by calling `setSignificantFigures()`. This is mutually exclusive with precision scaling such that whichever method is called last will be used.
+
+```php
+(new ByteFormatter)->setBase(Base::DECIMAL)->setSignificantFigures(2)->format(123);
+```
+> 120
+
+```php
+(new ByteFormatter)->setBase(Base::DECIMAL)->setSignificantFigures(2)->format(1234);
+```
+> 1.2K
+
+```php
+(new ByteFormatter)->setBase(Base::DECIMAL)->setSignificantFigures(3)->format(1234);
+```
+> 1.23K
+
+This is particularly useful for keeping the display width of formatted numbers predicable.
+
 Output format
 -------------
 

src/Byte/ByteFormatter.php

@@ -21,6 +21,8 @@ class ByteFormatter
 
     private ?int $exponent = null;
 
+    private ?int $significantFigures = null;
+
     private UnitDecorator $unitDecorator;
 
     /**
@@ -52,26 +54,49 @@ public function format(int|float $bytes, ?int $precision = null): string
 
         $log = log($bytes, $this->getBase());
         $exponent = $this->hasFixedExponent() ? $this->getFixedExponent() : max(0, (int)$log);
-        $value = round($this->getBase() ** ($log - $exponent), $precision);
+        $rawValue = $this->getBase() ** ($log - $exponent);
+        $value = $this->significantFigures ? $this->roundToSignificantFigures($rawValue) : round($rawValue, $precision);
         $units = $this->getUnitDecorator()->decorate($exponent, $this->getBase(), $value);
 
         return trim(sprintf($this->sprintfFormat, $this->formatValue($value, $precision), $units));
     }
 
     /**
-     * Formats the specified number with the specified precision.
+     * Rounds the specified value to the number of significant figures defined for this instance.
+     *
+     * @param float $value Value.
+     *
+     * @return float Rounded value.
+     */
+    private function roundToSignificantFigures(float $value): float
+    {
+        if ($value === 0.) {
+            return 0.;
+        }
+
+        $factor = 10 ** ($this->significantFigures - floor(log10(abs($value))) - 1);
+
+        return round($value * $factor) / $factor;
+    }
+
+    /**
+     * Formats the specified number with the specified precision or significant figures.
      *
-     * If precision scaling is enabled the precision may be reduced when it
-     * contains insignificant digits. If the fractional part is zero it will
+     * If precision scaling is enabled, the precision may be reduced when it
+     * contains insignificant digits. If the fractional part is zero, it will
      * be completely removed.
      *
      * @param float $value Number.
-     * @param int $precision Number of fractional digits.
+     * @param int $precision Number of fractional digits. Ignored when significant figures are set.
      *
      * @return string Formatted number.
      */
     private function formatValue(float $value, int $precision): string
     {
+        if ($this->significantFigures !== null) {
+            return (string)$value;
+        }
+
         $formatted = sprintf("%0.{$precision}F", $value);
 
         if ($this->hasAutomaticPrecision()) {
@@ -115,7 +140,7 @@ public function getBase(): int
     }
 
     /**
-     * Sets the exponentiation base which should usually be a Base constant.
+     * Sets the exponentiation base, which should usually be a Base constant.
      *
      * @param int $base Exponentiation base.
      *
@@ -166,13 +191,14 @@ public function getPrecision(): int
     /**
      * Sets the maximum number of fractional digits.
      *
-     * @param int $precision
+     * @param int $precision Fractional digits.
      *
      * @return $this
      */
     public function setPrecision(int $precision): self
     {
         $this->precision = $precision;
+        $this->significantFigures = null;
 
         return $this;
     }
@@ -204,8 +230,7 @@ public function disableAutomaticPrecision(): self
     /**
      * Gets a value indicating whether precision will be scaled automatically.
      *
-     * @return bool True if precision will be scaled automatically, otherwise
-     *     false.
+     * @return bool True if precision is scaled automatically, otherwise false.
      */
     public function hasAutomaticPrecision(): bool
     {
@@ -258,6 +283,18 @@ public function hasFixedExponent(): bool
         return $this->exponent !== null;
     }
 
+    /**
+     * Sets the number of significant figures.
+     *
+     * @param int $significantFigures Number of significant figures.
+     */
+    public function setSignificantFigures(int $significantFigures): self
+    {
+        $this->significantFigures = $significantFigures;
+
+        return $this;
+    }
+
     /**
      * Gets the unit decorator.
      *

test/Integration/Byte/ByteFormatterTest.php

@@ -177,4 +177,77 @@ public function testCustomUnitSequence(): void
 
         self::assertSame('1 foo', $formatter->format(1));
     }
+
+    /** @dataProvider provideSignificantFigures */
+    public function testSignificantFigures(int $significantFigures, int $in, string $out): void
+    {
+        $formatter = $this->formatter->setBase(Base::DECIMAL)->setSignificantFigures($significantFigures);
+
+        self::assertSame($out, $formatter->format($in));
+    }
+
+    public static function provideSignificantFigures(): iterable
+    {
+        return [
+            // Small numbers.
+            [1, 1, '1'],
+            [2, 1, '1'],
+            [1, 12, '10'],
+            [2, 12, '12'],
+            [3, 12, '12'],
+            [1, 123, '100'],
+            [2, 123, '120'],
+            [3, 123, '123'],
+
+            // Thousands.
+            [1, 1_234, '1K'],
+            [2, 1_234, '1.2K'],
+            [3, 1_234, '1.23K'],
+            [4, 1_234, '1.234K'],
+
+            [1, 12_345, '10K'],
+            [2, 12_345, '12K'],
+            [3, 12_345, '12.3K'],
+            [4, 12_345, '12.35K'],
+            [5, 12_345, '12.345K'],
+
+            // Millions.
+            [1, 1_234_567, '1M'],
+            [2, 1_234_567, '1.2M'],
+            [3, 1_234_567, '1.23M'],
+            [4, 1_234_567, '1.235M'],
+            [7, 1_234_567, '1.234567M'],
+
+            // Billions.
+            [1, 12_345_678_901, '10G'],
+            [2, 12_345_678_901, '12G'],
+            [3, 12_345_678_901, '12.3G'],
+            [4, 12_345_678_901, '12.35G'],
+
+            // Trillions.
+            [1, 1_234_567_890_123, '1T'],
+            [2, 1_234_567_890_123, '1.2T'],
+            [3, 1_234_567_890_123, '1.23T'],
+            [4, 1_234_567_890_123, '1.235T'],
+
+            // Quadrillions.
+            [1, 1_234_567_890_123_456, '1P'],
+            [2, 1_234_567_890_123_456, '1.2P'],
+            [3, 1_234_567_890_123_456, '1.23P'],
+            [4, 1_234_567_890_123_456, '1.235P'],
+
+            // PHP_INT_MAX boundary case.
+            [1, 9_223_372_036_854_775_807, '9E'],
+            [2, 9_223_372_036_854_775_807, '9.2E'],
+            [3, 9_223_372_036_854_775_807, '9.22E'],
+            [4, 9_223_372_036_854_775_807, '9.223E'],
+        ];
+    }
+
+    public function testClearingSigFigFallsBackToPrecision(): void
+    {
+        $formatter = $this->formatter->setBase(Base::DECIMAL)->setSignificantFigures(3)->setPrecision(2);
+
+        self::assertSame('908.61K', $formatter->format(908_614));
+    }
 }