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

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15103 -->
<sect1 id="zend.locale.date.datesandtimes">

    <title>日付および時刻の扱い</title>

    <para>
        <classname>Zend_Locale_Format</classname> では、日付や時刻を扱うためのメソッドを提供しています。
        これらを使用して、さまざまなロケールのさまざまな書式間での変換や正規化を行います。
        日付データや
        <link linkend="zend.date.constants">
          <classname>Zend_Date</classname> がサポートする、さまざまな標準書式や地域化された日付書式
        </link>
        を満たす日付文字列の操作には <classname>Zend_Date</classname> を使用します。
        既存の定義済み書式を使用すると、「十分にテストされたコードが使用できる」
        「(一般的な使用法に従う限り) 可搬性や相互運用性を保証できる」といった利点があります。
        以下の例は、ここで推奨した内容に従っていません。しかし、
        非標準の書式を使用することで、これらの例は不必要にわかりにくくなってしまっています。
    </para>

    <sect2 id="zend.locale.date.normalize">

        <title>日付および時刻の正規化</title>

        <para>
            <code>getDate()</code> メソッドは、地域化された書式の日付を含む文字列をパースします。
            結果は構造化された配列で返されます。この配列のキーが、日付の各部分を表します。
            さらに、この配列には 'date_format' というキーがあり、
            入力日付文字列をパースする際に使用する書式文字列がここに含まれます。
            地域化された日付文字列が日付/時刻のすべての要素を含んでいるとは限らないので、
            配列のすべてのキーが存在するとは限りません。
            たとえば年月日のみが指定された場合は、時刻に関する情報は配列から取り除かれます。
            逆に時分秒のみが指定された場合も同様です。
            入力に日付や時刻が含まれない場合は、例外がスローされます。
        </para>

        <para>
            <code>setOption(array('fix_date' => true))</code> が設定されると、
            <code>getDate()</code> メソッドは
            'fixed' というキーを追加します。ここには数値が格納され、
            入力の日付文字列の年月日の順序を入れ替えたりして
            使用する書式にあわせるための情報を表します。
        </para>

        <table id="zend.locale.date.normalize.table-1">
            <title>getDate() のオプション 'fix_date' のキーの値</title>
            <tgroup cols='2'>
                <thead>
                    <row>
                        <entry>値</entry>
                        <entry>意味</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>0</entry>
                        <entry>なにも修正しません。</entry>
                    </row>
                    <row>
                        <entry>1</entry>
                        <entry>無効な月を修正します。</entry>
                    </row>
                    <row>
                        <entry>2</entry>
                        <entry>日付と年の位置を入れ替えます。</entry>
                    </row>
                    <row>
                        <entry>3</entry>
                        <entry>月と年の位置を入れ替えます。</entry>
                    </row>
                    <row>
                        <entry>4</entry>
                        <entry>月と日の位置を入れ替えます。</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            日付文字列の書式を明示的に指定したい場合のために、次のような書式トークン指定子をサポートしています。
            <classname>Zend_Locale_Format</classname> のメソッドでユーザ定義書式に対応しているものの中で無効な書式指定子を使用した場合、
            たとえば ISO モードで PHP の 'i' 指定子を使用した場合などには例外がスローされます。
        </para>

        <para>
            これらの (以下の) 指定子は、<classname>Zend_Date</classname> の <code>toString()</code> がサポートしている完全な "ISO"
            セットの一部です。PHP の <code>date()</code> 関数と同じ形式の指定子を使用したい場合は、
            まず最初に <code>setOptions(array('format_type' => 'php'))</code> をコールしてください。
            特定のひとつの書式文字列だけを PHP の <code>date()</code> 互換形式から
            "ISO" 形式に変換したい場合は <code>convertPhpToIsoFormat()</code>
            を使用します。現時点では、分の形式のみが異なっています
            (ISO のデフォルトでは 'm'、PHP の date 関数では 'i' を使用します)。
        </para>

        <table id="zend.locale.date.normalize.table-2">
            <title>返り値</title>
            <tgroup cols='5'>
                <thead>
                    <row>
                        <entry>getDate() 書式文字</entry>
                        <entry>配列のキー</entry>
                        <entry>返される値</entry>
                        <entry>最小値</entry>
                        <entry>最大値</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>d</entry>
                        <entry>day</entry>
                        <entry>integer</entry>
                        <entry>1</entry>
                        <entry>31</entry>
                    </row>
                    <row>
                        <entry>M</entry>
                        <entry>month</entry>
                        <entry>integer</entry>
                        <entry>1</entry>
                        <entry>12</entry>
                    </row>
                    <row>
                        <entry>y</entry>
                        <entry>year</entry>
                        <entry>integer</entry>
                        <entry>無制限</entry>
                        <entry>PHP の整数型の最大値</entry>
                    </row>
                    <row>
                        <entry>h</entry>
                        <entry>hour</entry>
                        <entry>integer</entry>
                        <entry>0</entry>
                        <entry>PHP の整数型の最大値</entry>
                    </row>
                    <row>
                        <entry>m</entry>
                        <entry>minute</entry>
                        <entry>integer</entry>
                        <entry>0</entry>
                        <entry>PHP の整数型の最大値</entry>
                    </row>
                    <row>
                        <entry>s</entry>
                        <entry>second</entry>
                        <entry>integer</entry>
                        <entry>0</entry>
                        <entry>PHP の整数型の最大値</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <example id="zend.locale.date.normalize.example-1">
            <title>日付の正規化</title>
            <programlisting role="php"><![CDATA[
$dateString = Zend_Locale_Format::getDate('13.04.2006',
                                          array('date_format' =>
                                                    'dd.MM.yyyy')
                                         );

// この日付に対応する Zend_Date オブジェクトを作成します
$dateObject = Zend_Date('13.04.2006',
                         array('date_format' => 'dd.MM.yyyy'));

print_r($dateString); // 出力は、このようになります

Array
(
    [format] => dd.MM.yyyy
    [day] => 13
    [month] => 4
    [year] => 2006
)

// 入力値に何らかの問題がある場合に、自動的に修正します
$date = Zend_Locale_Format::getDate('04.13.2006',
                                    array('date_format' => 'dd.MM.yyyy',
                                          'fix_date' => true)
                                   );

print_r($date); // 出力は、このようになります

Array
(
    [format] => dd.MM.yyyy
    [day] => 13
    [month] => 4
    [year] => 2006
    [fixed] => 4
)
]]>
            </programlisting>
        </example>

        <para>
            <code>getDate()</code> は "ロケール対応" なので、
            <code>$locale</code> を指定することで
            そのロケールの書式の日付文字列を使用できます。
            オプション '<code>fix_date</code>' は、簡単なテストを行って
            日付や月の妥当性を確認します。問題が見つかったら、
            経験則によってそれを何とか修正しようとします。
            '<classname>Zend_Locale_Format::STANDARD</classname>' を '<code>date_format</code>'
            の値として指定すると、<code>setOptions()</code>
            で設定されているクラス全体のデフォルト日付書式を使用しないようにできます。
            これにより、getDate は <code>$locale</code>
            のデフォルトの日付書式を使用するようになります。
        </para>

        <example id="zend.locale.date.normalize.example-2">
            <title>ロケールを指定した日付の正規化</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$date = Zend_Locale_Format::getDate('13.04.2006',
                                    array('date_format' =>
                                              Zend_Locale_Format::STANDARD,
                                          'locale' => $locale)
                                   );

print_r ($date);
]]>
            </programlisting>
        </example>

        <para>
            入力に日付と時刻の両方が含まれている場合に、
            完全な日付と時刻が返されます。
        </para>

        <example id="zend.locale.date.normalize.example-3">
            <title>日付と時刻の正規化</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
$date = Zend_Locale_Format::getDate('13.04.2005 22:14:55',
                                    array('date_format' =>
                                                Zend_Locale_Format::STANDARD,
                                          'locale' => $locale)
                                    );

print_r ($date);
]]>
            </programlisting>
        </example>

        <para>
            書式を指定したい場合は、
            <code>$locale</code> ではなく <code>$format</code> 引数を指定します。
            <code>$format</code> としてサポートされるのは、一文字のコード
            (H, m, s, y, M, d) および MMMM、EEEE だけです。
        </para>

        <example id="zend.locale.date.normalize.example-4">
            <title>ユーザ定義の日付書式への正規化</title>
            <programlisting role="php"><![CDATA[
$date = Zend_Locale_Format::getDate('13200504T551422',
                                    array('date_format' =>
                                              'ddyyyyMM ssmmHH')
                                   );

print_r ($date);
]]>
            </programlisting>
        </example>

        <para>
            書式には次の記号が使用できます。
        </para>

        <table id="zend.locale.date.normalize.table-3">
            <title>書式定義</title>
            <tgroup cols='2'>
                <thead>
                    <row>
                        <entry>書式指定文字</entry>
                        <entry>説明</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>d あるいは dd</entry>
                        <entry>1 桁あるいは 2 桁の日</entry>
                    </row>
                    <row>
                        <entry>M あるいは MM</entry>
                        <entry>1 桁あるいは 2 桁の月</entry>
                    </row>
                    <row>
                        <entry>y あるいは yy</entry>
                        <entry>1 桁あるいは 2 桁の年</entry>
                    </row>
                    <row>
                        <entry>yyyy</entry>
                        <entry>4 桁の年</entry>
                    </row>
                    <row>
                        <entry>h</entry>
                        <entry>1 桁あるいは 2 桁の時</entry>
                    </row>
                    <row>
                        <entry>m</entry>
                        <entry>1 桁あるいは 2 桁の分</entry>
                    </row>
                    <row>
                        <entry>s</entry>
                        <entry>1 桁あるいは 2 桁の秒</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <para>
            適切な書式の例は、次のようになります。
        </para>

        <table id="zend.locale.date.normalize.table-4">
            <title>書式の例</title>
            <tgroup cols='3'>
                <thead>
                    <row>
                        <entry>書式</entry>
                        <entry>入力</entry>
                        <entry>出力</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>dd.MM.yy</entry>
                        <entry>1.4.6</entry>
                        <entry>['day'] => 1,
                                   ['month'] => 4,
                                   ['year'] => 6</entry>
                    </row>
                    <row>
                        <entry>dd.MM.yy</entry>
                        <entry>01.04.2006</entry>
                        <entry>['day'] => 1, ['month'] => 4, ['year'] => 2006</entry>
                    </row>
                    <row>
                        <entry>yyyyMMdd</entry>
                        <entry>1.4.6</entry>
                        <entry>['day'] => 6, ['month'] => 4, ['year'] => 1</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>

        <note>
            <title>データベースの日付書式</title>
            <para>
                データベース (たとえば MySql や MsSql など) の日付値をパースするには、
                getDate() のかわりに <classname>Zend_Date</classname> の ISO_8601 書式を使用します。
            </para>
        </note>

        <para>
            オプション '<code>fix_date</code>' は、簡単なテストを行って
            日付や月の妥当性を確認します。問題が見つかったら、
            経験則によってそれを何とか修正しようとします。
            <code>getDate()</code> は、
            入力に問題がある場合にそれを自動で検出し、訂正します。
            たとえば年の位置が違っている場合などがこれにあたります。
        </para>

        <example id="zend.locale.date.normalize.example-5">
            <title>入力された日付の訂正処理</title>
            <programlisting role="php"><![CDATA[
$date = Zend_Locale_Format::getDate('41.10.20',
                                    array('date_format' => 'ddMMyy',
                                          'fix_date' => true)
                                   );

// 41 は、日付ではなく年として返されます
print_r ($date);
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.date.test">

        <title>日付かどうかの確認</title>

        <para>
            <code>checkDateFormat($inputString, array('date_format' => $format, $locale))</code> を使用して、
            指定した文字列が期待通りの日付を含むかどうかを調べます。
            <code>checkDateFormat()</code> メソッドは <code>getDate()</code> を使用します。
            しかし、オプション <code>'fixdate'</code> は使用しません。これを使用すると、
            入力が日付書式を満たしていない場合にも true を返してしまうからです。
            月と日の位置が入れ替わっているなどのエラーが入力で検出された場合、
            オプション <code>'fixdate'</code> は
            経験則によってそれを "修正" してから検証します。
        </para>

        <example id="zend.locale.date.test.example-1">
            <title>日付かどうかの確認</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
if (Zend_Locale_Format::checkDateFormat('13.Apr.2006',
                                        array('date_format' =>
                                                  Zend_Locale_Format::STANDARD,
                                              $locale)
                                       ) {
    print "日付です";
} else {
    print "日付ではありません";
}
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.time.normalizing">

        <title>時刻の正規化</title>

        <para>
            通常、入力に日付と時刻が両方含まれている場合は、
            時刻は日付とともに返されます。
            適切な書式はわからないが、ユーザの入力のロケールがわかるという場合に
            <code>getTime()</code> を使用します。
            これは、選択したロケールに対するデフォルトの時刻書式を使用するからです。
        </para>

        <example id="zend.locale.time.normalizing.example-1">
            <title>未知の時刻の正規化</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
if (Zend_Locale_Format::getTime('13:44:42',
                                array('date_format' =>
                                          Zend_Locale_Format::STANDARD,
                                      'locale' => $locale)) {
    print "時刻です";
} else {
    print "時刻ではありません";
}
]]>
            </programlisting>
        </example>

    </sect2>

    <sect2 id="zend.locale.time.test">

        <title>時刻かどうかの確認</title>

        <para>
            <code><code>checkDateFormat()</code></code> を使用して、
            指定した文字列が有効な時刻を含むかどうかを調べます。
            使用法は、日付の確認の場合と同じです。ただし、
            <code>date_format</code> には期待するパーツを指定しなければなりません。
        </para>

        <example id="zend.locale.time.test.example-1">
            <title>時刻かどうかの確認</title>
            <programlisting role="php"><![CDATA[
$locale = new Zend_Locale('de_AT');
if (Zend_Locale_Format::checkDateFormat('13:44:42',
                                        array('date_format' => 'HH:mm:ss',
                                              'locale' => $locale)) {
    print "時刻です";
} else {
    print "時刻ではありません";
}
]]>
            </programlisting>
        </example>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->