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

-->