# substr

(PHP 4, PHP 5, PHP 7)

substr — 返回字符串的子串

### 说明

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

返回字符串 `string` 由 `start` 和 `length` 参数指定的子字符串。

### 参数

`string`

  输入字符串。必须至少有一个字符。

`start`

  如果 `start` 是非负数，返回的字符串将从 `string` 的 `start` 位置开始，从 0 开始计算。例如，在字符串 “abcdef” 中，在位置 0 的字符是 “a”，位置 2 的字符串是 “c” 等等。

  如果 `start` 是负数，返回的字符串将从 `string` 结尾处向前数第 `start` 个字符开始。

  如果 `string` 的长度小于 `start`，将返回 `FALSE`。

  Example #1 使用负数 `start`

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

`length`

  如果提供了正数的 `length`，返回的字符串将从 `start` 处开始最多包括 `length` 个字符（取决于 `string` 的长度）。

  如果提供了负数的 `length`，那么 `string` 末尾处的 `length` 个字符将会被省略（若 `start` 是负数则从字符串尾部算起）。如果 `start` 不在这段文本中，那么将返回 `FALSE`。

  如果提供了值为 0，`FALSE` 或 `NULL` 的 `length`，那么将返回一个空字符串。

  如果没有提供 `length`，返回的子字符串将从 `start` 位置开始直到字符串结尾。

  Example #2 使用负数 `length`

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

### 返回值

返回提取的子字符串， 或者在失败时返回 `FALSE`。

### 更新日志

版本 | 说明
--- | ---
7.0.0 | 如果 `string` 的字符串长度与 `start` 相同时将返回一个空字符串。在之前的版本中，这种情况将返回 `FALSE` 。
5.2.2 - 5.2.6 | If the `start` parameter indicates the position of a negative truncation or beyond, false is returned. Other versions get the string from start.

### 范例

Example #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

    // 访问字符串中的单个字符
    // 也可以使用中括号
    $string = 'abcdef';
    echo $string[0];                 // a
    echo $string[3];                 // d
    echo $string[strlen($string)-1]; // f
    ?>

Example #4 substr() casting behaviour

    <?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;
    ?>

Output of the above example in PHP 7:

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

Output of the above example in 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)
    ?>

### 参见

- strrchr() - 查找指定字符在字符串中的最后一次出现
- substr_replace() - 替换字符串的子串
- preg_match() - 执行匹配正则表达式
- trim() - 去除字符串首尾处的空白字符（或者其他字符）
- mb_substr() - 获取部分字符串
- wordwrap() - 打断字符串为指定数量的字串
- 字符串访问和修改