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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <!-- EN-Revision: 20792 -->
   4 <sect1 id="zend.locale.date.datesandtimes">
   5
   6     <title>日付および時刻の扱い</title>
   7
   8     <para>
   9         <classname>Zend_Locale_Format</classname> では、日付や時刻を扱うためのメソッドを提供しています。
  10         これらを使用して、さまざまなロケールのさまざまな書式間での変換や正規化を行います。
  11         日付データや
  12         <link linkend="zend.date.constants">
  13           <classname>Zend_Date</classname> がサポートする、さまざまな標準書式や地域化された日付書式
  14         </link>
  15         を満たす日付文字列の操作には <classname>Zend_Date</classname> を使用します。
  16         既存の定義済み書式を使用すると、「十分にテストされたコードが使用できる」
  17         「(一般的な使用法に従う限り) 可搬性や相互運用性を保証できる」といった利点があります。
  18         以下の例は、ここで推奨した内容に従っていません。しかし、
  19         非標準の書式を使用することで、これらの例は不必要にわかりにくくなってしまっています。
  20     </para>
  21
  22     <sect2 id="zend.locale.date.normalize">
  23
  24         <title>日付および時刻の正規化</title>
  25
  26         <para>
  27             <methodname>getDate()</methodname> メソッドは、地域化された書式の日付を含む文字列をパースします。
  28             結果は構造化された配列で返されます。この配列のキーが、日付の各部分を表します。
  29             さらに、この配列には 'date_format' というキーがあり、
  30             入力日付文字列をパースする際に使用する書式文字列がここに含まれます。
  31             地域化された日付文字列が日付/時刻のすべての要素を含んでいるとは限らないので、
  32             配列のすべてのキーが存在するとは限りません。
  33             たとえば年月日のみが指定された場合は、時刻に関する情報は配列から取り除かれます。
  34             逆に時分秒のみが指定された場合も同様です。
  35             入力に日付や時刻が含まれない場合は、例外がスローされます。
  36         </para>
  37
  38         <para>
  39             <methodname>setOption(array('fix_date' => true))</methodname> が設定されると、
  40             <methodname>getDate()</methodname> メソッドは
  41             'fixed' というキーを追加します。ここには数値が格納され、
  42             入力の日付文字列の年月日の順序を入れ替えたりして
  43             使用する書式にあわせるための情報を表します。
  44         </para>
  45
  46         <table id="zend.locale.date.normalize.table-1">
  47             <title>getDate() のオプション 'fix_date' のキーの値</title>
  48             <tgroup cols='2'>
  49                 <thead>
  50                     <row>
  51                         <entry>値</entry>
  52                         <entry>意味</entry>
  53                     </row>
  54                 </thead>
  55                 <tbody>
  56                     <row>
  57                         <entry>0</entry>
  58                         <entry>なにも修正しません。</entry>
  59                     </row>
  60                     <row>
  61                         <entry>1</entry>
  62                         <entry>無効な月を修正します。</entry>
  63                     </row>
  64                     <row>
  65                         <entry>2</entry>
  66                         <entry>日付と年の位置を入れ替えます。</entry>
  67                     </row>
  68                     <row>
  69                         <entry>3</entry>
  70                         <entry>月と年の位置を入れ替えます。</entry>
  71                     </row>
  72                     <row>
  73                         <entry>4</entry>
  74                         <entry>月と日の位置を入れ替えます。</entry>
  75                     </row>
  76                 </tbody>
  77             </tgroup>
  78         </table>
  79
  80         <para>
  81             日付文字列の書式を明示的に指定したい場合のために、次のような書式トークン指定子をサポートしています。
  82             <classname>Zend_Locale_Format</classname> のメソッドでユーザ定義書式に対応しているものの中で無効な書式指定子を使用した場合、
  83             たとえば <acronym>ISO</acronym> モードで <acronym>PHP</acronym> の 'i' 指定子を使用した場合などには例外がスローされます。
  84         </para>
  85
  86         <para>
  87             これらの (以下の) 指定子は、<classname>Zend_Date</classname> の <methodname>toString()</methodname> がサポートしている完全な "<acronym>ISO</acronym>"
  88             セットの一部です。<acronym>PHP</acronym> の <methodname>date()</methodname> 関数と同じ形式の指定子を使用したい場合は、
  89             まず最初に <methodname>setOptions(array('format_type' => 'php'))</methodname> をコールしてください。
  90             特定のひとつの書式文字列だけを <acronym>PHP</acronym> の <methodname>date()</methodname> 互換形式から
  91             "<acronym>ISO</acronym>" 形式に変換したい場合は <methodname>convertPhpToIsoFormat()</methodname>
  92             を使用します。現時点では、分の形式のみが異なっています
  93             (<acronym>ISO</acronym> のデフォルトでは 'm'、<acronym>PHP</acronym> の date 関数では 'i' を使用します)。
  94         </para>
  95
  96         <table id="zend.locale.date.normalize.table-2">
  97             <title>返り値</title>
  98             <tgroup cols='5'>
  99                 <thead>
 100                     <row>
 101                         <entry>getDate() 書式文字</entry>
 102                         <entry>配列のキー</entry>
 103                         <entry>返される値</entry>
 104                         <entry>最小値</entry>
 105                         <entry>最大値</entry>
 106                     </row>
 107                 </thead>
 108                 <tbody>
 109                     <row>
 110                         <entry>d</entry>
 111                         <entry>day</entry>
 112                         <entry>integer</entry>
 113                         <entry>1</entry>
 114                         <entry>31</entry>
 115                     </row>
 116                     <row>
 117                         <entry>M</entry>
 118                         <entry>month</entry>
 119                         <entry>integer</entry>
 120                         <entry>1</entry>
 121                         <entry>12</entry>
 122                     </row>
 123                     <row>
 124                         <entry>y</entry>
 125                         <entry>year</entry>
 126                         <entry>integer</entry>
 127                         <entry>無制限</entry>
 128                         <entry>PHP の整数型の最大値</entry>
 129                     </row>
 130                     <row>
 131                         <entry>h</entry>
 132                         <entry>hour</entry>
 133                         <entry>integer</entry>
 134                         <entry>0</entry>
 135                         <entry>PHP の整数型の最大値</entry>
 136                     </row>
 137                     <row>
 138                         <entry>m</entry>
 139                         <entry>minute</entry>
 140                         <entry>integer</entry>
 141                         <entry>0</entry>
 142                         <entry>PHP の整数型の最大値</entry>
 143                     </row>
 144                     <row>
 145                         <entry>s</entry>
 146                         <entry>second</entry>
 147                         <entry>integer</entry>
 148                         <entry>0</entry>
 149                         <entry>PHP の整数型の最大値</entry>
 150                     </row>
 151                 </tbody>
 152             </tgroup>
 153         </table>
 154
 155         <example id="zend.locale.date.normalize.example-1">
 156             <title>日付の正規化</title>
 157             <programlisting language="php"><![CDATA[
 158 $dateString = Zend_Locale_Format::getDate('13.04.2006',
 159                                           array('date_format' =>
 160                                                     'dd.MM.yyyy')
 161                                          );
 162
 163 // この日付に対応する Zend_Date オブジェクトを作成します
 164 $dateObject = Zend_Date('13.04.2006',
 165                          array('date_format' => 'dd.MM.yyyy'));
 166
 167 print_r($dateString); // 出力は、このようになります
 168
 169 Array
 170 (
 171     [format] => dd.MM.yyyy
 172     [day] => 13
 173     [month] => 4
 174     [year] => 2006
 175 )
 176
 177 // 入力値に何らかの問題がある場合に、自動的に修正します
 178 $date = Zend_Locale_Format::getDate('04.13.2006',
 179                                     array('date_format' => 'dd.MM.yyyy',
 180                                           'fix_date' => true)
 181                                    );
 182
 183 print_r($date); // 出力は、このようになります
 184
 185 Array
 186 (
 187     [format] => dd.MM.yyyy
 188     [day] => 13
 189     [month] => 4
 190     [year] => 2006
 191     [fixed] => 4
 192 )
 193 ]]></programlisting>
 194         </example>
 195
 196         <para>
 197             <methodname>getDate()</methodname> は "ロケール対応" なので、
 198             <code>$locale</code> を指定することで
 199             そのロケールの書式の日付文字列を使用できます。
 200             オプション '<code>fix_date</code>' は、簡単なテストを行って
 201             日付や月の妥当性を確認します。問題が見つかったら、
 202             経験則によってそれを何とか修正しようとします。
 203             '<constant>Zend_Locale_Format::STANDARD</constant>' を '<code>date_format</code>'
 204             の値として指定すると、<methodname>setOptions()</methodname>
 205             で設定されているクラス全体のデフォルト日付書式を使用しないようにできます。
 206             これにより、getDate は <code>$locale</code>
 207             のデフォルトの日付書式を使用するようになります。
 208         </para>
 209
 210         <example id="zend.locale.date.normalize.example-2">
 211             <title>ロケールを指定した日付の正規化</title>
 212             <programlisting language="php"><![CDATA[
 213 $locale = new Zend_Locale('de_AT');
 214 $date = Zend_Locale_Format::getDate('13.04.2006',
 215                                     array('date_format' =>
 216                                               Zend_Locale_Format::STANDARD,
 217                                           'locale' => $locale)
 218                                    );
 219
 220 print_r ($date);
 221 ]]></programlisting>
 222         </example>
 223
 224         <para>
 225             入力に日付と時刻の両方が含まれている場合に、
 226             完全な日付と時刻が返されます。
 227         </para>
 228
 229         <example id="zend.locale.date.normalize.example-3">
 230             <title>日付と時刻の正規化</title>
 231             <programlisting language="php"><![CDATA[
 232 $locale = new Zend_Locale('de_AT');
 233 $date = Zend_Locale_Format::getDate('13.04.2005 22:14:55',
 234                                     array('date_format' =>
 235                                                 Zend_Locale_Format::STANDARD,
 236                                           'locale' => $locale)
 237                                     );
 238
 239 print_r ($date);
 240 ]]></programlisting>
 241         </example>
 242
 243         <para>
 244             書式を指定したい場合は、
 245             <code>$locale</code> ではなく <code>$format</code> 引数を指定します。
 246             <code>$format</code> としてサポートされるのは、一文字のコード
 247             (H, m, s, y, M, d) および MMMM、EEEE だけです。
 248         </para>
 249
 250         <example id="zend.locale.date.normalize.example-4">
 251             <title>ユーザ定義の日付書式への正規化</title>
 252             <programlisting language="php"><![CDATA[
 253 $date = Zend_Locale_Format::getDate('13200504T551422',
 254                                     array('date_format' =>
 255                                               'ddyyyyMM ssmmHH')
 256                                    );
 257
 258 print_r ($date);
 259 ]]></programlisting>
 260         </example>
 261
 262         <para>
 263             書式には次の記号が使用できます。
 264         </para>
 265
 266         <table id="zend.locale.date.normalize.table-3">
 267             <title>書式定義</title>
 268             <tgroup cols='2'>
 269                 <thead>
 270                     <row>
 271                         <entry>書式指定文字</entry>
 272                         <entry>説明</entry>
 273                     </row>
 274                 </thead>
 275                 <tbody>
 276                     <row>
 277                         <entry>d あるいは dd</entry>
 278                         <entry>1 桁あるいは 2 桁の日</entry>
 279                     </row>
 280                     <row>
 281                         <entry>M あるいは MM</entry>
 282                         <entry>1 桁あるいは 2 桁の月</entry>
 283                     </row>
 284                     <row>
 285                         <entry>y あるいは yy</entry>
 286                         <entry>1 桁あるいは 2 桁の年</entry>
 287                     </row>
 288                     <row>
 289                         <entry>yyyy</entry>
 290                         <entry>4 桁の年</entry>
 291                     </row>
 292                     <row>
 293                         <entry>h</entry>
 294                         <entry>1 桁あるいは 2 桁の時</entry>
 295                     </row>
 296                     <row>
 297                         <entry>m</entry>
 298                         <entry>1 桁あるいは 2 桁の分</entry>
 299                     </row>
 300                     <row>
 301                         <entry>s</entry>
 302                         <entry>1 桁あるいは 2 桁の秒</entry>
 303                     </row>
 304                 </tbody>
 305             </tgroup>
 306         </table>
 307
 308         <para>
 309             適切な書式の例は、次のようになります。
 310         </para>
 311
 312         <table id="zend.locale.date.normalize.table-4">
 313             <title>書式の例</title>
 314             <tgroup cols='3'>
 315                 <thead>
 316                     <row>
 317                         <entry>書式</entry>
 318                         <entry>入力</entry>
 319                         <entry>出力</entry>
 320                     </row>
 321                 </thead>
 322                 <tbody>
 323                     <row>
 324                         <entry>dd.MM.yy</entry>
 325                         <entry>1.4.6</entry>
 326                         <entry>['day'] => 1,
 327                                    ['month'] => 4,
 328                                    ['year'] => 6</entry>
 329                     </row>
 330                     <row>
 331                         <entry>dd.MM.yy</entry>
 332                         <entry>01.04.2006</entry>
 333                         <entry>['day'] => 1, ['month'] => 4, ['year'] => 2006</entry>
 334                     </row>
 335                     <row>
 336                         <entry>yyyyMMdd</entry>
 337                         <entry>1.4.6</entry>
 338                         <entry>['day'] => 6, ['month'] => 4, ['year'] => 1</entry>
 339                     </row>
 340                 </tbody>
 341             </tgroup>
 342         </table>
 343
 344         <note>
 345             <title>データベースの日付書式</title>
 346             <para>
 347                 データベース (たとえば MySql や MsSql など) の日付値をパースするには、
 348                 getDate() のかわりに <classname>Zend_Date</classname> の ISO_8601 書式を使用します。
 349             </para>
 350         </note>
 351
 352         <para>
 353             オプション '<code>fix_date</code>' は、簡単なテストを行って
 354             日付や月の妥当性を確認します。問題が見つかったら、
 355             経験則によってそれを何とか修正しようとします。
 356             <methodname>getDate()</methodname> は、
 357             入力に問題がある場合にそれを自動で検出し、訂正します。
 358             たとえば年の位置が違っている場合などがこれにあたります。
 359         </para>
 360
 361         <example id="zend.locale.date.normalize.example-5">
 362             <title>入力された日付の訂正処理</title>
 363             <programlisting language="php"><![CDATA[
 364 $date = Zend_Locale_Format::getDate('41.10.20',
 365                                     array('date_format' => 'ddMMyy',
 366                                           'fix_date' => true)
 367                                    );
 368
 369 // 41 は、日付ではなく年として返されます
 370 print_r ($date);
 371 ]]></programlisting>
 372         </example>
 373
 374     </sect2>
 375
 376     <sect2 id="zend.locale.date.test">
 377
 378         <title>日付かどうかの確認</title>
 379
 380         <para>
 381             <methodname>checkDateFormat($inputString, array('date_format' => $format, $locale))</methodname> を使用して、
 382             指定した文字列が期待通りの日付を含むかどうかを調べます。
 383             <methodname>checkDateFormat()</methodname> メソッドは <methodname>getDate()</methodname> を使用します。
 384             しかし、オプション <code>'fixdate'</code> は使用しません。これを使用すると、
 385             入力が日付書式を満たしていない場合にも <constant>TRUE</constant> を返してしまうからです。
 386             月と日の位置が入れ替わっているなどのエラーが入力で検出された場合、
 387             オプション <code>'fixdate'</code> は
 388             経験則によってそれを "修正" してから検証します。
 389         </para>
 390
 391         <example id="zend.locale.date.test.example-1">
 392             <title>日付かどうかの確認</title>
 393             <programlisting language="php"><![CDATA[
 394 $locale = new Zend_Locale('de_AT');
 395 if (Zend_Locale_Format::checkDateFormat('13.Apr.2006',
 396                                         array('date_format' =>
 397                                                   Zend_Locale_Format::STANDARD,
 398                                               $locale)
 399                                        ) {
 400     print "日付です";
 401 } else {
 402     print "日付ではありません";
 403 }
 404 ]]></programlisting>
 405         </example>
 406
 407     </sect2>
 408
 409     <sect2 id="zend.locale.time.normalizing">
 410
 411         <title>時刻の正規化</title>
 412
 413         <para>
 414             通常、入力に日付と時刻が両方含まれている場合は、
 415             時刻は日付とともに返されます。
 416             適切な書式はわからないが、ユーザの入力のロケールがわかるという場合に
 417             <methodname>getTime()</methodname> を使用します。
 418             これは、選択したロケールに対するデフォルトの時刻書式を使用するからです。
 419         </para>
 420
 421         <example id="zend.locale.time.normalizing.example-1">
 422             <title>未知の時刻の正規化</title>
 423             <programlisting language="php"><![CDATA[
 424 $locale = new Zend_Locale('de_AT');
 425 if (Zend_Locale_Format::getTime('13:44:42',
 426                                 array('date_format' =>
 427                                           Zend_Locale_Format::STANDARD,
 428                                       'locale' => $locale)) {
 429     print "時刻です";
 430 } else {
 431     print "時刻ではありません";
 432 }
 433 ]]></programlisting>
 434         </example>
 435
 436     </sect2>
 437
 438     <sect2 id="zend.locale.time.test">
 439
 440         <title>時刻かどうかの確認</title>
 441
 442         <para>
 443             <methodname>checkDateFormat()</methodname> を使用して、
 444             指定した文字列が有効な時刻を含むかどうかを調べます。
 445             使用法は、日付の確認の場合と同じです。ただし、
 446             <code>date_format</code> には期待するパーツを指定しなければなりません。
 447         </para>
 448
 449         <example id="zend.locale.time.test.example-1">
 450             <title>時刻かどうかの確認</title>
 451             <programlisting language="php"><![CDATA[
 452 $locale = new Zend_Locale('de_AT');
 453 if (Zend_Locale_Format::checkDateFormat('13:44:42',
 454                                         array('date_format' => 'HH:mm:ss',
 455                                               'locale' => $locale)) {
 456     print "時刻です";
 457 } else {
 458     print "時刻ではありません";
 459 }
 460 ]]></programlisting>
 461         </example>
 462
 463     </sect2>
 464
 465 </sect1>
 466 <!--
 467 vim:se ts=4 sw=4 et:
 468 -->