Improve OrderedMap interface

Author: nyamsprod

CHANGELOG.md

@@ -6,11 +6,11 @@ All Notable changes to `bakame/http-strucured-fields` will be documented in this
 
 ### Added
 
-- `Item::parameterByOffset` and `InnerList::parameterByOffset` tu returns the parameter as a tuple.
+- Public API around accessing parameters using their index instead of their key.
 
 ### Fixed
 
-- `Parser` class is no longer internal
+- `Parameters::remove` also removes parameters per indexes
 
 ### Deprecated
 

README.md

@@ -57,7 +57,7 @@ composer require bakame/http-structured-fields
 
 ### Foreword
 
-**While this package parses and serializes the header value, it does not validate its content.
+**⚠️WARNING: While this package parses and serializes the header value, it does not validate its content.
 It is still required to validate the parsed data against the constraints of the corresponding
 header. Content validation is out of scope for this library.**
 
@@ -195,7 +195,7 @@ $token->type(); // returns Type::Token enum
 $byte->type();  // returns Type::ByteSequence
 ```
 
-**Both classes DO NOT expose the `Stringable` interface to distinguish them
+**⚠️WARNING: Both classes DO NOT expose the `Stringable` interface to distinguish them
 from a string or a string like object**
 
 #### Item
@@ -310,9 +310,9 @@ use Bakame\Http\StructuredFields\Item;
 Item::withValue(DateTimeInterface|ByteSequence|Token|string|int|float|bool $value): static
 ```
 
-#### Dictionaries
+#### Ordered Maps
 
-The `Dictionary` and `Parameters` instances can be build with an associative iterable structure as shown below
+The `Dictionary` and `Parameters` are ordered map instances. They can be built using their keys with an associative iterable structure as shown below
 
 ```php
 use Bakame\Http\StructuredFields\Dictionary;
@@ -327,7 +327,7 @@ echo $value->toHttpValue(); //"b=?0, a=bar, c=@1671800423"
 echo $value;                //"b=?0, a=bar, c=@1671800423"
 ```
 
-or with an iterable structure of pairs (tuple) as defined in the RFC:
+or using their indexes with an iterable structure of pairs (tuple) as defined in the RFC:
 
 ```php
 use Bakame\Http\StructuredFields\Parameters;
@@ -358,6 +358,7 @@ $map->mergeAssociative(...$others): static;
 $map->mergePairs(...$others): static;
 $map->remove(string ...$key): static;
 ```
+
 As shown below:
 `
 ```php
@@ -380,6 +381,49 @@ echo $value->toHttpValue(); //b=?0, a=(bar "42" 42 42.0), c=@1671800423
 echo $value;                //b=?0, a=(bar "42" 42 42.0), c=@1671800423
 ```
 
+Since version `1.1.0` it is possible to also build `Dictionary` and `Parameters` instances
+using indexes and pair as per described in the RFC.
+
+The `$pair` parameter is a tuple (ie: an array as list with exactly two members) where:
+
+- the first array member is the parameter `$key`
+- the second array member is the parameter `$value`
+
+```php
+// since version 1.1
+$map->unshift(array ...$pairs): static;
+$map->push(array ...$pairs): static;
+$map->insert(int $key, array ...$pairs): static;
+$map->replace(int $key, array $pair): static;
+```
+
+We can rewrite the previous example
+
+```php
+use Bakame\Http\StructuredFields\Dictionary;
+use Bakame\Http\StructuredFields\Item;
+use Bakame\Http\StructuredFields\Token;
+
+$value = Dictionary::new()
+    ->push(
+        ['a', InnerList::new(
+            Item::fromToken('bar'),
+            Item::fromString('42'),
+            Item::fromInteger(42),
+            Item::fromDecimal(42)
+         )],
+         ['c', true]
+     )
+    ->unshift(['b', Item::false()])
+    ->replace(2, ['c', Item::fromDateString('2022-12-23 13:00:23')])
+;
+
+echo $value->toHttpValue(); //b=?0, a=(bar "42" 42 42.0), c=@1671800423
+echo $value;                //b=?0, a=(bar "42" 42 42.0), c=@1671800423
+```
+
+**⚠️WARNING: on duplication parameters with the same `keys` are merged as per RFC logic.**
+
 #### Automatic conversion
 
 For all containers, to ease instantiation the following automatic conversion are applied on
@@ -501,17 +545,29 @@ Both objects provide additional modifying methods to help deal with parameters.
 You can attach and update the associated `Parameters` instance using the following methods.
 
 ```php
-use Bakame\Http\StructuredFields\Parameters;
-
 $field->addParameter(string $key, mixed $value): static;
 $field->appendParameter(string $key, mixed $value): static;
 $field->prependParameter(string $key, mixed $value): static;
 $field->withoutParameters(string ...$keys): static;
 $field->withoutAnyParameter(): static;
 $field->withParameters(Parameters $parameters): static;
 ```
+Since verrsion `1.1` it is also possible to use the index of each member to perform additional
+modifications.
+
+```php
+$field->pushParameters(array ...$pairs): static
+$field->unshiftParameters(array ...$pairs): static
+$field->insertParameters(int $index, array ...$pairs): static
+$field->replaceParameter(int $index, array $pair): static
+```
+
+The `$pair` parameter is a tuple (ie: an array as list with exactly two members) where:
+
+- the first array member is the parameter `$key`
+- the second array member is the parameter `$value`
 
-**The return value will be the parent class an NOT a `Parameters` instance**
+**⚠️WARNING: The return value will be the parent class an NOT a `Parameters` instance**
 
 ```php
 use Bakame\Http\StructuredFields\InnerList;
@@ -523,7 +579,15 @@ echo InnerList::new('foo', 'bar')
     ->addParameter('max-age', 2500)
     ->toHttpValue();
 
-// return the InnerList HTTP value 
+echo InnerList::new('foo', 'bar')
+    ->pushParameter(
+        ['expire', Item::fromDateString('+30 minutes')],
+        ['path', '/'],
+        ['max-age', 2500],
+    )
+    ->toHttpValue();
+
+// both flow return the InnerList HTTP value 
 // ("foo" "bar");expire=@1681538756;path="/";max-age=2500
 ```
 

src/Dictionary.php

@@ -16,7 +16,6 @@
 use function is_array;
 use function is_iterable;
 use function is_string;
-use const ARRAY_FILTER_USE_KEY;
 
 /**
  * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-3.2
@@ -210,9 +209,7 @@ public function get(string|int $key): StructuredField
     public function hasPair(int ...$indexes): bool
     {
         foreach ($indexes as $index) {
-            try {
-                $this->filterIndex($index);
-            } catch (InvalidOffset) {
+            if (null === $this->filterIndex($index)) {
                 return false;
             }
         }
@@ -223,12 +220,12 @@ public function hasPair(int ...$indexes): bool
     /**
      * Filters and format instance index.
      */
-    private function filterIndex(int $index): int
+    private function filterIndex(int $index): int|null
     {
         $max = count($this->members);
 
         return match (true) {
-            [] === $this->members, 0 > $max + $index, 0 > $max - $index - 1 => throw InvalidOffset::dueToIndexNotFound($index),
+            [] === $this->members, 0 > $max + $index, 0 > $max - $index - 1 => null,
             0 > $index => $max + $index,
             default => $index,
         };
@@ -241,7 +238,12 @@ private function filterIndex(int $index): int
      */
     public function pair(int $index): array
     {
-        return [...$this->toPairs()][$this->filterIndex($index)];
+        $offset = $this->filterIndex($index);
+        if (null === $offset) {
+            throw InvalidOffset::dueToIndexNotFound($index);
+        }
+
+        return [...$this->toPairs()][$offset];
     }
 
     /**
@@ -269,13 +271,20 @@ private function newInstance(array $members): self
 
     public function remove(string|int ...$keys): static
     {
-        $members = array_filter(
-            $this->members,
-            fn (string|int $key): bool => !in_array($key, $keys, true),
-            ARRAY_FILTER_USE_KEY
-        );
+        /** @var array<array-key, true> $indexes */
+        $indexes = array_fill_keys($keys, true);
+        $pairs = [];
+        foreach ($this->toPairs() as $index => $pair) {
+            if (!isset($indexes[$index]) && !isset($indexes[$pair[0]])) {
+                $pairs[] = $pair;
+            }
+        }
 
-        return $this->newInstance($members);
+        if (count($this->members) === count($pairs)) {
+            return $this;
+        }
+
+        return self::fromPairs($pairs);
     }
 
     /**
@@ -302,6 +311,79 @@ public function prepend(string $key, iterable|StructuredField|Token|ByteSequence
         return $this->newInstance($members);
     }
 
+    /**
+     * @param array{0:string, 1:SfMember|SfMemberInput} ...$pairs
+     */
+    public function push(array ...$pairs): self
+    {
+        if ([] === $pairs) {
+            return $this;
+        }
+
+        $newPairs = iterator_to_array($this->toPairs());
+        foreach ($pairs as $pair) {
+            $newPairs[] = $pair;
+        }
+
+        return self::fromPairs($newPairs);
+    }
+
+    /**
+     * @param array{0:string, 1:SfMember|SfMemberInput} ...$pairs
+     */
+    public function unshift(array ...$pairs): self
+    {
+        if ([] === $pairs) {
+            return $this;
+        }
+
+        foreach ($this->members as $key => $member) {
+            $pairs[] = [$key, $member];
+        }
+
+        return self::fromPairs($pairs);
+    }
+
+    /**
+     * @param array{0:string, 1:SfMember|SfMemberInput} ...$members
+     */
+    public function insert(int $index, array ...$members): static
+    {
+        $offset = $this->filterIndex($index);
+
+        return match (true) {
+            null === $offset => throw InvalidOffset::dueToIndexNotFound($index),
+            [] === $members => $this,
+            0 === $offset => $this->unshift(...$members),
+            count($this->members) === $offset => $this->push(...$members),
+            default => (function (Iterator $newMembers) use ($offset, $members) {
+                $newMembers = iterator_to_array($newMembers);
+                array_splice($newMembers, $offset, 0, $members);
+
+                return self::fromPairs($newMembers);
+            })($this->toPairs()),
+        };
+    }
+
+    /**
+     * @param array{0:string, 1:SfMember|SfMemberInput} $member
+     */
+    public function replace(int $index, array $member): static
+    {
+        $offset = $this->filterIndex($index);
+        if (null === $offset) {
+            throw InvalidOffset::dueToIndexNotFound($index);
+        }
+
+        $member[1] = self::filterMember($member[1]);
+        $pairs = iterator_to_array($this->toPairs());
+        if ($pairs[$offset] == $member) {
+            return $this;
+        }
+
+        return self::fromPairs(array_replace($pairs, [$offset => $member]));
+    }
+
     /**
      * @param iterable<string, SfMember|SfMemberInput> ...$others
      */

src/DictionaryTest.php

@@ -316,4 +316,63 @@ public function it_forbids_adding_members_using_the_array_access_interface(): vo
 
         Dictionary::fromPairs([['foobar', 'foobar'], ['zero', 0]])['foobar'] = Item::false();
     }
+
+    #[Test]
+    public function it_can_returns_the_container_member_keys_with_pairs(): void
+    {
+        $instance = Dictionary::new();
+
+        self::assertSame([], $instance->keys());
+        self::assertSame(['a', 'b'], $instance->push(['a', false], ['b', true])->keys());
+
+        $container = Dictionary::new()
+            ->unshift(['a', '42'])
+            ->push(['b', 42])
+            ->insert(1, ['c', 42.0])
+            ->replace(0, ['d', 'forty-two']);
+
+        self::assertSame(['d', 'c', 'b'], $container->keys());
+        self::assertSame('d="forty-two", c=42.0, b=42', $container->toHttpValue());
+    }
+
+    #[Test]
+    public function it_can_push_and_unshift_new_pair(): void
+    {
+        $instance = Dictionary::new()
+            ->push(['a', false])
+            ->unshift(['b', true]);
+
+        self::assertSame('b, a=?0', $instance->toHttpValue());
+        self::assertSame('b, a=?0', (string) $instance);
+    }
+
+    #[Test]
+    public function it_fails_to_insert_at_an_invalid_index(): void
+    {
+        $this->expectException(InvalidOffset::class);
+
+        Dictionary::new()->insert(3, ['a', 1]);
+    }
+
+    #[Test]
+    public function it_can_push_nothing(): void
+    {
+        self::assertEquals(Dictionary::new()->push()->unshift(), Dictionary::new());
+    }
+
+    #[Test]
+    public function it_fails_to_replace_unknown_index(): void
+    {
+        $this->expectException(InvalidOffset::class);
+
+        Dictionary::new()->replace(0, ['a', true]);
+    }
+
+    #[Test]
+    public function it_returns_the_same_instance_if_nothing_is_replaced(): void
+    {
+        $field = Dictionary::new()->push(['a', true]);
+
+        self::assertSame($field->replace(0, ['a', true]), $field);
+    }
 }