repo_zf1/documentation/manual/es/module_specs/Zend_Date-Overview.xml

<?xml version="1.0" encoding="UTF-8"?>
    <!-- EN-Revision: 24249 -->
    <!-- Reviewed: no -->
<sect1 id="zend.date.overview">
    <title>Zend_Date API Overview</title>

    <para>
        While the
        <classname>Zend_Date</classname>
        <acronym>API</acronym>
        remains simplistic and unitary, its design remains flexible and
        powerful through the rich
        permutations of operations and operands.
    </para>

    <sect2 id="zend.date.options">
        <title>Zend_Date Options</title>

        <sect3 id="zend.date.options.formattype">
            <title>Selecting the Date Format Type</title>

            <para>
                Several methods use date format strings, in a way similar to
                <acronym>PHP</acronym>
                's
                <methodname>date()</methodname>
                . If you are more
                comfortable with
                <acronym>PHP</acronym>
                's date format specifier than with
                <acronym>ISO</acronym>
                format specifiers, then you can use
                <methodname>Zend_Date::setOptions(array('format_type' => 'php'))</methodname>
                .
                Afterward, use
                <acronym>PHP</acronym>
                's date format specifiers for all functions
                which accept a
                <varname>$format</varname>
                parameter. Use
                <methodname>Zend_Date::setOptions(array('format_type' => 'iso'))</methodname>
                to
                switch back to the default mode of supporting only
                <acronym>ISO</acronym>
                date
                format tokens. For a list of supported format codes, see
                <link linkend="zend.date.constants.phpformats">Self-Defined OUTPUT Formats Using PHP's
                    date() Format Specifiers</link>
            </para>
        </sect3>

        <sect3 id="zend.date.options.fixdst">
            <title>DST and Date Math</title>

            <para>
                When dates are manipulated, sometimes they cross over a
                <acronym>DST</acronym>
                change, normally resulting in the date losing or gaining an hour. For exmaple, when
                adding months to a date before a
                <acronym>DST</acronym>
                change, if the resulting
                date is after the
                <acronym>DST</acronym>
                change, then the resulting date will appear
                to lose or gain an hour, resulting in the
                time value of the date changing. For
                boundary dates, such as midnight of the first or
                last day of a month, adding enough
                months to cross a date boundary results in the
                date losing an hour and becoming the
                last hour of the preceding month, giving the
                appearance of an "off by 1" error. To
                avoid this situation, the
                <acronym>DST</acronym>
                change ignored by using the
                <property>fix_dst</property>
                option. When crossing the Summer or Winter
                <acronym>DST</acronym>
                boundary, normally an hour is substracted or added
                depending on the date. For
                example, date math crossing the Spring
                <acronym>DST</acronym>
                leads to a date having a day value one less than
                expected, if the time part of the
                date was originally 00:00:00. Since
                <classname>Zend_Date</classname>
                is based on timestamps, and not calendar dates
                with a time component, the timestamp
                loses an hour, resulting in the date having a
                calendar day value one less than
                expected. To prevent such problems use the option
                <property>fix_dst</property>
                , which defaults to
                <constant>TRUE</constant>
                ,
                causing
                <acronym>DST</acronym>
                to have no effect on date "math"
                (
                <methodname>addMonth()</methodname>
                ,
                <methodname>subMonth()</methodname>
                ). Use
                <methodname>Zend_Date::setOptions(array('fix_dst' => false))</methodname>
                to
                enable the subtraction or addition of the
                <acronym>DST</acronym>
                adjustment when
                performing date "math".
            </para>

            <para>
                <emphasis>
                    If your actual timezone within the instance of
                    <classname>Zend_Date</classname>
                    is set to
                    <acronym>UTC</acronym>
                    or
                    <acronym>GMT</acronym>
                    the option '
                    <property>fix_dst</property>
                    ' will not be
                    used
                </emphasis>
                because these two timezones do not work with
                <acronym>DST</acronym>
                . When you change the timezone for this instance again to
                a timezone which is not
                <acronym>UTC</acronym>
                or
                <acronym>GMT</acronym>
                the
                previous set 'fix_dst' option will be used again for date "math".
            </para>
        </sect3>

        <sect3 id="zend.date.options.extendmonth">
            <title>Month Calculations</title>

            <para>
                When adding or substracting months from an existing date, the resulting value for
                the day of the month might be unexpected, if the original date fell on a day close
                to the end of the month. For example, when adding one month to January 31st, people
                familiar with
                <acronym>SQL</acronym>
                will expect February 28th as the result. On the
                other side, people familiar with
                Excel and OpenOffice will expect March 3rd as the
                result. The problem only occurs, if
                the resulting month does not have the day, which
                is set in the original date. For
                Zend Framework developers, the desired behavior is
                selectable using the
                <property>extend_month</property>
                option to choose either the
                <acronym>SQL</acronym>
                behaviour, if set to
                <constant>FALSE</constant>
                , or the
                spreadsheet behaviour when set to
                <constant>TRUE</constant>
                . The default behaviour
                for
                <property>extend_month</property>
                is
                <constant>FALSE</constant>
                , providing
                behavior compatible to
                <acronym>SQL</acronym>
                . By default,
                <classname>Zend_Date</classname>
                computes month calculations by truncating dates
                to the end of the month (if
                necessary), without wrapping into the next month when
                the original date designates a
                day of the month exceeding the number of days in the
                resulting month. Use
                <methodname>Zend_Date::setOptions(array('extend_month' =>
                    true))</methodname>
                to make month calculations work like popular spreadsheet
                programs.
            </para>
        </sect3>

        <sect3 id="zend.date.options.cache">
            <title>Speed up Date Localization and Normalization with Zend_Cache</title>

            <para>
                You can speed up
                <classname>Zend_Date</classname>
                by using an
                <classname>Zend_Cache</classname>
                adapter. This speeds up all methods of
                <classname>Zend_Date</classname>
                when you are using localized data. For example
                all methods which accept
                <constant>Zend_Date::DATE</constant>
                and
                <constant>Zend_Date::TIME</constant>
                constants would benefit from this. To set
                an
                <classname>Zend_Cache</classname>
                adapter to
                <classname>Zend_Date</classname>
                just use
                <methodname>Zend_Date::setOptions(array('cache' => $adapter))</methodname>
                .
            </para>
        </sect3>

        <sect3 id="zend.date.options.timesync">
            <title>Receiving Syncronised Timestamps with Zend_TimeSync</title>

            <para>
                Normally the clocks from servers and computers differ from each other.
                <classname>Zend_Date</classname>
                is able to handle such problems with the help
                of
                <classname>Zend_TimeSync</classname>
                . You can set a timeserver with
                <methodname>Zend_Date::setOptions(array('timesync' => $timeserver))</methodname>
                which will set the offset between the own actual timestamp and the real actual
                timestamp for all instances of
                <classname>Zend_Date</classname>
                . Using this option
                does not change the timestamp of existing instances. So best
                usage is to set it
                within the bootstrap file.
            </para>
        </sect3>
    </sect2>

    <sect2 id="zend.date.values">
        <title>Working with Date Values</title>

        <para>
            Once input has been normalized via the creation of a
            <classname>Zend_Date</classname>
            object, it will have an associated timezone, but an internal representation using
            standard
            <ulink url="http://en.wikipedia.org/wiki/Unix_Time">UNIX timestamps</ulink>
            . In
            order for a date to be rendered in a localized manner, a timezone must be known
            first.
            The default timezone is always
            <acronym>GMT</acronym>
            or
            <acronym>UTC</acronym>
            . To
            examine an object's timezone use
            <methodname>getTimeZone()</methodname>
            . To change an
            object's timezone, use
            <methodname>setTimeZone()</methodname>
            . All manipulations of
            these objects are assumed to be relative to this timezone.
        </para>

        <para>
            Beware of mixing and matching operations with date parts between date objects for
            different timezones, which generally produce undesireable results, unless the
            manipulations are only related to the timestamp. Operating on
            <classname>Zend_Date</classname>
            objects having different timezones generally works,
            except as just noted, since dates are
            normalized to
            <acronym>UNIX</acronym>
            timestamps
            on instantiation of
            <classname>Zend_Date</classname>
            .
        </para>

        <para>
            Most methods expect a constant selecting the desired
            <varname>$part</varname>
            of a
            date, such as
            <constant>Zend_Date::HOUR</constant>
            . These constants are valid for all of
            the functions below. A list of all available
            constants is provided in
            <link linkend="zend.date.constants.list">list of all constants</link>
            . If no
            <varname>$part</varname>
            is specified, then
            <constant>Zend_Date::TIMESTAMP</constant>
            is assumed. Alternatively, a
            user-specified format may be used for
            <varname>$part</varname>
            , using the same
            underlying mechanism and format codes as
            <link linkend="zend.locale.date.normalize">
                <methodname>Zend_Locale_Format::getDate()</methodname>
            </link>
            . If a date object is constructed using an obviously invalid date (e.g. a month
            number
            greater than 12), then
            <classname>Zend_Date</classname>
            will throw an exception,
            unless no specific date format has been selected -i.e.
            <varname>$part</varname>
            is
            either
            <constant>NULL</constant>
            or
            <constant>Zend_Date::DATES</constant>
            (a "loose"
            format).
        </para>

        <example id="zend.date.values.example-1">
            <title>User-Specified Input Date Format</title>
            <programlisting language="php"><![CDATA[
$date1 = new Zend_Date('Feb 31, 2007', null, 'en_US');
echo $date1, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"

$date2 = new Zend_Date('Feb 31, 2007', Zend_Date::DATES, 'en_US');
echo $date2, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"

// strictly restricts interpretation to specified format
$date3 = new Zend_Date('Feb 31, 2007', 'MM.dd.yyyy');
echo $date3, "\n"; // outputs "Mar 3, 2007 12:00:00 AM"
]]></programlisting>
        </example>

        <para>
            If the optional
            <varname>$locale</varname>
            parameter is provided, then the
            <varname>$locale</varname>
            disambiguates the
            <varname>$date</varname>
            operand by
            replacing month and weekday names for string
            <varname>$date</varname>
            operands, and even
            parsing date strings expressed according to the conventions of that
            locale (see
            <link linkend="zend.locale.date.normalize">Zend_Locale_Format::getDate()</link>
            ). The
            automatic normalization of localized
            <varname>$date</varname>
            operands of a string type
            occurs when
            <varname>$part</varname>
            is one of the
            <constant>Zend_Date::DATE</constant>
            *
            or
            <constant>Zend_Date::TIME</constant>
            * constants. The locale identifies which language
            should be used to parse month names and
            weekday names, if the
            <varname>$date</varname>
            is a string containing a date. If there is no
            <varname>$date</varname>
            input parameter,
            then the
            <varname>$locale</varname>
            parameter specifies the locale to use for localizing
            output (e.g. the date format for a
            string representation). Note that the
            <varname>$date</varname>
            input parameter might actually have a type name instead
            (e.g.
            <varname>$hour</varname>
            for
            <methodname>addHour()</methodname>
            ), although that
            does not prevent the use of
            <classname>Zend_Date</classname>
            objects as arguments for
            that parameter. If no
            <varname>$locale</varname>
            was specified, then the locale of the
            current object is used to interpret
            <varname>$date</varname>
            , or select the localized
            format for output.
        </para>

        <para>
            Since Zend Framework 1.7.0
            <classname>Zend_Date</classname>
            does also support the
            usage of an application wide locale. You can simply set a
            <classname>Zend_Locale</classname>
            instance to the registry like shown below. With
            this notation you can forget about
            setting the locale manually with each instance when
            you want to use the same locale
            multiple times.
        </para>

        <programlisting language="php"><![CDATA[
// in your bootstrap file
$locale = new Zend_Locale('de_AT');
Zend_Registry::set('Zend_Locale', $locale);

// somewhere in your application
$date = new Zend_Date('31.Feb.2007');
]]></programlisting>
    </sect2>

    <sect2 id="id.date.basic">
        <title>Basic Zend_Date Operations Common to Many Date Parts</title>

        <para>
            The methods
            <methodname>add()</methodname>
            ,
            <methodname>sub()</methodname>
            ,
            <methodname>compare()</methodname>
            ,
            <methodname>get()</methodname>
            , and
            <methodname>set()</methodname>
            operate generically on dates. In each case, the
            operation is performed on the date held
            in the instance object. The
            <varname>$date</varname>
            operand is required for all of these methods, except
            <methodname>get()</methodname>
            , and may be a
            <classname>Zend_Date</classname>
            instance object, a numeric string, or an integer. These methods assume
            <varname>$date</varname>
            is a timestamp, if it is not an object. However, the
            <varname>$part</varname>
            operand controls which logical part of the two dates are
            operated on, allowing operations
            on parts of the object's date, such as year or minute,
            even when
            <varname>$date</varname>
            contains a long form date string, such as, "December
            31, 2007 23:59:59". The result of
            the operation changes the date in the object, except
            for
            <methodname>compare()</methodname>
            , and
            <methodname>get()</methodname>
            .
        </para>

        <example id="zend.date.basic.example-1">
            <title>Operating on Parts of Dates</title>
            <programlisting language="php"><![CDATA[
$date = new Zend_Date(); // $date's timestamp === time()

// changes $date by adding 12 hours
$date->add('12', Zend_Date::HOUR);
print $date;
]]></programlisting>
        </example>

        <para>
            Convenience methods exist for each combination of the basic operations and several
            common date parts as shown in the tables below. These convenience methods help us lazy
            programmers avoid having to type out the
            <link linkend="zend.date.constants.list">date
                part constants</link>
            when using the general methods above. Conveniently, they are
            named by combining a prefix
            (name of a basic operation) with a suffix (type of date
            part), such as
            <methodname>addYear()</methodname>
            . In the list below, all combinations
            of "Date Parts" and "Basic Operations" exist. For
            example, the operation "add" exists
            for each of these date parts, including
            <methodname>addDay()</methodname>
            ,
            <methodname>addYear()</methodname>
            , etc.
        </para>

        <para>
            These convenience methods have the same equivalent functionality as the basic
            operation
            methods, but expect string and integer
            <varname>$date</varname>
            operands
            containing only the values representing the type indicated by the suffix of the
            convenience method. Thus, the names of these methods (e.g. "Year" or "Minute") identify
            the units of the
            <varname>$date</varname>
            operand, when
            <varname>$date</varname>
            is a
            string or integer.
        </para>

        <sect3 id="id.date.basic.parts">
            <title>List of Date Parts</title>

            <table id="id.date.basic.parts.table">
                <title>Date Parts</title>
                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Date Part</entry>
                            <entry>Explanation</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/Unix_Time">Timestamp</ulink>
                            </entry>
                            <entry>
                                UNIX timestamp, expressed in seconds elapsed since January 1st,
                                1970
                                00:00:00
                                <acronym>GMT</acronym>
                                .
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/Gregorian_calendar">Year</ulink>
                            </entry>
                            <entry>Gregorian calendar year (e.g. 2006)</entry>
                        </row>
                        <row>
                            <entry>
                                <ulink
                                    url="http://en.wikipedia.org/wiki/Month#Julian_and_Gregorian_calendars"
                                >Month</ulink>
                            </entry>
                            <entry> Gregorian calendar month (1-12, localized names supported)
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/24-hour_clock">24 hour
                                    clock</ulink>
                            </entry>
                            <entry> Hours of the day (0-23) denote the hours elapsed, since the
                                start of the day. </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/Minute">minute</ulink>
                            </entry>
                            <entry> Minutes of the hour (0-59) denote minutes elapsed, since the
                                start of the hour. </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/Second">Second</ulink>
                            </entry>
                            <entry> Seconds of the minute (0-59) denote the elapsed seconds, since
                                the start of the minute. </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/Millisecond">millisecond</ulink>
                            </entry>
                            <entry>
                                Milliseconds denote thousandths of a second (0-999).
                                <classname>Zend_Date</classname>
                                supports two additional methods
                                for working with time units smaller
                                than seconds. By default,
                                <classname>Zend_Date</classname>
                                instances use a precision
                                defaulting to milliseconds, as seen using
                                <methodname>getFractionalPrecision()</methodname>
                                . To change the
                                precision use
                                <methodname>setFractionalPrecision($precision)</methodname>
                                .
                                However, precision is limited practically to microseconds, since
                                <classname>Zend_Date</classname>
                                uses
                                <ulink url="http://php.net/microtime">microtime()</ulink>
                                .
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/Day">Day</ulink>
                            </entry>
                            <entry>
                                <constant>Zend_Date::DAY_SHORT</constant>
                                is extracted from
                                <varname>$date</varname>
                                if the
                                <varname>$date</varname>
                                operand
                                is an instance of
                                <classname>Zend_Date</classname>
                                or a numeric
                                string. Otherwise, an attempt is made to extract the day
                                according
                                to the conventions documented for these constants:
                                <constant>Zend_Date::WEEKDAY_NARROW</constant>
                                ,
                                <constant>Zend_Date::WEEKDAY_NAME</constant>
                                ,
                                <constant>Zend_Date::WEEKDAY_SHORT</constant>
                                ,
                                <constant>Zend_Date::WEEKDAY</constant>
                                (Gregorian calendar
                                assumed)
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/Week">Week</ulink>
                            </entry>
                            <entry>
                                <constant>Zend_Date::WEEK</constant>
                                is extracted from
                                <varname>$date</varname>
                                if the
                                <varname>$date</varname>
                                operand
                                is an instance of
                                <classname>Zend_Date</classname>
                                or a numeric
                                string. Otherwise an exception is raised. (Gregorian
                                calendar
                                assumed)
                            </entry>
                        </row>
                        <row>
                            <entry>Date</entry>
                            <entry>
                                <constant>Zend_Date::DAY_MEDIUM</constant>
                                is extracted from
                                <varname>$date</varname>
                                if the
                                <varname>$date</varname>
                                operand
                                is an instance of
                                <classname>Zend_Date</classname>
                                . Otherwise, an
                                attempt is made to normalize the
                                <varname>$date</varname>
                                string
                                into a
                                <constant>Zend_Date::DATE_MEDIUM</constant>
                                formatted date.
                                The format of
                                <constant>Zend_Date::DAY_MEDIUM</constant>
                                depends on
                                the object's locale.
                            </entry>
                        </row>
                        <row>
                            <entry>Weekday</entry>
                            <entry>
                                Weekdays are represented numerically as 0 (for Sunday) through 6
                                (for Saturday).
                                <constant>Zend_Date::WEEKDAY_DIGIT</constant>
                                is
                                extracted from
                                <varname>$date</varname>
                                , if the
                                <varname>$date</varname>
                                operand is an instance of
                                <classname>Zend_Date</classname>
                                or a numeric string. Otherwise,
                                an attempt is made to extract the day
                                according to the conventions
                                documented for these constants:
                                <constant>Zend_Date::WEEKDAY_NARROW</constant>
                                ,
                                <constant>Zend_Date::WEEKDAY_NAME</constant>
                                ,
                                <constant>Zend_Date::WEEKDAY_SHORT</constant>
                                ,
                                <constant>Zend_Date::WEEKDAY</constant>
                                (Gregorian calendar
                                assumed)
                            </entry>
                        </row>
                        <row>
                            <entry>DayOfYear</entry>
                            <entry>
                                In
                                <classname>Zend_Date</classname>
                                , the day of the year
                                represents the number of calendar days elapsed
                                since the start of
                                the year (0-365). As with other units above,
                                fractions are rounded
                                down to the nearest whole number. (Gregorian
                                calendar assumed)
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://www.faqs.org/rfcs/rfc822.html">Arpa</ulink>
                            </entry>
                            <entry>
                                Arpa dates (i.e.
                                <acronym>RFC</acronym>
                                822 formatted dates) are
                                supported. Output uses either a "GMT" or
                                "Local differential
                                hours+min" format (see section 5 of
                                <acronym>RFC</acronym>
                                822).
                                Before
                                <acronym>PHP</acronym>
                                5.2.2, using the
                                <constant>DATE_RFC822</constant>
                                constant with
                                <acronym>PHP</acronym>
                                date functions sometimes produces
                                <ulink url="http://bugs.php.net/bug.php?id=40308">incorrect
                                    results</ulink>
                                .
                                <classname>Zend_Date</classname>
                                's results are
                                correct. Example: Mon, 31 Dec 06 23:59:59
                                <acronym>GMT</acronym>
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <ulink url="http://en.wikipedia.org/wiki/ISO_8601">Iso</ulink>
                            </entry>
                            <entry>
                                Only complete
                                <acronym>ISO</acronym>
                                8601 dates are supported
                                for output. Example:
                                2009-02-14T00:31:30+01:00
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>

        <sect3 id="id.date.basic.operations">
            <title>List of Date Operations</title>

            <para>
                The basic operations below can be used instead of the convenience operations for
                specific date parts, if the
                <link linkend="zend.date.constants.list">appropriate
                    constant</link>
                is used for the
                <varname>$part</varname>
                parameter.
            </para>

            <table id="id.date.basic.operations.table">
                <title>Basic Operations</title>
                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Basic Operation</entry>
                            <entry>Explanation</entry>
                        </row>
                    </thead>
                    <tbody>
                        <row>
                            <entry>
                                <methodname>get()</methodname>
                            </entry>
                            <entry>
                                <para>
                                    <emphasis>
                                        <methodname>get($part = null, $locale = null)</methodname>
                                    </emphasis>
                                </para>
                                <para>
                                    Use
                                    <methodname>get($part)</methodname>
                                    to retrieve the date
                                    <varname>$part</varname>
                                    of this object's date localized to
                                    <varname>$locale</varname>
                                    as a formatted string or integer.
                                    When using the BCMath
                                    extension, numeric strings might be
                                    returned instead of integers
                                    for large values.
                                </para>

                                <note>
                                    <title>Behaviour of get()</title>

                                    <para>
                                        Unlike
                                        <methodname>get()</methodname>
                                        , the other get*()
                                        convenience methods only return instances
                                        of
                                        <classname>Zend_Date</classname>
                                        containing a date
                                        representing the selected or computed date
                                        or time.
                                    </para>
                                </note>
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <methodname>set()</methodname>
                            </entry>
                            <entry>
                                <para>
                                    <emphasis>
                                        <methodname>set($date, $part = null, $locale =
                                            null)</methodname>
                                    </emphasis>
                                </para>
                                <para>
                                    Sets the
                                    <varname>$part</varname>
                                    of the current object to the
                                    corresponding value for that part
                                    found in the input
                                    <varname>$date</varname>
                                    having a locale
                                    <varname>$locale</varname>
                                    .
                                </para>
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <methodname>add()</methodname>
                            </entry>
                            <entry>
                                <para>
                                    <emphasis>
                                        <methodname>add($date, $part = null, $locale =
                                            null)</methodname>
                                    </emphasis>
                                </para>
                                <para>
                                    Adds the
                                    <varname>$part</varname>
                                    of
                                    <varname>$date</varname>
                                    having a locale
                                    <varname>$locale</varname>
                                    to the current
                                    object's date.
                                </para>
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <methodname>sub()</methodname>
                            </entry>
                            <entry>
                                <para>
                                    <emphasis>
                                        <methodname>sub($date, $part = null, $locale =
                                            null)</methodname>
                                    </emphasis>
                                </para>
                                <para>
                                    Subtracts the
                                    <varname>$part</varname>
                                    of
                                    <varname>$date</varname>
                                    having a locale
                                    <varname>$locale</varname>
                                    from the current object's date.
                                </para>
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <methodname>copyPart()</methodname>
                            </entry>
                            <entry>
                                <para>
                                    <emphasis>
                                        <methodname>copyPart($part, $locale = null)</methodname>
                                    </emphasis>
                                </para>
                                <para>
                                    Returns a cloned object, with only
                                    <varname>$part</varname>
                                    of
                                    the object's date copied to the clone, with the clone have its
                                    locale arbitrarily set to
                                    <varname>$locale</varname>
                                    (if
                                    specified).
                                </para>
                            </entry>
                        </row>
                        <row>
                            <entry>
                                <methodname>compare()</methodname>
                            </entry>
                            <entry>
                                <para>
                                    <emphasis>
                                        <methodname>compare($date, $part = null, $locale =
                                            null)</methodname>
                                    </emphasis>
                                </para>
                                <para>
                                    compares
                                    <varname>$part</varname>
                                    of
                                    <varname>$date</varname>
                                    to this object's timestamp, returning 0 if they are equal, 1 if
                                    this object's part was more recent than
                                    <varname>$date</varname>
                                    's part, otherwise -1.
                                </para>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </sect3>
    </sect2>

    <sect2 id="zend.date.others.comparison">
        <title>Comparing Dates</title>

        <para>
            The following basic operations do not have corresponding convenience methods for the
            date parts listed in
            <link linkend="zend.date.overview">Zend_Date API
                Overview</link>
            .
        </para>

        <table id="zend.date.others.comparison.table">
            <title>Date Comparison Methods</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Method</entry>
                        <entry>Explanation</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>
                            <methodname>equals()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>equals($date, $part = null, $locale =
                                        null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                returns
                                <constant>TRUE</constant>
                                , if
                                <varname>$part</varname>
                                of
                                <varname>$date</varname>
                                having locale
                                <varname>$locale</varname>
                                is the same as this object's date
                                <varname>$part</varname>
                                , otherwise
                                <constant>FALSE</constant>
                            </para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>isEarlier()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>isEarlier($date, $part = null, $locale =
                                        null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                returns
                                <constant>TRUE</constant>
                                , if
                                <varname>$part</varname>
                                of
                                this object's date is earlier than
                                <varname>$part</varname>
                                of
                                <varname>$date</varname>
                                having a locale
                                <varname>$locale</varname>
                            </para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>isLater()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>isLater($date, $part = null, $locale =
                                        null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                returns
                                <constant>TRUE</constant>
                                , if
                                <varname>$part</varname>
                                of
                                this object's date is later than
                                <varname>$part</varname>
                                of
                                <varname>$date</varname>
                                having a locale
                                <varname>$locale</varname>
                            </para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>isToday()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>isToday()</methodname>
                                </emphasis>
                            </para>
                            <para>Tests if today's year, month, and day match this object's date
                                value, using this object's timezone.</para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>isTomorrow()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>isTomorrow()</methodname>
                                </emphasis>
                            </para>
                            <para>Tests if tomorrow's year, month, and day match this object's date
                                value, using this object's timezone.</para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>isYesterday()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>isYesterday()</methodname>
                                </emphasis>
                            </para>
                            <para>Tests if yesterday's year, month, and day match this object's date
                                value, using this object's timezone.</para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>isLeapYear()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>isLeapYear()</methodname>
                                </emphasis>
                            </para>
                            <para>
                                Use
                                <methodname>isLeapYear()</methodname>
                                to determine if the
                                current object is a leap year, or use
                                <methodname>Zend_Date::checkLeapYear($year)</methodname>
                                to
                                check
                                <varname>$year</varname>
                                , which can be a string, integer, or
                                instance of
                                <classname>Zend_Date</classname>
                                . Is the year a leap
                                year?
                            </para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>isDate()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>isDate($date, $format = null, $locale =
                                        null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                This method checks if a given date is a real date and returns
                                <constant>TRUE</constant>
                                if all checks are ok. It works like
                                <acronym>PHP</acronym>
                                's
                                <methodname>checkdate()</methodname>
                                function but can also check for localized month names and for dates
                                extending the range of
                                <methodname>checkdate()</methodname>
                            </para>
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.date.others.gettingparts">
        <title>Getting Dates and Date Parts</title>

        <para>
            Several methods support retrieving values related to a
            <classname>Zend_Date</classname>
            instance.
        </para>

        <table id="zend.date.others.gettingparts.table">
            <title>Date Output Methods</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Method</entry>
                        <entry>Explanation</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>
                            <methodname>toString()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>toString($format = null, $locale =
                                        null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                Invoke directly or via the magic method
                                <methodname>__toString()</methodname>
                                . The
                                <methodname>toString()</methodname>
                                method automatically formats
                                the date object's value according to the
                                conventions of the object's
                                locale, or an optionally specified
                                <varname>$locale</varname>
                                . For a
                                list of supported format codes, see
                                <link linkend="zend.date.constants.selfdefinedformats">Self-Defined
                                    OUTPUT Formats with ISO</link>
                                .
                            </para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>toArray()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>toArray()</methodname>
                                </emphasis>
                            </para>
                            <para>
                                Returns an array representation of the selected date according to
                                the conventions of the object's locale. The returned array is
                                equivalent to
                                <acronym>PHP</acronym>
                                's
                                <ulink url="http://php.net/getdate">getdate()</ulink>
                                function and
                                includes:
                            </para>

                            <itemizedlist>
                                <listitem>
                                    <para>
                                        Number of day as '
                                        <emphasis>day</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::DAY_SHORT</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Number of month as '
                                        <emphasis>month</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::MONTH_SHORT</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Year as '
                                        <emphasis>year</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::YEAR</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Hour as '
                                        <emphasis>hour</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::HOUR_SHORT</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Minute as '
                                        <emphasis>minute</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::MINUTE_SHORT</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Second as '
                                        <emphasis>second</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::SECOND_SHORT</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Abbreviated timezone as '
                                        <emphasis>timezone</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::TIMEZONE</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Unix timestamp as '
                                        <emphasis>timestamp</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::TIMESTAMP</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Number of weekday as '
                                        <emphasis>weekday</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::WEEKDAY_DIGIT</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Day of year as '
                                        <emphasis>dayofyear</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::DAY_OF_YEAR</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Week as '
                                        <emphasis>week</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::WEEK</constant>
                                        )
                                    </para>
                                </listitem>

                                <listitem>
                                    <para>
                                        Delay of timezone to
                                        <acronym>GMT</acronym>
                                        as
                                        '
                                        <emphasis>gmtsecs</emphasis>
                                        '
                                        (
                                        <constant>Zend_Date::GMT_SECS</constant>
                                        )
                                    </para>
                                </listitem>
                            </itemizedlist>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>toValue()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>toValue($part = null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                Returns an integer representation of the selected date
                                <varname>$part</varname>
                                according to the conventions of the
                                object's locale. Returns
                                <constant>FALSE</constant>
                                when
                                <varname>$part</varname>
                                selects a non-numeric value, such as
                                <constant>Zend_Date::MONTH_NAME_SHORT</constant>
                                .
                            </para>

                            <note>
                                <title>Limitation of toValue()</title>

                                <para>
                                    This method calls
                                    <link linkend="id.date.basic.operations">
                                        <methodname>get()</methodname>
                                    </link>
                                    and casts the result to a
                                    <acronym>PHP</acronym>
                                    integer, which will give unpredictable results, if
                                    <methodname>get()</methodname>
                                    returns a numeric string
                                    containing a number too large for a
                                    <acronym>PHP</acronym>
                                    integer on your system. Use
                                    <methodname>get()</methodname>
                                    instead.
                                </para>
                            </note>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <link linkend="id.date.basic.operations">get()</link>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>get($part = null, $locale = null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                This method returns the
                                <varname>$part</varname>
                                of object's date
                                localized to
                                <varname>$locale</varname>
                                as a formatted string or
                                integer. See
                                <link linkend="id.date.basic.operations">get()</link>
                                for more information.
                            </para>
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <methodname>now()</methodname>
                        </entry>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>now($locale = null)</methodname>
                                </emphasis>
                            </para>
                            <para>
                                This convenience function is equivalent to
                                <command>new
                                    Zend_Date()</command>
                                . It returns the current date as a
                                <classname>Zend_Date</classname>
                                object, having
                                <varname>$locale</varname>
                            </para>
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.date.others.fractions">
        <title>Working with Fractions of Seconds</title>

        <para>
            Several methods support retrieving values related to a
            <classname>Zend_Date</classname>
            instance.
        </para>

        <table id="zend.date.others.fractions.table">
            <title>Date Output Methods</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Method</entry>
                        <entry>Explanation</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>getFractionalPrecision()</methodname>
                                </emphasis>
                            </para>
                        </entry>
                        <entry>Return the precision of the part seconds</entry>
                    </row>
                    <row>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>setFractionalPrecision()</methodname>
                                </emphasis>
                            </para>
                        </entry>
                        <entry>Set the precision of the part seconds</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>

    <sect2 id="zend.date.other.sun">
        <title>Sunrise / Sunset</title>

        <para>Three methods provide access to geographically localized information about the Sun,
            including the time of sunrise and sunset.</para>

        <table id="zend.date.other.sun.table">
            <title>Miscellaneous Methods</title>
            <tgroup cols="2">
                <thead>
                    <row>
                        <entry>Method</entry>
                        <entry>Explanation</entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>getSunrise($location)</methodname>
                                </emphasis>
                            </para>
                        </entry>
                        <entry>Return the date's time of sunrise</entry>
                    </row>
                    <row>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>getSunset($location)</methodname>
                                </emphasis>
                            </para>
                        </entry>
                        <entry>Return the date's time of sunset</entry>
                    </row>
                    <row>
                        <entry>
                            <para>
                                <emphasis>
                                    <methodname>getSunInfo($location)</methodname>
                                </emphasis>
                            </para>
                        </entry>
                        <entry>Return an array with the date's sun dates</entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
    </sect2>
</sect1>