substr

(PHP 4, PHP 5, PHP 7, PHP 8)

substr — Возвращает подстроку

Описание

substr(string $string, int $offset, ?int $length = null): string

Функция возвращает часть строки string. Начало подстроки указывают в параметре offset, а длину — в параметре length.

Список параметров

string

Входная строка.

offset

При нулевом или положительном значении смещения offset функция возвращает правую часть строки string, которая начинается с позиции смещения offset. Отсчёт позиций начинается с нуля. В строке "abcdef", например, на позиции 0 стоит символ "a", на позиции 2 — символ "c" и т. д.

Отрицательные смещения offset отсчитываются с конца строки и функция также возвращает подстроку, которая начинается с позиции смещения offset и идёт до конца строки string.

Функция вернёт пустую строку, если длина строки string меньше значения смещения offset.

Пример #1 Пример установки для параметра offset отрицательного смещения

<?php

echo substr("abcdef", -1), PHP_EOL;    // Функция возвращает значение "f"
echo substr("abcdef", -2), PHP_EOL;    // Функция возвращает значение "ef"
echo substr("abcdef", -3, 1), PHP_EOL; // Функция возвращает значение "d"

?>

length

Параметр length ограничивает количество символов, которое возвращает функция. При установке для параметра length положительного значения возвращается правая часть строки string, начиная с позиции смещения offset. Функция вернёт меньше символов, если часть строки с позиции смещения меньше заданной длины.

При установке для параметра length отрицательного значения такое же количество символов отбрасывается из конца строки string или из конца подстроки, которая осталась после вычисления стартовой позиции при отрицательном смещении offset. Функция вернёт пустую строку, если позиции смещения offset и усечения совпадают или пересекаются.

При установке для параметра length значения 0 функция вернёт пустую строку.

При пропуске параметра length или установке значения null функция вернёт подстроку с позиции смещения offset до конца строки.

Пример #2 Пример с отрицательным значением параметра length

<?php

echo substr("abcdef", 0, -1), PHP_EOL;  // Функция возвращает значение "abcde"
echo substr("abcdef", 2, -1), PHP_EOL;  // Функция возвращает значение "cde"
echo substr("abcdef", 4, -4), PHP_EOL;  // Функция возвращает значение ""; до PHP 8.0.0 возвращалось значение false
echo substr("abcdef", -3, -1), PHP_EOL; // Функция возвращает значение "de"

?>

Возвращаемые значения

Функция возвращает извлечённую часть строки string или пустую строку.

Список изменений

Версия	Описание
8.0.0	Параметр `length` теперь принимает значение null. При явной установке для параметра `length` значения `null` функция возвращает подстроку, которая заканчивается в конце строки; раньше возвращалась пустая строка.
8.0.0	Функция возвращает пустую строку там, где раньше возвращала `false`.

Примеры

Пример #3 Стандартный пример поиска подстроки функцией substr()

<?php

echo substr('abcdef', 1), PHP_EOL;     // bcdef
echo substr("abcdef", 1, null), PHP_EOL; // bcdef; до PHP 8.0.0 возвращалась пустая строка
echo substr('abcdef', 1, 3), PHP_EOL;  // bcd
echo substr('abcdef', 0, 4), PHP_EOL;  // abcd
echo substr('abcdef', 0, 8), PHP_EOL;  // abcdef
echo substr('abcdef', -1, 1), PHP_EOL; // f

// Доступ к отдельному символу в строке получают
// также через квадратные скобки
$string = 'abcdef';
echo $string[0], PHP_EOL;                 // a
echo $string[3], PHP_EOL;                 // d
echo $string[strlen($string)-1], PHP_EOL; // f

?>

Пример #4 Функция substr() и приведение типов

<?php

class apple
{
    public function __toString()
    {
        return "green";
    }
}

echo "1) ", var_export(substr("pear", 0, 2), true), PHP_EOL;
echo "2) ", var_export(substr(54321, 0, 2), true), PHP_EOL;
echo "3) ", var_export(substr(new apple(), 0, 2), true), PHP_EOL;
echo "4) ", var_export(substr(true, 0, 1), true), PHP_EOL;
echo "5) ", var_export(substr(false, 0, 1), true), PHP_EOL;
echo "6) ", var_export(substr("", 0, 1), true), PHP_EOL;
echo "7) ", var_export(substr(1.2e3, 0, 4), true), PHP_EOL;

?>

Результат выполнения приведённого примера:

1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) ''
6) ''
7) '1200'

Пример #5 Недопустимый диапазон символов

При запросе недопустимого диапазона символов функция substr() начиная с PHP 8.0.0 возвращает пустую строку; раньше возвращалось значение false.

<?php

var_dump(substr('a', 2));

?>

Результат выполнения приведённого примера в PHP 8:

string(0) ""

Результат выполнения приведённого примера в PHP 7:

bool(false)

Смотрите также

strrchr() - Находит последнее вхождение символа в строке
substr_replace() - Заменяет часть строки
preg_match() - Выполняет проверку на соответствие регулярному выражению
trim() - Удаляет пробельные или другие символы в начале и конце строки
mb_substr() - Возвращает часть строки
wordwrap() - Переносит строку через заданное количество символов
Посимвольный доступ и изменение строки