Clarify return value of strcmp() and friends (fixes #3629) (#4295)

Author: jimwins

language-snippets.ent

@@ -854,8 +854,10 @@ function.</simpara></warning>'>
 <!ENTITY standard.changelog.binary-safe-string-comparison '<row xmlns="http://docbook.org/ns/docbook">
  <entry>8.2.0</entry>
  <entry>
-  This function now returns <literal>-1</literal> or <literal>1</literal>,
-  where it previously returned a negative or positive number.
+  This function is no longer guaranteed to return
+  <code>strlen($string1) - strlen($string2)</code> when string lengths
+  are not equal, but may now return <literal>-1</literal> or
+  <literal>1</literal> instead.
  </entry>
 </row>
 '>
@@ -4390,6 +4392,18 @@ local: {
   </para>
 '>
 
+<!ENTITY strings.comparison.return '
+  <simpara xmlns="http://docbook.org/ns/docbook">
+   Returns a value less than 0 if <parameter>string1</parameter>
+   is less than <parameter>string2</parameter>; a value greater
+   than 0 if <parameter>string1</parameter> is greater than
+   <parameter>string2</parameter>, and <literal>0</literal> if they
+   are equal.
+   No particular meaning can be reliably inferred from the value aside
+   from its sign.
+  </simpara>
+'>
+
 <!-- filter snippets -->
 <!-- TODO: Remove -->
 <!ENTITY filter.param.filter '

reference/strings/functions/strcasecmp.xml

@@ -46,12 +46,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>-1</literal> if <parameter>string1</parameter> is less than
-   <parameter>string2</parameter>; <literal>1</literal> if <parameter>string1</parameter>
-   is greater than <parameter>string2</parameter>, and <literal>0</literal> if they are
-   equal.
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">

reference/strings/functions/strcmp.xml

@@ -44,12 +44,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>-1</literal> if <parameter>string1</parameter> is less than
-   <parameter>string2</parameter>; <literal>1</literal> if <parameter>string1</parameter>
-   is greater than <parameter>string2</parameter>, and <literal>0</literal> if they are
-   equal.
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">

reference/strings/functions/strnatcasecmp.xml

@@ -48,12 +48,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Similar to other string comparison functions, this one returns <literal>-1</literal> if
-   <parameter>string1</parameter> is less than <parameter>string2</parameter>
-   <literal>1</literal> if <parameter>string1</parameter> is greater than
-   <parameter>string2</parameter>, and <literal>0</literal> if they are equal.
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">

reference/strings/functions/strnatcmp.xml

@@ -47,12 +47,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Similar to other string comparison functions, this one returns <literal>-1</literal> if
-   <parameter>string1</parameter> is less than <parameter>string2</parameter>;
-   <literal>1</literal> if <parameter>string1</parameter> is greater than
-   <parameter>string2</parameter>, and <literal>0</literal> if they are equal.
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">

reference/strings/functions/strncasecmp.xml

@@ -55,11 +55,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>-1</literal> if <parameter>string1</parameter> is less than
-   <parameter>string2</parameter>; <literal>1</literal> if <parameter>string1</parameter> is
-   greater than <parameter>string2</parameter>, and <literal>0</literal> if they are equal.
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">

reference/strings/functions/strncmp.xml

@@ -58,12 +58,7 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns <literal>-1</literal> if <parameter>string1</parameter> is less than
-   <parameter>string2</parameter>; <literal>1</literal> if <parameter>string1</parameter>
-   is greater than <parameter>string2</parameter>, and <literal>0</literal> if they are
-   equal.
-  </para>
+  &strings.comparison.return;
  </refsect1>
 
  <refsect1 role="changelog">

reference/strings/functions/substr-compare.xml

@@ -78,10 +78,8 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
+  &strings.comparison.return;
   <para>
-   Returns <literal>-1</literal> if <parameter>haystack</parameter> from position
-   <parameter>offset</parameter> is less than <parameter>needle</parameter>, <literal>1</literal>
-   if it is greater than <parameter>needle</parameter>, and <literal>0</literal> if they are equal.
    If <parameter>offset</parameter> is equal to (prior to PHP 7.2.18, 7.3.5) or
    greater than the length of <parameter>haystack</parameter>, or the
    <parameter>length</parameter> is set and is less than 0,