Changed byte unit sequences into collections that inherit from ByteUnitCollection.

Removed Sequence namespace and classes.

Author: Bilge

README.md

@@ -58,13 +58,13 @@ The format can be changed by calling the `setFormat($format)` function which tak
 
 Customizing units
 -----------------
-Units are generated by sequence generators. The current unit sequence generator instance can be retrieved from `ByteFormatter::getUnitSequence()`.
+Units are provided by collections that extend `ByteUnitCollection`. The current unit collection instance can be retrieved from `ByteFormatter::getUnitCollection()`.
 
-Sequence generators are notified of base changes in the formatter so that different units can be generated for different bases. For example, the default generator outputs `KiB` in base 1024 for *2<sup>10</sup> < bytes < 2<sup>20</sup>* but outputs `KB` in base 1000 for *1000 < bytes < 1000000*. This behaviour can be suppressed by calling `disableAutomaticUnitSwitching(true)` to prevent units changing when the base is changed.
+Unit collections are notified of base changes in the formatter so that different units can be returned for different bases. For example, the default collection outputs `KiB` in base 1024 for *2<sup>10</sup> < bytes < 2<sup>20</sup>* but outputs `KB` in base 1000 for *1000 < bytes < 1000000*. This behaviour can be suppressed by calling `disableAutomaticUnitSwitching(true)` to prevent units changing when the base is changed.
 
-### Byte unit symbol sequence
+### Symbol collection
 
-`ByteUnitSymbolSequence` is the default unit sequence and generates units like *B*, *KB*, *MB*, etc. The symbol's suffix can be changed according to one of the constants from the following table.
+`ByteUnitSymbolCollection` is the default unit collection 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.
 
 | Constant      | B |  K  |  M  |  G  |  T  |  P  |  E  |  Z  |  Y  |
 |---------------|:-:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
@@ -77,7 +77,7 @@ The following example uses base 1024 but displays the metric suffix, like Window
 ```php
 (new ByteFormatter)
     ->setBase(Base::BINARY)
-    ->setUnitSymbolSuffix(ByteUnitSymbolSequence::SUFFIX_METRIC)
+    ->setUnitSymbolSuffix(ByteUnitSymbolCollection::SUFFIX_METRIC)
     ->format(0x80000);
 ```
 > 512 KB
@@ -86,32 +86,32 @@ If you prefer terse notation the suffix may be removed with `SUFFIX_NONE`.
 
 ```php
 (new ByteFormatter)
-    ->setUnitSymbolSuffix(ByteUnitSymbolSequence::SUFFIX_NONE)
+    ->setUnitSymbolSuffix(ByteUnitSymbolCollection::SUFFIX_NONE)
     ->format(0x80000);
 ```
 > 512 K
 
-Note that no unit is displayed for bytes when the suffix is disabled. If this is undesired, byte units can be forced with `ByteUnitSymbolSequence::alwaysShowUnit()`.
+Note that no unit is displayed for bytes when the suffix is disabled. If this is undesired, byte units can be forced with `ByteUnitSymbolCollection::alwaysShowUnit()`.
 
 ```php
 $formatter = (new ByteFormatter)
-    ->setUnitSymbolSuffix(ByteUnitSymbolSequence::SUFFIX_NONE)
+    ->setUnitSymbolSuffix(ByteUnitSymbolCollection::SUFFIX_NONE)
     ->format(512);
 ```
 > 512
 
 ```php
-$formatter->getUnitSequence()->alwaysShowUnit();
+$formatter->getUnitCollection()->alwaysShowUnit();
 $formatter->format(512);
 ```
 > 512 B
 
-### Byte unit name sequence
-`ByteUnitNameSequence` can be used to replace the default unit sequence generator and generates units like *byte*, *kilobyte*, *megabyte*, etc.
+### Name collection
+`ByteUnitNameCollection` can be used to replace the default collection and returns units like *byte*, *kilobyte*, *megabyte*, etc.
 
 ```php
 (new ByteFormatter)
-    ->setUnitSequence(new ByteUnitNameSequence)
+    ->setUnitCollection(new ByteUnitNameCollection)
     ->format(0x80000);
 ```
 > 512 kibibytes
@@ -120,7 +120,7 @@ Using decimal base:
 
 ```php
 (new ByteFormatter)
-    ->setUnitSequence(new ByteUnitNameSequence)
+    ->setUnitCollection(new ByteUnitNameCollection)
     ->setBase(Base::DECIMAL)
     ->format(500000);
 ```

composer.lock

@@ -1,8 +1,6 @@
 <?php
 namespace ScriptFUSION\Byte;
 
-use ScriptFUSION\Sequence\FiniteSequence;
-
 /**
  * Formats byte values as human-readable strings.
  */
@@ -16,7 +14,7 @@ class ByteFormatter implements BaseAware {
 
     private
         $normalizedFormat,
-        $unitSequence
+        $unitCollection
     ;
 
     public function __construct($precision = 0, $base = Base::BINARY, $format = '%v %u') {
@@ -27,24 +25,31 @@ public function format($bytes) {
         $log = log($bytes, $this->base);
         $scale = max(0, $log|0);
         $value = round(pow($this->base, $log - $scale), $this->precision);
-        $units = $this->getUnitSequence()->getSequenceIndex($scale);
+        $units = $this->getUnits($value, $scale);
 
         return sprintf($this->normalizedFormat, $value, $units);
     }
 
+    protected function getUnits($value, $scale) {
+        $collection = $this->getUnitCollection();
+        $collection instanceof ValueAware && $collection->setValue($value);
+
+        return $collection[$scale];
+    }
+
     private function normalizeFormat($format) {
         return str_replace(['%v', '%u'], ['%1$s', '%2$s'], $format);
     }
 
     /**
-     * Notifies the unit sequence of base changes.
+     * Notifies the unit collection of base changes.
      *
      * @param int $base Numeric base.
      */
     private function notifyBaseChanged($base) {
         $this->automaticUnitSwitching
-            && ($seq = $this->getUnitSequence()) instanceof BaseAware
-            && $seq->setBase($base);
+            && ($collection = $this->getUnitCollection()) instanceof BaseAware
+            && $collection->setBase($base);
     }
 
     public function getBase() {
@@ -74,34 +79,34 @@ public function setPrecision($precision) {
         return $this;
     }
 
-    public function getUnitSequence() {
-        return $this->unitSequence ?: $this->unitSequence = new ByteUnitSymbolSequence;
+    public function getUnitCollection() {
+        return $this->unitCollection ?: $this->unitCollection = new ByteUnitSymbolCollection;
     }
-    public function setUnitSequence(FiniteSequence $sequence) {
-        $this->unitSequence = $sequence;
+    public function setUnitCollection(ByteUnitCollection $collection) {
+        $this->unitCollection = $collection;
 
-        //Notify new sequence of current base.
+        //Notify new collection of current base.
         $this->notifyBaseChanged($this->base);
 
         return $this;
     }
 
     /**
      * Sets the unit symbol suffix to the specified value.
-     * This is a shortcut method for interfacing with the default unit sequence generator and cannot be used if the
-     * default generator has been replaced with a non-derived object.
+     * This is a shortcut method for interfacing with the default unit collection and cannot be used if the default
+     * collection has been replaced with a non-derived object.
      *
      * @param string $suffix Unit symbol suffix. Defaults to no suffix.
      * @return $this
-     * @throws \BadFunctionCallException when unit sequence is not an instance of ByteUnitSymbolSequence.
+     * @throws \BadFunctionCallException when unit collection is not an instance of ByteUnitSymbolCollection.
      */
-    public function setUnitSymbolSuffix($suffix = ByteUnitSymbolSequence::SUFFIX_NONE) {
-        if (!($seq = $this->getUnitSequence()) instanceof ByteUnitSymbolSequence)
+    public function setUnitSymbolSuffix($suffix = ByteUnitSymbolCollection::SUFFIX_NONE) {
+        if (!($collection = $this->getUnitCollection()) instanceof ByteUnitSymbolCollection)
             throw new \BadFunctionCallException(
-                'Cannot set suffix: unit sequence not instance of ByteUnitSymbolSequence.'
+                'Cannot set suffix: unit collection not instance of ByteUnitSymbolCollection.'
             );
 
-        $seq->setSuffix($suffix);
+        $collection->setSuffix($suffix);
 
         return $this;
     }

src/Byte/ByteFormatter.php

@@ -0,0 +1,28 @@
+<?php
+namespace ScriptFUSION\Byte;
+
+/**
+ * Provides a collection of byte units.
+ */
+abstract class ByteUnitCollection implements \Countable, \ArrayAccess, \IteratorAggregate {
+    public function count() {
+        return 9;
+    }
+
+    public function offsetExists($offset) {
+        return $offset > 0 && $offset < count($this);
+    }
+
+    public function offsetSet($offset, $value) {
+        throw new \BadFunctionCallException('Collection is read-only.');
+    }
+
+    public function offsetUnset($offset) {
+        throw new \BadFunctionCallException('Collection is read-only.');
+    }
+
+    public function getIterator() {
+        for ($i = 0; $i < count($this); ++$i)
+            yield $this[$i];
+    }
+}

src/Byte/ByteUnitCollection.php

@@ -0,0 +1,41 @@
+<?php
+namespace ScriptFUSION\Byte;
+
+/**
+ * Provides a collection of byte unit names.
+ */
+class ByteUnitNameCollection extends ByteUnitCollection implements BaseAware, ValueAware {
+    private
+        $base,
+        $value
+    ;
+
+    protected static $sequences = [
+        Base::BINARY => [ 'kibi', 'mebi', 'gibi', 'tebi', 'pebi', 'exbi', 'zebi', 'yobi' ],
+        Base::DECIMAL => [ 'kilo', 'mega', 'giga', 'tera', 'peta', 'exa', 'zetta', 'yotta' ],
+    ];
+
+    public function __construct($base = Base::BINARY) {
+        $this->setBase($base);
+    }
+
+    public function offsetGet($offset) {
+        $suffix = $this->value == 1 ? 'byte' : 'bytes';
+
+        if (!$offset) return $suffix;
+
+        return static::$sequences[$this->base][--$offset] . $suffix;
+    }
+
+    public function setBase($base) {
+        $this->base = +$base;
+
+        return $this;
+    }
+
+    function setValue($value) {
+        $this->value = +$value;
+
+        return $this;
+    }
+}

src/Byte/ByteUnitNameCollection.php

@@ -1,15 +1,13 @@
 <?php
 namespace ScriptFUSION\Byte;
 
-use ScriptFUSION\Sequence\FiniteSequence;
-
 /**
- * Provides a sequence of byte unit symbols from least to most significant.
+ * Provides a collection of byte unit symbols.
  */
-class ByteUnitSymbolSequence extends FiniteSequence implements BaseAware {
-    protected static $prefixes = 'KMGTPEZY';
-
+class ByteUnitSymbolCollection extends ByteUnitCollection implements BaseAware {
     const
+        PREFIXES = 'KMGTPEZY',
+
         SUFFIX_NONE   = '',
         SUFFIX_METRIC = 'B',
         SUFFIX_IEC    = 'iB'
@@ -24,17 +22,10 @@ public function __construct($suffix = self::SUFFIX_NONE, $alwaysShowUnit = false
         $this->setSuffix($suffix)->alwaysShowUnit($alwaysShowUnit);
     }
 
-    public function getSequence() {
-        yield $this->suffix !== self::SUFFIX_NONE || $this->alwaysShowUnit ? 'B' : '';
-
-        for ($i = 0; $i < strlen(static::$prefixes); ++$i)
-            yield static::$prefixes[$i] . $this->suffix;
-    }
-
-    public function getSequenceIndex($index) {
-        $sequence = $this->getSequenceArray();
+    public function offsetGet($offset) {
+        if (!$offset) return $this->suffix !== static::SUFFIX_NONE || $this->alwaysShowUnit ? 'B' : '';
 
-        return $sequence[min($index, count($sequence) - 1)];
+        return substr(static::PREFIXES, min(--$offset, count($this) - 1), 1) . $this->suffix;
     }
 
     public function setBase($base) {

src/Byte/ByteUnitNameSequence.php

@@ -0,0 +1,6 @@
+<?php
+namespace ScriptFUSION\Byte;
+
+interface ValueAware {
+    function setValue($value);
+}