archived-doc-zh/reference/strings/functions/substr-replace.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e095023e408c8cb6378ae16bb6870343a3946919 Maintainer: HonestQiao Status: ready -->
<!-- CREDITS: mowangjuanzi -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.substr-replace">
 <refnamediv>
  <refname>substr_replace</refname>
  <refpurpose>替换字符串的子串</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>string</type><type>array</type></type><methodname>substr_replace</methodname>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>string</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>string</type></type><parameter>replace</parameter></methodparam>
   <methodparam><type class="union"><type>array</type><type>int</type></type><parameter>offset</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   <function>substr_replace</function> 在字符串 <parameter>string</parameter> 的副本中将由 <parameter>offset</parameter>
   和可选的 <parameter>length</parameter> 参数限定的子字符串使用 <parameter>replace</parameter> 进行替换。
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>string</parameter></term>
     <listitem>
      <para>
       输入字符串。
      </para>
      <para>
       可以提供 <type>array</type> 类型的 <type>string</type>，会依次替换出现的字符串。在这种情况下，<parameter>replace</parameter>、<parameter>offset</parameter>
       和 <parameter>length</parameter> 参数可以作为标量值依次提供给每个输入字符串，或者作为 <type>array</type> 提供，然后数组元素将会相应的用于每个输入字符串。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>replace</parameter></term>
     <listitem>
      <para>
       替换字符串。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       如果 <parameter>offset</parameter> 为非负数，替换将从 <parameter>string</parameter> 的 <parameter>offset</parameter> 位置开始。
      </para>
      <para>
       如果 <parameter>offset</parameter> 为负数，替换将从 <parameter>string</parameter> 的倒数第 <parameter>offset</parameter> 个位置开始。
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>length</parameter></term>
     <listitem>
      <para>
       如果设定了这个参数并且为正数，表示 <parameter>string</parameter> 中被替换的子字符串的长度。如果设定为负数，它表示待替换的子字符串结尾处距离
       <parameter>string</parameter> 末端的字符个数。如果没有提供此参数，那么它默认为 strlen( <parameter>string</parameter>
       )（字符串的长度）。当然，如果 <parameter>length</parameter> 为 0，那么这个函数的功能为将 <parameter>replace</parameter> 插入到
       <parameter>string</parameter> 的 <parameter>offset</parameter> 位置处。
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   返回结果字符串。如果 <parameter>string</parameter> 是个数组，那么也将返回一个数组。
  </para>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <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> 现在允许为 null。
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>substr_replace</function> 示例</title>
    <programlisting role="php">
<![CDATA[
<?php
$var = 'ABCDEFGH:/MNRPQR/';
echo "Original: $var<hr />\n";

/* 这两个例子使用 “bob” 替换整个 $var。*/
echo substr_replace($var, 'bob', 0) . "<br />\n";
echo substr_replace($var, 'bob', 0, strlen($var)) . "<br />\n";

/* 将 “bob” 插入到 $var 的开头处。*/
echo substr_replace($var, 'bob', 0, 0) . "<br />\n";

/* 下面两个例子使用 “bob” 替换 $var 中的 “MNRPQR”。*/
echo substr_replace($var, 'bob', 10, -1) . "<br />\n";
echo substr_replace($var, 'bob', -7, -1) . "<br />\n";

/* 从 $var 中删除 “MNRPQR”。*/
echo substr_replace($var, '', 10, -1) . "<br />\n";
?>
]]>
    </programlisting>
  </example>
  </para>
  <para>
   <example>
    <title>
     一次性使用 <function>substr_replace</function> 替换多个字符串
    </title>
    <programlisting role="php">
<![CDATA[
<?php
$input = array('A: XXX', 'B: XXX', 'C: XXX');

// 简单用例：将每个字符串使用 YYY 替换为 XXX。
echo implode('; ', substr_replace($input, 'YYY', 3, 3))."\n";

// 更复杂的情况，每种替换都不同。
$replace = array('AAA', 'BBB', 'CCC');
echo implode('; ', substr_replace($input, $replace, 3, 3))."\n";

// 每次替换的字符数不同。
$length = array(1, 2, 3);
echo implode('; ', substr_replace($input, $replace, 3, $length))."\n";
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
A: YYY; B: YYY; C: YYY
A: AAA; B: BBB; C: CCC
A: AAAXX; B: BBBX; C: CCC
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.bin-safe;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>str_replace</function></member>
    <member><function>substr</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
-->