Skip to content

Commit bcba04f

Browse files
author
Martin Brecht-Precht
committed
Updated exception messages.
Added doc blocks. Updated readme.
1 parent 12344fa commit bcba04f

File tree

2 files changed

+114
-34
lines changed

2 files changed

+114
-34
lines changed

‎README.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,6 +108,38 @@ will output the following
108108
12. Whether the string contains "ipsum" 1
109109
```
110110

111+
### Exception handling
112+
113+
All methods throw an `\InvalidArgumentException` if misconfigured except `indexOf` and `lastIndexOf` wich returns `null` if the given subtring is not contained by the string to build.
114+
115+
```{php}
116+
use Markenwerk\StringBuilder\StringBuilder;
117+
118+
try {
119+
$builder = new StringBuilder();
120+
121+
$result = $builder->indexOf('a');
122+
fwrite(STDOUT, '1. Result ' . $result . PHP_EOL);
123+
124+
$result = $builder->lastIndexOf('a');
125+
fwrite(STDOUT, '2. Result ' . $result . PHP_EOL);
126+
127+
$result = $builder->charAt(10);
128+
fwrite(STDOUT, '3. Result ' . $result . PHP_EOL);
129+
130+
} catch (\InvalidArgumentException $exception) {
131+
fwrite(STDERR, 'Exception with message ' . $exception->getMessage() . PHP_EOL);
132+
}
133+
```
134+
135+
will output the following
136+
137+
```{txt}
138+
1. Result <NULL>
139+
2. Result <NULL>
140+
Exception with message Position invalid
141+
```
142+
111143
---
112144

113145
## Contribution

‎src/StringBuilder.php‎

Lines changed: 82 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,9 @@ class StringBuilder
1616
private $string;
1717

1818
/**
19-
* SimpleStringBuilder constructor.
19+
* SimpleStringBuilder constructor
20+
*
21+
* Takes an initial string as argument
2022
*
2123
* @param null $string
2224
*/
@@ -29,19 +31,8 @@ public function __construct($string = null)
2931
}
3032

3133
/**
32-
* @param int $position
33-
* @return string
34-
*/
35-
public function charAt($position)
36-
{
37-
$this->validateInteger($position);
38-
if ($position >= $this->length()) {
39-
throw new \InvalidArgumentException('Position invalid.');
40-
}
41-
return mb_substr($this->string, $position, 1);
42-
}
43-
44-
/**
34+
* Appends the given string
35+
*
4536
* @param string $string
4637
* @return $this
4738
*/
@@ -53,6 +44,8 @@ public function append($string)
5344
}
5445

5546
/**
47+
* Prepends the given string
48+
*
5649
* @param string $string
5750
* @return $this
5851
*/
@@ -64,6 +57,8 @@ public function prepend($string)
6457
}
6558

6659
/**
60+
* Inserts the given string at the given position
61+
*
6762
* @param int $position
6863
* @param string $string
6964
* @return $this
@@ -74,13 +69,15 @@ public function insert($position, $string)
7469
->validateInteger($position)
7570
->validateScalar($string);
7671
if ($position >= $this->length()) {
77-
throw new \InvalidArgumentException('Position invalid.');
72+
throw new \InvalidArgumentException('Position invalid');
7873
}
7974
$this->string = mb_substr($this->string, 0, $position) . (string)$string . mb_substr($this->string, $position);
8075
return $this;
8176
}
8277

8378
/**
79+
* Replaces the characters defined by the given position and length with the given string
80+
*
8481
* @param int $position
8582
* @param int $length
8683
* @param string $string
@@ -93,36 +90,40 @@ public function replace($position, $length, $string)
9390
->validateInteger($length)
9491
->validateScalar($string);
9592
if ($position >= $this->length()) {
96-
throw new \InvalidArgumentException('Position invalid.');
93+
throw new \InvalidArgumentException('Position invalid');
9794
}
9895
if ($position + $length > $this->length()) {
99-
throw new \InvalidArgumentException('Length invalid.');
96+
throw new \InvalidArgumentException('Length invalid');
10097
}
10198
$this->string = mb_substr($this->string, 0, $position) . (string)$string . mb_substr($this->string, $position + $length);
10299
return $this;
103100
}
104101

105102
/**
103+
* Sets the character at the given position
104+
*
106105
* @param int $position
107-
* @param string $string
106+
* @param string $character
108107
* @return $this
109108
*/
110-
public function setCharAt($position, $string)
109+
public function setCharAt($position, $character)
111110
{
112111
$this
113112
->validateInteger($position)
114-
->validateScalar($string);
113+
->validateScalar($character);
115114
if ($position >= $this->length()) {
116-
throw new \InvalidArgumentException('Position invalid.');
115+
throw new \InvalidArgumentException('Position invalid');
117116
}
118-
if (mb_strlen((string)$string) !== 1) {
119-
throw new \InvalidArgumentException('Expected a scalar value of length 1.');
117+
if (mb_strlen((string)$character) !== 1) {
118+
throw new \InvalidArgumentException('Expected a scalar value of length 1');
120119
}
121-
$this->string = mb_substr($this->string, 0, $position) . (string)$string . mb_substr($this->string, $position + 1);
120+
$this->string = mb_substr($this->string, 0, $position) . (string)$character . mb_substr($this->string, $position + 1);
122121
return $this;
123122
}
124123

125124
/**
125+
* Reverts the string to build
126+
*
126127
* @return $this
127128
*/
128129
public function reverse()
@@ -137,6 +138,8 @@ public function reverse()
137138
}
138139

139140
/**
141+
* Removes the portion defined by the given position and length
142+
*
140143
* @param int $position
141144
* @param int $length
142145
* @return $this
@@ -147,7 +150,7 @@ public function delete($position, $length = null)
147150
->validateInteger($position)
148151
->validateIntegerOrNull($length);
149152
if ($position >= $this->length()) {
150-
throw new \InvalidArgumentException('Position invalid.');
153+
throw new \InvalidArgumentException('Position invalid');
151154
}
152155
if (is_null($length)) {
153156
$this->string = mb_substr($this->string, 0, $position);
@@ -158,30 +161,38 @@ public function delete($position, $length = null)
158161
}
159162

160163
/**
164+
* Removes the character at the given position
165+
*
161166
* @param int $position
162167
* @return $this
163168
*/
164169
public function deleteCharAt($position)
165170
{
166171
$this->validateInteger($position);
167172
if ($position >= $this->length()) {
168-
throw new \InvalidArgumentException('Position invalid.');
173+
throw new \InvalidArgumentException('Position invalid');
169174
}
170175
$this->string = mb_substr($this->string, 0, $position) . mb_substr($this->string, $position + 1);
171176
return $this;
172177
}
173178

174179
/**
175-
* @param string $string
180+
* Whether the string to build contains the given substring
181+
*
182+
* @param string $substring
176183
* @return bool
177184
*/
178-
public function contains($string)
185+
public function contains($substring)
179186
{
180-
$this->validateScalar($string);
181-
return strpos($this->string, (string)$string) !== false;
187+
$this->validateScalar($substring);
188+
return strpos($this->string, (string)$substring) !== false;
182189
}
183190

184191
/**
192+
* Returns the index of the first occurence of the given substring or null
193+
*
194+
* Takes an optional parameter to begin searching after the given offset
195+
*
185196
* @param string $string
186197
* @param int $offset
187198
* @return int
@@ -197,6 +208,10 @@ public function indexOf($string, $offset = 0)
197208
}
198209

199210
/**
211+
* Returns the index of the last occurence of the given substring or null
212+
*
213+
* Takes an optional parameter to end searching before the given offset
214+
*
200215
* @param string $string
201216
* @param int $offset
202217
* @return int
@@ -212,6 +227,8 @@ public function lastIndexOf($string, $offset = 0)
212227
}
213228

214229
/**
230+
* Returns the number of bytes of the string to build
231+
*
215232
* @return int
216233
*/
217234
public function size()
@@ -220,6 +237,8 @@ public function size()
220237
}
221238

222239
/**
240+
* Returns the number of characters of the string to build
241+
*
223242
* @return int
224243
*/
225244
public function length()
@@ -228,6 +247,23 @@ public function length()
228247
}
229248

230249
/**
250+
* Returns the character at the given position
251+
*
252+
* @param int $position
253+
* @return string
254+
*/
255+
public function charAt($position)
256+
{
257+
$this->validateInteger($position);
258+
if ($position >= $this->length()) {
259+
throw new \InvalidArgumentException('Position invalid');
260+
}
261+
return mb_substr($this->string, $position, 1);
262+
}
263+
264+
/**
265+
* Returns an substring defined by startPosition and length
266+
*
231267
* @param int $startPosition
232268
* @param int $length
233269
* @return string
@@ -238,7 +274,7 @@ public function buildSubstring($startPosition, $length = null)
238274
->validateInteger($startPosition)
239275
->validateIntegerOrNull($length);
240276
if ($startPosition >= $this->length()) {
241-
throw new \InvalidArgumentException('Start position ' . (string)$startPosition . ' invalid.');
277+
throw new \InvalidArgumentException('Start position ' . (string)$startPosition . ' invalid');
242278
}
243279
if (is_null($length)) {
244280
return mb_substr($this->string, $startPosition);
@@ -248,13 +284,25 @@ public function buildSubstring($startPosition, $length = null)
248284
}
249285

250286
/**
287+
* Returns the whole resulting string
288+
*
251289
* @return string
252290
*/
253291
public function build()
254292
{
255293
return $this->string;
256294
}
257295

296+
/**
297+
* Returns the whole resulting string
298+
*
299+
* @return string
300+
*/
301+
public function __toString()
302+
{
303+
return $this->build();
304+
}
305+
258306
/**
259307
* @param mixed $value
260308
* @return $this
@@ -263,7 +311,7 @@ private function validateScalar($value)
263311
{
264312
if (!is_scalar($value)) {
265313
$type = is_object($value) ? get_class($value) : gettype($value);
266-
throw new \InvalidArgumentException('Expected a scalar value. Got ' . $type . '.');
314+
throw new \InvalidArgumentException('Expected a scalar value; got ' . $type);
267315
}
268316
return $this;
269317
}
@@ -276,7 +324,7 @@ private function validateInteger($value)
276324
{
277325
if (!is_int($value)) {
278326
$type = is_object($value) ? get_class($value) : gettype($value);
279-
throw new \InvalidArgumentException('Expected integer. Got ' . $type . '.');
327+
throw new \InvalidArgumentException('Expected integer; got ' . $type);
280328
}
281329
return $this;
282330
}
@@ -301,7 +349,7 @@ private function validateEmpty($value)
301349
{
302350
$value = (string)$value;
303351
if (empty($value)) {
304-
throw new \InvalidArgumentException('Empty string is invalid.');
352+
throw new \InvalidArgumentException('Empty string is invalid');
305353
}
306354
return $this;
307355
}

0 commit comments

Comments
 (0)