From a69f6cf5d2437de2f6011b25fc2b2b890e60ab2b Mon Sep 17 00:00:00 2001
From: "Christoph M. Becker" <cmbecker69@gmx.de>
Date: Mon, 15 Feb 2021 17:12:04 +0100
Subject: [PATCH] Clarify what the 'width' in mb_strimwidth means

Co-authored-by: Alex Dowad <alexinbeijing@gmail.com>

Closes GH-124.
---
 .../mbstring/functions/mb-strimwidth.xml      |  6 ++++-
 reference/mbstring/functions/mb-strwidth.xml  | 26 +++++++++++++++++++
 2 files changed, 31 insertions(+), 1 deletion(-)

diff --git a/reference/mbstring/functions/mb-strimwidth.xml b/reference/mbstring/functions/mb-strimwidth.xml
index 8246e974f2..3462e38482 100644
--- a/reference/mbstring/functions/mb-strimwidth.xml
+++ b/reference/mbstring/functions/mb-strimwidth.xml
@@ -17,7 +17,11 @@
    <methodparam choice="opt"><type class="union"><type>string</type><type>null</type></type><parameter>encoding</parameter><initializer>&null;</initializer></methodparam>
   </methodsynopsis>
   <para>
-   Truncates <type>string</type> <parameter>string</parameter> to specified <parameter>width</parameter>. 
+   Truncates <type>string</type> <parameter>string</parameter> to specified <parameter>width</parameter>,
+   where halfwidth characters count as <literal>1</literal>, and fullwidth
+   characters count as <literal>2</literal>.
+   See <link xlink:href="&url.unicode.reports.tr;11/">&url.unicode.reports.tr;11/</link>
+   for details regarding East Asian character widths.
   </para>
  </refsect1>
 
diff --git a/reference/mbstring/functions/mb-strwidth.xml b/reference/mbstring/functions/mb-strwidth.xml
index 5625cbc1e8..d391c24eee 100644
--- a/reference/mbstring/functions/mb-strwidth.xml
+++ b/reference/mbstring/functions/mb-strwidth.xml
@@ -17,6 +17,8 @@
    Returns the width of <type>string</type> <parameter>string</parameter>,
    where halfwidth characters count as <literal>1</literal>, and fullwidth
    characters count as <literal>2</literal>.
+   See <link xlink:href="&url.unicode.reports.tr;11/">&url.unicode.reports.tr;11/</link>
+   for details regarding East Asian character widths.
   </para>
   <para>
    The fullwidth characters are:
@@ -109,6 +111,30 @@
   </informaltable>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example xml:id="mb-strwidth.example.basic">
+   <title><function>mb_strwidth</function> example</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+var_dump(
+    mb_strwidth('a'),       // LATIN SMALL LETTER A
+    mb_strwidth("\u{ff41}") // FULLWIDTH LATIN SMALL LETTER A
+);
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+int(1)
+int(2)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>