immutable

#Str

This class gives a higher api to manipulate strings.

#::of()

This named constructor will create a new object for the given string.

use Innmind\Immutable\Str;

$str = Str::of('whatever');
$str instanceof Str; // true

You can also specify the encoding to use for manupilating the string.

$str = Str::of('👋', 'UTF-8');
$str->length(); // 1
Str::of('👋')->length(); // 4

#->toString()

This will return the encapsulated string.

Str::of('whataver')->toString(); // 'whatever'

#->encoding()

This will return the encoding used to manipulate the string.

Str::of('', 'UTF-8')->encoding()->equals(Str::of('UTF-8')); // true

#->toEncoding()

Use this method to change the encoding used to manipulate the string.

Str::of('👋')->toEncoding('UTF-8');

#->split()

Use this method to split a string into a Sequence of smaller strings.

Str::of('foo')->split()->equals(Sequence::of(
    Str::of('f'),
    Str::of('o'),
    Str::of('o'),
));
Str::of('foo|bar')->split('|')->equals(Sequence::of(
    Str::of('foo'),
    Str::of('bar'),
));

#->chunk()

This will create a Sequence of strings of the given size.

Str::of('foobar')->chunk(2)->equals(Sequence::of(
    Str::class,
    Str::of('fo'),
    Str::of('ob'),
    Str::of('ar'),
));

#->position()

Returns the position of the searched string in the original string.

Str::of('foobar')->position('ob'); // Maybe::just(2)
Str::of('foobar')->position('unknown'); // Maybe::nothing()

#->replace()

Replace the searched string by its replacement.

Str::of('foobar')->replace('ob', 'bo')->equals(Str::of('foboar')); // true

#->toUpper()

Return the string in upper case.

Str::of('foobar')->toUpper()->equals(Str::of('FOOBAR'));

#->toLower()

Return the string in lower case.

Str::of('FOOBAR')->toUpper()->equals(Str::of('foobar'));

#->length()

Returns the length of the string depending on the used encoding.

Str::of('👋', 'UTF-8')->length(); // 1
Str::of('👋')->length(); // 4

#->empty()

Check if the string is an empty string.

Str::of('')->empty(); // true
Str::of('', 'UTF-8')->empty(); // true
Str::of('null')->empty(); // false
Str::of('0')->empty(); // false
Str::of('false')->empty(); // false

#->reverse()

Reverse the order of the characters.

Str::of('foobar')->reverse()->equals(Str::of('raboof'));

#->rightPad()

Add the given string to the right of the string in order of the new string to be at least of the given size.

Str::of('Alien')->rightPad(10)->equals(Str::of('Alien     '));
Str::of('Alien')->rightPad(10, '_')->equals(Str::of('Alien_____'));
Str::of('Alien')->rightPad(3, '_')->equals(Str::of('Alien'));

#->leftPad()

Add the given string to the left of the string in order of the new string to be at least of the given size.

Str::of('Alien')->leftPad(10)->equals(Str::of('     Alien'));
Str::of('Alien')->leftPad(10, '_')->equals(Str::of('_____Alien'));
Str::of('Alien')->leftPad(3, '_')->equals(Str::of('Alien'));

#->uniPad()

Add the given string to both sides of the string in order of the new string to be at least of the given size.

Str::of('Alien')->uniPad(10,)->equals(Str::of('  Alien   '));
Str::of('Alien')->uniPad(10, '_')->equals(Str::of('__Alien___'));

#->repeat()

Repeat the original string the number of given times.

Str::of('foo')->repeat(3)->equals(Str::of('foofoofoo'));

#->stripSlashes()

Same behaviour as the native stripslashes function.

#->stripCSlashes()

Same behaviour as the native stripcslashes function.

#->wordCount()

Counts the number in the string.

Str::of('foo bar')->wordCount(); // 2

#->words()

The list of words with their position.

Str::of('foo bar')->words()->equals(
    Map::of(
        [0, Str::of('foo')],
        [4, Str::of('bar')],
    ),
);

#->pregSplit()

Split the string using a regular expression.

Str::of('hypertext language, programming')->pregSplit('/[\s,]+/')->equals(
    Sequence::of(
        Str::of('hypertext'),
        Str::of('language'),
        Str::of('programming'),
    ),
);

#->matches()

Check if the string match the given regular expression.

Str::of('abcdef')->matches('/^a/'); // true
Str::of('abcdef')->matches('/^b/'); // false

#->capture

Return a map of the elements matching the regular expression.

Str::of('http://www.php.net/index.html')->capture('@^(?:http://)?(?P[^/]+)@i')->equals(
    Map::of(
        [0, Str::of('http://www.php.net')],
        [1, Str::of('www.php.net')],
        ['host', Str::of('www.php.net')],
    ),
);

#->pregReplace()

Replace part of the string by using a regular expression.

Str::of('April 15, 2003')->pregReplace('/(\w+) (\d+), (\d+)/i', '${1}1,$3')->equals(
    Str::of('April1,2003'),
);

#->substring()

Return part of the string.

Str::of('foobar')->substring(3)->equals(Str::of('bar')); // true
Str::of('foobar')->substring(3, 1)->equals(Str::of('b')); // true

#->take()

Return a new string with only the n first characters.

Str::of('foobar')->take(3)->equals(Str::of('foo')); // true

#->takeEnd()

Return a new string with only the n last characters.

Str::of('foobar')->takeEnd(3)->equals(Str::of('bar')); // true

#->drop()

Return a new string without the n first characters.

Str::of('foobar')->drop(3)->equals(Str::of('bar')); // true

#->dropEnd()

Return a new string without the n last characters.

Str::of('foobar')->dropEnd(3)->equals(Str::of('foo')); // true

#->sprintf()

Return a formatted string.

Str::of('%s %s')->sprintf('hello', 'world')->equals(Str::of('hello world')); // true

#->ucfirst()

Return the string with the first letter as uppercase.

Str::of('foobar')->ucfirst()->equals(Str::of('Foobar'));

#->camelize()

Return a CamelCase representation of the string.

Str::of('foo bar_baz')->camelize()->equals(Str::of('fooBarBaz'));

#->append()

Append a string at the end of the current one.

Str::of('foo')->append('bar')->equals(Str::of('foobar')); // true

#->prepend()

Prepend a string at the beginning of the current one.

Str::of('foo')->prepend('bar')->equals(Str::of('barfoo')); // true

#->equals()

Check if the 2 strings are equal.

Str::of('foo')->equals(Str::of('foo')); // true
Str::of('foo')->equals(Str::of('foo', 'UTF-8')); // true
Str::of('foo')->equals(Str::of('bar')); // false

#->trim()

Remove whitespace characters from both ends of the string.

Str::of('  foo ')->trim()->equals(Str::of('foo')); // true

#->contains()

Check if the string contains another string.

Str::of('foobar')->contains('ob'); // true
Str::of('foobar')->contains('baz'); // false

#->startsWith()

Check if the current string starts with the given string.

Str::of('foobar')->startsWith('foo'); // true
Str::of('foobar')->startsWith('bar'); // false

#->endsWith()

Check if the current string ends with the given string.

Str::of('foobar')->endsWith('bar'); // true
Str::of('foobar')->endsWith('foo'); // false

#->join()

This method will create a new Str object with all the values from the set/sequence separated by the vlue of the original string.

Str::of('|')
    ->join(Sequence::of('foo', 'bar', 'baz'))
    ->equals(Str::of('foo|bar|baz')); // true

#->map()

This function will create a new Str object with the value modified by the given function.

$str = Str::of('foo|bar|baz')->map(
    fn(string $value, string $encoding): string => \implode(',', \explode('|', $string)),
);
$str->equals(Str::of('foo,bar,baz')); // true

#->flatMap()

This is similar to ->map() but instead of the function returning a value it must return a new Str object.

$str = Str::of('foo|bar|baz')->flatMap(
    fn(string $value, string $encoding): Str => Str::of(',')->join(Sequence::of(...\explode('|', $string))),
);
$str->equals(Str::of('foo,bar,baz')); // true

#->maybe()

The is a shortcut method, the 2 examples below do the same thing.

Str::of('foobar')->maybe(static fn($str) => $str->startsWith('foo')); // Maybe
Maybe::of(Str::of('foobar'))->filter(static fn($str) => $str->startsWith('foo')); // Maybe