From 0053ae2acdb344475a49b14cfe8b5b4c7d11d4aa Mon Sep 17 00:00:00 2001
From: Louis-Arnaud <la.catoire@gmail.com>
Date: Wed, 9 Sep 2026 09:55:00 +0200
Subject: [PATCH] [Sync-En] mbstring: clarify the mb_*_numericentity ValueError
 conditions and reformat the examples

---
 .../functions/mb-decode-numericentity.xml     | 124 ++++++++++--------
 .../functions/mb-encode-numericentity.xml     |  26 ++--
 2 files changed, 82 insertions(+), 68 deletions(-)

diff --git a/reference/mbstring/functions/mb-decode-numericentity.xml b/reference/mbstring/functions/mb-decode-numericentity.xml
index 9fe776c671..cedd43afad 100644
--- a/reference/mbstring/functions/mb-decode-numericentity.xml
+++ b/reference/mbstring/functions/mb-decode-numericentity.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 4e69a9f2b14deefca0befec576335e33152448f3 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 0bb8d1a0dda028c1086f07dbae25d320850d7a90 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.mb-decode-numericentity" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -63,7 +63,8 @@
   &reftitle.errors;
   <simpara>
    Genera una excepción <exceptionname>ValueError</exceptionname> si
-   <parameter>map</parameter> no es una lista de &integer;s.
+   <parameter>map</parameter> contiene algún valor que no sea un
+   &integer;, &float;, &boolean;, &null;, o una <link linkend="language.types.numeric-strings">string numérica</link>.
   </simpara>
  </refsect1>
 
@@ -81,9 +82,9 @@
      <row>
       <entry>8.4.0</entry>
       <entry>
-       <function>mb_decode_numericentity</function> ahora genera una
+       La función <function>mb_decode_numericentity</function> ahora genera una
        <exceptionname>ValueError</exceptionname> si <parameter>map</parameter>
-       no es una lista de &integer;s.
+       contiene algún valor que no pueda convertirse implícitamente a int.
       </entry>
      </row>
      &mbstring.changelog.encoding-nullable;
@@ -100,11 +101,13 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$convmap = array (
-   int start_code1, int end_code1, int offset1, int mask1,
-   int start_code2, int end_code2, int offset2, int mask2,
-   // ........
-   int start_codeN, int end_codeN, int offsetN, int maskN );
+
+$convmap = array(
+    int start_code1, int end_code1, int offset1, int mask1,
+    int start_code2, int end_code2, int offset2, int mask2,
+    // ........
+    int start_codeN, int end_codeN, int offsetN, int maskN
+);
 // Especificar valor Unicode para start_codeN y end_codeN
 // Añadir offsetN al valor y realizar 'AND' a nivel de bits con maskN,
 // luego convertir el valor a referencia numérica de cadena.
@@ -120,60 +123,67 @@ $convmap = array (
     <programlisting role="php">
 <![CDATA[
 <?php
-function escape_javascript_string($str) {
-  $map = [
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,0,0, // 49
-          0,0,0,0,0,0,0,0,1,1,
-          1,1,1,1,1,0,0,0,0,0,
-          0,0,0,0,0,0,0,0,0,0,
-          0,0,0,0,0,0,0,0,0,0,
-          0,1,1,1,1,1,1,0,0,0, // 99
-          0,0,0,0,0,0,0,0,0,0,
-          0,0,0,0,0,0,0,0,0,0,
-          0,0,0,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1, // 149
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1, // 199
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1,
-          1,1,1,1,1,1,1,1,1,1, // 249
-          1,1,1,1,1,1,1, // 255
-          ];
-  // Codificación de caracteres es UTF-8
-  $mblen = mb_strlen($str, 'UTF-8');
-  $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
-  for ($i=0, $encoded=''; $i < $mblen; $i++) {
-      $u = substr($utf32, $i*8, 8);
-      $v = base_convert($u, 16, 10);
-      if ($v < 256 && $map[$v]) {
-        $encoded .= '\\x'.substr($u, 6,2);
-      } else if ($v == 2028) {
-        $encoded .= '\\u2028';
-      } else if ($v == 2029) {
-        $encoded .= '\\u2029';
-      } else {
-        $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
-      }
-   }
-   return $encoded;
+
+function escape_javascript_string($str)
+{
+    $map = [
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,0,0, // 49
+        0,0,0,0,0,0,0,0,1,1,
+        1,1,1,1,1,0,0,0,0,0,
+        0,0,0,0,0,0,0,0,0,0,
+        0,0,0,0,0,0,0,0,0,0,
+        0,1,1,1,1,1,1,0,0,0, // 99
+        0,0,0,0,0,0,0,0,0,0,
+        0,0,0,0,0,0,0,0,0,0,
+        0,0,0,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1, // 149
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1, // 199
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1,
+        1,1,1,1,1,1,1,1,1,1, // 249
+        1,1,1,1,1,1,1, // 255
+    ];
+
+    // La codificación de caracteres es UTF-8
+    $mblen = mb_strlen($str, 'UTF-8');
+    $utf32 = bin2hex(mb_convert_encoding($str, 'UTF-32', 'UTF-8'));
+
+    for ($i=0, $encoded=''; $i < $mblen; $i++) {
+        $u = substr($utf32, $i * 8, 8);
+        $v = base_convert($u, 16, 10);
+
+        if ($v < 256 && $map[$v]) {
+            $encoded .= '\\x' . substr($u, 6,2);
+        } else if ($v == 2028) {
+            $encoded .= '\\u2028';
+        } else if ($v == 2029) {
+            $encoded .= '\\u2029';
+        } else {
+            $encoded .= mb_convert_encoding(hex2bin($u), 'UTF-8', 'UTF-32');
+        }
+    }
+
+    return $encoded;
 }
 
-  // Datos de prueba
+// Datos de prueba
 $convmap = [ 0x0, 0xffff, 0, 0xffff ];
 $msg = '';
+
 for ($i=0; $i < 1000; $i++) {
   // chr() no puede generar datos UTF-8 correctos mayores que 128, usar mb_decode_numericentity().
-  $msg .= mb_decode_numericentity('&#'.$i.';', $convmap, 'UTF-8');
+  $msg .= mb_decode_numericentity('&#' . $i . ';', $convmap, 'UTF-8');
 }
 
 // var_dump($msg);
diff --git a/reference/mbstring/functions/mb-encode-numericentity.xml b/reference/mbstring/functions/mb-encode-numericentity.xml
index dd423dc56e..6023d25bf7 100644
--- a/reference/mbstring/functions/mb-encode-numericentity.xml
+++ b/reference/mbstring/functions/mb-encode-numericentity.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: a60ef65239113c7871643be68ada91081376c936 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 0bb8d1a0dda028c1086f07dbae25d320850d7a90 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no -->
 <refentry xml:id="function.mb-encode-numericentity" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
@@ -74,7 +74,8 @@
   &reftitle.errors;
   <simpara>
    Lanza una <exceptionname>ValueError</exceptionname> si
-   <parameter>map</parameter> no es una lista de &integer;s.
+   <parameter>map</parameter> contiene algún valor que no sea un
+   &integer;, &float;, &boolean;, &null;, o una <link linkend="language.types.numeric-strings">string numérica</link>.
   </simpara>
  </refsect1>
 
@@ -92,9 +93,9 @@
      <row>
       <entry>8.4.0</entry>
       <entry>
-       <function>mb_encode_numericentity</function> ahora lanza una
+       La función <function>mb_encode_numericentity</function> ahora lanza una
        <exceptionname>ValueError</exceptionname> si <parameter>map</parameter>
-       no es una lista de &integer;s.
+       contiene algún valor que no pueda convertirse implícitamente a int.
       </entry>
      </row>
      &mbstring.changelog.encoding-nullable;
@@ -111,14 +112,16 @@
     <programlisting role="php">
 <![CDATA[
 <?php
-$convmap = array (
- int start_code1, int end_code1, int offset1, int mask1,
- int start_code2, int end_code2, int offset2, int mask2,
- ........
- int start_codeN, int end_codeN, int offsetN, int maskN );
+
+$convmap = array(
+    int start_code1, int end_code1, int offset1, int mask1,
+    int start_code2, int end_code2, int offset2, int mask2,
+    // ........
+    int start_codeN, int end_codeN, int offsetN, int maskN
+);
 // Especificar valor Unicode para start_codeN y end_codeN
-// Añadir offsetN al valor y hacer un 'AND' a nivel de bits con maskN, luego
-// convierte el valor a referencia numérica de string.
+// Añadir offsetN al valor y hacer un 'AND' a nivel de bits con maskN,
+// luego convierte el valor a referencia numérica de string.
 ?>
 ]]>
     </programlisting>
@@ -143,6 +146,7 @@ $convmap = [
     0x80, 0x7FF, 0, 0x10FFFF,
     0x10000, 0x1FFFFF, 0, 0x10FFFF,
 ];
+
 var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
 ?>
 ]]>