Skip to content

Commit 93f41dc

Browse files
nyamsprodnyamsprod
committed
Simplify container public API
1 parent 7c23201 commit 93f41dc

File tree

5 files changed

+33
-30
lines changed

5 files changed

+33
-30
lines changed

‎README.md

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -141,23 +141,16 @@ is possible to:
141141
- iterate over each contained element and its optional associated key via the `IteratorAggregate` interface;
142142
- tell whether the container is empty via an `isEmpty` method;
143143
- know the number of elements contained in the container via the `Countable` interface;
144-
- tell whether an element is attached to the container using its `index` or `key` via `hasIndex` and `hasKey` methods;
145-
- get any element by its string `key` or by its integer `index` via `getByKey` and `getByIndex` methods when applicable;
146144
- merge multiple instance of the same container using the `merge` method;
147145

148146
```php
149147
use Bakame\Http\StructuredFields\Parameters;
150148

151149
$parameters = new Parameters(['a' => 1, 'b' => 2, 'c' => Item::from("hello world")]);
152150
count($parameters); // return 2
153-
$parameters->getByKey('b'); // return Item::from(2);
154-
$parameters->getByIndex(-1); // return Item::from("hello world");
155-
$parameters->hasKey(42); // return false because the key does not exist.
151+
$parameters->isEmpty(); // returns false
156152
$parameters->toHttpValue(); // return ";a=1;b=2"
157-
$parameters->keys(); // return ["a", "b", "c"]
158153
```
159-
- *`getByIndex` supports negative index*
160-
- *Item types are inferred using `Item::from` if a `Item` object is not submitted.*
161154

162155
#### Ordered Maps
163156

@@ -168,6 +161,8 @@ key to its members as such they expose the following methods:
168161
- `append` always add an element at the end of the container, if already present the previous value is removed;
169162
- `prepend` always add an element at the beginning of the container, if already present the previous value is removed;
170163
- `delete` to remove elements based on their associated keys;
164+
- tell whether an element is attached to the container using its `index` or `key` via `hasIndex` and `hasKey` methods;
165+
- get any element by its string `key` or by its integer `index` via `getByKey` and `getByIndex` methods when applicable;
171166

172167
```php
173168
use Bakame\Http\StructuredFields\Dictionary;
@@ -181,11 +176,15 @@ $dictionary->toHttpValue(); //returns "a=?0, b, c;foo=bar"
181176
$dictionary->hasKey('a'); //return true
182177
$dictionary->hasKey('foo'); //return false
183178
$dictionary->getByIndex(1); //return Item::fromBoolean(true)
179+
$dictionary->hasIndex(-1); //return Item::fromBoolean(true)
184180
$dictionary->append('z', 42.0);
185181
$dictionary->delete('b', 'c');
186182
echo $dictionary->toHttpValue(); //returns "a=?0, z=42.0"
187183
```
188184

185+
**Item types are inferred using `Item::from` if a `Item` object is not submitted.**
186+
187+
- `getByIndex` supports negative index
189188
- `Parameters` can only contains `Item` instances
190189
- `Dictionary` instance can contain `Item` and `InnerList` instances.
191190

@@ -194,6 +193,8 @@ echo $dictionary->toHttpValue(); //returns "a=?0, z=42.0"
194193
The `OrderedList` and the `InnerList` classes are list of members
195194
that act as containers and also expose the following methods
196195

196+
- `get` to access an element at a given index (negative indexes are supported)
197+
- `has` tell whether an element is attached to the container using its `index`;
197198
- `push` to add elements at the end of the list;
198199
- `unshift` to add elements at the beginning of the list;
199200
- `insert` to add elements at a given position in the list;
@@ -202,14 +203,16 @@ that act as containers and also expose the following methods
202203

203204
to enable manipulation their content.
204205

206+
**Item types are inferred using `Item::from` if a `Item` object is not submitted.**
207+
205208
**EVERY CHANGE IN THE LIST WILL RE-INDEX THE LIST AS TO NOT EXPOSE MISSING INDEXES**
206209

207210
```php
208211
use Bakame\Http\StructuredFields\OrderedList;
209212

210-
$list = OrderedList::fromHttpValue("(\"foo\" \"bar\"), (\"baz\"), (\"bat\" \"one\"), ()");
211-
$list->hasIndex(2); //return true
212-
$list->hasIndex(42); //return false
213+
$list = OrderedList::fromHttpValue('("foo" "bar"), ("baz"), ("bat" "one"), ()');
214+
$list->has(2); //return true
215+
$list->has(42); //return false
213216
$list->push(42);
214217
$list->remove(0, 2);
215218
echo $list->toHttpValue(); //returns "("baz"), (), 42.0"

‎src/InnerList.php

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -125,7 +125,7 @@ private function filterIndex(int $index): int|null
125125

126126
public function replace(int $index, Item|ByteSequence|Token|bool|int|float|string|null $element): void
127127
{
128-
if (!$this->hasIndex($index)) {
128+
if (!$this->has($index)) {
129129
throw InvalidOffset::dueToIndexNotFound($index);
130130
}
131131

@@ -158,7 +158,7 @@ public function isEmpty(): bool
158158
return [] === $this->elements;
159159
}
160160

161-
public function getByIndex(int $index): Item|null
161+
public function get(int $index): Item|null
162162
{
163163
$offset = $this->filterIndex($index);
164164
if (null === $offset) {
@@ -168,7 +168,7 @@ public function getByIndex(int $index): Item|null
168168
return $this->elements[$offset];
169169
}
170170

171-
public function hasIndex(int $index): bool
171+
public function has(int $index): bool
172172
{
173173
return null !== $this->filterIndex($index);
174174
}

‎src/InnerListTest.php

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
2222
$instance = new InnerList($arrayParams, new Parameters(['test' => Item::from(42)]));
2323
self::assertFalse($instance->parameters()->isEmpty());
2424

25-
self::assertSame($stringItem, $instance->getByIndex(0));
25+
self::assertSame($stringItem, $instance->get(0));
2626
self::assertFalse($instance->isEmpty());
2727

2828
self::assertEquals($arrayParams, iterator_to_array($instance, true));
@@ -39,18 +39,18 @@ public function it_can_add_or_remove_elements(): void
3939
$instance = new InnerList($arrayParams);
4040

4141
self::assertCount(2, $instance);
42-
self::assertNotNull($instance->getByIndex(1));
43-
self::assertTrue($instance->hasIndex(1));
42+
self::assertNotNull($instance->get(1));
43+
self::assertTrue($instance->has(1));
4444
self::assertTrue($instance->parameters()->isEmpty());
4545

4646
$instance->remove(1);
4747

4848
self::assertCount(1, $instance);
49-
self::assertFalse($instance->hasIndex(1));
49+
self::assertFalse($instance->has(1));
5050

5151
$instance->push('BarBaz');
5252
$instance->insert(1, );
53-
$element = $instance->getByIndex(1);
53+
$element = $instance->get(1);
5454
self::assertCount(2, $instance);
5555
self::assertInstanceOf(Item::class, $element);
5656
self::assertIsString($element->value());
@@ -117,9 +117,9 @@ public function it_fails_to_return_an_member_with_invalid_index(): void
117117
$this->expectException(InvalidOffset::class);
118118

119119
$instance = new InnerList();
120-
self::assertFalse($instance->hasIndex(3));
120+
self::assertFalse($instance->has(3));
121121

122-
$instance->getByIndex(3);
122+
$instance->get(3);
123123
}
124124

125125
/**

‎src/OrderedList.php

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ public function isEmpty(): bool
5757
return [] === $this->elements;
5858
}
5959

60-
public function hasIndex(int $index): bool
60+
public function has(int $index): bool
6161
{
6262
return null !== $this->filterIndex($index);
6363
}
@@ -73,7 +73,7 @@ private function filterIndex(int $index): int|null
7373
};
7474
}
7575

76-
public function getByIndex(int $index): Item|InnerList
76+
public function get(int $index): Item|InnerList
7777
{
7878
$offset = $this->filterIndex($index);
7979
if (null === $offset) {
@@ -125,7 +125,7 @@ public function insert(
125125

126126
public function replace(int $index, InnerList|Item|ByteSequence|Token|bool|int|float|string $element): void
127127
{
128-
if (!$this->hasIndex($index)) {
128+
if (!$this->has($index)) {
129129
throw InvalidOffset::dueToIndexNotFound($index);
130130
}
131131

‎src/OrderedListTest.php

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ public function it_can_be_instantiated_with_an_collection_of_item(): void
2525
$arrayParams = [$stringItem, $booleanItem];
2626
$instance = new OrderedList($arrayParams);
2727

28-
self::assertSame($stringItem, $instance->getByIndex(0));
28+
self::assertSame($stringItem, $instance->get(0));
2929
self::assertFalse($instance->isEmpty());
3030

3131
self::assertEquals($arrayParams, iterator_to_array($instance, true));
@@ -42,15 +42,15 @@ public function it_can_add_or_remove_elements(): void
4242
$instance = new OrderedList($arrayParams);
4343

4444
self::assertCount(2, $instance);
45-
self::assertSame($booleanItem, $instance->getByIndex(1));
45+
self::assertSame($booleanItem, $instance->get(1));
4646

4747
$instance->remove(1);
4848

4949
self::assertCount(1, $instance);
50-
self::assertFalse($instance->hasIndex(1));
50+
self::assertFalse($instance->has(1));
5151

5252
$instance->push(Item::from('BarBaz'));
53-
$element = $instance->getByIndex(1);
53+
$element = $instance->get(1);
5454

5555
self::assertCount(2, $instance);
5656
self::assertInstanceOf(Item::class, $element);
@@ -108,9 +108,9 @@ public function it_fails_to_return_an_member_with_invalid_index(): void
108108
$this->expectException(InvalidOffset::class);
109109

110110
$instance = new OrderedList();
111-
self::assertFalse($instance->hasIndex(3));
111+
self::assertFalse($instance->has(3));
112112

113-
$instance->getByIndex(3);
113+
$instance->get(3);
114114
}
115115

116116
/**

0 commit comments

Comments
 (0)