Adding ::hasNoMember method

nyamsprod · nyamsprod · commit 46812ca6a9f3 · 2023-01-17T16:28:05.000+01:00
diff --git a/src/Dictionary.php b/src/Dictionary.php
@@ -105,6 +105,11 @@ public function count(): int
         return count($this->members);
     }
 
+    public function hasNoMembers(): bool
+    {
+        return !$this->hasMembers();
+    }
+
     public function hasMembers(): bool
     {
         return [] !== $this->members;
diff --git a/src/DictionaryTest.php b/src/DictionaryTest.php
@@ -34,6 +34,7 @@ public function it_can_be_instantiated_with_an_collection_of_item_or_inner_list(
         $instance->clear();
 
         self::assertFalse($instance->hasMembers());
+        self::assertTrue($instance->hasNoMembers());
     }
 
     /** @test */
@@ -65,6 +66,7 @@ public function it_can_add_or_remove_members(): void
 
         self::assertCount(2, $instance);
         self::assertTrue($instance->hasMembers());
+        self::assertFalse($instance->hasNoMembers());
 
         $instance->delete('boolean');
 
diff --git a/src/InnerList.php b/src/InnerList.php
@@ -105,6 +105,11 @@ public function count(): int
         return count($this->members);
     }
 
+    public function hasNoMembers(): bool
+    {
+        return !$this->hasMembers();
+    }
+
     public function hasMembers(): bool
     {
         return [] !== $this->members;
diff --git a/src/InnerListTest.php b/src/InnerListTest.php
@@ -22,12 +22,14 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
 
         self::assertSame($stringItem, $instance->get(0));
         self::assertTrue($instance->hasMembers());
+        self::assertFalse($instance->hasNoMembers());
         self::assertTrue($instance->parameters()->hasMembers());
         self::assertEquals($arrayParams, iterator_to_array($instance));
 
         $instance->clear();
 
         self::assertFalse($instance->hasMembers());
+        self::assertTrue($instance->hasNoMembers());
         self::assertTrue($instance->parameters()->hasMembers());
     }
 
diff --git a/src/Item.php b/src/Item.php
@@ -48,7 +48,7 @@ public static function fromHttpValue(Stringable|string $httpValue): self
             throw new SyntaxError('The HTTP textual representation "'.$httpValue.'" for an item contains invalid characters.');
         }
 
-        return new self($value, Parameters::fromHttpValue(substr($itemString, $offset)));
+        return self::from($value, Parameters::fromHttpValue(substr($itemString, $offset)));
     }
 
     /**
diff --git a/src/MemberContainer.php b/src/MemberContainer.php
@@ -17,6 +17,11 @@
  */
 interface MemberContainer extends Countable, ArrayAccess, IteratorAggregate, StructuredField
 {
+    /**
+     * Tells whether the instance contains no members.
+     */
+    public function hasNoMembers(): bool;
+
     /**
      * Tells whether the instance contains members.
      */
diff --git a/src/OrderedList.php b/src/OrderedList.php
@@ -27,11 +27,6 @@ private function __construct()
     {
     }
 
-    /**
-     * @param InnerList<int, Item>|Item|DataType ...$members
-     *
-     * @return static
-     */
     public static function from(InnerList|Item|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): self
     {
         return self::fromList($members);
@@ -82,6 +77,11 @@ public function count(): int
         return count($this->members);
     }
 
+    public function hasNoMembers(): bool
+    {
+        return !$this->hasMembers();
+    }
+
     public function hasMembers(): bool
     {
         return [] !== $this->members;
@@ -132,8 +132,6 @@ public function get(string|int $offset): Item|InnerList
 
     /**
      * Inserts members at the beginning of the list.
-     *
-     * @param InnerList<int, Item>|Item|DataType ...$members
      */
     public function unshift(StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): self
     {
@@ -144,8 +142,6 @@ public function unshift(StructuredField|Token|ByteSequence|DateTimeInterface|Str
 
     /**
      * Inserts members at the end of the list.
-     *
-     * @param InnerList<int, Item>|Item|DataType ...$members
      */
     public function push(StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): self
     {
@@ -157,8 +153,6 @@ public function push(StructuredField|Token|ByteSequence|DateTimeInterface|String
     /**
      * Inserts members starting at the given index.
      *
-     * @param InnerList<int, Item>|Item|DataType $members
-     *
      * @throws InvalidOffset If the index does not exist
      */
     public function insert(int $index, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool ...$members): self
@@ -177,8 +171,6 @@ public function insert(int $index, StructuredField|Token|ByteSequence|DateTimeIn
     /**
      * Replaces the member associated with the index.
      *
-     * @param InnerList<int, Item>|Item|DataType $member
-     *
      * @throws InvalidOffset If the index does not exist
      */
     public function replace(int $index, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): self
diff --git a/src/OrderedListTest.php b/src/OrderedListTest.php
@@ -25,6 +25,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
 
         self::assertSame($stringItem, $instance->get(0));
         self::assertTrue($instance->hasMembers());
+        self::assertFalse($instance->hasNoMembers());
         self::assertEquals($arrayParams, iterator_to_array($instance));
     }
 
@@ -55,6 +56,7 @@ public function it_can_add_or_remove_members(): void
         $instance->remove(0, 1);
 
         self::assertCount(0, $instance);
+        self::assertTrue($instance->hasNoMembers());
         self::assertFalse($instance->hasMembers());
     }
 
diff --git a/src/Parameters.php b/src/Parameters.php
@@ -44,9 +44,6 @@ public static function create(): self
      * its values represent the dictionary entry value
      *
      * @param iterable<array-key, Item|DataType> $members
-     *
-     * @throws SyntaxError         If the string is not a valid
-     * @throws ForbiddenStateError If the bare item contains parameters
      */
     public static function fromAssociative(iterable $members): self
     {
@@ -66,8 +63,6 @@ public static function fromAssociative(iterable $members): self
      * the second member represents the instance entry value
      *
      * @param MemberOrderedMap<string, Item>|iterable<array{0:string, 1:Item|DataType}> $pairs
-     *
-     * @throws ForbiddenStateError If the bare item contains parameters
      */
     public static function fromPairs(MemberOrderedMap|iterable $pairs): self
     {
@@ -88,7 +83,7 @@ public static function fromPairs(MemberOrderedMap|iterable $pairs): self
      */
     private static function filterMember(Item $item): Item
     {
-        if (!$item->parameters()->hasMembers()) {
+        if ($item->parameters()->hasNoMembers()) {
             return $item;
         }
 
@@ -133,9 +128,6 @@ public static function fromHttpValue(Stringable|string $httpValue): self
         return $instance;
     }
 
-    /**
-     * @throws ForbiddenStateError if the bare item contains parameters itself
-     */
     public function toHttpValue(): string
     {
         $formatter = fn (Item $member, string $offset): string => match (true) {
@@ -151,14 +143,17 @@ public function count(): int
         return count($this->members);
     }
 
+    public function hasNoMembers(): bool
+    {
+        return !$this->hasMembers();
+    }
+
     public function hasMembers(): bool
     {
         return [] !== $this->members;
     }
 
     /**
-     * @throws ForbiddenStateError if the bare item contains parameters itself
-     *
      * @return Iterator<array-key, Item>
      */
     public function getIterator(): Iterator
@@ -169,14 +164,12 @@ public function getIterator(): Iterator
     /**
      * Returns an iterable construct of dictionary pairs.
      *
-     * @throws ForbiddenStateError if the bare item contains parameters itself
-     *
      * @return Iterator<array{0:string, 1:Item}>
      */
     public function toPairs(): Iterator
     {
         foreach ($this->members as $index => $member) {
-            yield [$index, self::filterMember($member)];
+            yield [$index, $member];
         }
     }
 
@@ -201,8 +194,7 @@ public function has(string|int $offset): bool
     /**
      * Returns the Item associated to the key.
      *
-     * @throws InvalidOffset       if the key is not found
-     * @throws ForbiddenStateError if the bare item contains parameters itself
+     * @throws InvalidOffset if the key is not found
      */
     public function get(string|int $offset): Item
     {
@@ -244,8 +236,7 @@ private function filterIndex(int $index): int
     /**
      * Returns the key-item pair found at a given index.
      *
-     * @throws InvalidOffset       if the index is not found
-     * @throws ForbiddenStateError if the found item is in invalid state
+     * @throws InvalidOffset if the index is not found
      *
      * @return array{0:string, 1:Item}
      */
@@ -268,9 +259,6 @@ public function pair(int $index): array
 
     /**
      * Adds a member at the end of the instance otherwise updates the value associated with the key if already present.
-     *
-     * @throws SyntaxError         If the string key is not a valid
-     * @throws ForbiddenStateError if the found item is in invalid state
      */
     public function set(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): self
     {
@@ -300,9 +288,6 @@ public function clear(): self
 
     /**
      * Adds a member at the end of the instance and deletes any previous reference to the key if present.
-     *
-     * @throws SyntaxError         If the string key is not a valid
-     * @throws ForbiddenStateError if the found item is in invalid state
      */
     public function append(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): self
     {
@@ -315,9 +300,6 @@ public function append(string $key, StructuredField|Token|ByteSequence|DateTimeI
 
     /**
      * Adds a member at the beginning of the instance and deletes any previous reference to the key if present.
-     *
-     * @throws SyntaxError         If the string key is not a valid
-     * @throws ForbiddenStateError if the found item is in invalid state
      */
     public function prepend(string $key, StructuredField|Token|ByteSequence|DateTimeInterface|Stringable|string|int|float|bool $member): self
     {
diff --git a/src/ParametersTest.php b/src/ParametersTest.php
@@ -38,6 +38,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
 
         self::assertFalse(isset($instance['foobar']));
         self::assertFalse($instance->hasMembers());
+        self::assertTrue($instance->hasNoMembers());
     }
 
     /** @test */
@@ -102,6 +103,7 @@ public function it_can_add_or_remove_members(): void
         $instance->delete('foobar', 'string');
         self::assertCount(0, $instance);
         self::assertFalse($instance->hasMembers());
+        self::assertTrue($instance->hasNoMembers());
     }
 
     /** @test */
diff --git a/src/Parser.php b/src/Parser.php
@@ -5,6 +5,7 @@
 namespace Bakame\Http\StructuredFields;
 
 use DateTimeImmutable;
+use DateTimeInterface;
 use DateTimeZone;
 use Stringable;
 use function in_array;
@@ -31,10 +32,10 @@ final class Parser
      *
      * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.1
      *
-     * @return array<array{
+     * @return array<Item|DataType|array{
      *     0:array<Item|DataType>,
      *     1:array<string,Item|DataType>
-     * }|Item|DataType>
+     * }>
      */
     public static function parseList(Stringable|string $httpValue): array
     {
@@ -117,7 +118,7 @@ private static function removeCommaSeparatedWhiteSpaces(string $httpValue, int $
 
         $httpValue = substr($httpValue, strlen($found['space']));
         if ('' === $httpValue) {
-            throw new SyntaxError('Unexpected end of line for The HTTP textual representation.');
+            throw new SyntaxError('The HTTP textual representation has an unexpected end of line.');
         }
 
         return $httpValue;
@@ -180,15 +181,15 @@ private static function parseInnerListValue(string $httpValue): array
             }
         }
 
-        throw new SyntaxError("Unexpected end of line for The HTTP textual representation \"$remainder\" for a inner list.");
+        throw new SyntaxError("The HTTP textual representation \"$remainder\" for a inner list has an unexpected end of line.");
     }
 
     /**
      * Returns an Item value from an HTTP textual representation and the consumed offset in a tuple.
      *
      * @see https://www.rfc-editor.org/rfc/rfc8941.html#section-4.2.3.1
      *
-     * @return array{0:Token|ByteSequence|DateTimeImmutable|string|int|float|bool, 1:int}
+     * @return array{0:DataType, 1:int}
      */
     public static function parseBareItem(string $httpValue): array
     {
@@ -199,7 +200,7 @@ public static function parseBareItem(string $httpValue): array
             '@' === $httpValue[0] => self::parseDate($httpValue),
             1 === preg_match('/^(-|\d)/', $httpValue) => self::parseNumber($httpValue),
             1 === preg_match('/^([a-z*])/i', $httpValue) => self::parseToken($httpValue),
-            default => throw new SyntaxError('Unknown or unsupported string for The HTTP textual representation of an item.'),
+            default => throw new SyntaxError("The HTTP textual representation \"$httpValue\" for an Item is unknown or unsupported."),
         };
     }
 
@@ -264,7 +265,7 @@ private static function parseNumber(string $httpValue): array
         return match (true) {
             1 === preg_match('/^-?\d{1,12}\.\d{1,3}$/', $found['number']) => [(float) $found['number'], strlen($found['number'])],
             1 === preg_match('/^-?\d{1,15}$/', $found['number']) => [(int) $found['number'], strlen($found['number'])],
-            default => throw new SyntaxError("The number format in the HTTP textual representation \"$httpValue\" contains too much digit."),
+            default => throw new SyntaxError("The HTTP textual representation \"$httpValue\" for a Number contains too much digit."),
         };
     }
 
@@ -273,12 +274,12 @@ private static function parseNumber(string $httpValue): array
      *
      * @see https://httpwg.org/http-extensions/draft-ietf-httpbis-sfbis.html#name-dates
      *
-     * @return array{0:DateTimeImmutable, 1:int}
+     * @return array{0:DateTimeInterface, 1:int}
      */
     private static function parseDate(string $httpValue): array
     {
         if (1 !== preg_match('/^@(?<date>-?\d{1,15})(?:[^\d.]|$)/', $httpValue, $found)) {
-            throw new SyntaxError("The Date format in the HTTP textual representation \"$httpValue\" contains invalid characters.");
+            throw new SyntaxError("The HTTP textual representation \"$httpValue\" for a Date contains invalid characters.");
         }
 
         return [
@@ -358,7 +359,7 @@ private static function parseToken(string $httpValue): array
     private static function parseByteSequence(string $httpValue): array
     {
         if (1 !== preg_match('/^(?<sequence>:(?<byte>[a-z\d+\/=]*):)/i', $httpValue, $matches)) {
-            throw new SyntaxError("Invalid characters in the HTTP textual representation of a Byte Sequence \"$httpValue\".");
+            throw new SyntaxError("The HTTP textual representation \"$httpValue\" for a Byte sequence contains invalid characters.");
         }
 
         return [ByteSequence::fromEncoded($matches['byte']), strlen($matches['sequence'])];

Original file line number	Diff line number	Diff line change
`@@ -105,6 +105,11 @@ public function count(): int`
`105`	`105`	`return count($this->members);`
`106`	`106`	`}`
`107`	`107`
	`108`	`+ public function hasNoMembers(): bool`
	`109`	`+ {`
	`110`	`+ return !$this->hasMembers();`
	`111`	`+ }`
	`112`	`+`
`108`	`113`	`public function hasMembers(): bool`
`109`	`114`	`{`
`110`	`115`	`return [] !== $this->members;`
Original file line number	Diff line number	Diff line change
`@@ -48,7 +48,7 @@ public static function fromHttpValue(Stringable\|string $httpValue): self`
`48`	`48`	`throw new SyntaxError('The HTTP textual representation "'.$httpValue.'" for an item contains invalid characters.');`
`49`	`49`	`}`
`50`	`50`
`51`		`- return new self($value, Parameters::fromHttpValue(substr($itemString, $offset)));`
	`51`	`+ return self::from($value, Parameters::fromHttpValue(substr($itemString, $offset)));`
`52`	`52`	`}`
`53`	`53`
`54`	`54`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void`
`25`	`25`
`26`	`26`	`self::assertSame($stringItem, $instance->get(0));`
`27`	`27`	`self::assertTrue($instance->hasMembers());`
	`28`	`+ self::assertFalse($instance->hasNoMembers());`
`28`	`29`	`self::assertEquals($arrayParams, iterator_to_array($instance));`
`29`	`30`	`}`
`30`	`31`
`@@ -55,6 +56,7 @@ public function it_can_add_or_remove_members(): void`
`55`	`56`	`$instance->remove(0, 1);`
`56`	`57`
`57`	`58`	`self::assertCount(0, $instance);`
	`59`	`+ self::assertTrue($instance->hasNoMembers());`
`58`	`60`	`self::assertFalse($instance->hasMembers());`
`59`	`61`	`}`
`60`	`62`
Original file line number	Diff line number	Diff line change
`@@ -44,9 +44,6 @@ public static function create(): self`
`44`	`44`	`* its values represent the dictionary entry value`
`45`	`45`	`*`
`46`	`46`	`* @param iterable<array-key, Item\|DataType> $members`
`47`		`- *`
`48`		`- * @throws SyntaxError If the string is not a valid`
`49`		`- * @throws ForbiddenStateError If the bare item contains parameters`
`50`	`47`	`*/`
`51`	`48`	`public static function fromAssociative(iterable $members): self`
`52`	`49`	`{`
`@@ -66,8 +63,6 @@ public static function fromAssociative(iterable $members): self`
`66`	`63`	`* the second member represents the instance entry value`
`67`	`64`	`*`
`68`	`65`	`* @param MemberOrderedMap<string, Item>\|iterable<array{0:string, 1:Item\|DataType}> $pairs`
`69`		`- *`
`70`		`- * @throws ForbiddenStateError If the bare item contains parameters`
`71`	`66`	`*/`
`72`	`67`	`public static function fromPairs(MemberOrderedMap\|iterable $pairs): self`
`73`	`68`	`{`
`@@ -88,7 +83,7 @@ public static function fromPairs(MemberOrderedMap\|iterable $pairs): self`
`88`	`83`	`*/`
`89`	`84`	`private static function filterMember(Item $item): Item`
`90`	`85`	`{`
`91`		`- if (!$item->parameters()->hasMembers()) {`
	`86`	`+ if ($item->parameters()->hasNoMembers()) {`
`92`	`87`	`return $item;`
`93`	`88`	`}`
`94`	`89`
`@@ -133,9 +128,6 @@ public static function fromHttpValue(Stringable\|string $httpValue): self`
`133`	`128`	`return $instance;`
`134`	`129`	`}`
`135`	`130`
`136`		`- /**`
`137`		`- * @throws ForbiddenStateError if the bare item contains parameters itself`
`138`		`- */`
`139`	`131`	`public function toHttpValue(): string`
`140`	`132`	`{`
`141`	`133`	`$formatter = fn (Item $member, string $offset): string => match (true) {`
`@@ -151,14 +143,17 @@ public function count(): int`
`151`	`143`	`return count($this->members);`
`152`	`144`	`}`
`153`	`145`
	`146`	`+ public function hasNoMembers(): bool`
	`147`	`+ {`
	`148`	`+ return !$this->hasMembers();`
	`149`	`+ }`
	`150`	`+`
`154`	`151`	`public function hasMembers(): bool`
`155`	`152`	`{`
`156`	`153`	`return [] !== $this->members;`
`157`	`154`	`}`
`158`	`155`
`159`	`156`	`/**`
`160`		`- * @throws ForbiddenStateError if the bare item contains parameters itself`
`161`		`- *`
`162`	`157`	`* @return Iterator<array-key, Item>`
`163`	`158`	`*/`
`164`	`159`	`public function getIterator(): Iterator`
`@@ -169,14 +164,12 @@ public function getIterator(): Iterator`
`169`	`164`	`/**`
`170`	`165`	`* Returns an iterable construct of dictionary pairs.`
`171`	`166`	`*`
`172`		`- * @throws ForbiddenStateError if the bare item contains parameters itself`
`173`		`- *`
`174`	`167`	`* @return Iterator<array{0:string, 1:Item}>`
`175`	`168`	`*/`
`176`	`169`	`public function toPairs(): Iterator`
`177`	`170`	`{`
`178`	`171`	`foreach ($this->members as $index => $member) {`
`179`		`- yield [$index, self::filterMember($member)];`
	`172`	`+ yield [$index, $member];`
`180`	`173`	`}`
`181`	`174`	`}`
`182`	`175`
`@@ -201,8 +194,7 @@ public function has(string\|int $offset): bool`
`201`	`194`	`/**`
`202`	`195`	`* Returns the Item associated to the key.`
`203`	`196`	`*`
`204`		`- * @throws InvalidOffset if the key is not found`
`205`		`- * @throws ForbiddenStateError if the bare item contains parameters itself`
	`197`	`+ * @throws InvalidOffset if the key is not found`
`206`	`198`	`*/`
`207`	`199`	`public function get(string\|int $offset): Item`
`208`	`200`	`{`
`@@ -244,8 +236,7 @@ private function filterIndex(int $index): int`
`244`	`236`	`/**`
`245`	`237`	`* Returns the key-item pair found at a given index.`
`246`	`238`	`*`
`247`		`- * @throws InvalidOffset if the index is not found`
`248`		`- * @throws ForbiddenStateError if the found item is in invalid state`
	`239`	`+ * @throws InvalidOffset if the index is not found`
`249`	`240`	`*`
`250`	`241`	`* @return array{0:string, 1:Item}`
`251`	`242`	`*/`
`@@ -268,9 +259,6 @@ public function pair(int $index): array`
`268`	`259`
`269`	`260`	`/**`
`270`	`261`	`* Adds a member at the end of the instance otherwise updates the value associated with the key if already present.`
`271`		`- *`
`272`		`- * @throws SyntaxError If the string key is not a valid`
`273`		`- * @throws ForbiddenStateError if the found item is in invalid state`
`274`	`262`	`*/`
`275`	`263`	`public function set(string $key, StructuredField\|Token\|ByteSequence\|DateTimeInterface\|Stringable\|string\|int\|float\|bool $member): self`
`276`	`264`	`{`
`@@ -300,9 +288,6 @@ public function clear(): self`
`300`	`288`
`301`	`289`	`/**`
`302`	`290`	`* Adds a member at the end of the instance and deletes any previous reference to the key if present.`
`303`		`- *`
`304`		`- * @throws SyntaxError If the string key is not a valid`
`305`		`- * @throws ForbiddenStateError if the found item is in invalid state`
`306`	`291`	`*/`
`307`	`292`	`public function append(string $key, StructuredField\|Token\|ByteSequence\|DateTimeInterface\|Stringable\|string\|int\|float\|bool $member): self`
`308`	`293`	`{`
`@@ -315,9 +300,6 @@ public function append(string $key, StructuredField\|Token\|ByteSequence\|DateTimeI`
`315`	`300`
`316`	`301`	`/**`
`317`	`302`	`* Adds a member at the beginning of the instance and deletes any previous reference to the key if present.`
`318`		`- *`
`319`		`- * @throws SyntaxError If the string key is not a valid`
`320`		`- * @throws ForbiddenStateError if the found item is in invalid state`
`321`	`303`	`*/`
`322`	`304`	`public function prepend(string $key, StructuredField\|Token\|ByteSequence\|DateTimeInterface\|Stringable\|string\|int\|float\|bool $member): self`
`323`	`305`	`{`
Original file line number	Diff line number	Diff line change
`@@ -38,6 +38,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void`
`38`	`38`
`39`	`39`	`self::assertFalse(isset($instance['foobar']));`
`40`	`40`	`self::assertFalse($instance->hasMembers());`
	`41`	`+ self::assertTrue($instance->hasNoMembers());`
`41`	`42`	`}`
`42`	`43`
`43`	`44`	`/** @test */`
`@@ -102,6 +103,7 @@ public function it_can_add_or_remove_members(): void`
`102`	`103`	`$instance->delete('foobar', 'string');`
`103`	`104`	`self::assertCount(0, $instance);`
`104`	`105`	`self::assertFalse($instance->hasMembers());`
	`106`	`+ self::assertTrue($instance->hasNoMembers());`
`105`	`107`	`}`
`106`	`108`
`107`	`109`	`/** @test */`