array ( 0 => 'index.php', 1 => 'PHP Manual', ), 'head' => array ( 0 => 'UTF-8', 1 => 'pt_BR', ), 'this' => array ( 0 => 'function.substr.php', 1 => 'substr', ), 'up' => array ( 0 => 'ref.strings.php', 1 => 'Funções de String', ), 'prev' => array ( 0 => 'function.substr-replace.php', 1 => 'substr_replace', ), 'next' => array ( 0 => 'function.trim.php', 1 => 'trim', ), 'alternatives' => array ( ), 'source' => array ( 'lang' => 'pt_BR', 'path' => 'reference/strings/functions/substr.xml', ), ); $setup["toc"] = $TOC; $setup["toc_deprecated"] = $TOC_DEPRECATED; $setup["parents"] = $PARENTS; manual_setup($setup); ?>
(PHP 4, PHP 5, PHP 7, PHP 8)
substr — Retorna parte de uma string
Retorna a parte de string
especificada pelo
parâmetro offset
e length
.
string
A string de entrada
offset
Se offset
for não-negativo, a string retornada iniciará
na posição offset
em
string
, começando em zero. Por exemplo,
na string 'abcdef
', o caractere na posição
0
é 'a
', na
posição 2
é
'c
', e assim por diante.
Se offset
for negativo, a string retornada
irá começar no caractere offset
contado a partir do fim da string
.
Se a string
for mais curta que o parâmetro
offset
, uma string vazia será retornada.
Exemplo #1 Usando um offset
negativo
<?php
$rest = substr("abcdef", -1); // retorna "f"
$rest = substr("abcdef", -2); // retorna "ef"
$rest = substr("abcdef", -3, 1); // retorna "d"
?>
length
Se length
for fornecido e for positivo,
a string retornada irá conter, no máximo, length
caracteres
começando em offset
(dependendo do tamanho da
string
).
Se length
for informado e for negativo, então esta quantidade
caracteres será omitida do final da string
(após a posicão de inicio ter sido calculada quando
offset
for negativo). Se
offset
denota a posição da truncagem ou
além, uma string vazia será retornada.
Se length
for informado e for igual a 0
,
uma string vazia será retornada.
Se length
for omitido ou null
, a substring iniciando em
offset
será
retornada.
Exemplo #2 Usando um length
negativo
<?php
$rest = substr("abcdef", 0, -1); // retorna "abcde"
$rest = substr("abcdef", 2, -1); // retorna "cde"
$rest = substr("abcdef", 4, -4); // retorna ""; antes do PHP 8.0.0, falso era retornado
$rest = substr("abcdef", -3, -1); // retorna "de"
?>
Retorna a parte extraída da string
, ou
uma string vazia.
Versão | Descrição |
---|---|
8.0.0 |
length agora pode ser nulo.
Quando length for especificamente definido para null ,
a função retorna uma substring terminando no final da string, quando anteriormente retornava uma string vazia.
|
8.0.0 |
A função retorna uma string vazia quando antes retornava false .
|
Exemplo #3 Uso básico de substr()
<?php
echo substr('abcdef', 1); // bcdef
echo substr("abcdef", 1, null); // bcdef; antes do PHP 8.0.0, string vazia era retornada
echo substr('abcdef', 1, 3); // bcd
echo substr('abcdef', 0, 4); // abcd
echo substr('abcdef', 0, 8); // abcdef
echo substr('abcdef', -1, 1); // f
// O acesso a caracteres individuais pode
// ser feito atravéz de indexação
$string = 'abcdef';
echo $string[0]; // a
echo $string[3]; // d
echo $string[strlen($string)-1]; // f
?>
Exemplo #4 Comportamento de conversão no 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;
?>
O exemplo acima produzirá:
1) 'pe' 2) '54' 3) 'gr' 4) '1' 5) '' 6) '' 7) '1200'
Exemplo #5 Faixa Inválida de Caracteres
Se uma faixa inválida de caracteres for requisitada, substr() retorna
uma string vazia a partir do PHP 8.0.0; anteriormente, false
era retornado.
<?php
var_dump(substr('a', 2));
?>
Saída do exemplo acima no PHP 8:
string(0) ""
Saída do exemplo acima no PHP 7:
bool(false)