From 09699945bfc02361f906b97a4c4b94aae86df228 Mon Sep 17 00:00:00 2001
From: Luffy <lufei@php.net>
Date: Wed, 18 Dec 2024 08:56:30 +0800
Subject: [PATCH] Clarify return value of strcmp() and friends (#953)

---
 language-snippets.ent                          | 14 +++++++++++---
 reference/strings/functions/strcasecmp.xml     | 10 +++-------
 reference/strings/functions/strcmp.xml         | 10 +++-------
 reference/strings/functions/strnatcasecmp.xml  | 11 +++--------
 reference/strings/functions/strnatcmp.xml      | 12 +++---------
 reference/strings/functions/strncasecmp.xml    | 10 +++-------
 reference/strings/functions/strncmp.xml        |  8 ++------
 reference/strings/functions/substr-compare.xml | 11 ++++-------
 reference/var/functions/empty.xml              | 14 +++++++-------
 9 files changed, 39 insertions(+), 61 deletions(-)

diff --git a/language-snippets.ent b/language-snippets.ent
index 2429fbb47..92076a0ea 100644
--- a/language-snippets.ent
+++ b/language-snippets.ent
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: e93feee2870bb551cd11d625271b7f82da3ccb05 Maintainer: Gregory Status: ready -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: Gregory Status: ready -->
 <!-- CREDITS: dallas, mowangjuanzi, Luffy -->
 <!-- 请保持此文件与英文文件中相应的每个 ENTITY 行号一一对应以便于对照，修改与更新！ -->
 
@@ -854,7 +854,8 @@ linkend="language.types.boolean">布尔类型</link>章节以获取更多信息
 <!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.2.0</entry>
  <entry>
-  现在此函数返回 <literal>-1</literal> 或者 <literal>1</literal>，之前返回负数或正数。
+  当字符串长度不相等时，此函数不再保证返回 <literal>strlen($string1) - strlen($string2)</literal>，
+  而可能返回 <literal>-1</literal> 或 <literal>1</literal>。
  </entry>
 </row>
 '>
@@ -4385,7 +4386,14 @@ local: {
   </para>
 '>
 
-
+<!ENTITY strings.comparison.return '
+  <simpara xmlns="http://docbook.org/ns/docbook">
+   如果 <parameter>string1</parameter> 小于 <parameter>string2</parameter>，则返回小于 0 的值；
+   如果 <parameter>string1</parameter> 大于 <parameter>string2</parameter>，则返回大于 0 的值；
+   如果它们相等，则返回 <literal>0</literal>。
+   除了它的符号外，不能从返回值中可靠推断出任何特定的含义。
+  </simpara>
+'>
 
 <!-- filter snippets -->
 <!ENTITY filter.param.filter '
diff --git a/reference/strings/functions/strcasecmp.xml b/reference/strings/functions/strcasecmp.xml
index ae6a09249..a1ef4c687 100644
--- a/reference/strings/functions/strcasecmp.xml
+++ b/reference/strings/functions/strcasecmp.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a3573c18b89fd32aca1c3924d3fd9568900b4a33 Maintainer: daijie Status: ready -->
-<!-- CREDITS: mowangjuanzi -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: daijie Status: ready -->
+<!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xml:id="function.strcasecmp" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>strcasecmp</refname>
@@ -46,11 +46,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   如果 <parameter>string1</parameter> 小于 <parameter>string2</parameter> 返回
-   <literal>-1</literal>；如果 <parameter>string1</parameter> 大于 <parameter>string2</parameter>
-   返回 <literal>1</literal>；如果两者相等，返回 <literal>0</literal>。
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">
diff --git a/reference/strings/functions/strcmp.xml b/reference/strings/functions/strcmp.xml
index 501adb97b..ab8d28321 100644
--- a/reference/strings/functions/strcmp.xml
+++ b/reference/strings/functions/strcmp.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a3573c18b89fd32aca1c3924d3fd9568900b4a33 Maintainer: daijie Status: ready -->
-<!-- CREDITS: mowangjuanzi -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: daijie Status: ready -->
+<!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strcmp">
  <refnamediv>
   <refname>strcmp</refname>
@@ -46,11 +46,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   如果 <parameter>string1</parameter> 小于 <parameter>string2</parameter> 返回
-   <literal>-1</literal>；如果 <parameter>string1</parameter> 大于 <parameter>string2</parameter>
-   返回 <literal>1</literal>；如果两者相等，返回 <literal>0</literal>。
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">
diff --git a/reference/strings/functions/strnatcasecmp.xml b/reference/strings/functions/strnatcasecmp.xml
index 4ad338310..37178629b 100644
--- a/reference/strings/functions/strnatcasecmp.xml
+++ b/reference/strings/functions/strnatcasecmp.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a3573c18b89fd32aca1c3924d3fd9568900b4a33 Maintainer: daijie Status: ready -->
-<!-- CREDITS: mowangjuanzi -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: daijie Status: ready -->
+<!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.strnatcasecmp">
  <refnamediv>
   <refname>strnatcasecmp</refname>
@@ -47,12 +47,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   与其他字符串比较函数类似，如果 <parameter>string1</parameter> 小于
-   <parameter>string2</parameter> 返回 <literal>-1</literal>；
-   如果 <parameter>string1</parameter> 大于 <parameter>string2</parameter>
-   返回 <literal>1</literal>；如果两者相等，返回 <literal>0</literal>。
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">
diff --git a/reference/strings/functions/strnatcmp.xml b/reference/strings/functions/strnatcmp.xml
index e53126099..8aac0ae68 100644
--- a/reference/strings/functions/strnatcmp.xml
+++ b/reference/strings/functions/strnatcmp.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a3573c18b89fd32aca1c3924d3fd9568900b4a33 Maintainer: daijie Status: ready -->
-<!-- CREDITS: mowangjuanzi -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: daijie Status: ready -->
+<!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xmlns:xlink="http://www.w3.org/1999/xlink" xmlns="http://docbook.org/ns/docbook" xml:id="function.strnatcmp">
  <refnamediv>
   <refname>strnatcmp</refname>
@@ -46,13 +46,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   与其他字符串比较函数类似，如果 <parameter>string1</parameter> 小于
-   <parameter>string2</parameter> 返回 <literal>-1</literal>；
-   如果 <parameter>string1</parameter>
-   大于 <parameter>string2</parameter>
-   返回 <literal>1</literal>；如果两者相等，返回 <literal>0</literal>。
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">
diff --git a/reference/strings/functions/strncasecmp.xml b/reference/strings/functions/strncasecmp.xml
index 14c552eb3..966b3a534 100644
--- a/reference/strings/functions/strncasecmp.xml
+++ b/reference/strings/functions/strncasecmp.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a3573c18b89fd32aca1c3924d3fd9568900b4a33 Maintainer: daijie Status: ready -->
-<!-- CREDITS: mowangjuanzi -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: daijie Status: ready -->
+<!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xml:id="function.strncasecmp" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>strncasecmp</refname>
@@ -55,11 +55,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   如果 <parameter>string1</parameter> 小于 <parameter>string2</parameter> 返回
-   <literal>-1</literal>；如果 <parameter>string1</parameter> 大于
-   <parameter>string2</parameter>，返回 <literal>1</literal>；如果两者相等，返回 <literal>0</literal>。
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">
diff --git a/reference/strings/functions/strncmp.xml b/reference/strings/functions/strncmp.xml
index 37299ae19..ee21d7063 100644
--- a/reference/strings/functions/strncmp.xml
+++ b/reference/strings/functions/strncmp.xml
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 43cc4ed372bde0a8ee986d57bf522d14099d54a6 Maintainer: daijie Status: ready -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: daijie Status: ready -->
 <!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xml:id="function.strncmp" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -58,11 +58,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   如果 <parameter>string1</parameter> 小于 <parameter>string2</parameter> 返回
-   <literal>-1</literal>；如果 <parameter>string1</parameter> 大于 <parameter>string2</parameter>
-   返回 <literal>1</literal>；如果两者相等，返回 <literal>0</literal>。
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">
diff --git a/reference/strings/functions/substr-compare.xml b/reference/strings/functions/substr-compare.xml
index 7a6a38403..1962d676b 100644
--- a/reference/strings/functions/substr-compare.xml
+++ b/reference/strings/functions/substr-compare.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: a3573c18b89fd32aca1c3924d3fd9568900b4a33 Maintainer: daijie Status: ready -->
-<!-- CREDITS: mowangjuanzi -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: daijie Status: ready -->
+<!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xml:id="function.substr-compare" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>substr_compare</refname>
@@ -79,12 +79,9 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
+  &strings.comparison.return;
   <para>
-   如果 <parameter>haystack</parameter> 从偏移位置
-   <parameter>offset</parameter> 起的子字符串小于
-   <parameter>needle</parameter>，则返回 <literal>-1</literal>；如果大于
-   <parameter>needle</parameter>，则返回 <literal>1</literal>；如果二者相等，则返回 <literal>0</literal>。如果
-   <parameter>offset</parameter> 等于（在 PHP 7.2.18, 7.3.5 之前）或大于
+   如果 <parameter>offset</parameter> 等于（在 PHP 7.2.18, 7.3.5 之前）或大于
    <parameter>haystack</parameter> 的长度，或设置
    <parameter>length</parameter> 小于或等于 0，<function>substr_compare</function>
    将打印出警告信息并且返回 &false;。
diff --git a/reference/var/functions/empty.xml b/reference/var/functions/empty.xml
index bcf433302..e585ce50b 100644
--- a/reference/var/functions/empty.xml
+++ b/reference/var/functions/empty.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 4a07033f7ac5ab121357051cc94ec48b9f6f58fc Maintainer: HonestQiao Status: ready -->
-<!-- CREDITS: mowangjuanzi -->
+<!-- EN-Revision: 9b68bf2b63200534e022bc65e800cae6c75abf26 Maintainer: HonestQiao Status: ready -->
+<!-- CREDITS: mowangjuanzi, Luffy -->
 <refentry xml:id="function.empty" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
   <refname>empty</refname>
@@ -14,8 +14,8 @@
    <methodparam><type>mixed</type><parameter>var</parameter></methodparam>
   </methodsynopsis>
   <para>
-   判断变量是否为是空。当变量不存在或者它的值等于
-   &false;，那么视为空。如果变量不存在，<function>empty</function> 不会产生警告。
+   判断变量是否为空。如果变量不存在或其值等于 &false;，则认为变量为空。
+   <function>empty</function> 不会在变量不存在时产生警告。
   </para>
  </refsect1>
  <refsect1 role="parameters">
@@ -29,8 +29,8 @@
        待检查的变量
       </para>
       <para>
-       没有警告会产生，哪怕变量并不存在。这意味着 <function>empty</function> 本质上与
-       <command>!isset($var) || $var == false</command> 等价。
+       不会在变量不存在时产生警告。
+       这意味着 <function>empty</function> 本质上等同于 <command>!isset($var) || $var == false</command>。
       </para>
      </listitem>
     </varlistentry>
@@ -40,7 +40,7 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
-   当 <parameter>var</parameter> 不存在、值为空、等于 0、为 false 时，返回 &true;。参阅 <link
+   当 <parameter>var</parameter> 不存在、值为空、等于 0、为 false 时，返回 &true;，参阅 <link
    linkend="language.types.boolean.casting">转换为 boolean</link>。否则返回 &false;。
   </para>
  </refsect1>