[PHP 8.4] Add more explaination for added mbstring functions (php#3929)

* [PHP 8.4] mb_[lr]?trim functions trimmed characters and some words modified. Add more explaination for mb_ucfirst and mb_lcfirst functions
lufei · Nov 13, 2024 · d0e23f4 · d0e23f4
1 parent 87ea6d1
commit d0e23f4
Show file tree

Hide file tree

Showing 6 changed files with 177 additions and 15 deletions.
diff --git a/language-snippets.ent b/language-snippets.ent
@@ -3625,6 +3625,146 @@ local: {
    </itemizedlist>
 '>
 
+<!ENTITY strings.stripped.unicode '
+ <itemizedlist xmlns="http://docbook.org/ns/docbook">
+    <listitem>
+     <simpara>
+      <literal>" "</literal> (<acronym>Unicode</acronym> U+0020), an ordinary space.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\t"</literal> (<acronym>Unicode</acronym> U+0009), a tab.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\n"</literal> (<acronym>Unicode</acronym> U+000A), a new line (line feed).
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\r"</literal> (<acronym>Unicode</acronym> U+000D), a carriage return.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\0"</literal> (<acronym>Unicode</acronym> U+0000), the NUL-byte.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\v"</literal> (<acronym>Unicode</acronym> U+000B), a vertical tab.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\f"</literal> (<acronym>Unicode</acronym> U+000C), a form feed.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u00A0"</literal> (<acronym>Unicode</acronym> U+00A0), a NO-BREAK SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u1680"</literal> (<acronym>Unicode</acronym> U+1680), a OGHAM SPACE MARK.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u2000"</literal> (<acronym>Unicode</acronym> U+2000), a EN QUAD.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u2001"</literal> (<acronym>Unicode</acronym> U+2001), a EM QUAD.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u2002"</literal> (<acronym>Unicode</acronym> U+2002), a EN SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u2003"</literal> (<acronym>Unicode</acronym> U+2003), a EM SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u2004"</literal> (<acronym>Unicode</acronym> U+2004), a THREE-PER-EM SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u2005"</literal> (<acronym>Unicode</acronym> U+2005), a FOUR-PER-EM SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <literal>"\u2006"</literal> (<acronym>Unicode</acronym> U+2006), a SIX-PER-EM SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u2007"</literal> (<acronym>Unicode</acronym> U+2007), a FIGURE SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u2008"</literal> (<acronym>Unicode</acronym> U+2008), a PUNCTUATION SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u2009"</literal> (<acronym>Unicode</acronym> U+2009), a THIN SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u200A"</literal> (<acronym>Unicode</acronym> U+200A), a HAIR SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u2028"</literal> (<acronym>Unicode</acronym> U+2028), a LINE SEPARATOR.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u2029"</literal> (<acronym>Unicode</acronym> U+2029), a PARAGRAPH SEPARATOR.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u202F"</literal> (<acronym>Unicode</acronym> U+202F), a NARROW NO-BREAK SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u205F"</literal> (<acronym>Unicode</acronym> U+205F), a MEDIUM MATHEMATICAL SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u3000"</literal> (<acronym>Unicode</acronym> U+3000), a IDEOGRAPHIC SPACE.
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u0085"</literal> (<acronym>Unicode</acronym> U+0085), a NEXT LINE (NEL).
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+     <literal>"\u180E"</literal> (<acronym>Unicode</acronym> U+180E), a MONGOLIAN VOWEL SEPARATOR.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+'>
+
 <!ENTITY strings.parameter.characters.optional '
  <simpara xmlns="http://docbook.org/ns/docbook">
   Optionally, the stripped characters can also be specified using
@@ -3634,6 +3774,14 @@ local: {
  </simpara>
 '>
 
+<!ENTITY strings.parameter.unicode.optional '
+ <simpara xmlns="http://docbook.org/ns/docbook">
+  Optionally, the stripped characters can also be specified using
+  the <parameter>characters</parameter> parameter.
+  Simply list all characters that need to be stripped.
+ </simpara>
+'>
+
 <!ENTITY strings.parameter.encoding '
  <para xmlns="http://docbook.org/ns/docbook">
   An optional argument defining the encoding used when converting characters.

diff --git a/reference/mbstring/functions/mb-lcfirst.xml b/reference/mbstring/functions/mb-lcfirst.xml
@@ -15,9 +15,7 @@
   <simpara>
    Performs a multi-byte safe <function>lcfirst</function> operation,
    and returns a string with the first character of
-   <parameter>string</parameter> lowercased if that character is
-   an ASCII character in the range <literal>"A"</literal> (0x41) to
-   <literal>"Z"</literal> (0x5a).
+   <parameter>string</parameter> lowercased.
   </simpara>
  </refsect1>
 

diff --git a/reference/mbstring/functions/mb-ltrim.xml b/reference/mbstring/functions/mb-ltrim.xml
@@ -21,7 +21,7 @@
    Without the second parameter,
    <function>mb_ltrim</function> will strip these characters:
   </simpara>
-  &strings.stripped.characters;
+  &strings.stripped.unicode;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -38,7 +38,7 @@
    <varlistentry>
     <term><parameter>characters</parameter></term>
     <listitem>
-     &strings.parameter.characters.optional;
+     &strings.parameter.unicode.optional;
     </listitem>
    </varlistentry>
    <varlistentry>

diff --git a/reference/mbstring/functions/mb-rtrim.xml b/reference/mbstring/functions/mb-rtrim.xml
@@ -20,9 +20,9 @@
   </simpara>
   <simpara>
    Without the second parameter,
-   <function>rtrim</function> will strip these characters:
+   <function>mb_rtrim</function> will strip these characters:
   </simpara>
-  &strings.stripped.characters;
+  &strings.stripped.unicode;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -39,7 +39,7 @@
    <varlistentry>
     <term><parameter>characters</parameter></term>
     <listitem>
-     &strings.parameter.characters.optional;
+     &strings.parameter.unicode.optional;
     </listitem>
    </varlistentry>
    <varlistentry>

diff --git a/reference/mbstring/functions/mb-trim.xml b/reference/mbstring/functions/mb-trim.xml
@@ -18,9 +18,9 @@
    and returns a string with whitespace stripped from the
    beginning and end of <parameter>string</parameter>.
    Without the second parameter,
-   <function>trim</function> will strip these characters:
+   <function>mb_trim</function> will strip these characters:
   </simpara>
-  &strings.stripped.characters;
+  &strings.stripped.unicode;
  </refsect1>
 
  <refsect1 role="parameters">
@@ -37,7 +37,7 @@
    <varlistentry>
     <term><parameter>characters</parameter></term>
     <listitem>
-     &strings.parameter.characters.optional;
+     &strings.parameter.unicode.optional;
     </listitem>
    </varlistentry>
    <varlistentry>

diff --git a/reference/mbstring/functions/mb-ucfirst.xml b/reference/mbstring/functions/mb-ucfirst.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<refentry xml:id="function.mb-ucfirst" xmlns="http://docbook.org/ns/docbook">
+<refentry xml:id="function.mb-ucfirst" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>mb_ucfirst</refname>
   <refpurpose>Make a string's first character uppercase</refpurpose>
@@ -15,9 +15,7 @@
   <simpara>
    Performs a multi-byte safe <function>ucfirst</function> operation,
    and returns a string with the first character of
-   <parameter>string</parameter> capitalized, if that character is
-   an ASCII character in the range from <literal>"a"</literal> (0x61) to
-   <literal>"z"</literal> (0x7a).
+   <parameter>string</parameter> title-cased.
   </simpara>
  </refsect1>
 
@@ -50,6 +48,24 @@
   </simpara>
  </refsect1>
 
+ <refsect1 role="notes">
+  &reftitle.notes;
+  <note>
+   <para>
+    By contrast to the standard case folding functions such as
+    <function>strtolower</function> and <function>strtoupper</function>,
+    case folding is performed on the basis of the Unicode character
+    properties. Thus the behaviour of this function is not affected
+    by locale settings and it can convert any characters that have
+    'alphabetic' property, such a-umlaut (ä).
+   </para>
+  </note>
+  <para>
+   For more information about the Unicode properties, please see <link
+   xlink:href="&url.unicode.reports;">&url.unicode.reports;</link>.
+  </para>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <simplelist>