[DOC-CVS] [doc-en] master: String comparison / similarity doc improvements (#4647)

Author: AllenJB (AllenJB)
Committer: GitHub (web-flow)
Pusher: Crell
Date: 2025-10-03T09:47:29-05:00

Commit: https://github.com/php/doc-en/commit/873f4a3d5027bd1b584f1d1e590e22cd4a08ae84
Raw diff: https://github.com/php/doc-en/commit/873f4a3d5027bd1b584f1d1e590e22cd4a08ae84.diff

String comparison / similarity doc improvements (#4647)

* strcmp: Improve behavior description and direct users to alternative functions (strcoll and Collator::compare) where appropriate;
Add the "similarity" functions to seealso
Removed substr from seealso (why is it here?)

* Cross-link all the string similarity functions

* Trailing whitespace removal

* Update reference/strings/functions/strcmp.xml

Co-authored-by: Kamil Tekiela <[email protected]>

* strcmp: Improve behavior description and direct users to alternative functions (strcoll and Collator::compare) where appropriate

---------

Co-authored-by: Kamil Tekiela <[email protected]>

Changed paths:
  M  reference/strings/functions/levenshtein.xml
  M  reference/strings/functions/metaphone.xml
  M  reference/strings/functions/similar-text.xml
  M  reference/strings/functions/soundex.xml
  M  reference/strings/functions/strcmp.xml


Diff:

diff --git a/reference/strings/functions/levenshtein.xml b/reference/strings/functions/levenshtein.xml
index b9a1f46b967b..f8f783ce8661 100644
--- a/reference/strings/functions/levenshtein.xml
+++ b/reference/strings/functions/levenshtein.xml
@@ -5,7 +5,7 @@
   <refname>levenshtein</refname>
   <refpurpose>Calculate Levenshtein distance between two strings</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -83,7 +83,7 @@
    </variablelist>
   </para>
  </refsect1>
- 
+
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <para>
diff --git a/reference/strings/functions/metaphone.xml b/reference/strings/functions/metaphone.xml
index f9a10da1de5b..ce5f7921dbfa 100644
--- a/reference/strings/functions/metaphone.xml
+++ b/reference/strings/functions/metaphone.xml
@@ -5,7 +5,7 @@
   <refname>metaphone</refname>
   <refpurpose>Calculate the metaphone key of a string</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -155,6 +155,16 @@ string(6) "ASTRKS"
   </para>
  </refsect1><!-- }}} -->
 
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>levenshtein</function></member>
+    <member><function>similar_text</function></member>
+    <member><function>soundex</function></member>
+   </simplelist>
+  </para>
+ </refsect1>
 </refentry>
 <!-- Keep this comment at the end of the file
 Local variables:
diff --git a/reference/strings/functions/similar-text.xml b/reference/strings/functions/similar-text.xml
index d3ea50b2b997..7756b73882d5 100644
--- a/reference/strings/functions/similar-text.xml
+++ b/reference/strings/functions/similar-text.xml
@@ -5,7 +5,7 @@
   <refname>similar_text</refname>
   <refpurpose>Calculate the similarity between two strings</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -110,6 +110,7 @@ similarity: 3 (42.857142857143 %)
   <para>
    <simplelist>
     <member><function>levenshtein</function></member>
+    <member><function>metaphone</function></member>
     <member><function>soundex</function></member>
    </simplelist>
   </para>
diff --git a/reference/strings/functions/soundex.xml b/reference/strings/functions/soundex.xml
index c20cfa65a75e..a167a5f8a631 100644
--- a/reference/strings/functions/soundex.xml
+++ b/reference/strings/functions/soundex.xml
@@ -5,7 +5,7 @@
   <refname>soundex</refname>
   <refpurpose>Calculate the soundex key of a string</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
diff --git a/reference/strings/functions/strcmp.xml b/reference/strings/functions/strcmp.xml
index f34c127bf74f..c0438c3e3349 100644
--- a/reference/strings/functions/strcmp.xml
+++ b/reference/strings/functions/strcmp.xml
@@ -5,7 +5,7 @@
   <refname>strcmp</refname>
   <refpurpose>Binary safe string comparison</refpurpose>
  </refnamediv>
- 
+
  <refsect1 role="description">
   &reftitle.description;
   <methodsynopsis>
@@ -14,7 +14,12 @@
    <methodparam><type>string</type><parameter>string2</parameter></methodparam>
   </methodsynopsis>
   <simpara>
-   Note that this comparison is case sensitive.
+   Note that this comparison is case sensitive. For case-insensitive comparison,
+   see <function>strcasecmp</function>.
+  </simpara>
+  <simpara>
+   Note that this comparison is not locale aware. For locale aware comparison see
+   <function>strcoll</function> or <methodname>Collator::compare</methodname>
   </simpara>
  </refsect1>
 
@@ -83,18 +88,38 @@ if (strcmp($var1, $var2) !== 0) {
    </example>   
   </para>
  </refsect1>
- 
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
-   <simplelist>
-    <member><function>strcasecmp</function></member>
-    <member><function>preg_match</function></member>
-    <member><function>substr_compare</function></member>
-    <member><function>strncmp</function></member>
-    <member><function>strstr</function></member>
-    <member><function>substr</function></member>
-   </simplelist>
+   <itemizedlist>
+    <listitem>
+     <simpara>Full string comparison</simpara>
+     <simplelist>
+      <member><function>strcasecmp</function></member>
+      <member><methodname>Collator::compare</methodname></member>
+      <member><function>strcoll</function></member>
+     </simplelist>
+    </listitem>
+    <listitem>
+     <simpara>Partial string comparison</simpara>
+     <simplelist>
+      <member><function>substr_compare</function></member>
+      <member><function>strncmp</function></member>
+      <member><function>strstr</function></member>
+     </simplelist>
+    </listitem>
+    <listitem>
+     <simpara>Similar / other string comparison</simpara>
+     <simplelist>
+      <member><function>preg_match</function></member>
+      <member><function>levenshtein</function></member>
+      <member><function>metaphone</function></member>
+      <member><function>similar_text</function></member>
+      <member><function>soundex</function></member>
+     </simplelist>
+    </listitem>
+   </itemizedlist>
   </para>
  </refsect1>