documentation/manual/ja/module_specs/Zend_Locale-Parsing.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20792 -->
   4 <sect1 id="zend.locale.parsing">
   5
   6     <title>正規化および地域化</title>
   7
   8     <para>
   9         <classname>Zend_Locale_Format</classname> は、<classname>Zend_Locale</classname> が内部で使用しているコンポーネントです。
  10         ロケール対応のクラスは、<classname>Zend_Locale_Format</classname>
  11         を用いて数値や日付の正規化および地域化を行います。
  12         正規化とは、さまざまな形式で表されるデータ (日付など) を取り込んで解析し、
  13         標準化された構造化表現 (year、month、day の各要素からなる配列など) に変換することです。
  14     </para>
  15
  16     <para>
  17         まったく同じ文字列からなる数値や日付でも、
  18         異なる習慣や規約を使用している人が見ると異なる意味にとられることがあります。
  19         数値や日付を、あいまいさをなくして正確に解釈するには、
  20         これらの文字列を正規化し、標準化されたデータ構造に変換する必要があります。
  21         したがって、<classname>Zend_Locale_Format</classname> のすべてのメソッドは、
  22         入力データを処理するためにロケール情報を必要とします。
  23         <note>
  24             <title>デフォルトの "root" ロケール</title>
  25             <para>
  26                 ロケールを省略した場合は、正規化や地域化の際に
  27                 標準の "root" ロケールを使用します。
  28                 これは予期せぬ動作を引き起こす可能性があります。
  29                 さまざまなロケールの入力を扱ったり、特定のロケールで出力したい場合などに注意が必要です。
  30             </para>
  31         </note>
  32     </para>
  33
  34     <sect2 id="zend.locale.number.normalize">
  35
  36         <title>数値の正規化: getNumber($input, Array $options)</title>
  37
  38         <para>
  39             標準の
  40             <ulink url="http://en.wikipedia.org/wiki/Decimal">十進形式</ulink>
  41             (例: "3.14") とは異なる
  42             <ulink url="http://en.wikipedia.org/wiki/Numeral">数値形式</ulink>
  43             には、さまざまなものがあります。
  44             数値を正規化するには <methodname>getNumber()</methodname>
  45             関数を使用します。これは、標準の十進形式を返します。
  46             このマニュアルにおける数値関連の説明はすべて、特にことわりがない限り
  47             <ulink url="http://en.wikipedia.org/wiki/Arabic_numerals">アラビア数字 (0,1,2,3,4,5,6,7,8,9)</ulink>
  48             を想定したものです。オプションの配列で 'locale'
  49             を指定し、桁区切り文字および小数点を定義できます。
  50             また、配列に 'precision' を指定すると、
  51             あふれた桁を結果から取り除きます。
  52         </para>
  53
  54         <example id="zend.locale.number.normalize.example-1">
  55             <title>数値の正規化</title>
  56             <programlisting language="php"><![CDATA[
  57 $locale = new Zend_Locale('de_AT');
  58 $number = Zend_Locale_Format::getNumber('13.524,678',
  59                                         array('locale' => $locale,
  60                                               'precision' => 3)
  61                                        );
  62
  63 print $number; // 13524.678 を返します
  64 ]]></programlisting>
  65         </example>
  66
  67         <sect3 id="zend.locale.number.normalize.precision">
  68
  69             <title>計算の精度</title>
  70
  71             <para>
  72                 <methodname>getNumber($value, array $options = array())</methodname> では非常に大きな数値も正規化できるので、
  73                 <acronym>PHP</acronym> の通常の数値計算のように精度が限られている計算をする前には注意しましょう。
  74                 たとえば <code>if
  75                 ((string)int_val($number) != $number) {
  76                 <ulink url="http://www.php.net/bc">BCMath</ulink>
  77                 あるいは
  78                 <ulink url="http://www.php.net/gmp">GMP</ulink>
  79                 を使用するなど。
  80                 </code>
  81                 実際にインストールされている <acronym>PHP</acronym> のほとんどは、
  82                 BCMath 拡張モジュールをサポートしています。
  83             </para>
  84
  85             <para>
  86                 また、結果の十進表現の精度も、<methodname>getNumber()</methodname>
  87                 のオプション <code>'precision'</code> で指定した長さに丸められます。
  88                 精度を指定しなかった場合は、丸め処理は行われません。
  89                 精度を指定するには、<acronym>PHP</acronym> の整数のみを使用します。
  90             </para>
  91
  92             <para>
  93                 十進表現で表した結果を丸めるのではなく指定した桁数で切り詰めたい場合は、
  94                 オプション <code>'number_format'</code> を代わりに使用します。
  95                 十進表現の精度を定義するには、必要な桁数ぶんのゼロを指定します。
  96                 結果の丸めは行われません。つまり、もし <code>number_format</code>
  97                 で定義した精度がゼロなら、
  98                 "1.6" は "1" であり、"2" とはなりません。
  99                 例を参照ください。
 100             </para>
 101
 102             <example id="zend.locale.number.normalize.precision.example-1">
 103                 <title>精度を指定した数値の正規化</title>
 104                 <programlisting language="php"><![CDATA[
 105 $locale = new Zend_Locale('de_AT');
 106 $number = Zend_Locale_Format::getNumber('13.524,678',
 107                                         array('precision' => 1,
 108                                               'locale' => $locale)
 109                                        );
 110 print $number; // 13524.7 を返します
 111
 112 $number = Zend_Locale_Format::getNumber('13.524,678',
 113                                         array('number_format' => '#.00',
 114                                               'locale' => $locale)
 115                                        );
 116 print $number; // 13524.67 を返します
 117 ]]></programlisting>
 118             </example>
 119
 120         </sect3>
 121
 122     </sect2>
 123
 124     <sect2 id="zend.locale.number.localize">
 125
 126         <title>数値の地域化</title>
 127
 128         <para>
 129             <methodname>toNumber($value, array $options = array())</methodname> は、
 130             <link linkend="zend.locale.appendix">サポートするロケール</link>
 131             にあわせて数値を正規化します。
 132             この関数は、指定した数値を、特定のロケールにあわせて書式化した文字列を返します。
 133             オプション 'number_format' を使用すると、
 134             <methodname>toNumber()</methodname> で用いるデフォルト以外の数値書式を設定できます。
 135         </para>
 136
 137         <example id="zend.locale.number.localize.example-1">
 138             <title>数値の地域化</title>
 139             <programlisting language="php"><![CDATA[
 140 $locale = new Zend_Locale('de_AT');
 141 $number = Zend_Locale_Format::toNumber(13547.36,
 142                                        array('locale' => $locale));
 143
 144 // 13.547,36 を返します
 145 print $number;
 146 ]]></programlisting>
 147         </example>
 148
 149         <para>
 150             <note>
 151                 <title>長さは無制限</title>
 152                 <para>
 153                     <methodname>toNumber()</methodname> が地域化できる数値の長さには制限がありません。
 154                     整数や浮動小数点数の範囲の制限を受けることはありません。
 155                 </para>
 156             </note>
 157         </para>
 158
 159         <para>
 160             <methodname>getNumber()</methodname> と同様の方法で、
 161             <methodname>toNumber()</methodname> も精度を扱います。
 162             精度を指定しなかった場合は、地域化した数値を完全な状態で返します。
 163         </para>
 164
 165         <example id="zend.locale.number.localize.example-2">
 166             <title>精度を指定した数値の地域化</title>
 167             <programlisting language="php"><![CDATA[
 168 $locale = new Zend_Locale('de_AT');
 169 $number = Zend_Locale_Format::toNumber(13547.3678,
 170                                        array('precision' => 2,
 171                                              'locale' => $locale));
 172
 173 // 13.547,37 を返します
 174 print $number;
 175 ]]></programlisting>
 176         </example>
 177
 178         <para>
 179             オプション 'number_format' を使用すると、
 180             独自の数値書式を定義できます。
 181             書式を指定するには、以下の <acronym>CLDR</acronym> 書式を使用します。
 182             ロケールを元に、桁区切りや小数点、その他の数値記号を取得します。
 183             たとえば、ドイツ語では小数点として
 184             ',' を用いますが、英語では小数点に '.' を使用します。
 185         </para>
 186
 187         <table id="zend.locale.number.localize.table-1">
 188             <title>自分で作成する数値書式用の書式トークン
 189             </title>
 190             <tgroup cols="4">
 191                 <thead>
 192                     <row>
 193                         <entry>トークン</entry>
 194                         <entry>説明</entry>
 195                         <entry>書式の例</entry>
 196                         <entry>出力結果</entry>
 197                     </row>
 198                 </thead>
 199                 <tbody>
 200                     <row>
 201                         <entry>#0</entry>
 202                         <entry>桁区切りや小数点のない数値を生成します。</entry>
 203                         <entry>#0</entry>
 204                         <entry>1234567</entry>
 205                     </row>
 206                     <row>
 207                         <entry>,</entry>
 208                         <entry>指定した桁数ごとに区切り文字を生成します。</entry>
 209                         <entry>#,##0</entry>
 210                         <entry>1,234,567</entry>
 211                     </row>
 212                     <row>
 213                         <entry>#,##,##0</entry>
 214                         <entry>最初は標準の 3 桁で区切り、それ以降は 2 桁ごとに区切ります。</entry>
 215                         <entry>#,##,##0</entry>
 216                         <entry>12,34,567</entry>
 217                     </row>
 218                     <row>
 219                         <entry>.</entry>
 220                         <entry>小数点を生成します。</entry>
 221                         <entry>#0.#</entry>
 222                         <entry>1234567.1234</entry>
 223                     </row>
 224                     <row>
 225                         <entry>0</entry>
 226                         <entry>小数点以下を指定した桁数にします。</entry>
 227                         <entry>#0.00</entry>
 228                         <entry>1234567.12</entry>
 229                     </row>
 230                 </tbody>
 231             </tgroup>
 232         </table>
 233
 234         <example id="zend.locale.number.localize.example-3">
 235             <title>自分で定義した数値書式の使用</title>
 236             <programlisting language="php"><![CDATA[
 237 $locale = new Zend_Locale('de_AT');
 238 $number = Zend_Locale_Format::toNumber(13547.3678,
 239                                        array('number_format' => '#,#0.00',
 240                                              'locale' => 'de')
 241                                       );
 242
 243 // 1.35.47,36 を返します
 244 print $number;
 245
 246 $number = Zend_Locale_Format::toNumber(13547.3,
 247                                        array('number_format' => '#,##0.00',
 248                                              'locale' => 'de')
 249                                        );
 250
 251 // 13.547,30 を返します
 252 print $number;
 253 ]]></programlisting>
 254         </example>
 255
 256     </sect2>
 257
 258     <sect2 id="zend.locale.number.test">
 259
 260         <title>数値かどうかの確認</title>
 261
 262         <para>
 263             <methodname>isNumber($value, array $options = array())</methodname> は、指定した文字列が数値であるかどうかを
 264             <constant>TRUE</constant> あるいは <constant>FALSE</constant> で返します。
 265         </para>
 266
 267         <example id="zend.locale.number.test.example-1">
 268             <title>数値かどうかの確認</title>
 269             <programlisting language="php"><![CDATA[
 270 $locale = new Zend_Locale();
 271 if (Zend_Locale_Format::isNumber('13.445,36', array('locale' => 'de_AT')) {
 272     print "数値です";
 273 } else {
 274     print "数値ではありません";
 275 }
 276 ]]></programlisting>
 277         </example>
 278
 279     </sect2>
 280
 281     <sect2 id="zend.locale.float.normalize">
 282
 283         <title>浮動小数点値の正規化</title>
 284
 285         <para>
 286             浮動小数点値のパースには <methodname>getFloat($value, array $options = array())</methodname>
 287             関数を使用します。これは、浮動小数点値を返します。
 288         </para>
 289
 290         <example id="zend.locale.float.normalize.example-1">
 291             <title>浮動小数点値の正規化</title>
 292             <programlisting language="php"><![CDATA[
 293 $locale = new Zend_Locale('de_AT');
 294 $number = Zend_Locale_Format::getFloat('13.524,678',
 295                                        array('precision' => 2,
 296                                              'locale' => $locale)
 297                                       );
 298
 299 // 13524.68 を返します
 300 print $number;
 301 ]]></programlisting>
 302         </example>
 303
 304     </sect2>
 305
 306     <sect2 id="zend.locale.float.localize">
 307
 308         <title>浮動小数点値の地域化</title>
 309
 310         <para>
 311             <methodname>toFloat()</methodname> は、浮動小数点値の地域化を行います。
 312             この関数は、指定した数値を地域化した文字列を返します。
 313         </para>
 314
 315         <example id="zend.locale.float.localize.example-1">
 316             <title>浮動小数点値の地域化</title>
 317             <programlisting language="php"><![CDATA[
 318 $locale = new Zend_Locale('de_AT');
 319 $number = Zend_Locale_Format::toFloat(13547.3655,
 320                                       array('precision' => 1,
 321                                             'locale' => $locale)
 322                                      );
 323
 324 // 13.547,4 を返します
 325 print $number;
 326 ]]></programlisting>
 327         </example>
 328
 329     </sect2>
 330
 331     <sect2 id="zend.locale.float.test">
 332
 333         <title>浮動小数点値かどうかの確認</title>
 334
 335         <para>
 336             <methodname>isFloat($value, array $options = array())</methodname> は、
 337             指定した文字列が浮動小数点値であるかどうかを
 338             <constant>TRUE</constant> あるいは <constant>FALSE</constant> で返します。
 339         </para>
 340
 341         <example id="zend.locale.float.test.example-1">
 342             <title>浮動小数点値かどうかの確認</title>
 343             <programlisting language="php"><![CDATA[
 344 $locale = new Zend_Locale('de_AT');
 345 if (Zend_Locale_Format::isFloat('13.445,36', array('locale' => $locale)) {
 346     print "float です";
 347 } else {
 348     print "float ではありません";
 349 }
 350 ]]></programlisting>
 351         </example>
 352
 353     </sect2>
 354
 355     <sect2 id="zend.locale.integer.normalize">
 356
 357         <title>整数値の正規化</title>
 358
 359         <para>
 360             整数値のパースには <methodname>getInteger()</methodname>
 361             関数を使用します。これは、整数値を返します。
 362         </para>
 363
 364         <example id="zend.locale.integer.normalize.example-1">
 365             <title>整数値の正規化</title>
 366             <programlisting language="php"><![CDATA[
 367 $locale = new Zend_Locale('de_AT');
 368 $number = Zend_Locale_Format::getInteger('13.524,678',
 369                                          array('locale' => $locale));
 370
 371 // 13524 を返します
 372 print $number;
 373 ]]></programlisting>
 374         </example>
 375
 376     </sect2>
 377
 378     <sect2 id="zend.locale.integer.localize">
 379
 380         <title>整数値の地域化</title>
 381
 382         <para>
 383             <methodname>toInteger($value, array $options = array())</methodname> は、整数値の地域化を行います。
 384             この関数は、指定した数値を地域化した文字列を返します。
 385         </para>
 386
 387         <example id="zend.locale.integer.localize.example-1">
 388             <title>整数値の地域化</title>
 389             <programlisting language="php"><![CDATA[
 390 $locale = new Zend_Locale('de_AT');
 391 $number = Zend_Locale_Format::toInteger(13547.3655,
 392                                         array('locale' => $locale));
 393
 394 // 13.547 を返します
 395 print $number;
 396 ]]></programlisting>
 397         </example>
 398
 399     </sect2>
 400
 401     <sect2 id="zend.locale.integer.test">
 402
 403         <title>整数値かどうかの確認</title>
 404
 405         <para>
 406             <methodname>isInteger($value, array $options = array())</methodname> は、
 407             指定した文字列が整数値であるかどうかを
 408             <constant>TRUE</constant> あるいは <constant>FALSE</constant> で返します。
 409         </para>
 410
 411         <example id="zend.locale.integer.test.example-1">
 412             <title>整数値かどうかの確認</title>
 413             <programlisting language="php"><![CDATA[
 414 $locale = new Zend_Locale('de_AT');
 415 if (Zend_Locale_Format::isInteger('13.445', array('locale' => $locale)) {
 416     print "integer です";
 417 } else {
 418     print "integer ではありません";
 419 }
 420 ]]></programlisting>
 421         </example>
 422
 423     </sect2>
 424
 425     <sect2 id="zend.locale.numbersystems">
 426
 427         <title>数値系の変換</title>
 428
 429         <para>
 430             <methodname>Zend_Locale_Format::convertNumerals()</methodname> は、
 431             さまざまな
 432             <ulink url="http://en.wikipedia.org/wiki/Arabic_numerals">数値系</ulink>
 433             の間での数値の変換を行います。その中には、標準のアラビア数字
 434             (0,1,2,3,4,5,6,7,8,9) も含まれます。これは、
 435             <ulink url="http://en.wikipedia.org/wiki/Eastern_Arabic_numerals">東アラビア数字</ulink>
 436             とは異なることに注意しましょう。
 437             東アラビア数字は、アラビア語で数字を表す際に用いられることがあります。
 438             サポートしていない数値系を使用すると、例外が発生します。
 439             これは、不正確な変換によってエラーが発生するのを防ぐためです。
 440             指定された数値系で数値として扱われない文字は、
 441             そのまま出力に渡されます。つまり、単位の区切り文字などは変換されないということです。
 442             <classname>Zend_Locale*</classname> コンポーネントは、<acronym>CLDR</acronym> が提供するデータに依存しています
 443             (<ulink url="http://unicode.org/cldr/data/diff/supplemental/languages_and_scripts.html?sortby=date">
 444                 言語ごとの文字の一覧</ulink> を参照ください)。
 445         </para>
 446
 447         <para>
 448             <acronym>CLDR</acronym> では今後、Europena/Latin 数値のことを "Latin"
 449             と呼ぶようになります。4 文字に略した形式は "Latn" です。
 450             また、<acronym>CLDR</acronym> ではこの数値系のことを "scripts" と呼ぶようになります。
 451         </para>
 452
 453         <para>
 454             あるウェブフォームから、東アラビア文字 "١‎٠٠"
 455             が入力されたとしましょう。
 456             大半のソフトウェアや <acronym>PHP</acronym> の関数は、アラビア数字にしか対応していません。
 457             幸いなことに、この入力をそれと同等のラテン数字 "100"
 458             に変換するのは簡単で、<methodname>convertNumerals($inputNumeralString,
 459             $sourceNumeralSystem, $destNumeralSystem)</methodname> を使用するだけです。
 460             これは、数値 <code>$input</code> の script を
 461             <code>$sourceNumeralSystem</code> から <code>$destNumeralSystem</code>
 462             に変換したものを返します。
 463         </para>
 464
 465         <example id="zend.locale.numbersystems.example-1">
 466             <title>東アラビア文字から European/Latin 文字への変換</title>
 467             <programlisting language="php"><![CDATA[
 468 $arabicScript = "١‎٠٠";   // アラビア文字で "100" を表します
 469 $latinScript = Zend_Locale_Format::convertNumerals($arabicScript,
 470                                                    'Arab',
 471                                                    'Latn');
 472
 473 print "\n元の内容:   " . $arabicScript;
 474 print "\n正規化したもの: " . $latinScript;
 475 ]]></programlisting>
 476         </example>
 477
 478         <para>
 479             同様にして、任意の数値系をその他サポートしている数値系に変換できます。
 480         </para>
 481
 482         <example id="zend.locale.numbersystems.example-2">
 483             <title>ラテン文字から東アラビア文字への変換</title>
 484             <programlisting language="php"><![CDATA[
 485 $latinScript = '123';
 486 $arabicScript = Zend_Locale_Format::convertNumerals($latinScript,
 487                                                     'Latn',
 488                                                     'Arab');
 489
 490 print "\n元の内容: ".$latinScript;
 491 print "\n地域化したもの: " . $arabicScript;
 492 ]]></programlisting>
 493         </example>
 494
 495         <example id="zend.locale.numbersystems.example-3">
 496             <title>各国語での文字名を使用した、4 文字の <acronym>CLDR</acronym> 文字コードの取得</title>
 497             <programlisting language="php"><![CDATA[
 498 function getScriptCode($scriptName, $locale)
 499 {
 500     $scripts2names = Zend_Locale_Data::getList($locale, 'script');
 501     $names2scripts = array_flip($scripts2names);
 502     return $names2scripts[$scriptName];
 503 }
 504 echo getScriptCode('Latin', 'en'); // 出力は "Latn" となります
 505 echo getScriptCode('Tamil', 'en'); // 出力は "Taml" となります
 506 echo getScriptCode('tamoul', 'fr'); // 出力は "Taml" となります
 507 ]]></programlisting>
 508         </example>
 509
 510         <para>
 511             サポートする数値系の一覧は
 512             <methodname>Zend_Locale::getTranslationList('numberingsystem', 'en')</methodname>
 513             をコールすれば取得できます。
 514         </para>
 515
 516     </sect2>
 517
 518 </sect1>
 519 <!--
 520 vim:se ts=4 sw=4 et:
 521 -->