Final Class Yiisoft\Strings\StringHelper

                public static function base64UrlDecode(string $input): string
{
    return base64_decode(strtr($input, '-_', '+/'));
}

            

                public static function base64UrlEncode(string $input): string
{
    return strtr(base64_encode($input), '+/', '-_');
}

            

                public static function baseName(string $path, string $suffix = ''): string
{
    $length = mb_strlen($suffix);
    if ($length > 0 && mb_substr($path, -$length) === $suffix) {
        $path = mb_substr($path, 0, -$length);
    }
    $path = rtrim(str_replace('\\', '/', $path), '/\\');
    $position = mb_strrpos($path, '/');
    if ($position !== false) {
        return mb_substr($path, $position + 1);
    }
    return $path;
}

            

                public static function byteLength(string|null $input): int
{
    return mb_strlen((string)$input, '8bit');
}

            

                public static function byteSubstring(string $input, int $start, ?int $length = null): string
{
    return mb_substr($input, $start, $length ?? mb_strlen($input, '8bit'), '8bit');
}

            

                public static function countWords(string $input): int
{
    /** @var array $words */
    $words = preg_split('/\s+/u', $input, -1, PREG_SPLIT_NO_EMPTY);
    return count($words);
}

            

                public static function directoryName(string $path): string
{
    $position = mb_strrpos(str_replace('\\', '/', $path), '/');
    if ($position !== false) {
        return mb_substr($path, 0, $position);
    }
    return '';
}

            

                public static function endsWith(string $input, string|null $with): bool
{
    return $with === null || str_ends_with($input, $with);
}

            

                public static function endsWithIgnoringCase(string $input, string|null $with): bool
{
    $bytes = self::byteLength($with);
    if ($bytes === 0) {
        return true;
    }
    /** @psalm-suppress PossiblyNullArgument */
    return self::lowercase(mb_substr($input, -$bytes, mb_strlen($input, '8bit'), '8bit')) === self::lowercase($with);
}

            

                public static function findBetween(string $string, string $start, ?string $end = null): ?string
{
    if ($end === null) {
        $end = $start;
    }
    $startPos = mb_strpos($string, $start);
    if ($startPos === false) {
        return null;
    }
    $startPos += mb_strlen($start);
    $endPos = mb_strrpos($string, $end, $startPos);
    if ($endPos === false) {
        return null;
    }
    return mb_substr($string, $startPos, $endPos - $startPos);
}

            

                public static function findBetweenFirst(string $string, string $start, ?string $end = null): ?string
{
    if ($end === null) {
        $end = $start;
    }
    $startPos = mb_strpos($string, $start);
    if ($startPos === false) {
        return null;
    }
    $startPos += mb_strlen($start);
    $endPos = mb_strpos($string, $end, $startPos);
    if ($endPos === false) {
        return null;
    }
    return mb_substr($string, $startPos, $endPos - $startPos);
}

            

                public static function findBetweenLast(string $string, string $start, ?string $end = null): ?string
{
    if ($end === null) {
        $end = $start;
    }
    $endPos = mb_strrpos($string, $end);
    if ($endPos === false) {
        return null;
    }
    $startPos = mb_strrpos(mb_substr($string, 0, $endPos), $start);
    if ($startPos === false) {
        return null;
    }
    $startPos += mb_strlen($start);
    return mb_substr($string, $startPos, $endPos - $startPos);
}

            

                public static function length(string $string, string $encoding = 'UTF-8'): int
{
    return mb_strlen($string, $encoding);
}

            

                public static function lowercase(string $string, string $encoding = 'UTF-8'): string
{
    return mb_strtolower($string, $encoding);
}

            

                public static function ltrim(string|array $string, string $pattern = self::DEFAULT_WHITESPACE_PATTERN): string|array
{
    self::ensureUtf8String($string);
    self::ensureUtf8Pattern($pattern);
    /**
     * @var string|string[] `$string` is correct UTF-8 string and `$pattern` is correct (it should be passed
     * already prepared), so `preg_replace` never returns `null`.
     */
    return preg_replace("#^[$pattern]+#u", '', $string);
}

            

                public static function matchAnyRegex(string $string, array $patterns, string $flags = ''): bool
{
    if (empty($patterns)) {
        return false;
    }
    return (new CombinedRegexp($patterns, $flags))->matches($string);
}

            

                public static function parsePath(
    string $path,
    string $delimiter = '.',
    string $escapeCharacter = '\\',
    bool $preserveDelimiterEscaping = false
): array {
    if (strlen($delimiter) !== 1) {
        throw new InvalidArgumentException('Only 1 character is allowed for delimiter.');
    }
    if (strlen($escapeCharacter) !== 1) {
        throw new InvalidArgumentException('Only 1 escape character is allowed.');
    }
    if ($delimiter === $escapeCharacter) {
        throw new InvalidArgumentException('Delimiter and escape character must be different.');
    }
    if ($path === '') {
        return [''];
    }
    if (!str_contains($path, $delimiter)) {
        if ($preserveDelimiterEscaping) {
            return [$path];
        }
        return [str_replace($escapeCharacter . $escapeCharacter, $escapeCharacter, $path)];
    }
    /** @psalm-var non-empty-list<array{0:string, 1:int}> $matches */
    $matches = preg_split(
        sprintf(
            '/(?<!%1$s)((?>%1$s%1$s)*)%2$s/',
            preg_quote($escapeCharacter, '/'),
            preg_quote($delimiter, '/')
        ),
        $path,
        -1,
        PREG_SPLIT_OFFSET_CAPTURE
    );
    $result = [];
    $countResults = count($matches);
    for ($i = 1; $i < $countResults; $i++) {
        $l = $matches[$i][1] - $matches[$i - 1][1] - strlen($matches[$i - 1][0]) - 1;
        $result[] = $matches[$i - 1][0] . ($l > 0 ? str_repeat($escapeCharacter, $l) : '');
    }
    $result[] = $matches[$countResults - 1][0];
    if ($preserveDelimiterEscaping === true) {
        return $result;
    }
    return array_map(
        static fn (string $key): string => str_replace(
            [
                $escapeCharacter . $escapeCharacter,
                $escapeCharacter . $delimiter,
            ],
            [
                $escapeCharacter,
                $delimiter,
            ],
            $key
        ),
        $result
    );
}

            

                public static function replaceSubstring(
    string $string,
    string $replacement,
    int $start,
    int|null $length = null,
    string $encoding = 'UTF-8',
): string {
    $stringLength = mb_strlen($string, $encoding);
    if ($start < 0) {
        $start = max(0, $stringLength + $start);
    } elseif ($start > $stringLength) {
        $start = $stringLength;
    }
    if ($length !== null && $length < 0) {
        $length = max(0, $stringLength - $start + $length);
    } elseif ($length === null || $length > $stringLength) {
        $length = $stringLength;
    }
    if (($start + $length) > $stringLength) {
        $length = $stringLength - $start;
    }
    return mb_substr($string, 0, $start, $encoding)
        . $replacement
        . mb_substr($string, $start + $length, $stringLength - $start - $length, $encoding);
}

            

                public static function rtrim(string|array $string, string $pattern = self::DEFAULT_WHITESPACE_PATTERN): string|array
{
    self::ensureUtf8String($string);
    self::ensureUtf8Pattern($pattern);
    /**
     * @var string|string[] `$string` is correct UTF-8 string and `$pattern` is correct (it should be passed
     * already prepared), so `preg_replace` never returns `null`.
     */
    return preg_replace("#[$pattern]+$#uD", '', $string);
}

            

                public static function split(string $string, string $separator = '\R'): array
{
    /**
     * @var string $string We assume that `$string` is valid UTF-8 string, so `preg_replace()` never returns
     * `false`.
     */
    $string = preg_replace('(^\s*|\s*$)', '', $string);
    /**
     * @var array We assume that $separator is prepared by `preg_quote()` and $string is valid UTF-8 string,
     * so `preg_split()` never returns `false`.
     */
    return preg_split('~\s*' . $separator . '\s*~u', $string, -1, PREG_SPLIT_NO_EMPTY);
}

            

                public static function startsWith(string $input, string|null $with): bool
{
    return $with === null || str_starts_with($input, $with);
}

            

                public static function startsWithIgnoringCase(string $input, string|null $with): bool
{
    $bytes = self::byteLength($with);
    if ($bytes === 0) {
        return true;
    }
    /** @psalm-suppress PossiblyNullArgument */
    return self::lowercase(self::substring($input, 0, $bytes, '8bit')) === self::lowercase($with);
}

            

                public static function substring(string $string, int $start, ?int $length = null, string $encoding = 'UTF-8'): string
{
    return mb_substr($string, $start, $length, $encoding);
}

            

                public static function trim(string|array $string, string $pattern = self::DEFAULT_WHITESPACE_PATTERN): string|array
{
    self::ensureUtf8String($string);
    self::ensureUtf8Pattern($pattern);
    /**
     * @var string|string[] `$string` is correct UTF-8 string and `$pattern` is correct (it should be passed
     * already prepared), so `preg_replace` never returns `null`.
     */
    return preg_replace("#^[$pattern]+|[$pattern]+$#uD", '', $string);
}

            

                public static function truncateBegin(string $input, int $length, string $trimMarker = '…', string $encoding = 'UTF-8'): string
{
    $inputLength = mb_strlen($input, $encoding);
    if ($inputLength <= $length) {
        return $input;
    }
    $trimMarkerLength = mb_strlen($trimMarker, $encoding);
    return self::replaceSubstring($input, $trimMarker, 0, -$length + $trimMarkerLength, $encoding);
}

            

                public static function truncateEnd(string $input, int $length, string $trimMarker = '…', string $encoding = 'UTF-8'): string
{
    $inputLength = mb_strlen($input, $encoding);
    if ($inputLength <= $length) {
        return $input;
    }
    $trimMarkerLength = mb_strlen($trimMarker, $encoding);
    return rtrim(mb_substr($input, 0, $length - $trimMarkerLength, $encoding)) . $trimMarker;
}

            

                public static function truncateMiddle(string $input, int $length, string $trimMarker = '…', string $encoding = 'UTF-8'): string
{
    $inputLength = mb_strlen($input, $encoding);
    if ($inputLength <= $length) {
        return $input;
    }
    $trimMarkerLength = mb_strlen($trimMarker, $encoding);
    $start = (int)ceil(($length - $trimMarkerLength) / 2);
    $end = $length - $start - $trimMarkerLength;
    return self::replaceSubstring($input, $trimMarker, $start, -$end, $encoding);
}

            

                public static function truncateWords(string $input, int $count, string $trimMarker = '…'): string
{
    /** @psalm-var list<string> $words */
    $words = preg_split('/(\s+)/u', trim($input), -1, PREG_SPLIT_DELIM_CAPTURE);
    if (count($words) / 2 > $count) {
        $words = array_slice($words, 0, ($count * 2) - 1);
        return implode('', $words) . $trimMarker;
    }
    return $input;
}

            

                public static function truncateWordsByLength(
    string $input,
    int $length,
    string $trimMarker = '…',
    string $encoding = 'UTF-8',
): string {
    $input = trim($input);
    if ($input === '') {
        return '';
    }
    if (mb_strlen($input, $encoding) <= $length) {
        return $input;
    }
    $markerLength = mb_strlen($trimMarker, $encoding);
    if ($length <= $markerLength) {
        return mb_substr($trimMarker, 0, $length, $encoding);
    }
    $truncated = mb_substr($input, 0, $length - $markerLength, $encoding);
    // Prefer not to break words if there's a space within the snippet.
    $lastSpace = mb_strrpos($truncated, ' ', 0, $encoding);
    if ($lastSpace !== false) {
        $cut = rtrim(mb_substr($truncated, 0, $lastSpace, $encoding));
        return $cut === ''
            ? mb_substr($trimMarker, 0, $length, $encoding)
            : $cut . $trimMarker;
    }
    return $truncated . $trimMarker;
}

            

                public static function uppercase(string $string, string $encoding = 'UTF-8'): string
{
    return mb_strtoupper($string, $encoding);
}

            

                public static function uppercaseFirstCharacter(string $string, string $encoding = 'UTF-8'): string
{
    $firstCharacter = self::substring($string, 0, 1, $encoding);
    $rest = self::substring($string, 1, null, $encoding);
    return self::uppercase($firstCharacter, $encoding) . $rest;
}

            

                public static function uppercaseFirstCharacterInEachWord(string $string, string $encoding = 'UTF-8'): string
{
    /**
     * @var array $words We assume that `$string` is valid UTF-8 string, so `preg_split()` never returns `false`.
     */
    $words = preg_split('/\s/u', $string, -1, PREG_SPLIT_NO_EMPTY);
    $wordsWithUppercaseFirstCharacter = array_map(
        static fn (string $word) => self::uppercaseFirstCharacter($word, $encoding),
        $words
    );
    return implode(' ', $wordsWithUppercaseFirstCharacter);
}