fluent-boards / vendor / wpfluent / framework / src / WPFluent / Support / Stringable.php

Stringable.php in FluentBoards – Project Management, Task Management, Goal Tracking, Kanban Board, and, Team Collaboration 1.20, at vendor/wpfluent/framework/src/WPFluent/Support/Stringable.php

1,302 lines 30.1 KB

Raw Download Zip

1	<?php
2
3	namespace FluentBoards\Framework\Support;
4
5	use Closure;
6	use ArrayAccess;
7	use JsonSerializable;
8	use FluentBoards\Framework\Support\DateTime;
9	use FluentBoards\Framework\Support\Tappable;
10	use FluentBoards\Framework\Support\Conditionable;
11	use FluentBoards\Framework\Support\MacroableTrait;
12	use FluentBoards\Framework\Support\HelperFunctionsTrait;
13
14	class Stringable implements JsonSerializable
15	{
16	use Tappable, Conditionable, MacroableTrait, HelperFunctionsTrait;
17
18	/**
19	* The underlying string value.
20	*
21	* @var string
22	*/
23	protected $value;
24
25	/**
26	* Create a new instance of the class.
27	*
28	* @param string $value
29	* @return void
30	*/
31	public function __construct($value = '')
32	{
33	$this->value = (string) $value;
34	}
35
36	/**
37	* Makes an acronum from a string of words
38	*
39	* @param string $delimiter
40	* @return self
41	*/
42	public function acronym(string $delimiter = '')
43	{
44	return new static(Str::acronym($this->value, $delimiter));
45	}
46
47	/**
48	* Return the remainder of a string after the first occurrence of a given value.
49	*
50	* @param string $search
51	* @return static
52	*/
53	public function after($search)
54	{
55	return new static(Str::after($this->value, $search));
56	}
57
58	/**
59	* Return the remainder of a string after the last occurrence of a given value.
60	*
61	* @param string $search
62	* @return static
63	*/
64	public function afterLast($search)
65	{
66	return new static(Str::afterLast($this->value, $search));
67	}
68
69	/**
70	* Append the given values to the string.
71	*
72	* @param array\|string ...$values
73	* @return static
74	*/
75	public function append(...$values)
76	{
77	return new static($this->value.implode('', $values));
78	}
79
80	/**
81	* Append a new line to the string.
82	*
83	* @param int $count
84	* @return $this
85	*/
86	public function newLine($count = 1)
87	{
88	return $this->append(str_repeat(PHP_EOL, $count));
89	}
90
91	/**
92	* Transliterate a UTF-8 value to ASCII.
93	*
94	* @param string $language
95	* @return static
96	*/
97	public function ascii($language = 'en')
98	{
99	return new static(Str::ascii($this->value, $language));
100	}
101
102	/**
103	* Checks if the word(s) are in capitalized form.
104	*
105	* @param boolean $onlyFirst if true, checks only the first charatcer
106	* @return boolean
107	*/
108	public function isCapitalized($onlyFirst = false)
109	{
110	return Str::isCapitalized($this->value, $onlyFirst);
111	}
112
113	/**
114	* Checks if the first character is in capital form.
115	*
116	* @return boolean
117	*/
118	public function isCapital()
119	{
120	return $this->isCapitalized(true);
121	}
122
123	/**
124	* Checks if the chracters are in upper case
125	*
126	* @return boolean
127	*/
128	public static function isUpper()
129	{
130	return Str::isUpper($this->value);
131	}
132
133	/**
134	* Checks if the chracters are in lower case
135	*
136	* @return boolean
137	*/
138	public static function isLower()
139	{
140	return Str::isLower($this->value);
141	}
142
143	/**
144	* Checks if two words sounds alike
145	*
146	* @param string $str
147	*
148	* @return bool
149	*/
150	public function soundsAlike($str)
151	{
152	return Str::soundsAlike($this->value, $str);
153	}
154
155	/**
156	* Checks if two words are similar
157	*
158	* @param string $str
159	* @param int $accuracy
160	*
161	* @return bool
162	*/
163	public function isSimilar($str, $accuracy = 50)
164	{
165	return Str::isSimilar($this->value, $str, $accuracy);
166	}
167
168	/**
169	* Checks if two words are similar
170	*
171	* @param string $str
172	*
173	* @return bool
174	*/
175	public function similarityOf($str)
176	{
177	return Str::similarityOf($this->value, $str);
178	}
179
180	/**
181	* Get the trailing name component of the path.
182	*
183	* @param string $suffix
184	* @return static
185	*/
186	public function basename($suffix = '')
187	{
188	return new static(basename($this->value, $suffix));
189	}
190
191	/**
192	* Get the character at the specified index.
193	*
194	* @param int $index
195	* @return string\|false
196	*/
197	public function charAt($index)
198	{
199	return Str::charAt($this->value, $index);
200	}
201
202	/**
203	* Get the basename of the class path.
204	*
205	* @return static
206	*/
207	public function classBasename()
208	{
209	return new static(static::classBasename($this->value));
210	}
211
212	/**
213	* Get the portion of a string before the first occurrence of a given value.
214	*
215	* @param string $search
216	* @return static
217	*/
218	public function before($search)
219	{
220	return new static(Str::before($this->value, $search));
221	}
222
223	/**
224	* Get the portion of a string before the last occurrence of a given value.
225	*
226	* @param string $search
227	* @return static
228	*/
229	public function beforeLast($search)
230	{
231	return new static(Str::beforeLast($this->value, $search));
232	}
233
234	/**
235	* Get the portion of a string between two given values.
236	*
237	* @param string $from
238	* @param string $to
239	* @return static
240	*/
241	public function between($from, $to)
242	{
243	return new static(Str::between($this->value, $from, $to));
244	}
245
246	/**
247	* Get the smallest possible portion of a string between two given values.
248	*
249	* @param string $from
250	* @param string $to
251	* @return static
252	*/
253	public function betweenFirst($from, $to)
254	{
255	return new static(Str::betweenFirst($this->value, $from, $to));
256	}
257
258	/**
259	* Convert a value to camel case.
260	*
261	* @return static
262	*/
263	public function camel()
264	{
265	return new static(Str::camel($this->value));
266	}
267
268	/**
269	* Determine if a given string contains a given substring.
270	*
271	* @param string\|iterable<string> $needles
272	* @param bool $ignoreCase
273	* @return bool
274	*/
275	public function contains($needles, $ignoreCase = false)
276	{
277	return Str::contains($this->value, $needles, $ignoreCase);
278	}
279
280	/**
281	* Determine if a given string contains all array values.
282	*
283	* @param iterable<string> $needles
284	* @param bool $ignoreCase
285	* @return bool
286	*/
287	public function containsAll($needles, $ignoreCase = false)
288	{
289	return Str::containsAll($this->value, $needles, $ignoreCase);
290	}
291
292	/**
293	* Get the parent directory's path.
294	*
295	* @param int $levels
296	* @return static
297	*/
298	public function dirname($levels = 1)
299	{
300	return new static(dirname($this->value, $levels));
301	}
302
303	/**
304	* Determine if a given string ends with a given substring.
305	*
306	* @param string\|iterable<string> $needles
307	* @return bool
308	*/
309	public function endsWith($needles)
310	{
311	return Str::endsWith($this->value, $needles);
312	}
313
314	/**
315	* Determine if the string is an exact match with the given value.
316	*
317	* @param \FluentBoards\Framework\Support\Stringable\|string $value
318	* @return bool
319	*/
320	public function exactly($value)
321	{
322	if ($value instanceof Stringable) {
323	$value = $value->toString();
324	}
325
326	return $this->value === $value;
327	}
328
329	/**
330	* Explode the string into an array.
331	*
332	* @param string $delimiter
333	* @param int $limit
334	* @return \FluentBoards\Framework\Support\Collection<int, string>
335	*/
336	public function explode($delimiter, $limit = PHP_INT_MAX)
337	{
338	return Helper::collect(explode($delimiter, $this->value, $limit));
339	}
340
341	/**
342	* Split a string using a regular expression or by length.
343	*
344	* @param string\|int $pattern
345	* @param int $limit
346	* @param int $flags
347	* @return \FluentBoards\Framework\Support\Collection<int, string>
348	*/
349	public function split($pattern, $limit = -1, $flags = 0)
350	{
351	if (filter_var($pattern, FILTER_VALIDATE_INT) !== false) {
352	return Helper::collect(mb_str_split($this->value, $pattern));
353	}
354
355	$segments = preg_split($pattern, $this->value, $limit, $flags);
356
357	return ! empty($segments) ? Helper::collect($segments) : Helper::collect();
358	}
359
360	/**
361	* Cap a string with a single instance of a given value.
362	*
363	* @param string $cap
364	* @return static
365	*/
366	public function finish($cap)
367	{
368	return new static(Str::finish($this->value, $cap));
369	}
370
371	/**
372	* Determine if a given string matches a given pattern.
373	*
374	* @param string\|iterable<string> $pattern
375	* @return bool
376	*/
377	public function is($pattern)
378	{
379	return Str::is($pattern, $this->value);
380	}
381
382	/**
383	* Determine if a given string is 7 bit ASCII.
384	*
385	* @return bool
386	*/
387	public function isAscii()
388	{
389	return Str::isAscii($this->value);
390	}
391
392	/**
393	* Determine if a given string is valid JSON.
394	*
395	* @return bool
396	*/
397	public function isJson()
398	{
399	return Str::isJson($this->value);
400	}
401
402	/**
403	* Determine if a given value is a valid URL.
404	*
405	* @return bool
406	*/
407	public function isUrl()
408	{
409	return Str::isUrl($this->value);
410	}
411
412	/**
413	* Determine if a given string is a valid UUID.
414	*
415	* @return bool
416	*/
417	public function isUuid()
418	{
419	return Str::isUuid($this->value);
420	}
421
422	/**
423	* Determine if the given string is empty.
424	*
425	* @return bool
426	*/
427	public function isEmpty()
428	{
429	return $this->value === '';
430	}
431
432	/**
433	* Determine if the given string is not empty.
434	*
435	* @return bool
436	*/
437	public function isNotEmpty()
438	{
439	return ! $this->isEmpty();
440	}
441
442	/**
443	* Convert a string to kebab case.
444	*
445	* @return static
446	*/
447	public function kebab()
448	{
449	return new static(Str::kebab($this->value));
450	}
451
452	/**
453	* Return the length of the given string.
454	*
455	* @param string\|null $encoding
456	* @return int
457	*/
458	public function length($encoding = null)
459	{
460	return Str::length($this->value, $encoding);
461	}
462
463	/**
464	* Limit the number of characters in a string.
465	*
466	* @param int $limit
467	* @param string $end
468	* @return static
469	*/
470	public function limit($limit = 100, $end = '...')
471	{
472	return new static(Str::limit($this->value, $limit, $end));
473	}
474
475	/**
476	* Convert the given string to lower-case.
477	*
478	* @return static
479	*/
480	public function lower()
481	{
482	return new static(Str::lower($this->value));
483	}
484
485	/**
486	* Masks a portion of a string with a repeated character.
487	*
488	* @param string $character
489	* @param int $index
490	* @param int\|null $length
491	* @param string $encoding
492	* @return static
493	*/
494	public function mask($character, $index, $length = null, $encoding = 'UTF-8')
495	{
496	return new static(Str::mask($this->value, $character, $index, $length, $encoding));
497	}
498
499	/**
500	* Get the string matching the given pattern.
501	*
502	* @param string $pattern
503	* @return static
504	*/
505	public function match($pattern)
506	{
507	return new static(Str::match($pattern, $this->value));
508	}
509
510	/**
511	* Determine if a given string matches a given pattern.
512	*
513	* @param string\|iterable<string> $pattern
514	* @return bool
515	*/
516	public function isMatch($pattern)
517	{
518	return Str::isMatch($pattern, $this->value);
519	}
520
521	/**
522	* Get the string matching the given pattern.
523	*
524	* @param string $pattern
525	* @return \FluentBoards\Framework\Support\Collection
526	*/
527	public function matchAll($pattern)
528	{
529	return Str::matchAll($pattern, $this->value);
530	}
531
532	/**
533	* Determine if the string matches the given pattern.
534	*
535	* @param string $pattern
536	* @return bool
537	*/
538	public function test($pattern)
539	{
540	return $this->isMatch($pattern);
541	}
542
543	/**
544	* Pad both sides of the string with another.
545	*
546	* @param int $length
547	* @param string $pad
548	* @return static
549	*/
550	public function padBoth($length, $pad = ' ')
551	{
552	return new static(Str::padBoth($this->value, $length, $pad));
553	}
554
555	/**
556	* Pad the left side of the string with another.
557	*
558	* @param int $length
559	* @param string $pad
560	* @return static
561	*/
562	public function padLeft($length, $pad = ' ')
563	{
564	return new static(Str::padLeft($this->value, $length, $pad));
565	}
566
567	/**
568	* Pad the right side of the string with another.
569	*
570	* @param int $length
571	* @param string $pad
572	* @return static
573	*/
574	public function padRight($length, $pad = ' ')
575	{
576	return new static(Str::padRight($this->value, $length, $pad));
577	}
578
579	/**
580	* Parse a Class@method style callback into class and method.
581	*
582	* @param string\|null $default
583	* @return array<int, string\|null>
584	*/
585	public function parseCallback($default = null)
586	{
587	return Str::parseCallback($this->value, $default);
588	}
589
590	/**
591	* Call the given callback and return a new string.
592	*
593	* @param callable $callback
594	* @return static
595	*/
596	public function pipe(callable $callback)
597	{
598	return new static($callback($this));
599	}
600
601	/**
602	* Get the plural form of an English word.
603	*
604	* @param int\|array\|\Countable $count
605	* @return static
606	*/
607	public function plural($count = 2)
608	{
609	return new static(Str::plural($this->value, $count));
610	}
611
612	/**
613	* Pluralize the last word of an English, studly caps case string.
614	*
615	* @param int\|array\|\Countable $count
616	* @return static
617	*/
618	public function pluralStudly($count = 2)
619	{
620	return new static(Str::pluralStudly($this->value, $count));
621	}
622
623	/**
624	* Prepend the given values to the string.
625	*
626	* @param string ...$values
627	* @return static
628	*/
629	public function prepend(...$values)
630	{
631	return new static(implode('', $values).$this->value);
632	}
633
634	/**
635	* Remove any occurrence of the given string in the subject.
636	*
637	* @param string\|iterable<string> $search
638	* @param bool $caseSensitive
639	* @return static
640	*/
641	public function remove($search, $caseSensitive = true)
642	{
643	return new static(Str::remove($search, $this->value, $caseSensitive));
644	}
645
646	/**
647	* Reverse the string.
648	*
649	* @return static
650	*/
651	public function reverse()
652	{
653	return new static(Str::reverse($this->value));
654	}
655
656	/**
657	* Repeat the string.
658	*
659	* @param int $times
660	* @return static
661	*/
662	public function repeat(int $times)
663	{
664	return new static(str_repeat($this->value, $times));
665	}
666
667	/**
668	* Replace the given value in the given string.
669	*
670	* @param string\|iterable<string> $search
671	* @param string\|iterable<string> $replace
672	* @param bool $caseSensitive
673	* @return static
674	*/
675	public function replace($search, $replace, $caseSensitive = true)
676	{
677	return new static(Str::replace($search, $replace, $this->value, $caseSensitive));
678	}
679
680	/**
681	* Replace a given value in the string sequentially with an array.
682	*
683	* @param string $search
684	* @param iterable<string> $replace
685	* @return static
686	*/
687	public function replaceArray($search, $replace)
688	{
689	return new static(Str::replaceArray($search, $replace, $this->value));
690	}
691
692	/**
693	* Replace the first occurrence of a given value in the string.
694	*
695	* @param string $search
696	* @param string $replace
697	* @return static
698	*/
699	public function replaceFirst($search, $replace)
700	{
701	return new static(Str::replaceFirst($search, $replace, $this->value));
702	}
703
704	/**
705	* Replace the last occurrence of a given value in the string.
706	*
707	* @param string $search
708	* @param string $replace
709	* @return static
710	*/
711	public function replaceLast($search, $replace)
712	{
713	return new static(Str::replaceLast($search, $replace, $this->value));
714	}
715
716	/**
717	* Replace the patterns matching the given regular expression.
718	*
719	* @param string $pattern
720	* @param \Closure\|string $replace
721	* @param int $limit
722	* @return static
723	*/
724	public function replaceMatches($pattern, $replace, $limit = -1)
725	{
726	if ($replace instanceof Closure) {
727	return new static(preg_replace_callback($pattern, $replace, $this->value, $limit));
728	}
729
730	return new static(preg_replace($pattern, $replace, $this->value, $limit));
731	}
732
733	/**
734	* Parse input from a string to a collection, according to a format.
735	*
736	* @param string $format
737	* @return \FluentBoards\Framework\Support\Collection
738	*/
739	public function scan($format)
740	{
741	return Helper::collect(sscanf($this->value, $format));
742	}
743
744	/**
745	* Remove all "extra" blank space from the given string.
746	*
747	* @return static
748	*/
749	public function squish()
750	{
751	return new static(Str::squish($this->value));
752	}
753
754	/**
755	* Begin a string with a single instance of a given value.
756	*
757	* @param string $prefix
758	* @return static
759	*/
760	public function start($prefix)
761	{
762	return new static(Str::start($this->value, $prefix));
763	}
764
765	/**
766	* Strip HTML and PHP tags from the given string.
767	*
768	* @param string $allowedTags
769	* @return static
770	*/
771	public function stripTags($allowedTags = null)
772	{
773	return new static(strip_tags($this->value, $allowedTags));
774	}
775
776	/**
777	* Convert the given string to upper-case.
778	*
779	* @return static
780	*/
781	public function upper()
782	{
783	return new static(Str::upper($this->value));
784	}
785
786	/**
787	* Convert the given string to title case.
788	*
789	* @return static
790	*/
791	public function title()
792	{
793	return new static(Str::title($this->value));
794	}
795
796	/**
797	* Convert the given string to title case for each word.
798	*
799	* @return static
800	*/
801	public function headline()
802	{
803	return new static(Str::headline($this->value));
804	}
805
806	/**
807	* Get the singular form of an English word.
808	*
809	* @return static
810	*/
811	public function singular()
812	{
813	return new static(Str::singular($this->value));
814	}
815
816	/**
817	* Generate a URL friendly "slug" from a given string.
818	*
819	* @param string $separator
820	* @param string\|null $language
821	* @param array<string, string> $dictionary
822	* @return static
823	*/
824	public function slug($separator = '-', $language = 'en', $dictionary = ['@' => 'at'])
825	{
826	return new static(Str::slug($this->value, $separator, $language, $dictionary));
827	}
828
829	/**
830	* Convert a string to snake case.
831	*
832	* @param string $delimiter
833	* @return static
834	*/
835	public function snake($delimiter = '_')
836	{
837	return new static(Str::snake($this->value, $delimiter));
838	}
839
840	/**
841	* Determine if a given string starts with a given substring.
842	*
843	* @param string\|iterable<string> $needles
844	* @return bool
845	*/
846	public function startsWith($needles)
847	{
848	return Str::startsWith($this->value, $needles);
849	}
850
851	/**
852	* Convert a value to studly caps case.
853	*
854	* @return static
855	*/
856	public function studly()
857	{
858	return new static(Str::studly($this->value));
859	}
860
861	/**
862	* Returns the portion of the string specified by the start and length parameters.
863	*
864	* @param int $start
865	* @param int\|null $length
866	* @param string $encoding
867	* @return static
868	*/
869	public function substr($start, $length = null, $encoding = 'UTF-8')
870	{
871	return new static(Str::substr($this->value, $start, $length, $encoding));
872	}
873
874	/**
875	* Returns the number of substring occurrences.
876	*
877	* @param string $needle
878	* @param int $offset
879	* @param int\|null $length
880	* @return int
881	*/
882	public function substrCount($needle, $offset = 0, $length = null)
883	{
884	return Str::substrCount($this->value, $needle, $offset, $length);
885	}
886
887	/**
888	* Replace text within a portion of a string.
889	*
890	* @param string\|string[] $replace
891	* @param int\|int[] $offset
892	* @param int\|int[]\|null $length
893	* @return static
894	*/
895	public function substrReplace($replace, $offset = 0, $length = null)
896	{
897	return new static(Str::substrReplace($this->value, $replace, $offset, $length));
898	}
899
900	/**
901	* Swap multiple keywords in a string with other keywords.
902	*
903	* @param array $map
904	* @return static
905	*/
906	public function swap(array $map)
907	{
908	return new static(strtr($this->value, $map));
909	}
910
911	/**
912	* Trim the string of the given characters.
913	*
914	* @param string $characters
915	* @return static
916	*/
917	public function trim($characters = null)
918	{
919	return new static(trim(...array_merge([$this->value], func_get_args())));
920	}
921
922	/**
923	* Left trim the string of the given characters.
924	*
925	* @param string $characters
926	* @return static
927	*/
928	public function ltrim($characters = null)
929	{
930	return new static(ltrim(...array_merge([$this->value], func_get_args())));
931	}
932
933	/**
934	* Right trim the string of the given characters.
935	*
936	* @param string $characters
937	* @return static
938	*/
939	public function rtrim($characters = null)
940	{
941	return new static(rtrim(...array_merge([$this->value], func_get_args())));
942	}
943
944	/**
945	* Make a string's first character lowercase.
946	*
947	* @return static
948	*/
949	public function lcfirst()
950	{
951	return new static(Str::lcfirst($this->value));
952	}
953
954	/**
955	* Make a string's first character uppercase.
956	*
957	* @return static
958	*/
959	public function ucfirst()
960	{
961	return new static(Str::ucfirst($this->value));
962	}
963
964	/**
965	* Split a string by uppercase characters.
966	*
967	* @return \FluentBoards\Framework\Support\Collection<int, string>
968	*/
969	public function ucsplit()
970	{
971	return Helper::collect(Str::ucsplit($this->value));
972	}
973
974	/**
975	* Execute the given callback if the string contains a given substring.
976	*
977	* @param string\|iterable<string> $needles
978	* @param callable $callback
979	* @param callable\|null $default
980	* @return static
981	*/
982	public function whenContains($needles, $callback, $default = null)
983	{
984	return $this->when($this->contains($needles), $callback, $default);
985	}
986
987	/**
988	* Execute the given callback if the string contains all array values.
989	*
990	* @param iterable<string> $needles
991	* @param callable $callback
992	* @param callable\|null $default
993	* @return static
994	*/
995	public function whenContainsAll(array $needles, $callback, $default = null)
996	{
997	return $this->when($this->containsAll($needles), $callback, $default);
998	}
999
1000	/**
1001	* Execute the given callback if the string is empty.
1002	*
1003	* @param callable $callback
1004	* @param callable\|null $default
1005	* @return static
1006	*/
1007	public function whenEmpty($callback, $default = null)
1008	{
1009	return $this->when($this->isEmpty(), $callback, $default);
1010	}
1011
1012	/**
1013	* Execute the given callback if the string is not empty.
1014	*
1015	* @param callable $callback
1016	* @param callable\|null $default
1017	* @return static
1018	*/
1019	public function whenNotEmpty($callback, $default = null)
1020	{
1021	return $this->when($this->isNotEmpty(), $callback, $default);
1022	}
1023
1024	/**
1025	* Execute the given callback if the string ends with a given substring.
1026	*
1027	* @param string\|iterable<string> $needles
1028	* @param callable $callback
1029	* @param callable\|null $default
1030	* @return static
1031	*/
1032	public function whenEndsWith($needles, $callback, $default = null)
1033	{
1034	return $this->when($this->endsWith($needles), $callback, $default);
1035	}
1036
1037	/**
1038	* Execute the given callback if the string is an exact match with the given value.
1039	*
1040	* @param string $value
1041	* @param callable $callback
1042	* @param callable\|null $default
1043	* @return static
1044	*/
1045	public function whenExactly($value, $callback, $default = null)
1046	{
1047	return $this->when($this->exactly($value), $callback, $default);
1048	}
1049
1050	/**
1051	* Execute the given callback if the string is not an exact match with the given value.
1052	*
1053	* @param string $value
1054	* @param callable $callback
1055	* @param callable\|null $default
1056	* @return static
1057	*/
1058	public function whenNotExactly($value, $callback, $default = null)
1059	{
1060	return $this->when(! $this->exactly($value), $callback, $default);
1061	}
1062
1063	/**
1064	* Execute the given callback if the string matches a given pattern.
1065	*
1066	* @param string\|iterable<string> $pattern
1067	* @param callable $callback
1068	* @param callable\|null $default
1069	* @return static
1070	*/
1071	public function whenIs($pattern, $callback, $default = null)
1072	{
1073	return $this->when($this->is($pattern), $callback, $default);
1074	}
1075
1076	/**
1077	* Execute the given callback if the string is 7 bit ASCII.
1078	*
1079	* @param callable $callback
1080	* @param callable\|null $default
1081	* @return static
1082	*/
1083	public function whenIsAscii($callback, $default = null)
1084	{
1085	return $this->when($this->isAscii(), $callback, $default);
1086	}
1087
1088	/**
1089	* Execute the given callback if the string is a valid UUID.
1090	*
1091	* @param callable $callback
1092	* @param callable\|null $default
1093	* @return static
1094	*/
1095	public function whenIsUuid($callback, $default = null)
1096	{
1097	return $this->when($this->isUuid(), $callback, $default);
1098	}
1099
1100	/**
1101	* Execute the given callback if the string starts with a given substring.
1102	*
1103	* @param string\|iterable<string> $needles
1104	* @param callable $callback
1105	* @param callable\|null $default
1106	* @return static
1107	*/
1108	public function whenStartsWith($needles, $callback, $default = null)
1109	{
1110	return $this->when($this->startsWith($needles), $callback, $default);
1111	}
1112
1113	/**
1114	* Execute the given callback if the string matches the given pattern.
1115	*
1116	* @param string $pattern
1117	* @param callable $callback
1118	* @param callable\|null $default
1119	* @return static
1120	*/
1121	public function whenTest($pattern, $callback, $default = null)
1122	{
1123	return $this->when($this->test($pattern), $callback, $default);
1124	}
1125
1126	/**
1127	* Limit the number of words in a string.
1128	*
1129	* @param int $words
1130	* @param string $end
1131	* @return static
1132	*/
1133	public function words($words = 100, $end = '...')
1134	{
1135	return new static(Str::words($this->value, $words, $end));
1136	}
1137
1138	/**
1139	* Get the number of words a string contains.
1140	*
1141	* @param string\|null $characters
1142	* @return int
1143	*/
1144	public function wordCount($characters = null)
1145	{
1146	return Str::wordCount($this->value, $characters);
1147	}
1148
1149	/**
1150	* Wrap a string to a given number of characters.
1151	*
1152	* @param int $characters
1153	* @param string $break
1154	* @param bool $cutLongWords
1155	* @return static
1156	*/
1157	public function wordWrap($characters = 75, $break = "\n", $cutLongWords = false)
1158	{
1159	return new static(Str::wordWrap($this->value, $characters, $break, $cutLongWords));
1160	}
1161
1162	/**
1163	* Wrap the string with the given strings.
1164	*
1165	* @param string $before
1166	* @param string\|null $after
1167	* @return static
1168	*/
1169	public function wrap($before, $after = null)
1170	{
1171	return new static(Str::wrap($this->value, $before, $after));
1172	}
1173
1174	/**
1175	* Dump the string.
1176	*
1177	* @return $this
1178	*/
1179	public function dump()
1180	{
1181	echo "<pre>";
1182	print_r($this->value);
1183	echo "</pre>";
1184
1185	return $this;
1186	}
1187
1188	/**
1189	* Dump the string and end the script.
1190	*
1191	* @return never
1192	*/
1193	public function dd()
1194	{
1195	$this->dump();
1196
1197	exit(1);
1198	}
1199
1200	/**
1201	* Get the underlying string value.
1202	*
1203	* @return string
1204	*/
1205	public function value()
1206	{
1207	return $this->toString();
1208	}
1209
1210	/**
1211	* Get the underlying string value.
1212	*
1213	* @return string
1214	*/
1215	public function toString()
1216	{
1217	return $this->value;
1218	}
1219
1220	/**
1221	* Get the underlying string value as an integer.
1222	*
1223	* @return int
1224	*/
1225	public function toInteger()
1226	{
1227	return intval($this->value);
1228	}
1229
1230	/**
1231	* Get the underlying string value as a float.
1232	*
1233	* @return float
1234	*/
1235	public function toFloat()
1236	{
1237	return floatval($this->value);
1238	}
1239
1240	/**
1241	* Get the underlying string value as a boolean.
1242	*
1243	* Returns true when value is "1", "true", "on", and "yes". Otherwise, returns false.
1244	*
1245	* @return bool
1246	*/
1247	public function toBoolean()
1248	{
1249	return filter_var($this->value, FILTER_VALIDATE_BOOLEAN);
1250	}
1251
1252	/**
1253	* Get the underlying string value as a Carbon instance.
1254	*
1255	* @param string\|null $format
1256	* @param string\|null $tz
1257	* @return \FluentBoards\Framework\Support\DateTime
1258	*
1259	* @throws \InvalidArgumentException
1260	*/
1261	public function toDate($format = null, $tz = null)
1262	{
1263	if (is_null($format)) {
1264	return DateTime::parse($this->value, $tz);
1265	}
1266
1267	return DateTime::createFromFormat($format, $this->value, $tz);
1268	}
1269
1270	/**
1271	* Convert the object to a string when JSON encoded.
1272	*
1273	* @return string
1274	*/
1275	#[\ReturnTypeWillChange]
1276	public function jsonSerialize()
1277	{
1278	return $this->__toString();
1279	}
1280
1281	/**
1282	* Proxy dynamic properties onto methods.
1283	*
1284	* @param string $key
1285	* @return mixed
1286	*/
1287	public function __get($key)
1288	{
1289	return $this->{$key}();
1290	}
1291
1292	/**
1293	* Get the raw string value.
1294	*
1295	* @return string
1296	*/
1297	public function __toString()
1298	{
1299	return (string) $this->value;
1300	}
1301	}
1302