substr

(PHP 4, PHP 5)

substr — Devuelve parte de una cadena

Descripción

string substr ( string $string , int $start [, int $length ] )

Devuelve una parte del string definida por los parámetros start y length.

Parámetros

string

La cadena de entrada. Debe ser de almenos de un caracter.

start

Si start no es negativo, la cadena devuelta comenzará en el start de la posición del string empezando desde cero. Por ejemplo, en la cadena 'abcdef', el caracter en la posición 0 es 'a', el caracter en la posición 2 es 'c', y así sucesivamente.

Si start es negativo, la cadena devuelta empezará en start contando desde el final de string.

Si la longitud del string es menor o igual a start, la función devolverá FALSE.

Ejemplo #1 Usando un start negativo

<?php
$rest = substr("abcdef", -1);    // devuelve "f"
$rest = substr("abcdef", -2);    // devuelve "ef"
$rest = substr("abcdef", -3, 1); // devuelve "d"
?>

length

Si se especifica el length y es positivo, la cadena devuelta contendrá como máximo de caracteres de la cantidad dada por length que comienza en start (dependiedo de la longitud del string).

Si se especifica length es negativo, entonces ese número de caracteres se omiten al final del string (después de la posición inicial se ha calculado a start es negativo). Si start indica la posición de su truncamiento o más allá, se devolverá false.

Si se omite el length, la subcadena empezará por start hasta el final de la cadena donde será devuelta.

Si se especifica length y es 0, FALSE o NULL devolverá una cadena vacía.

Ejemplo #2 Usando un length negativo

<?php
$rest = substr("abcdef", 0, -1);  // devuelve "abcde"
$rest = substr("abcdef", 2, -1);  // devuelve "cde"
$rest = substr("abcdef", 4, -4);  // devuelve false
$rest = substr("abcdef", -3, -1); // devuelve "de"
?>

Valores devueltos

Devuelve la parte extraída del string, o FALSE en caso de error o un string vacío.

Historial de cambios

Versión Descripción
5.2.2 - 5.2.6 Si el parámetro start indica una posición negativa de truncamiento o más allá, se devolverá false. En otras versiones de PHP obtienen la cadena desde el principio.

Ejemplos

Ejemplo #3 Uso básico de substr()

<?php
echo substr('abcdef', 1);     // bcdef
echo substr('abcdef', 1, 3);  // bcd
echo substr('abcdef', 0, 4);  // abcd
echo substr('abcdef', 0, 8);  // abcdef
echo substr('abcdef', -1, 1); // f

// El acceso a caracteres específicos en una cadena 
// se puede conseguir usando "corchetes"
$string = 'abcdef';
echo $string[0];                 // a
echo $string[3];                 // d
echo $string[strlen($string)-1]; // f

?>

Ejemplo #4 Comportamiento de casting de 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;
?>

El resultado del ejemplo sería:

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

Errores/Excepciones

Devuelve FALSE en caso de error.

<?php
var_dump(substr('a', 1)); // bool(false)
?>

Ver también