Skip to content

intl を原文の変更に追従 (4ファイル) #565

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

Open
KentarouTakeda wants to merge 1 commit into
base: master
Choose a base branch
from
Open

intl を原文の変更に追従 (4ファイル) #565

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
67 changes: 65 additions & 2 deletions reference/intl/collator/set-strength.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: e290572f2599305beb62b13988024b5da187979d Maintainer: takagi Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
<refentry xml:id="collator.setstrength" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>Collator::setStrength</refname>
Expand Down Expand Up @@ -205,7 +205,7 @@ $arr = array( 'aò', 'Ao', 'ao' );
$coll = collator_create( 'en_US' );

// デフォルトの強度で配列を並べ替えます
collator_sort( $coll, $arr );
collator_sort( $coll, $arr );
var_export( $arr );

// 第一段階の強度で配列を並べ替えます
Expand All @@ -228,6 +228,68 @@ array (
1 => 'Ao',
2 => 'ao',
)
]]>
</screen>
</example>
<example>
<title>Unicode ロケール拡張のキー <literal>ks</literal> で強度を設定する</title>
<simpara>
照合強度は、<classname>Collator</classname> の生成時に、ロケール識別子の中で
Unicode ロケール拡張のキー <literal>ks</literal> を使って設定することもできます。
<literal>ks</literal> の値と <classname>Collator</classname>
の定数の対応は次のとおりです。
</simpara>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>ロケールキーの値</entry>
<entry>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> に相当する <literal>ks-*</literal>
の値はありません。この強度にするには <function>collator_set_strength</function>
を使う必要があります。
</simpara>
<programlisting role="php">
<![CDATA[
<?php

$textStyle = "\u{263A}\u{FE0E}"; // U+263A + U+FE0E (テキスト表示の異体字セレクタ)
$emojiStyle = "\u{263A}\u{FE0F}"; // U+263A + U+FE0F (絵文字表示の異体字セレクタ)

// デフォルトの Collator (強度は TERTIARY): 異体字セレクタは無視されます
$collDefault = new Collator('en_US');
var_dump($collDefault->compare($textStyle, $emojiStyle) === 0); // bool(true)

// setStrength() で一致段階の強度を設定します
$coll1 = new Collator('en_US');
$coll1->setStrength(Collator::IDENTICAL);
var_dump($coll1->compare($textStyle, $emojiStyle) === 0); // bool(false)

// ロケール拡張のキー ks で一致段階の強度を設定しても同じです
$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 @@ -240,6 +302,7 @@ array (
<simplelist>
<member><link linkend="intl.collator-constants">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: takagi Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
<refentry xml:id="function.grapheme-extract" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>grapheme_extract</refname>
Expand Down Expand Up @@ -52,12 +52,24 @@
</para>
<para>
<simplelist>
<member>GRAPHEME_EXTR_COUNT (デフォルト) - <parameter>size</parameter> は、
<member><constant>GRAPHEME_EXTR_COUNT</constant> (デフォルト) - <parameter>size</parameter> は、
抽出するデフォルト書記素クラスタの数です。</member>
<member>GRAPHEME_EXTR_MAXBYTES - <parameter>size</parameter> は、返すバイト数の最大値です。</member>
<member>GRAPHEME_EXTR_MAXCHARS - <parameter>size</parameter> は、返す UTF-8 文字数の最大値です。</member>
<member><constant>GRAPHEME_EXTR_MAXBYTES</constant> - <parameter>size</parameter> は、返すバイト数の最大値です。</member>
<member><constant>GRAPHEME_EXTR_MAXCHARS</constant> - <parameter>size</parameter> は、返す UTF-8 文字数の最大値です。</member>
</simplelist>
</para>
<caution>
<simpara>
<constant>GRAPHEME_EXTR_COUNT</constant> が制限するのは書記素クラスタ (見た目上の単位) の数であり、
バイト数ではありません。ひとつの書記素クラスタが多数のバイトにまたがることがあります。
たとえば、ZWJ シーケンスで構成された家族の絵文字 (<literal>👨‍👩‍👧‍👦</literal>) は、
書記素クラスタとしてはひとつですが 25 バイトあります。
取り出す文字列をバイト数の上限に収める必要がある場合は、
代わりに <constant>GRAPHEME_EXTR_MAXBYTES</constant> を使ってください。
<constant>GRAPHEME_EXTR_MAXBYTES</constant> は、書記素クラスタを途中で切らずに、上限に収まる分だけを返します。
ただし、最初の書記素クラスタだけで上限を超える場合は空文字列を返します。
</simpara>
</caution>
</listitem>
</varlistentry>
<varlistentry>
Expand Down Expand Up @@ -149,11 +161,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: takagi Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
<refentry xml:id="function.grapheme-strlen" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>grapheme_strlen</refname>
Expand Down Expand Up @@ -66,6 +66,38 @@ print grapheme_strlen( 'abc' . $char_a_ring_nfd . $char_o_diaeresis_nfd . $char_
6
]]>
</screen>
<example>
<title>不正な UTF-8 入力の扱い</title>
<simpara>
<function>grapheme_strlen</function> は、入力が有効な UTF-8 でない場合など、
失敗したときに &null; または &false; を返します。
ICU のエラーの詳細は、<function>intl_get_error_code</function> と
<function>intl_error_name</function> で取得できます。
</simpara>
<programlisting role="php">
<![CDATA[
<?php

$string = "\xFF"; // 不正な UTF-8 のバイト列
$length = grapheme_strlen($string);

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

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

<refsect1 role="seealso">
Expand All @@ -80,6 +112,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
53 changes: 51 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: takagi Status: ready -->
<!-- EN-Revision: 0b916fb90f8862046a56a5e05057ef6cd78384c1 Maintainer: takagi Status: ready -->
<refentry xml:id="function.grapheme-strpos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
<refname>grapheme_strpos</refname>
Expand Down Expand Up @@ -56,7 +56,19 @@
<varlistentry>
<term><parameter>locale</parameter></term>
<listitem>
&intl.param.grapheme.locale;
<simpara>
使用するロケール。ロケールによって、書記素クラスターの定義と文字列の比較方法が変わります。
空文字列または &null; を指定すると、デフォルトのロケールを使用します。
</simpara>
<simpara>
ロケール識別子には、照合の挙動を制御する Unicode ロケール拡張のキーを含めることができます。
なかでも <literal>ks</literal> キーは照合強度を制御します。
たとえば <literal>en_US-u-ks-identic</literal> を指定すると一致段階で比較するようになり、
他の強度では同等とみなされる Unicode の異体字セレクタの違い
(絵文字表示とテキスト表示など) を区別します。
<literal>ks</literal> の値と照合強度の対応の一覧は、
<methodname>Collator::setStrength</methodname> を参照ください。
</simpara>
</listitem>
</varlistentry>
</variablelist>
Expand Down Expand Up @@ -117,6 +129,42 @@ print grapheme_strpos( $char_a_ring_nfd . $char_a_ring_nfd . $char_o_diaeresis_n
2
]]>
</screen>
<example>
<title><literal>ks-identic</literal> ロケールキーで異体字セレクタを区別する</title>
<simpara>
デフォルトでは、Unicode の異体字セレクタ (テキスト表示の U+FE0E、絵文字表示の U+FE0F)
は比較の際に無視されます。ロケール拡張のキー <literal>ks-identic</literal>
を使うと一致段階で照合するようになり、異体字セレクタの違いを区別します。
</simpara>
<note>
<simpara>
<parameter>locale</parameter> 引数は PHP 8.5.0 以降で利用可能です。
</simpara>
</note>
<programlisting role="php">
<![CDATA[
<?php

$textStyle = "\u{263A}\u{FE0E}"; // U+263A + U+FE0E (テキスト表示の異体字セレクタ)
$emojiStyle = "\u{263A}\u{FE0F}"; // U+263A + U+FE0F (絵文字表示の異体字セレクタ)

// デフォルトのロケール: 異体字セレクタは無視されるので、needle は位置 0 で見つかります
var_dump(grapheme_strpos($textStyle, $emojiStyle));

// ks-identic を指定した場合: 異体字セレクタが区別されるので、一致するものは見つかりません
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 @@ -128,6 +176,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