repo_zf1/documentation/manual/ja/module_specs/Zend_Date-Basic.xml

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

    <title>基本メソッド</title>

    <para>
        この章では、<classname>Zend_Date</classname> の基本的な使用法を、
        例をもとに説明します。このマニュアルで "日付"
        というときは、常に時刻も含んでいるものとします。
        これは、明示的に説明していなくても同様です。
        指定していない部分のデフォルトは "ゼロ" になります。
        つまり、日付情報をもたず 12 時間という時刻情報だけを持つ値と
        日付情報だけを持つ値を足すと、その日付の "正午" を表すようになります。
    </para>

    <para>
        日付のみを指定して時刻部を省略すると、時刻は 00:00:00 になります。
        逆に時刻のみを指定した場合は、日付の内部表現は
        01.01.1970 からの経過秒数と等しくなります。
        通常、人間が時間を計算する場合は西暦ゼロ年を基準とします。
        しかし、多くのソフトウェアは 1970 年を基準として時間を計算します。
        そして、ここからの経過秒数をタイムスタンプとして表します。
    </para>

    <sect2 id="zend.date.basic.creation">

        <title>現在の日付</title>

        <para>
            引数を指定せずにインスタンスを作成すると、
            デフォルトのロケールでの現在時刻を表すオブジェクトを返します。
            <acronym>PHP</acronym> の <methodname>time()</methodname> 関数で、このオブジェクトが使用する
            <ulink url="http://en.wikipedia.org/wiki/Unix_Time">UNIX タイムスタンプ</ulink>
            を取得します。<acronym>PHP</acronym> の環境で、
            <link linkend="zend.date.setdefaulttimezone">デフォルトのタイムゾーン</link>
            が正しく設定されていることを確認しておきましょう。
        </para>

        <example id="zend.date.basic.creation.example-1">
            <title>現在の日付の作成</title>
            <programlisting language="php"><![CDATA[
$date = new Zend_Date();

// 現在のタイムスタンプを出力します
print $date;
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.date.basic.functions">

        <title>Zend_Date の使用例</title>

        <para>
            <classname>Zend_Date</classname> の基本的なメソッドを見ていきましょう。
            他の言語やフレームワークの日付オブジェクトではあまり見かけないメソッドもあります。
            以下の各メソッドについて、簡単な例を示しています。
        </para>

        <sect3 id="zend.date.simple.functions.get">

            <title>日付の出力</title>

            <para>
                <classname>Zend_Date</classname> オブジェクトの日付を
                地域化された形式の整数あるいは文字列で取得する際に、
                <methodname>get()</methodname> メソッドを使用します。このメソッドには、
                さまざまなオプションが使用可能です。これらのオプションについてはあとで説明します。
            </para>

            <example id="zend.date.simple.functions.get.example-1">
                <title>get() - 日付の出力</title>
                <programlisting language="php"><![CDATA[
$date = new Zend_Date();

// 指定した日付を出力します
print $date->get();
]]></programlisting>
            </example>

        </sect3>

        <sect3 id="zend.date.simple.functions.set">

            <title>日付の設定</title>

            <para>
                <methodname>set()</methodname> メソッドは、オブジェクトに格納されている日付を変更し、
                変更後の値をタイムスタンプ (オブジェクトではありません) で返します。
                このメソッドでもさまざまなオプションが使用可能です。
                これらのオプションについてはあとで説明します。
            </para>

            <example id="zend.date.simple.functions.set.example-1">
                <title>set() - 日付の設定</title>
                <programlisting language="php"><![CDATA[
$date = new Zend_Date();

// 新しい時刻を設定します
$date->set('13:00:00',Zend_Date::TIMES);
print $date->get(Zend_Date::W3C);
]]></programlisting>
            </example>

        </sect3>

        <sect3 id="zend.date.simple.functions.add">

            <title>日付の加減算</title>

            <para>
                二つの日付を <methodname>add()</methodname> で加算するという場合、
                通常は実際の日付データにそうでない日付データの一部 ("12 時間" など)
                を加算することになります。たとえば以下の例のようなものです。
                <methodname>add()</methodname> および <methodname>sub()</methodname> は、どちらも
                <methodname>set()</methodname> と同様のオプションを使用します。
                これについてはあとで説明します。
            </para>

            <example id="zend.date.simple.functions.add.example-1">
                <title>add() - 日付の加算</title>
                <programlisting language="php"><![CDATA[
$date = new Zend_Date();

// $date に 12 時間加算します
$date->add('12:00:00', Zend_Date::TIMES);

echo "get() で取得した日付 = ", $date->get(Zend_Date::W3C), "\n";

// マジックメソッド __toString() から、Zend_Date の toString() をコールします
echo "toString() で取得した日付 = ", $date, "\n";
]]></programlisting>
            </example>

        </sect3>

        <sect3 id="zend.date.simple.functions.compare">

            <title>日付の比較</title>

            <para>
                <classname>Zend_Date</classname> の基本メソッド群はすべて、
                オブジェクトに含まれる日付データ全体に対して操作できます。
                また、日付の一部に対して操作する (日付の "分"
                の部分だけをある値と比較するなど) こともできます。
                たとえば、現在時刻の "分" の部分を指定した値と比較するには
                <methodname>compare()</methodname> を使用します。以下に例を示します。
            </para>

            <example id="zend.date.simple.functions.compare.example-1">
                <title>compare() - 日付の比較</title>
                <programlisting language="php"><![CDATA[
$date = new Zend_Date();

// 二つの時刻を比較します
if ($date->compare(10, Zend_Date::MINUTE) == -1) {
    print "This hour is less than 10 minutes old";
} else {
    print "This hour is at least 10 minutes old";
}
]]></programlisting>
            </example>

            <para>
                単純に等しいかどうかを比較するには <methodname>equals()</methodname>
                を使用します。これは boolean 値を返します。
            </para>

            <example id="zend.date.simple.functions.compare.example-2">
                <title>equals() - 日付あるいはその一部の同一性</title>
                <programlisting language="php"><![CDATA[
$date = new Zend_Date();

// 二つの日付を比較します
if ($date->equals(10, Zend_Date::HOUR)) {
    print "十時です。仕事を始める時間です。";
} else {
    print "十時ではありません。もうちょっと寝ていましょう。";
}
]]></programlisting>
            </example>

        </sect3>

    </sect2>

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