Improve Ordered Map public API

Author: nyamsprod

README.md

@@ -6,10 +6,11 @@ Structured Field Values for PHP
 [![Build](https://github.com/bakame-php/http-structured-fields/workflows/build/badge.svg)](https://github.com/bakame-php/http-structured-fields/actions?query=workflow%3A%22build%22)
 
 The package uses pragmatic value objects to parse and serialize [HTTP Structured Fields][1] in PHP.
-Structured fields are intended for use by specifications of new HTTP fields that wish to use a 
-common syntax that is more restrictive than traditional HTTP field values.
+HTTP Structured fields are intended for use by specifications of new HTTP fields that wish to 
+use a common syntax that is more restrictive than traditional HTTP field values or could be
+used to [retrofit current headers](https://www.ietf.org/id/draft-ietf-httpbis-retrofit-00.html) to have them compliant with the new syntax.
 
-You will be able to:
+The package can be used to:
 
 - parse and serialize HTTP Structured Fields
 - create and update HTTP Structured Fields in a predicable way;
@@ -25,7 +26,7 @@ echo $fields->toHttpValue(); //display "/terms";rel="copyright";anchor="#foo"
 System Requirements
 -------
 
-- You require **PHP >= 8.1** but the latest stable version of PHP is recommended
+**PHP >= 8.1** is required but the latest stable version of PHP is recommended.
 
 Installation
 ------------
@@ -51,7 +52,7 @@ For each of those top-level types, the package provide a dedicated value object
 and to serialize the value object back to the textual representation. 
 
 - Parsing is done via a common named constructor `fromHttpValue` which expects the Header or Trailer string value.
-- Serializing is done via a common `toHttpValue` public method. The method returns the normalized string representation suited for HTTP textual representation
+- Serializing is done via a common `toHttpValue` public method. The method returns the normalized string representation suited for HTTP textual representation.
 
 ```php
 use Bakame\Http\StructuredFields\Dictionary;
@@ -68,14 +69,14 @@ $item = Item::fromHttpValue('"foo";a=1;b=2"');
 echo $item->toHttpValue(); // "foo";a=1;b=2
 ```
 
-## Structured Data Types
+## Manipulating Structured Fields Value Objects
 
 ### Items
 
 #### Types
 
-Bare types defined in the RFC are translated to PHP 
-native type when possible. Two additional classes:
+Item types [defined in the RFC](https://www.rfc-editor.org/rfc/rfc8941.html#section-3.3) are translated to PHP native type when possible. 
+Two additional classes
 
 - `Bakame\Http\StructuredFields\Token` and
 - `Bakame\Http\StructuredFields\ByteSequence`
@@ -93,10 +94,10 @@ are used to represent non-native types as shown in the table below:
 
 #### Parameters
 
-As explain in the RFC, `Parameters` are containers of `Item` instances. They can be associated
-to an `Item` instance or other container types  **BUT** the items it contains can not 
-themselves contain `Parameters` instance. More on parameters public API 
-will be cover in subsequent paragraphs.
+As explain in the RFC, `Parameters` are an ordered map of key-value pairs that can be 
+associated with an `Item`. They can be associated **BUT** the items they contain 
+can not themselves contain `Parameters` instance. More on parameters 
+public API will be cover in subsequent paragraphs.
 
 #### Usage
 
@@ -109,13 +110,13 @@ $item = Item::from("hello world", ["a" => 1]);
 $item->value(); //returns "hello world"
 $item->isString(); //return true
 $item->isToken();  //return false
-$item->parameters()->getByKey("a")->value(); //returns 1
+$item->parameters()->get("a")->value(); //returns 1
 ```
 
 Once instantiated, accessing `Item` properties is done via two methods:
 
 - `Item::value()` which returns the instance underlying value
-- `Item::parameters()` which returns the item associated parameters as a distinct `Parameters` object
+- `Item::parameters()` which returns the parameters associated to the `Item` as a distinct `Parameters` object
 
 **To instantiate a decimal number a float MUST be used as the first argument input.**
 
@@ -134,19 +135,24 @@ $item->isInteger(); //return true
 ### Containers
 
 Apart from the `Item`, the RFC defines different containers with different requirements. The
-package exposes those containers via the following value objects `Parameters`, `Dictionary`, 
-`InnerList` and `OrderedList` with the same basic public API. At any given time it 
-is possible to:
+package exposes those containers via the following value objects:
+
+- `Parameters`, 
+- `Dictionary`,
+- `InnerList`,
+- and `OrderedList` to represent a generic list,
+ 
+At any given time it is possible with each of these objects to:
 
 - iterate over each contained element and its optional associated key via the `IteratorAggregate` interface;
 - tell whether the container is empty via an `isEmpty` method;
 - know the number of elements contained in the container via the `Countable` interface;
-- merge multiple instance of the same container using the `merge` method;
+- merge multiple instance of **the same type** using the `merge` method;
 
 ```php
 use Bakame\Http\StructuredFields\Parameters;
 
-$parameters = new Parameters(['a' => 1, 'b' => 2, 'c' => Item::from("hello world")]);
+$parameters = Parameters::fromAssociative(['a' => 1, 'b' => 2, 'c' => "hello world"]);
 count($parameters);          // return 2
 $parameters->isEmpty();      // returns false
 $parameters->toHttpValue();  // return ";a=1;b=2"
@@ -157,34 +163,39 @@ $parameters->toHttpValue();  // return ";a=1;b=2"
 The `Parameters` and the `Dictionary` classes allow associating a string 
 key to its members as such they expose the following methods:
 
+- `fromAssociative` a named constructor to instantiate the container with an associative array;
+- `fromPairs` a named constructor to instantiate the container with a list of key-value pairs;
+- `has` tell whether a specific element is associated to a given `key`;
+- `get` returns the element associated to a specific `key`;
+- `hasPair` tell whether a `key-value` association exists at a given `index` (negative indexes are supported);
+- `pair` returns the key-pair association present at a specific `index` (negative indexes are supported);
+- `pairs` returns an iterator to iterate over the container pairs;
 - `set` add an element at the end of the container if the key is new otherwise only the value is updated;
 - `append` always add an element at the end of the container, if already present the previous value is removed;
 - `prepend` always add an element at the beginning of the container, if already present the previous value is removed;
 - `delete` to remove elements based on their associated keys;
-- tell whether an element is attached to the container using its `index` or  `key` via `hasIndex` and `hasKey` methods;
-- get any element by its string `key` or by its integer `index` via `getByKey` and `getByIndex` methods when applicable;
 
 ```php
 use Bakame\Http\StructuredFields\Dictionary;
 use Bakame\Http\StructuredFields\Item;
 
-$dictionary = new Dictionary();
-$dictionary->set('b', true);
+$dictionary = Dictionary::fromPairs([['b', true]]);
 $dictionary->append('c', Item::from(true, ['foo' => new Token('bar')]));
 $dictionary->prepend('a', false);
 $dictionary->toHttpValue(); //returns "a=?0, b, c;foo=bar"
-$dictionary->hasKey('a');   //return true
-$dictionary->hasKey('foo'); //return false
-$dictionary->getByIndex(1); //return Item::fromBoolean(true)
-$dictionary->hasIndex(-1);  //return Item::fromBoolean(true)
+$dictionary->has('a');   //return true
+$dictionary->has('foo'); //return false
+$dictionary->pair(1); //return ['b', Item::fromBoolean(true)]
+$dictionary->hasPair(-1);  //return true
 $dictionary->append('z', 42.0);
 $dictionary->delete('b', 'c');
 echo $dictionary->toHttpValue(); //returns "a=?0, z=42.0"
 ```
 
 **Item types are inferred using `Item::from` if a `Item` object is not submitted.**
 
-- `getByIndex` supports negative index
+**EVERY CHANGE IN THE ORDERED MAP WILL RE-INDEX THE PAIRS AS TO NOT EXPOSE MISSING INDEXES**
+
 - `Parameters` can only contains `Item` instances 
 - `Dictionary` instance can contain `Item` and `InnerList` instances.
 
@@ -233,11 +244,12 @@ Contributions are welcome and will be fully credited. Please see [CONTRIBUTING](
 Testing
 -------
 
-The library has a :
+The library  :
 
-- a [PHPUnit](https://phpunit.de) test suite
-- a coding style compliance test suite using [PHP CS Fixer](https://cs.sensiolabs.org/).
-- a code analysis compliance test suite using [PHPStan](https://github.com/phpstan/phpstan).
+- has a [PHPUnit](https://phpunit.de) test suite
+- has a coding style compliance test suite using [PHP CS Fixer](https://cs.sensiolabs.org/).
+- has a code analysis compliance test suite using [PHPStan](https://github.com/phpstan/phpstan).
+- is compliant with [the language agnostic HTTP Structured Fields Test suite](https://github.com/httpwg/structured-field-tests).
 
 To run the tests, run the following command from the project folder.
 

src/Dictionary.php

@@ -13,18 +13,36 @@
  */
 final class Dictionary implements Countable, IteratorAggregate, StructuredField
 {
-    /** @var array<string, Item|InnerList>  */
-    private array $elements;
+    private function __construct(
+        /** @var array<string, Item|InnerList>  */
+        private array $elements = []
+    ) {
+    }
 
     /**
      * @param iterable<string, InnerList|Item|ByteSequence|Token|bool|int|float|string> $elements
      */
-    public function __construct(iterable $elements = [])
+    public static function fromAssociative(iterable $elements = []): self
     {
-        $this->elements = [];
+        $instance = new self();
         foreach ($elements as $index => $element) {
-            $this->set($index, $element);
+            $instance->set($index, $element);
+        }
+
+        return $instance;
+    }
+
+    /**
+     * @param iterable<array{0:string, 1:InnerList|Item|ByteSequence|Token|bool|int|float|string}> $pairs
+     */
+    public static function fromPairs(iterable $pairs = []): self
+    {
+        $instance = new self();
+        foreach ($pairs as [$key, $element]) {
+            $instance->set($key, $element);
         }
+
+        return $instance;
     }
 
     public static function fromHttpValue(string $httpValue): self
@@ -114,6 +132,16 @@ public function getIterator(): Iterator
         }
     }
 
+    /**
+     * @return Iterator<array{0:string, 1:Item|InnerList}>
+     */
+    public function toPairs(): Iterator
+    {
+        foreach ($this->elements as $index => $element) {
+            yield [$index, $element];
+        }
+    }
+
     /**
      * @return array<string>
      */
@@ -122,12 +150,12 @@ public function keys(): array
         return array_keys($this->elements);
     }
 
-    public function hasKey(string $key): bool
+    public function has(string $key): bool
     {
         return array_key_exists($key, $this->elements);
     }
 
-    public function getByKey(string $key): Item|InnerList|null
+    public function get(string $key): Item|InnerList
     {
         if (!array_key_exists($key, $this->elements)) {
             throw InvalidOffset::dueToKeyNotFound($key);
@@ -136,7 +164,7 @@ public function getByKey(string $key): Item|InnerList|null
         return $this->elements[$key];
     }
 
-    public function hasIndex(int $index): bool
+    public function hasPair(int $index): bool
     {
         return null !== $this->filterIndex($index);
     }
@@ -152,14 +180,20 @@ private function filterIndex(int $index): int|null
         };
     }
 
-    public function getByIndex(int $index): Item|InnerList|null
+    /**
+     * @return array{0:string, 1:Item|InnerList}
+     */
+    public function pair(int $index): array
     {
         $offset = $this->filterIndex($index);
         if (null === $offset) {
             throw InvalidOffset::dueToIndexNotFound($index);
         }
 
-        return array_values($this->elements)[$offset];
+        return [
+            array_keys($this->elements)[$offset],
+            array_values($this->elements)[$offset],
+        ];
     }
 
     public function set(string $key, InnerList|Item|ByteSequence|Token|bool|int|float|string $element): void