substr.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 62126c55f1c6ed444043e7272c4f9e233818a44b Maintainer: hirokawa Status: ready -->
<!-- CREDITS: shimooka,mumumu -->
<refentry xml:id="function.substr" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>substr</refname>
  <refpurpose>文字列の一部分を返す</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>substr</methodname>
   <methodparam><type>string</type><parameter>string</parameter></methodparam>
   <methodparam><type>int</type><parameter>offset</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   文字列 <parameter>string</parameter> の、<parameter>offset</parameter>
   で指定された位置から <parameter>length</parameter> バイト分の文字列を返します。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       入力文字列。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       <parameter>offset</parameter> が正の場合、返される文字列は、
       <parameter>string</parameter> の 0 から数えて
       <parameter>offset</parameter>番目から始まる文字列となります。
       例えば、文字列'<literal>abcdef</literal>'において位置
       <literal>0</literal>にある文字は、'<literal>a</literal>'であり、
       位置<literal>2</literal>には'<literal>c</literal>'があります。
      </para>
      <para>
       <parameter>offset</parameter> が負の場合、返される文字列は、
       <parameter>string</parameter>の後ろから数えて
       <parameter>offset</parameter>番目から始まる文字列となります。
      </para>
      <para>
       <parameter>string</parameter> の長さが
       <parameter>offset</parameter> 文字より短い場合は、
       空の文字列が返されます。
      </para>
      <para>
       <example>
        <title>負の <parameter>offset</parameter> の使用</title>
        <programlisting role="php">
<![CDATA[
<?php
$rest = substr("abcdef", -1);    // "f" を返す
$rest = substr("abcdef", -2);    // "ef" を返す
$rest = substr("abcdef", -3, 1); // "d" を返す
?>
]]>
        </programlisting>
       </example>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       <parameter>length</parameter> が指定され、かつ正である場合、
       返される文字列は <parameter>offset</parameter>
       (<parameter>string</parameter> の長さに依存します)
       から数えて<parameter>length</parameter>文字数分となります。
      </para>
      <para>
       <parameter>length</parameter> が指定され、かつ負である場合、
       <parameter>string</parameter> の終端からその文字数分の文字が省略されます
       (<parameter>offset</parameter> が負の場合は、
       開始位置を算出したあとで)。
       もし <parameter>offset</parameter> が切り出し位置を超える場合、
       空の文字列が返されます。
      </para>
      <para>
       <parameter>length</parameter> が指定され、かつ
       <literal>0</literal> であれば、空の文字が返されます。
      </para>
      <para>
       <parameter>length</parameter> を省略した場合、または &null; の場合は、
       <parameter>offset</parameter> の位置から文字列の最後までの部分文字列を返します。
      </para>
      <example>
       <title>負の <parameter>length</parameter> の使用</title>
       <programlisting role="php">
<![CDATA[
<?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" を返す
?>
]]>
       </programlisting>
      </example>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <parameter>string</parameter> の一部を返すか、空文字列を返します。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     <row>
      <entry>8.0.0</entry>
      <entry>
       <parameter>length</parameter> は、nullable になりました。
       <parameter>length</parameter> に明示的に &null; を設定すると、
       文字列の最後までを含む部分文字列を返すようになっています。
       これより前のバージョンでは、空文字列を返していました。
      </entry>
     </row>
     <row>
      <entry>8.0.0</entry>
      <entry>
       この関数は、前のバージョンで &false; を返す場合に、空文字列を返すようになりました。
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>基本的な <function>substr</function> の使用法</title>
    <programlisting role="php">
<![CDATA[
<?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

?>
]]>
    </programlisting>
   </example> 
   <example>
    <title><function>substr</function> でのキャストの挙動</title>
    <programlisting role="php">
<![CDATA[
<?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;
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
1) 'pe'
2) '54'
3) 'gr'
4) '1'
5) ''
6) ''
7) '1200'
]]>
    </screen>
   </example>
  <example>
   <title>文字列の範囲が不正な場合</title>
   <para>
    指定された文字列の範囲が正しくない場合、
    <function>substr</function> は PHP 8.0.0 以降では空文字列を返します。
    それより前のバージョンでは、&false; を返していました。
   </para>
   <programlisting role="php">
<![CDATA[
<?php
var_dump(substr('a', 2));
?>
]]>
   </programlisting>
   &example.outputs.8;
   <screen>
<![CDATA[
string(0) ""
]]>
   </screen>
   &example.outputs.7;
   <screen>
<![CDATA[
bool(false)
]]>
   </screen>
  </example>

  </para>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>strrchr</function></member>
    <member><function>substr_replace</function></member>
    <member><function>preg_match</function></member>
    <member><function>trim</function></member>
    <member><function>mb_substr</function></member>
    <member><function>wordwrap</function></member>
    <member><link linkend="language.types.string.substr">文字列への文字単位のアクセスと修正</link></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->