Skip to content

[Sync-En] intl: improve grapheme and Collator documentation #1519

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julionc merged 1 commit into from
Oct 26, 2026
Merged

[Sync-En] intl: improve grapheme and Collator documentation #1519

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 63 additions & 1 deletion reference/intl/collator/set-strength.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: e290572f2599305beb62b13988024b5da187979d Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="collator.setstrength" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand Down Expand Up @@ -173,6 +173,67 @@ array (
1 => 'Ao',
2 => 'ao',
)
]]>
</screen>
</example>
<example>
<title>Establecer la fuerza mediante la clave de extensión Unicode de la configuración regional <literal>ks</literal></title>
<simpara>
La fuerza de ordenación también puede establecerse al construir el objeto <classname>Collator</classname>
mediante la clave de extensión Unicode <literal>ks</literal> en el identificador de la configuración regional.
La correspondencia entre los valores de <literal>ks</literal> y las constantes de
<classname>Collator</classname> es la siguiente:
</simpara>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Valor de la clave de configuración regional</entry>
<entry>Constante de Collator</entry>
</row>
</thead>
<tbody>
<row><entry><literal>ks-level1</literal></entry><entry><constant>Collator::PRIMARY</constant></entry></row>
<row><entry><literal>ks-level2</literal></entry><entry><constant>Collator::SECONDARY</constant></entry></row>
<row><entry><literal>ks-level3</literal></entry><entry><constant>Collator::TERTIARY</constant></entry></row>
<row><entry><literal>ks-level4</literal></entry><entry><constant>Collator::QUATERNARY</constant></entry></row>
<row><entry><literal>ks-identic</literal></entry><entry><constant>Collator::IDENTICAL</constant></entry></row>
</tbody>
</tgroup>
</informaltable>
<simpara>
<constant>Collator::DEFAULT_STRENGTH</constant> no tiene ningún equivalente <literal>ks-*</literal>
y debe establecerse mediante programación con <function>collator_set_strength</function>.
</simpara>
<programlisting role="php">
<![CDATA[
<?php

$textStyle = "\u{263A}\u{FE0E}"; // U+263A + U+FE0E (selector de presentación como texto)
$emojiStyle = "\u{263A}\u{FE0F}"; // U+263A + U+FE0F (selector de presentación como emoji)

// Collator por defecto (fuerza TERTIARY): los selectores de variación se ignoran.
$collDefault = new Collator('en_US');
var_dump($collDefault->compare($textStyle, $emojiStyle) === 0); // bool(true)

// Fuerza idéntica mediante setStrength().
$coll1 = new Collator('en_US');
$coll1->setStrength(Collator::IDENTICAL);
var_dump($coll1->compare($textStyle, $emojiStyle) === 0); // bool(false)

// Equivalente: fuerza idéntica mediante la clave de extensión ks de la configuración regional.
$coll2 = new Collator('en_US-u-ks-identic');
var_dump($coll2->compare($textStyle, $emojiStyle) === 0); // bool(false)

?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
bool(true)
bool(false)
bool(false)
]]>
</screen>
</example>
Expand All @@ -185,6 +246,7 @@ array (
<simplelist>
<member><link linkend="intl.collator-constants">Constantes de Collator</link></member>
<member><function>collator_get_strength</function></member>
<member><function>collator_create</function></member>
</simplelist>
</para>
</refsect1>
Expand Down
32 changes: 23 additions & 9 deletions reference/intl/grapheme/grapheme-extract.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 2245ff665ae4b3037728ee52c247b409ad75de35 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<!-- CREDITS: DAnnebicque -->

Expand Down Expand Up @@ -54,13 +54,25 @@
</para>
<para>
<simplelist>
<member>GRAPHEME_EXTR_COUNT (por defecto): <parameter>size</parameter> es el número
<member><constant>GRAPHEME_EXTR_COUNT</constant> (por defecto) - <parameter>size</parameter> es el número
de grupos de grafemas a extraer.</member>
<member>GRAPHEME_EXTR_MAXBYTES: <parameter>size</parameter> es el número de bytes a devolver.</member>
<member>GRAPHEME_EXTR_MAXCHARS: <parameter>size</parameter> es el número de caracteres
<member><constant>GRAPHEME_EXTR_MAXBYTES</constant> - <parameter>size</parameter> es el número de bytes a devolver.</member>
<member><constant>GRAPHEME_EXTR_MAXCHARS</constant> - <parameter>size</parameter> es el número de caracteres
UTF-8 a devolver.</member>
</simplelist>
</para>
<caution>
<simpara>
<constant>GRAPHEME_EXTR_COUNT</constant> limita el número de grupos de grafemas (unidades
visuales), no el número de bytes. Un único grupo de grafemas puede ocupar muchos bytes: por
ejemplo, un emoji de familia con secuencias ZWJ (<literal>👨‍👩‍👧‍👦</literal>) es
un solo grupo de grafemas, pero ocupa 25 bytes. Cuando la cadena extraída deba ajustarse a un
presupuesto de bytes, utilice en su lugar <constant>GRAPHEME_EXTR_MAXBYTES</constant>.
<constant>GRAPHEME_EXTR_MAXBYTES</constant> siempre devuelve grupos de grafemas completos
dentro del presupuesto de bytes, pero devuelve una cadena vacía si el presupuesto es menor que
el primer grupo de grafemas.
</simpara>
</caution>
</listitem>
</varlistentry>
<varlistentry>
Expand Down Expand Up @@ -151,11 +163,13 @@ o%CC%88
<para>
<simplelist>
<member><function>grapheme_substr</function></member>
<member>
<link xlink:href="&uri.unicode.graphemes;">
Unicode Text Segmentation: Grapheme Cluster Boundaries
</link>
</member>
<member><function>grapheme_strlen</function></member>
<member><function>grapheme_strpos</function></member>
<member>
<link xlink:href="&uri.unicode.graphemes;">
Unicode Text Segmentation: Grapheme Cluster Boundaries
</link>
</member>
</simplelist>
</para>
</refsect1>
Expand Down
36 changes: 35 additions & 1 deletion reference/intl/grapheme/grapheme-strlen.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: e7d502fecc2e84d4c57e6451b16f68bec1295ba8 Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->

<refentry xml:id="function.grapheme-strlen" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
Expand Down Expand Up @@ -67,6 +67,38 @@ print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_
6
]]>
</screen>
<example>
<title>Gestión de una entrada UTF-8 no válida</title>
<simpara>
<function>grapheme_strlen</function> devuelve &null; o &false; en caso de fallo, incluido
cuando la entrada no es UTF-8 válido.
Utilice <function>intl_get_error_code</function> e <function>intl_error_name</function>
para obtener los detalles del error de ICU.
</simpara>
<programlisting role="php">
<![CDATA[
<?php

$string = "\xFF"; // secuencia de bytes UTF-8 no válida
$length = grapheme_strlen($string);

if (!is_int($length)) {
$code = intl_get_error_code();
printf("grapheme_strlen() falló: %s (%d)\n", intl_error_name($code), $code);
} else {
echo $length, PHP_EOL;
}

?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
grapheme_strlen() falló: U_INVALID_CHAR_FOUND (10)
]]>
</screen>
</example>
</refsect1>

<refsect1 role="seealso">
Expand All @@ -81,6 +113,8 @@ print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_
<member><function>iconv_strlen</function></member>
<member><function>mb_strlen</function></member>
<member><function>strlen</function></member>
<member><function>intl_get_error_code</function></member>
<member><function>intl_error_name</function></member>
</simplelist>
</para>
</refsect1>
Expand Down
55 changes: 53 additions & 2 deletions reference/intl/grapheme/grapheme-strpos.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 9a8c593c09cf7d84085989e42f3b2b23536279db Maintainer: PhilDaiguille Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no -->
<!-- CREDITS: DAnnebicque -->

Expand Down Expand Up @@ -60,7 +60,21 @@
<varlistentry>
<term><parameter>locale</parameter></term>
<listitem>
&intl.param.grapheme.locale;
<simpara>
Configuración regional a utilizar. La configuración regional afecta a cómo se definen los
grupos de grafemas y a cómo se comparan las cadenas. Una cadena vacía o &null; utiliza la
configuración regional por defecto.
</simpara>
<simpara>
El identificador de la configuración regional puede incluir claves de extensión Unicode de
la configuración regional para controlar el comportamiento de la ordenación. En particular,
la clave <literal>ks</literal> controla la fuerza de ordenación: por ejemplo,
<literal>en_US-u-ks-identic</literal> activa la comparación de nivel idéntico, que distingue
los selectores de variación Unicode (como la presentación como emoji frente a la presentación
como texto) que de otro modo se tratan como equivalentes.
Consulte <methodname>Collator::setStrength</methodname> para ver la correspondencia completa
entre los valores de <literal>ks</literal> y los niveles de fuerza de ordenación.
</simpara>
</listitem>
</varlistentry>
</variablelist>
Expand Down Expand Up @@ -121,6 +135,42 @@ print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_n
2
]]>
</screen>
<example>
<title>Uso de la clave de configuración regional <literal>ks-identic</literal> para distinguir los selectores de variación</title>
<simpara>
Por defecto, los selectores de variación Unicode (U+FE0E texto, U+FE0F emoji) se ignoran
durante la comparación. El uso de la clave de extensión de configuración regional <literal>ks-identic</literal>
activa la ordenación de nivel idéntico, que los trata como caracteres distintos.
</simpara>
<note>
<simpara>
El parámetro <parameter>locale</parameter> está disponible desde PHP 8.5.0.
</simpara>
</note>
<programlisting role="php">
<![CDATA[
<?php

$textStyle = "\u{263A}\u{FE0E}"; // U+263A + U+FE0E (selector de presentación como texto)
$emojiStyle = "\u{263A}\u{FE0F}"; // U+263A + U+FE0F (selector de presentación como emoji)

// Configuración regional por defecto: los selectores de variación se ignoran, por lo que la aguja se encuentra en la posición 0.
var_dump(grapheme_strpos($textStyle, $emojiStyle));

// Con ks-identic: los selectores de variación son significativos, por lo que no hay coincidencia.
var_dump(grapheme_strpos($textStyle, $emojiStyle, 0, 'en_US-u-ks-identic'));

?>
]]>
</programlisting>
&example.outputs;
<screen>
<![CDATA[
int(0)
bool(false)
]]>
</screen>
</example>
</refsect1>

<refsect1 role="seealso">
Expand All @@ -132,6 +182,7 @@ print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_n
<member><function>grapheme_strripos</function></member>
<member><function>grapheme_strrpos</function></member>
<member><function>grapheme_strstr</function></member>
<member><methodname>Collator::setStrength</methodname></member>
<member>
<link xlink:href="&uri.unicode.graphemes;">
Unicode Text Segmentation: Grapheme Cluster Boundaries
Expand Down
Loading