[phpdoc-zh] r210 committed - pcre库函数部分翻译完成

[phpd...@googlecode.com]

Revision: 210
Author: lgg860911
Date: Sun Apr 3 03:27:27 2011
Log: pcre库函数部分翻译完成
http://code.google.com/p/phpdoc-zh/source/detail?r=210

Added:
/trunk/xml/reference/pcre/functions/preg-match.xml
/trunk/xml/reference/pcre/functions/preg-quote.xml
/trunk/xml/reference/pcre/functions/preg-replace-callback.xml
/trunk/xml/reference/pcre/functions/preg-replace.xml
/trunk/xml/reference/pcre/functions/preg-split.xml

=======================================
--- /dev/null
+++ /trunk/xml/reference/pcre/functions/preg-match.xml Sun Apr 3 03:27:27
2011
@@ -0,0 +1,347 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 307739 $ -->
+<refentry xml:id="function.preg-match"
xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>preg_match</refname>
+ <refpurpose>执行一个正则表达式匹配</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>int</type><methodname>preg_match</methodname>
+
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
+
<methodparam><type>string</type><parameter>subject</parameter></methodparam>
+ <methodparam choice="opt"><type>array</type><parameter
role="reference">matches</parameter></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
+ </methodsynopsis>
+ <para>
+ 搜索<parameter>subject</parameter>与<parameter>pattern</parameter>给定的
正则表达式的一个匹配.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem>
+ <para>
+ 要搜索的模式, 字符串类型.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>subject</parameter></term>
+ <listitem>
+ <para>
+ 输入字符串.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>matches</parameter></term>
+ <listitem>
+ <para>
+ 如果提供了参数<parameter>matches</parameter>, 它讲被填充为搜索结果.
+ <varname>$matches[0]</varname>将包含完整模式匹配到的文本,
<varname>$matches[1]</varname>
+ 将包含第一个捕获子组匹配到的文本, 以此类推.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <para>
+ <parameter>flags</parameter>可以被设置为以下标记值:
+ <variablelist>
+ <varlistentry>
+ <term><constant>PREG_OFFSET_CAPTURE</constant></term>
+ <listitem>
+ <simpara>
+ 如果传递了这个标记, 对于每一个出现的匹配返回时会附加字符串偏移量
(相对于目标字符串的).
+ 注意: 这会改变填充到<parameter>matches</parameter>参数的数组, 使
其每个元素成为一个由
+ 第<literal>0</literal>个元素是匹配到的字符串, 第
<literal>1</literal>个元素是该匹配字符串
+ 在目标字符串<parameter>subject</parameter>中的偏移量.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>offset</parameter></term>
+ <listitem>
+ <para>
+ 通常, 搜索从目标字符串的开始未知开始.可选参数
<parameter>offset</parameter>用于
+ 指定从目标字符串的某个未知开始搜索(单位是字节).
+ </para>
+ <note>
+ <para>
+ 使用<parameter>offset</parameter>参数不同于向
<function>preg_match</function>
+ 传递按照位置通过<literal>substr($subject, $offset)</literal>截取目标
字符串结果,
+ 因为<parameter>pattern</parameter>可以包含断言比如
<emphasis>^</emphasis>, <emphasis>$</emphasis>
+ 或者<emphasis>(?&lt;=x)</emphasis>. 比较:
+ <informalexample>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$subject = "abcdef";
+$pattern = '/^def/';
+preg_match($pattern, $subject, $matches, PREG_OFFSET_CAPTURE, 3);
+print_r($matches);
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+)
+]]>
+ </screen>
+ <para>
+ 当这个示例使用截取后传递时
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$subject = "abcdef";
+$pattern = '/^def/';
+preg_match($pattern, substr($subject,3), $matches, PREG_OFFSET_CAPTURE);
+print_r($matches);
+?>
+]]>
+ </programlisting>
+ <para>
+ 将会产生匹配
+ </para>
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => Array
+ (
+ [0] => def
+ [1] => 0
+ )
+
+)
+]]>
+ </screen>
+ </informalexample>
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ <function>preg_match</function>返回<parameter>pattern</parameter>的匹配次
数.
+ 它的值将是0次(不匹配)或1次, 因为<function>preg_match</function>在第一次匹
配后
+ 将会停止搜索.<function>preg_match_all</function>不同于此, 它会一直搜索
<parameter>subject</parameter>
+ 直到到达结尾.
+ 如果发生错误<function>preg_match</function>返回&false;.
+ </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>5.2.2</entry>
+ <entry>
+ 命名子组可以接受<literal>(?&lt;name&gt;)</literal>,
<literal>(?'name')</literal>
+ 以及<literal>(?P&lt;name&gt;)</literal>语法. 之前版本仅接受
<literal>(?P&lt;name&gt;)</literal>语法.
+ </entry>
+ </row>
+ <row>
+ <entry>4.3.3</entry>
+ <entry>
+ 增加了参数<parameter>offset</parameter>.
+ </entry>
+ </row>
+ <row>
+ <entry>4.3.0</entry>
+ <entry>
+ 增加了标记<constant>PREG_OFFSET_CAPTURE</constant>.
+ </entry>
+ </row>
+ <row>
+ <entry>4.3.0</entry>
+ <entry>
+ 增加了参数<parameter>flags</parameter>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>查找文本字符串"php"</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+//模式分隔符后的"i"标记这是一个大小写不敏感的搜索
+if (preg_match("/php/i", "PHP is the web scripting language of choice.")) {
+ echo "A match was found.";
+} else {
+ echo "A match was not found.";
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>查找单词"word"</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+/* 模式中的\b标记一个单词边界, 所以只有独立的单词"web"会被匹配, 而不会匹配
+ * 单词的部分内容比如"webbing" 或 "cobweb" */
+if (preg_match("/\bweb\b/i", "PHP is the web scripting language of
choice.")) {
+ echo "A match was found.";
+} else {
+ echo "A match was not found.";
+}
+
+if (preg_match("/\bweb\b/i", "PHP is the website scripting language of
choice.")) {
+ echo "A match was found.";
+} else {
+ echo "A match was not found.";
+}
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>获取URL中的域名</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+//从URL中获取主机名称
+preg_match('@^(?:http://)?([^/]+)@i',
+ "http://www.php.net/index.html", $matches);
+$host = $matches[1];
+
+//获取主机名称的后面两部分
+preg_match('/[^.]+\.[^.]+$/', $host, $matches);
+echo "domain name is: {$matches[0]}\n";
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+domain name is: php.net
+]]>
+ </screen>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>使用命名子组</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+
+$str = 'foobar: 2008';
+
+preg_match('/(?P<name>\w+): (?P<digit>\d+)/', $str, $matches);
+
+/* 下面例子在php 5.2.2(pcre 7.0)或更新版本下工作, 然而, 为了后向兼容, 上面
的方式是推荐写法. */
+// preg_match('/(?<name>\w+): (?<digit>\d+)/', $str, $matches);
+
+print_r($matches);
+
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => foobar: 2008
+ [name] => foobar
+ [1] => foobar
+ [digit] => 2008
+ [2] => 2008
+)
+]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ <tip>
+ <para>
+ 如果你仅仅想要检查一个字符串是否包含另外一个字符串, 不要使用
<function>preg_match</function>.
+ 使用<function>strpos</function>或<function>strstr</function>替代完成工作
会更快.
+ </para>
+ </tip>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><link linkend="pcre.pattern">PCRE 模式</link></member>
+ <member><function>preg_match_all</function></member>
+ <member><function>preg_replace</function></member>
+ <member><function>preg_split</function></member>
+ <member><function>preg_last_error</function></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
+-->
=======================================
--- /dev/null
+++ /trunk/xml/reference/pcre/functions/preg-quote.xml Sun Apr 3 03:27:27
2011
@@ -0,0 +1,145 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 298918 $ -->
+<refentry xml:id="function.preg-quote"
xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>preg_quote</refname>
+ <refpurpose>转义正则表达式字符</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>string</type><methodname>preg_quote</methodname>
+ <methodparam><type>string</type><parameter>str</parameter></methodparam>
+ <methodparam
choice="opt"><type>string</type><parameter>delimiter</parameter><initializer>&null;</initializer></methodparam>
+ </methodsynopsis>
+ <para>
+ <function>preg_quote</function>需要参数<parameter>str</parameter>并向其中
+ 每个正则表达式语法中的字符前增加一个反斜线. 这通常用于你有一些运行时字符
串
+ 需要作为正则表达式进行匹配的时候.
+ </para>
+ <para>
+ 正则表达式特殊字符有:
+ <literal>. \ + * ? [ ^ ] $ ( ) { } = ! &lt; &gt; | : -</literal>
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>str</parameter></term>
+ <listitem>
+ <para>
+ 输入字符串
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>delimiter</parameter></term>
+ <listitem>
+ <para>
+ 如果指定了可选参数<parameter>delimiter</parameter>, 它也会被转义. 这
通常用于
+ 转义PCRE函数使用的分隔符. /是最通用的分隔符.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ 返回转义后的字符串.
+ </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>5.3.0</entry>
+ <entry>
+ 字符<literal>-</literal>被增加为需要转义的.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>preg_quote</function>示例</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$keywords = '$40 for a g3/400';
+$keywords = preg_quote($keywords, '/');
+echo $keywords; // 返回 \$40 for a g3\/400
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>将文本中的单词替换为斜体</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+//在这个例子中, preg_quote($word)用于保持星号原文涵义, 使其不使用正则表达式
中的特殊语义.
+
+$textbody = "This book is *very* difficult to find.";
+$word = "*very*";
+$textbody = preg_replace ("/" . preg_quote($word) . "/",
+ "<i>" . $word . "</i>",
+ $textbody);
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ &note.bin-safe;
+ </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
+-->
=======================================
--- /dev/null
+++ /trunk/xml/reference/pcre/functions/preg-replace-callback.xml Sun Apr
3 03:27:27 2011
@@ -0,0 +1,259 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 307739 $ -->
+<refentry xml:id="function.preg-replace-callback"
xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>preg_replace_callback</refname>
+ <refpurpose>执行一个正则表达式搜索并且使用一个回调进行替换</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>mixed</type><methodname>preg_replace_callback</methodname>
+
<methodparam><type>mixed</type><parameter>pattern</parameter></methodparam>
+
<methodparam><type>callback</type><parameter>callback</parameter></methodparam>
+
<methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter
role="reference">count</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ 这个函数的行为除了
+ 可以指定一个<parameter>callback</parameter>替代
<parameter>replacement</parameter>进行替换
+ 字符串的计算, 其他方面等同于<function>preg_replace</function>
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem>
+ <para>
+ 要搜索的模式, 可以使字符串或一个字符串数组.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>callback</parameter></term>
+ <listitem>
+ <para>
+ 一个回调函数, 在每次需要替换时调用, 调用时函数得到的参数是从
<parameter>subject</parameter>
+ 中匹配到的结果. 回调函数返回真正参与替换的字符串.
+ </para>
+ <para>
+ 你可能经常会需要<parameter>callback</parameter>函数而
+ 仅用于<function>preg_replace_callback</function>一个地方的调用. 在这
种情况下, 你可以
+ 使用<link linkend="functions.anonymous">匿名函数</link>来定义一个匿名
函数作
+ 为<function>preg_replace_callback</function>调用时的回调. 这样做你可
以保留所有
+ 调用信息在同一个位置并且不会因为一个不在任何其他地方使用的回调函数名
称而污染函数名称空间.
+ </para>
+ <para>
+ <example>
+ <title><function>preg_replace_callback</function>和
+ <function>create_function</function></title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+/* 一个unix样式的命令行过滤器, 用于将段落开始部分的大写字母转换为小写. */
+$fp = fopen("php://stdin", "r") or die("can't read stdin");
+while (!feof($fp)) {
+ $line = fgets($fp);
+ $line = preg_replace_callback(
+ '|<p>\s*\w|',
+ create_function(
+ // single quotes are essential here,
+ // or alternative escape all $ as \$
+ '$matches',
+ 'return strtolower($matches[0]);'
+ ),
+ $line
+ );
+ echo $line;
+}
+fclose($fp);
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>subject</parameter></term>
+ <listitem>
+ <para>
+ 要搜索替换的目标字符串或字符串数组.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>limit</parameter></term>
+ <listitem>
+ <para>
+ 对于每个模式用于每个<parameter>subject</parameter>字符串的最大可替换
次数.
+ 默认是<literal>-1</literal>(无限制).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>count</parameter></term>
+ <listitem>
+ <para>
+ 如果指定, 这个变量将被填充为替换执行的次数.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ 如果<parameter>subject</parameter>是一个数组,
+ <function>preg_replace_callback</function>返回一个数组, 其他情况返回字符
串.
+ 错误发生时返回&null;.
+ </para>
+ <para>
+ 如果查找到了匹配, 返回替换后的 目标字符串(或字符串数组), 其他情况
<parameter>subject</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>5.1.0</entry>
+ <entry>
+ 增加了参数<parameter>count</parameter>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>preg_replace_callback</function>示例</title>
+ <programlisting role='php'>
+<![CDATA[
+<?php
+// 将文本中的年份增加一年.
+$text = "April fools day is 04/01/2002\n";
+$text.= "Last christmas was 12/24/2001\n";
+// 回调函数
+function next_year($matches)
+{
+ // 通常: $matches[0]是完成的匹配
+ // $matches[1]是第一个捕获子组的匹配
+ // 以此类推
+ return $matches[1].($matches[2]+1);
+}
+echo preg_replace_callback(
+ "|(\d{2}/\d{2}/)(\d{4})|",
+ "next_year",
+ $text);
+
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+April fools day is 04/01/2003
+Last christmas was 12/24/2002
+]]>
+ </screen>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title><function>preg_replace_callback</function>使用递归构造处理BB码的
封装</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$input = "plain [indent] deep [indent] deeper [/indent] deep [/indent]
plain";
+
+function parseTagsRecursive($input)
+{
+ /* 译注: 对此正则表达式分段分析
+ * 首尾两个#是正则分隔符
+ * \[indent] 匹配一个原文的[indent]
+ * ((?:[^[]|\[(?!/?indent])|(?R))+)分析:
+ * (?:[^[]|\[(?!/?indent])分析:
+ * 首先它是一个非捕获子组
+ * 两个可选路径, 一个是非[字符, 另一个是[字符但后面紧跟着不是/indent或
indent.
+ * (?R) 正则表达式递归
+ * \[/indent] 匹配结束的[/indent]
+ * /
+ $regex = '#\[indent]((?:[^[]|\[(?!/?indent])|(?R))+)\[/indent]#';
+
+ if (is_array($input)) {
+ $input = '<div style="margin-left: 10px">'.$input[1].'</div>';
+ }
+
+ return preg_replace_callback($regex, 'parseTagsRecursive', $input);
+}
+
+$output = parseTagsRecursive($input);
+
+echo $output;
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><link linkend="pcre.pattern">PCRE 模式</link></member>
+ <member><function>preg_replace</function></member>
+ <member><function>preg_last_error</function></member>
+ <member><function>create_function</function></member>
+ <member><link linkend="functions.anonymous">匿名函数</link></member>
+ <member>&seealso.callback;</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
+-->
=======================================
--- /dev/null
+++ /trunk/xml/reference/pcre/functions/preg-replace.xml Sun Apr 3
03:27:27 2011
@@ -0,0 +1,351 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 307739 $ -->
+<refentry xml:id="function.preg-replace"
xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>preg_replace</refname>
+ <refpurpose>执行一个正则表达式的搜索和替换</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>mixed</type><methodname>preg_replace</methodname>
+
<methodparam><type>mixed</type><parameter>pattern</parameter></methodparam>
+
<methodparam><type>mixed</type><parameter>replacement</parameter></methodparam>
+
<methodparam><type>mixed</type><parameter>subject</parameter></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
+ <methodparam choice="opt"><type>int</type><parameter
role="reference">count</parameter></methodparam>
+ </methodsynopsis>
+ <para>
+ 搜索<parameter>subject</parameter>中匹配<parameter>pattern</parameter>的
部分,
+ 以<parameter>replacement</parameter>进行替换.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem>
+ <para>
+ 要搜索的模式. 可以使一个字符串或字符串数组.
+ </para>
+ <para>
+ 可以使用一些<link linkend="reference.pcre.pattern.modifiers">PCRE修
饰符</link>,
+ 包括'<literal>e</literal>'(PREG_REPLACE_EVAL), 可以为这个函数指定.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>replacement</parameter></term>
+ <listitem>
+ <para>
+ 用于替换的字符串或字符串数组. 如果这个参数是一个字符串, 并且
<parameter>pattern</parameter>
+ 是一个数组, 那么所有的模式都使用这个字符串进行替换. 如果
<parameter>pattern</parameter>和<parameter>replacement</parameter>
+ 都是数组, 每个<parameter>pattern</parameter>使用
<parameter>replacement</parameter>中对应的
+ 元素进行替换. 如果<parameter>replacement</parameter>中的元素比
<parameter>pattern</parameter>中的少,
+ 多出来的<parameter>pattern</parameter>使用空字符串进行替换.
+ </para>
+ <para>
+ <parameter>replacement</parameter>中可以包含后向引用
<literal>\\<replaceable>n</replaceable></literal>
+ 或(php 4.0.4以上可用
)<literal>$<replaceable>n</replaceable></literal>, 语法上首选后者. 每个
+ 这样的引用将被匹配到的第<replaceable>n</replaceable>个捕获子组捕获到
的文本替换. <replaceable>n</replaceable>
+ 可以是0-99, <literal>\\0</literal>和<literal>$0</literal>代表完整的模
式匹配文本.
+ 捕获子组的序号计数方式为: 代表捕获子组的左括号从左到右, 从1开始数. 如
果要在<parameter>replacement</parameter>
+ 中使用反斜线, 必须使用4个(<literal>"\\\\"</literal>, 译注: 因为这首先
是php的字符串, 经过转义后, 是两个, 再经过
+ 正则表达式引擎后才被认为是一个原文反斜线).
+ </para>
+ <para>
+ 当在替换模式下工作并且后向引用后面紧跟着需要是另外一个数字(比如: 在一
个匹配模式后紧接着增加一个原文数字),
+ 不能使用<literal>\\1</literal>这样的语法来描述后向引用. 比如,
<literal>\\11</literal>将会使<function>preg_replace</function>
+ 不能理解你希望的是一个<literal>\\1</literal>后向引用紧跟一个原文
<literal>1</literal>, 还是
+ 一个<literal>\\11</literal>后向引用后面不跟任何东西. 这种情况下解决方
案是使用<literal>\${1}1</literal>.
+ 这创建了一个独立的<literal>$1</literal>后向引用, 一个独立的原文
<literal>1</literal>.
+ </para>
+ <para>
+ 当使用<literal>e</literal>修饰符时, 这个函数会转义一些字符
(即:<literal>'</literal>, <literal>"</literal>,
+ <literal>\</literal>和NULL)然后进行后向引用替换. 当这些完成后请确保
后向引用解析完后没有单引号或
+ 双引号引起的语法错误(比如:
<literal>'strlen(\'$1\')+strlen("$2")'</literal>). 确保符合PHP的
+ <link linkend="language.types.string">字符串语法</link>, 并且符合
eval语法. 因为在完成替换后,
+ 引擎会讲结果字符串作为php代码使用eval方式进行评估并将返回值作为最终
参与替换的字符串.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>subject</parameter></term>
+ <listitem>
+ <para>
+ 要进行搜索和替换的字符串或字符串数组.
+ </para>
+ <para>
+ 如果<parameter>subject</parameter>是一个数组, 搜索和替换回在
<parameter>subject</parameter>
+ 的每一个元素上进行, 并且返回值也会是一个数组.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>limit</parameter></term>
+ <listitem>
+ <para>
+ 每个模式在每个<parameter>subject</parameter>上进行替换的最大次数. 默
认是
+ <literal>-1</literal>(无限).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>count</parameter></term>
+ <listitem>
+ <para>
+ 如果指定, 将会被填充为完成的替换次数.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ 如果<parameter>subject</parameter>是一个数组,
<function>preg_replace</function>返回一个数组,
+ 其他情况下返回一个字符串.
+ </para>
+ <para>
+ 如果匹配被查找到, 替换后的<parameter>subject</parameter>被返回, 其他情况
下
+ 返回没有改变的<parameter>subject</parameter>. 如果发生错误, 返回&null; .
+ </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>5.1.0</entry>
+ <entry>
+ 增加参数<parameter>count</parameter>.
+ </entry>
+ </row>
+ <row>
+ <entry>4.0.4</entry>
+ <entry>
+ 增加<parameter>replacement</parameter>参数中的'$n'用法.
+ </entry>
+ </row>
+ <row>
+ <entry>4.0.2</entry>
+ <entry>
+ 增加了参数<parameter>limit</parameter>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title>使用后向引用紧跟数值原文</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$string = 'April 15, 2003';
+$pattern = '/(\w+) (\d+), (\d+)/i';
+$replacement = '${1}1,$3';
+echo preg_replace($pattern, $replacement, $string);
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+April1,2003
+]]>
+ </screen>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title><function>preg_replace</function>中使用基于索引的数组</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$string = 'The quick brown fox jumped over the lazy dog.';
+$patterns = array();
+$patterns[0] = '/quick/';
+$patterns[1] = '/brown/';
+$patterns[2] = '/fox/';
+$replacements = array();
+$replacements[2] = 'bear';
+$replacements[1] = 'black';
+$replacements[0] = 'slow';
+echo preg_replace($patterns, $replacements, $string);
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+The bear black slow jumped over the lazy dog.
+]]>
+ </screen>
+ <para>
+ 对模式和替换内容按key进行排序我们可以得到期望的结果.
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+ksort($patterns);
+ksort($replacements);
+echo preg_replace($patterns, $replacements, $string);
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+The slow black bear jumped over the lazy dog.
+]]>
+ </screen>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>替换一些值</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$patterns = array ('/(19|20)(\d{2})-(\d{1,2})-(\d{1,2})/',
+ '/^\s*{(\w+)}\s*=/');
+$replace = array ('\3/\4/\1\2', '$\1 =');
+echo preg_replace($patterns, $replace, '{startDate} = 1999-5-27');
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+$startDate = 5/27/1999
+]]>
+ </screen>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>使用修饰符'e'</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+preg_replace("/(<\/?)(\w+)([^>]*>)/e",
+ "'\\1'.strtoupper('\\2').'\\3'",
+ $html_body);
+?>
+]]>
+ </programlisting>
+ <para>
+ 这可以捕获输入文本中所有的html标签
+ </para>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>剥离空白字符</title>
+ <para>
+ 这个例子剥离多余的空白字符
+ </para>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$str = 'foo o';
+$str = preg_replace('/\s\s+/', ' ', $str);
+// 将会改变为'foo o'
+echo $str;
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>使用参数<parameter>count</parameter></title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$count = 0;
+
+echo preg_replace(array('/\d/', '/\s/'), '*', 'xp 4 to', -1 , $count);
+echo $count; //3
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+xp***to
+3
+]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ <note>
+ <para>
+ 当使用数组形式的<parameter>pattern</parameter>和
<parameter>replacement</parameter>时,
+ 将会按照key在数组中出现的顺序进行处理. 这<emphasis>不一定</emphasis>和数
组的索引顺序一致.
+ 如果你期望使用索引对等方式用<parameter>replacement</parameter>对
<parameter>pattern</parameter>
+ 进行替换, 你可以在调用<function>preg_replace</function>之前对两个数组各
进行一次<function>ksort</function>排序.
+ </para>
+ </note>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><link linkend="pcre.pattern">PCRE 模式</link></member>
+ <member><function>preg_filter</function></member>
+ <member><function>preg_match</function></member>
+ <member><function>preg_replace_callback</function></member>
+ <member><function>preg_split</function></member>
+ <member><function>preg_last_error</function></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
+-->
=======================================
--- /dev/null
+++ /trunk/xml/reference/pcre/functions/preg-split.xml Sun Apr 3 03:27:27
2011
@@ -0,0 +1,248 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- $Revision: 307739 $ -->
+<refentry xml:id="function.preg-split"
xmlns="http://docbook.org/ns/docbook">
+ <refnamediv>
+ <refname>preg_split</refname>
+ <refpurpose>通过一个正则表达式分隔字符串</refpurpose>
+ </refnamediv>
+
+ <refsect1 role="description">
+ &reftitle.description;
+ <methodsynopsis>
+ <type>array</type><methodname>preg_split</methodname>
+
<methodparam><type>string</type><parameter>pattern</parameter></methodparam>
+
<methodparam><type>string</type><parameter>subject</parameter></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
+ <methodparam
choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
+ </methodsynopsis>
+ <para>
+ 通过一个正则表达式分隔给定字符串.
+ </para>
+ </refsect1>
+
+ <refsect1 role="parameters">
+ &reftitle.parameters;
+ <para>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>pattern</parameter></term>
+ <listitem>
+ <para>
+ 用于搜索的模式, 字符串形式.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>subject</parameter></term>
+ <listitem>
+ <para>
+ 输入字符串
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>limit</parameter></term>
+ <listitem>
+ <para>
+ 如果指定, 将限制分隔得到的子串最多只有
<parameter>limit</parameter>个, 返回的最后一个
+ 子串将包含所有剩余部分.<parameter>limit</parameter>值为-1， 0或null时
都代表"不限制",
+ 作为php的标准, 你可以使用null跳过对<parameter>flags</parameter>的设
置.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>flags</parameter></term>
+ <listitem>
+ <para>
+ <parameter>flags</parameter>可以是任何下面标记的组合(以位或运算
<literal>|</literal>组合):
+ <variablelist>
+ <varlistentry>
+ <term><constant>PREG_SPLIT_NO_EMPTY</constant></term>
+ <listitem>
+ <simpara>
+ 如果这个标记被设置, <function>preg_split</function>将进返回分隔后
的非空部分.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>PREG_SPLIT_DELIM_CAPTURE</constant></term>
+ <listitem>
+ <simpara>
+ 如果这个标记设置了, 用于分隔的模式中的括号表达式将被捕获并返回.
+ </simpara>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><constant>PREG_SPLIT_OFFSET_CAPTURE</constant></term>
+ <listitem>
+ <para>
+ 如果这个标记被设置, 对于每一个出现的匹配返回时将会附加字符串偏移
量.
+ 注意: 这将会改变返回数组中的每一个元素, 使其每个元素成为一个由第
<literal>0</literal>
+ 个元素为分隔后的子串, 第<literal>1</literal>个元素为该子串在
<parameter>subject</parameter>
+ 中的偏移量组成的数组.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+ &reftitle.returnvalues;
+ <para>
+ 返回一个使用<parameter>pattern</parameter>边界分隔
<parameter>subject</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>4.3.0</entry>
+ <entry>
+ 增加了标记<constant>PREG_SPLIT_OFFSET_CAPTURE</constant>.
+ </entry>
+ </row>
+ <row>
+ <entry>4.0.5</entry>
+ <entry>
+ 增加了标记<constant>PREG_SPLIT_DELIM_CAPTURE</constant>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </para>
+ </refsect1>
+
+ <refsect1 role="examples">
+ &reftitle.examples;
+ <para>
+ <example>
+ <title><function>preg_split</function>示例: 获取搜索字符串的部分
</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+//使用逗号或空格(包含" ", \r, \t, \n, \f)分隔短语
+$keywords = preg_split("/[\s,]+/", "hypertext language, programming");
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>将一个字符串分隔为组成它的字符</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$str = 'string';
+$chars = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);
+print_r($chars);
+?>
+]]>
+ </programlisting>
+ </example>
+ </para>
+ <para>
+ <example>
+ <title>分隔一个字符串并获取每部分的偏移量</title>
+ <programlisting role="php">
+<![CDATA[
+<?php
+$str = 'hypertext language programming';
+$chars = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);
+print_r($chars);
+?>
+]]>
+ </programlisting>
+ &example.outputs;
+ <screen>
+<![CDATA[
+Array
+(
+ [0] => Array
+ (
+ [0] => hypertext
+ [1] => 0
+ )
+
+ [1] => Array
+ (
+ [0] => language
+ [1] => 10
+ )
+
+ [2] => Array
+ (
+ [0] => programming
+ [1] => 19
+ )
+
+)
+]]>
+ </screen>
+ </example>
+ </para>
+ </refsect1>
+
+ <refsect1 role="notes">
+ &reftitle.notes;
+ <tip>
+ <para>
+ 如果你不需要正则表达式功能, 可以有更快(并且更简单)的选择比如
<function>explode</function>
+ 或<function>str_split</function>.
+ </para>
+ </tip>
+ </refsect1>
+
+ <refsect1 role="seealso">
+ &reftitle.seealso;
+ <para>
+ <simplelist>
+ <member><link linkend="pcre.pattern">PCRE 模式</link></member>
+ <member><function>implode</function></member>
+ <member><function>preg_match</function></member>
+ <member><function>preg_match_all</function></member>
+ <member><function>preg_replace</function></member>
+ <member><function>preg_last_error</function></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
+-->