substr

(PHP 4, PHP 5, PHP 7)

substr — 文字列の一部分を返す

説明

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

文字列 string の、start で指定された位置から length バイト分の文字列を返します。

パラメータ

string

入力文字列。最低 1 文字以上を指定しなければなりません。

start

start が正の場合、返される文字列は、 string の 0 から数えて start番目から始まる文字列となります。 例えば、文字列'abcdef'において位置 0にある文字は、'a'であり、 位置2には'c'があります。

start が負の場合、返される文字列は、 stringの後ろから数えて start番目から始まる文字列となります。

string の長さが start 文字より短い場合は FALSE が返されます。

例1 負の start の使用

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

length

length が指定され、かつ正である場合、 返される文字列は start (string の長さに依存します) から数えてlength文字数分となります。

length が指定され、かつ負である場合、 string の終端からその文字数分の文字が省略されます (start が負の場合は、 開始位置を算出したあとで)。 もし start が切り出し位置を超える場合、 FALSE が返されます。

length が指定され、かつ 0、NULL、もしくは FALSE であれば、空の文字が返されます。

length を省略した場合は、 start の位置から文字列の最後までの部分文字列を返します。

例2 負の length の使用

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

返り値

string の一部を返します。失敗した場合に FALSE を返します。あるいは空文字列を返します。

変更履歴

バージョン 説明
7.0.0 string の文字数が start と等しい場合に空文字列を返すようになりました。 これまでのバージョンでは、FALSE を返していました。
5.2.2 - 5.2.6 start が負の切り出しを意味したり 切り出し位置を超える値になった場合に false を返すようになりました。 それ以外のバージョンでは、文字列の先頭から取得します。

例

例3 基本的な 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

// 文字列中の 1 文字にアクセスすることも
// "角括弧" を使用することで可能
$string = 'abcdef';
echo $string[0];                 // a
echo $string[3];                 // d
echo $string[strlen($string)-1]; // 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;
?>

上の例の PHP 7 での出力は、このようになります。

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

上の例の PHP 5 での出力は、このようになります。

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

エラー / 例外

エラー時に FALSE を返します。

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

参考