From 3e15bc31a177779fd665f85f8abe2016a6a3c684 Mon Sep 17 00:00:00 2001
From: lacatoire <la.catoire@gmail.com>
Date: Mon, 31 Aug 2026 13:01:18 +0200
Subject: [PATCH 1/4] add the grapheme_levenshtein() manual page

---
 .../intl/grapheme/grapheme-levenshtein.xml    | 219 ++++++++++++++++++
 1 file changed, 219 insertions(+)
 create mode 100644 reference/intl/grapheme/grapheme-levenshtein.xml

diff --git a/reference/intl/grapheme/grapheme-levenshtein.xml b/reference/intl/grapheme/grapheme-levenshtein.xml
new file mode 100644
index 000000000..c343da2fe
--- /dev/null
+++ b/reference/intl/grapheme/grapheme-levenshtein.xml
@@ -0,0 +1,219 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- EN-Revision: 469efd89e78e8d003d7222550f7cdcf4a8f417b1 Maintainer: shein Status: ready -->
+<!-- Reviewed: no -->
+<refentry xml:id="function.grapheme-levenshtein" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
+ <refnamediv>
+  <refname>grapheme_levenshtein</refname>
+  <refpurpose>Вычисляет расстояние Левенштейна между двумя строками в единицах графем</refpurpose>
+ </refnamediv>
+ <refsect1 role="description">
+  &reftitle.description;
+  <simpara>&style.procedural;</simpara>
+  <methodsynopsis>
+   <type class="union"><type>int</type><type>false</type></type><methodname>grapheme_levenshtein</methodname>
+   <methodparam><type>string</type><parameter>string1</parameter></methodparam>
+   <methodparam><type>string</type><parameter>string2</parameter></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>insertion_cost</parameter><initializer>1</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>replacement_cost</parameter><initializer>1</initializer></methodparam>
+   <methodparam choice="opt"><type>int</type><parameter>deletion_cost</parameter><initializer>1</initializer></methodparam>
+   <methodparam choice="opt"><type>string</type><parameter>locale</parameter><initializer>""</initializer></methodparam>
+  </methodsynopsis>
+  <simpara>
+   Расстояние Левенштейна определяют как минимальное количество кластеров графем,
+   которые требуется заменить, вставить или удалить, чтобы преобразовать строку
+   <parameter>string1</parameter> в строку <parameter>string2</parameter>.
+   Сложность алгоритма — <literal>O(m*n)</literal>, где <literal>n</literal>
+   и <literal>m</literal> — длины строк <parameter>string1</parameter>
+   и <parameter>string2</parameter> в единицах графем.
+  </simpara>
+  <simpara>
+   В отличие от функции <function>levenshtein</function>, которая работает
+   с байтами, эта функция считает Unicode-кластеры графем, поэтому составную
+   и разложенную формы одного и того же символа, например
+   <literal>U+00E9</literal> и <literal>U+0065 U+0301</literal>, каждая
+   из которых представляет символ <literal>é</literal>, функция считает
+   равнозначными, а расстояние между ними — нулевым.
+  </simpara>
+  <simpara>
+   Если значения параметров <parameter>insertion_cost</parameter>,
+   <parameter>replacement_cost</parameter> или <parameter>deletion_cost</parameter>
+   отличаются от <literal>1</literal>, алгоритм подстраивается и выбирает
+   самые дешёвые преобразования.
+   Например, если <literal>$insertion_cost + $deletion_cost &lt; $replacement_cost</literal>,
+   замены не выполняются, а вместо них выполняются вставки и удаления.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="parameters">
+  &reftitle.parameters;
+  <para>
+   <variablelist>
+    <varlistentry>
+     <term><parameter>string1</parameter></term>
+     <listitem>
+      <simpara>
+       Одна из строк, для которых вычисляют расстояние Левенштейна.
+       Строка должна быть корректной в кодировке UTF-8.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>string2</parameter></term>
+     <listitem>
+      <simpara>
+       Одна из строк, для которых вычисляют расстояние Левенштейна.
+       Строка должна быть корректной в кодировке UTF-8.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>insertion_cost</parameter></term>
+     <listitem>
+      <simpara>
+       Задаёт стоимость вставки. Значение должно быть больше <literal>0</literal>.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>replacement_cost</parameter></term>
+     <listitem>
+      <simpara>
+       Задаёт стоимость замены. Значение должно быть больше <literal>0</literal>.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>deletion_cost</parameter></term>
+     <listitem>
+      <simpara>
+       Задаёт стоимость удаления. Значение должно быть больше <literal>0</literal>.
+      </simpara>
+     </listitem>
+    </varlistentry>
+    <varlistentry>
+     <term><parameter>locale</parameter></term>
+     <listitem>
+      &intl.param.grapheme.locale;
+     </listitem>
+    </varlistentry>
+   </variablelist>
+  </para>
+ </refsect1>
+
+ <refsect1 role="returnvalues">
+  &reftitle.returnvalues;
+  <simpara>
+   Функция возвращает расстояние Левенштейна между двумя строками в единицах
+   графем или &false; в случае ошибки. Подробности об ошибке возвращает
+   функция <function>intl_get_error_message</function>.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="errors">
+  &reftitle.errors;
+  <simpara>
+   Функция выбрасывает ошибку <exceptionname>ValueError</exceptionname>, если
+   значение параметра <parameter>insertion_cost</parameter>,
+   <parameter>replacement_cost</parameter> или <parameter>deletion_cost</parameter>
+   меньше или равно <literal>0</literal>.
+  </simpara>
+  <simpara>
+   Функция возвращает &false; и устанавливает ошибку intl, если одна
+   из входных строк некорректна в кодировке UTF-8, если значение параметра
+   <parameter>locale</parameter> — некорректный идентификатор локали
+   или если произошла внутренняя ошибка библиотеки ICU.
+  </simpara>
+ </refsect1>
+
+ <refsect1 role="changelog">
+  &reftitle.changelog;
+  <informaltable>
+   <tgroup cols="2">
+    <thead>
+     <row>
+      <entry>&Version;</entry>
+      <entry>&Description;</entry>
+     </row>
+    </thead>
+    <tbody>
+     <row>
+      <entry>8.5.0</entry>
+      <entry>
+       Функцию добавили.
+      </entry>
+     </row>
+    </tbody>
+   </tgroup>
+  </informaltable>
+ </refsect1>
+
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title>Пример использования функции <function>grapheme_levenshtein</function></title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+
+// Составная форма (NFC): U+00E9 LATIN SMALL LETTER E WITH ACUTE
+$e_composed = "\u{00E9}";
+
+// Разложенная форма (NFD): U+0065 + U+0301 (e + комбинируемый акут)
+$e_decomposed = "\u{0065}\u{0301}";
+
+// Функция grapheme_levenshtein считает их одним и тем же кластером графем
+var_dump(grapheme_levenshtein($e_composed, $e_decomposed));
+
+// Функция levenshtein() работает с байтами и видит их как разные
+var_dump(levenshtein($e_composed, $e_decomposed));
+
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+int(0)
+int(3)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
+ <refsect1 role="seealso">
+  &reftitle.seealso;
+  <para>
+   <simplelist>
+    <member><function>levenshtein</function></member>
+    <member><function>grapheme_strlen</function></member>
+    <member><function>grapheme_substr</function></member>
+    <member><function>similar_text</function></member>
+    <member>
+     <link xlink:href="&uri.unicode.graphemes;">
+      Unicode Text Segmentation: Grapheme Cluster Boundaries
+     </link>
+    </member>
+   </simplelist>
+  </para>
+ </refsect1>
+</refentry>
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:1
+sgml-indent-data:t
+indent-tabs-mode:nil
+sgml-parent-document:nil
+sgml-default-dtd-file:"~/.phpdoc/manual.ced"
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+vim600: syn=xml fen fdm=syntax fdl=2 si
+vim: et tw=78 syn=sgml
+vi: ts=1 sw=1
+-->

From 4136d213bcb6c5b9688f3a0f9b00601b5e85f14f Mon Sep 17 00:00:00 2001
From: Mikhail Alferov <malferov@gmail.com>
Date: Thu, 24 Sep 2026 21:36:21 +0300
Subject: [PATCH 2/4] Update grapheme-levenshtein.xml

---
 .../intl/grapheme/grapheme-levenshtein.xml    | 68 +++++++++----------
 1 file changed, 32 insertions(+), 36 deletions(-)

diff --git a/reference/intl/grapheme/grapheme-levenshtein.xml b/reference/intl/grapheme/grapheme-levenshtein.xml
index c343da2fe..ec0084bfc 100644
--- a/reference/intl/grapheme/grapheme-levenshtein.xml
+++ b/reference/intl/grapheme/grapheme-levenshtein.xml
@@ -4,7 +4,7 @@
 <refentry xml:id="function.grapheme-levenshtein" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>grapheme_levenshtein</refname>
-  <refpurpose>Вычисляет расстояние Левенштейна между двумя строками в единицах графем</refpurpose>
+  <refpurpose>Вычисляет расстояние Левенштейна между двумя строками в графемных кластерах</refpurpose>
  </refnamediv>
  <refsect1 role="description">
   &reftitle.description;
@@ -19,28 +19,28 @@
    <methodparam choice="opt"><type>string</type><parameter>locale</parameter><initializer>""</initializer></methodparam>
   </methodsynopsis>
   <simpara>
-   Расстояние Левенштейна определяют как минимальное количество кластеров графем,
+   Расстояние Левенштейна определяют как минимальное количество графемных кластеров,
    которые требуется заменить, вставить или удалить, чтобы преобразовать строку
    <parameter>string1</parameter> в строку <parameter>string2</parameter>.
    Сложность алгоритма — <literal>O(m*n)</literal>, где <literal>n</literal>
    и <literal>m</literal> — длины строк <parameter>string1</parameter>
-   и <parameter>string2</parameter> в единицах графем.
+   и <parameter>string2</parameter> в графемных кластерах.
   </simpara>
   <simpara>
-   В отличие от функции <function>levenshtein</function>, которая работает
-   с байтами, эта функция считает Unicode-кластеры графем, поэтому составную
-   и разложенную формы одного и того же символа, например
-   <literal>U+00E9</literal> и <literal>U+0065 U+0301</literal>, каждая
-   из которых представляет символ <literal>é</literal>, функция считает
-   равнозначными, а расстояние между ними — нулевым.
+   В отличие от функции <function>levenshtein</function>, которая работает с байтами,
+   функция считает графемные кластеры Юникода,
+   поэтому составную и разложенную формы одного и того же символа,
+   например <literal>U+00E9</literal> и <literal>U+0065 U+0301</literal>,
+   каждая из которых представляет символ <literal>é</literal>,
+   функция считает эквивалентными, а расстояние между формами — нулевым.
   </simpara>
   <simpara>
-   Если значения параметров <parameter>insertion_cost</parameter>,
+   Алгоритм подстроится и выберет самые дешёвые преобразования,
+   если значения параметров <parameter>insertion_cost</parameter>,
    <parameter>replacement_cost</parameter> или <parameter>deletion_cost</parameter>
-   отличаются от <literal>1</literal>, алгоритм подстраивается и выбирает
-   самые дешёвые преобразования.
-   Например, если <literal>$insertion_cost + $deletion_cost &lt; $replacement_cost</literal>,
-   замены не выполняются, а вместо них выполняются вставки и удаления.
+   не равны <literal>1</literal>.
+   Например, при истинности выражения <literal>$insertion_cost + $deletion_cost &lt; $replacement_cost</literal>
+   вместо замен выполняются вставки и удаления.
   </simpara>
  </refsect1>
 
@@ -52,8 +52,7 @@
      <term><parameter>string1</parameter></term>
      <listitem>
       <simpara>
-       Одна из строк, для которых вычисляют расстояние Левенштейна.
-       Строка должна быть корректной в кодировке UTF-8.
+       Строка в кодировке UTF-8 для вычисления расстояния Левенштейна.
       </simpara>
      </listitem>
     </varlistentry>
@@ -61,8 +60,7 @@
      <term><parameter>string2</parameter></term>
      <listitem>
       <simpara>
-       Одна из строк, для которых вычисляют расстояние Левенштейна.
-       Строка должна быть корректной в кодировке UTF-8.
+       Строка в кодировке UTF-8 для вычисления расстояния Левенштейна.
       </simpara>
      </listitem>
     </varlistentry>
@@ -70,7 +68,7 @@
      <term><parameter>insertion_cost</parameter></term>
      <listitem>
       <simpara>
-       Задаёт стоимость вставки. Значение должно быть больше <literal>0</literal>.
+       Стоимость вставки — значение больше <literal>0</literal>.
       </simpara>
      </listitem>
     </varlistentry>
@@ -78,7 +76,7 @@
      <term><parameter>replacement_cost</parameter></term>
      <listitem>
       <simpara>
-       Задаёт стоимость замены. Значение должно быть больше <literal>0</literal>.
+       Стоимость замены — значение больше <literal>0</literal>.
       </simpara>
      </listitem>
     </varlistentry>
@@ -86,7 +84,7 @@
      <term><parameter>deletion_cost</parameter></term>
      <listitem>
       <simpara>
-       Задаёт стоимость удаления. Значение должно быть больше <literal>0</literal>.
+       Стоимость удаления — значение больше <literal>0</literal>.
       </simpara>
      </listitem>
     </varlistentry>
@@ -103,8 +101,8 @@
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
   <simpara>
-   Функция возвращает расстояние Левенштейна между двумя строками в единицах
-   графем или &false; в случае ошибки. Подробности об ошибке возвращает
+   Функция возвращает расстояние Левенштейна между двумя строками в графемных
+   кластерах или &false;, если возникла ошибка. Подробности об ошибке возвращает
    функция <function>intl_get_error_message</function>.
   </simpara>
  </refsect1>
@@ -112,16 +110,16 @@
  <refsect1 role="errors">
   &reftitle.errors;
   <simpara>
-   Функция выбрасывает ошибку <exceptionname>ValueError</exceptionname>, если
-   значение параметра <parameter>insertion_cost</parameter>,
+   Функция выбрасывает ошибку <exceptionname>ValueError</exceptionname>,
+   если значение параметра <parameter>insertion_cost</parameter>,
    <parameter>replacement_cost</parameter> или <parameter>deletion_cost</parameter>
    меньше или равно <literal>0</literal>.
   </simpara>
   <simpara>
-   Функция возвращает &false; и устанавливает ошибку intl, если одна
-   из входных строк некорректна в кодировке UTF-8, если значение параметра
-   <parameter>locale</parameter> — некорректный идентификатор локали
-   или если произошла внутренняя ошибка библиотеки ICU.
+   Функция возвращает &false; и устанавливает ошибку модуля Intl,
+   если хотя бы одна входная строка не соответствует кодировке UTF-8,
+   в параметр <parameter>locale</parameter> передали недопустимый идентификатор локали
+   или возникла внутренняя ошибка библиотеки ICU.
   </simpara>
  </refsect1>
 
@@ -139,7 +137,7 @@
      <row>
       <entry>8.5.0</entry>
       <entry>
-       Функцию добавили.
+       Функцию добавили в модуль.
       </entry>
      </row>
     </tbody>
@@ -150,7 +148,7 @@
  <refsect1 role="examples">
   &reftitle.examples;
   <example>
-   <title>Пример использования функции <function>grapheme_levenshtein</function></title>
+   <title>Пример вычисления расстояния Левенштейна функцией <function>grapheme_levenshtein</function></title>
    <programlisting role="php">
 <![CDATA[
 <?php
@@ -161,13 +159,11 @@ $e_composed = "\u{00E9}";
 // Разложенная форма (NFD): U+0065 + U+0301 (e + комбинируемый акут)
 $e_decomposed = "\u{0065}\u{0301}";
 
-// Функция grapheme_levenshtein считает их одним и тем же кластером графем
+// Функция grapheme_levenshtein() считает обе формы как единый графемный кластер
 var_dump(grapheme_levenshtein($e_composed, $e_decomposed));
 
-// Функция levenshtein() работает с байтами и видит их как разные
+// Функция levenshtein() работает с байтами и видит разные байтовые последовательности
 var_dump(levenshtein($e_composed, $e_decomposed));
-
-?>
 ]]>
    </programlisting>
    &example.outputs;
@@ -190,7 +186,7 @@ int(3)
     <member><function>similar_text</function></member>
     <member>
      <link xlink:href="&uri.unicode.graphemes;">
-      Unicode Text Segmentation: Grapheme Cluster Boundaries
+      Сегментация текста в Юникоде: Границы графемных кластеров
      </link>
     </member>
    </simplelist>

From 7edf0f29740da4934445d9ca1553044c67df17c8 Mon Sep 17 00:00:00 2001
From: Mikhail Alferov <malferov@gmail.com>
Date: Thu, 24 Sep 2026 21:38:16 +0300
Subject: [PATCH 3/4] Update grapheme-levenshtein.xml

---
 reference/intl/grapheme/grapheme-levenshtein.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/intl/grapheme/grapheme-levenshtein.xml b/reference/intl/grapheme/grapheme-levenshtein.xml
index ec0084bfc..608b8933d 100644
--- a/reference/intl/grapheme/grapheme-levenshtein.xml
+++ b/reference/intl/grapheme/grapheme-levenshtein.xml
@@ -19,7 +19,7 @@
    <methodparam choice="opt"><type>string</type><parameter>locale</parameter><initializer>""</initializer></methodparam>
   </methodsynopsis>
   <simpara>
-   Расстояние Левенштейна определяют как минимальное количество графемных кластеров,
+   Расстояние Левенштейна определяется как минимальное количество графемных кластеров,
    которые требуется заменить, вставить или удалить, чтобы преобразовать строку
    <parameter>string1</parameter> в строку <parameter>string2</parameter>.
    Сложность алгоритма — <literal>O(m*n)</literal>, где <literal>n</literal>

From bcc6b295eb1627b0cbb31e64117882bdd9b36fac Mon Sep 17 00:00:00 2001
From: Mikhail Alferov <malferov@gmail.com>
Date: Thu, 24 Sep 2026 21:40:39 +0300
Subject: [PATCH 4/4] Update grapheme-levenshtein.xml

---
 reference/intl/grapheme/grapheme-levenshtein.xml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/reference/intl/grapheme/grapheme-levenshtein.xml b/reference/intl/grapheme/grapheme-levenshtein.xml
index 608b8933d..327caf840 100644
--- a/reference/intl/grapheme/grapheme-levenshtein.xml
+++ b/reference/intl/grapheme/grapheme-levenshtein.xml
@@ -19,7 +19,7 @@
    <methodparam choice="opt"><type>string</type><parameter>locale</parameter><initializer>""</initializer></methodparam>
   </methodsynopsis>
   <simpara>
-   Расстояние Левенштейна определяется как минимальное количество графемных кластеров,
+   Расстояние Левенштейна определяется как минимум графемных кластеров,
    которые требуется заменить, вставить или удалить, чтобы преобразовать строку
    <parameter>string1</parameter> в строку <parameter>string2</parameter>.
    Сложность алгоритма — <literal>O(m*n)</literal>, где <literal>n</literal>