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 の 0 から数えて offset番目から始まる文字列となります。 例えば、文字列'abcdef'において位置 0にある文字は、'a'であり、 位置2には'c'があります。

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

    string の長さが offset 文字より短い場合は、 空の文字列が返されます。

    例1 負の offset の使用

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

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

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

    length が指定され、かつ 0 であれば、空の文字が返されます。

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

    例2 負の length の使用

    <?php
    $rest     = substr("abcdef", 0, -1); // "abcde" を返す
    $rest = substr("abcdef", 2, -1); // "cde" を返す
    $rest = substr("abcdef", 4, -4); // "" を返す。PHP 8.0.0 より前のバージョンでは、false を返していました。
    $rest = substr("abcdef", -3, -1); // "de" を返す
    ?>

    戻り値

    string の一部を返すか、空文字列を返します。

    変更履歴

    バージョン説明
    8.0.0length は、nullable になりました。 length に明示的に null を設定すると、 文字列の最後までを含む部分文字列を返すようになっています。 これより前のバージョンでは、空文字列を返していました。
    8.0.0 この関数は、前のバージョンで false を返す場合に、空文字列を返すようになりました。

    例

    例3 基本的な substr() の使用法

    <?php
    echo substr('abcdef', 1); // bcdef
    echo substr("abcdef", 1, null); // bcdef, PHP 8.0.0 より前のバージョンでは、空の文字列を返していました。
    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;
    ?>

    上の例の出力は以下となります。

    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)

    参考

    To Top