Provided by: libdatetime-incomplete-perl_0.08-1_all bug

NAME

       DateTime::Incomplete - An incomplete datetime, like January 5

SYNOPSIS

         my $dti = DateTime::Incomplete->new( year => 2003 );
         # 2003-xx-xx
         $dti->set( month => 12 );
         # 2003-12-xx
         $dt = $dti->to_datetime( base => DateTime->now );
         # 2003-12-19T16:54:33

DESCRIPTION

       DateTime::Incomplete is a class for representing partial dates and times.

       These are actually encountered relatively frequently.  For example, a birthday is commonly
       given as a month and day, without a year.

ERROR HANDLING

       Constructor and mutator methods (such as "new" and "set") will die if there is an attempt
       to set the datetime to an invalid value.

       Invalid values are detected by setting the appropriate fields of a "base" datetime object.
       See the "set_base" method.

       Accessor methods (such as "day()") will return either a value or "undef", but will never
       die.

THE "BASE" DATETIME

       A "DateTime::Incomplete" object can have a "base" "DateTime.pm" object.  This object is
       used as a default datetime in the "to_datetime()" method, and it also used to validate
       inputs to the "set()" method.

       The base object must use the year/month/day system.  Most calendars use this system
       including Gregorian ("DateTime") and Julian.  Note that this module has not been well
       tested with base objects from classes other than "DateTime.pm" class.

       By default, newly created "DateTime::Incomplete" objects have no base.

DATETIME-LIKE METHODS

       Most methods provided by this class are designed to emulate the behavior of "DateTime.pm"
       whenever possible.

       ·   new()

           Creates a new incomplete date:

             my $dti = DateTime::Incomplete->new( year => 2003 );
             # 2003-xx-xx

           This class method accepts parameters for each date and time component: "year",
           "month", "day", "hour", "minute", "second", "nanosecond".  Additionally, it accepts
           "time_zone", "locale", and "base" parameters.

           Any parameters not given default to "undef".

           Calling the "new()" method without parameters creates a completely undefined datetime:

             my $dti = DateTime::Incomplete->new();

       ·   from_day_of_year( ... )

           This constructor takes the same arguments as can be given to the "new()" method,
           except that it does not accept a "month" or "day" argument.  Instead, it requires both
           "year" and "day_of_year".  The day of year must be between 1 and 366, and 366 is only
           allowed for leap years.

           It creates a "DateTime::Incomplete" object with all date fields defined, but with the
           time fields (hour, minute, etc.) set to undef.

       ·   from_object( object => $object, ... )

           This class method can be used to construct a new "DateTime::Incomplete" object from
           any object that implements the "utc_rd_values()" method.  All "DateTime::Calendar"
           modules must implement this method in order to provide cross-calendar compatibility.
           This method accepts a "locale" parameter.

           If the object passed to this method has a "time_zone()" method, that is used to set
           the time zone.  Otherwise UTC is used.

           It creates a "DateTime::Incomplete" object with all fields defined.

       ·   from_epoch( ... )

           This class method can be used to construct a new "DateTime::Incomplete" object from an
           epoch time instead of components.  Just as with the "new()" method, it accepts
           "time_zone" and "locale" parameters.

           If the epoch value is not an integer, the part after the decimal will be converted to
           nanoseconds.  This is done in order to be compatible with "Time::HiRes".

           It creates a "DateTime::Incomplete" object with all fields defined.

       ·   now( ... )

           This class method is equivalent to "DateTime->now".

           It creates a new "DateTime::Incomplete" object with all fields defined.

       ·   today( ... )

           This class method is equivalent to "now()", but it leaves hour, minute, second and
           nanosecond undefined.

       ·   clone

           Creates a new object with the same information as the object this method is called on.

   "Get" Methods
       ·   year

       ·   month

       ·   day

       ·   hour

       ·   minute

       ·   second

       ·   nanosecond

       ·   time_zone

       ·   locale

           These methods returns the field value for the object, or "undef".

           These values can also be accessed using the same alias methods available in
           "DateTime.pm", such as "mon()", "mday()", etc.

       ·   has_year

       ·   has_month

       ·   has_day

       ·   has_hour

       ·   has_minute

       ·   has_second

       ·   has_nanosecond

       ·   has_time_zone

       ·   has_locale

       ·   has_date

       ·   has_time

           Returns a boolean value indicating whether the corresponding component is defined.

           "has_date" tests for year, month, and day.

           "has_time" tests for hour, minute, and second.

       ·   has

               $has_date = $dti->has( 'year', 'month', 'day' );

           Returns a boolean value indicating whether all fields in the argument list are
           defined.

       ·   defined_fields

               @fields = $dti->defined_fields;   # list of field names

           Returns a list containing the names of the fields that are defined.

           The list order is: year, month, day, hour, minute, second, nanosecond, time_zone,
           locale.

       ·   datetime, ymd, date, hms, time, iso8601, mdy, dmy

           These are equivalent to DateTime stringification methods with the same name, except
           that the undefined fields are replaced by 'xx' or 'xxxx' as appropriate.

       ·   epoch

       ·   hires_epoch

       ·   is_dst

       ·   utc_rd_values

       ·   utc_rd_as_seconds

               my $epoch = $dti->epoch( base => $dt );

           These methods are equivalent to the "DateTime" methods with the same name.

           They all accept a "base" argument to use in order to calculate the method's return
           values.

           If no "base" argument is given, then "today" is used.

       ·   is_finite, is_infinite

           Incomplete dates are always "finite".

       ·   strftime( $format, ... )

           This method implements functionality similar to the "strftime()" method in C.
           However, if given multiple format strings, then it will return multiple scalars, one
           for each format string.

           See the "strftime Specifiers" section in the "DateTime.pm" documentation for a list of
           all possible format specifiers.

           Undefined fields are replaced by 'xx' or 'xxxx' as appropriate.

           The specification %s (epoch) is calculated using "today" as the base date, unless the
           object has a base datetime set.

       Computed Values

       All other accessors, such as "day_of_week()", or "week_year()" are computed from the base
       values for a datetime.  When these methods are called, they return the requested
       information if there is enough data to compute them, otherwise they return "undef"

       Unimplemented Methods

       The following "DateTime.pm" methods are not implemented in "DateTime::Incomplete", though
       some of them may be implemented in future versions:

       ·   add_duration

       ·   add

       ·   subtract_duration

       ·   subtract

       ·   subtract_datetime

       ·   subtract_datetime_absolute

       ·   delta_md

       ·   delta_days

       ·   delta_ms

       ·   compare

       ·   compare_ignore_floating

       ·   DefaultLanguage

   "Set" Methods
       ·   set

           Use this to set or undefine a datetime field:

             $dti->set( month => 12 );
             $dti->set( day => 24 );
             $dti->set( day => undef );

           This method takes the same arguments as the "set()" method in "DateTime.pm", but it
           can accept "undef" for any value.

       ·   set_time_zone

           This method accepts either a time zone object or a string that can be passed as the
           "name" parameter to "DateTime::TimeZone->new()".

           Unlike with "DateTime.pm", if the new time zone's offset is different from the
           previous time zone, no local time adjustment is made.

           You can remove time zone information by calling this method with the value "undef".

       ·   truncate( to => ... )

           This method allows you to reset some of the local time components in the object to
           their "zero" values.  The "to" parameter is used to specify which values to truncate,
           and it may be one of "year", "month", "day", "hour", "minute", or "second".  For
           example, if "month" is specified, then the local day becomes 1, and the hour, minute,
           and second all become 0.

           Note that the "to" parameter cannot be "week".

"DATETIME::INCOMPLETE" METHODS

       "DateTime::Incomplete" objects also have a number of methods unique to this class.

       ·   base

           Returns the base datetime value, or "undef" if the object has none.

       ·   has_base

           Returns a boolean value indicating whether or not the object has a base datetime set.

       ·   is_undef

           Returns true if the datetime is completely undefined.

       ·   can_be_datetime

           Returns true if the datetime has enough information to be converted to a proper
           DateTime object.

           The year field must be valid, followed by a sequence of valid fields.

           Examples:

             Can be datetime:
             2003-xx-xxTxx:xx:xx
             2003-10-xxTxx:xx:xx
             2003-10-13Txx:xx:xx

             Can not be datetime:
             2003-10-13Txx:xx:30
             xxxx-10-13Txx:xx:30

       ·   set_base

           Sets the base datetime object for the "DateTime::Incomplete" object.

           The default value for "base" is "undef", which means no validation is made on input.

       ·   to_datetime

           This method takes an optional "base" parameter and returns a "complete" datetime.

             $dt = $dti->to_datetime( base => DateTime->now );

             $dti->set_base( DateTime->now );
             $dt = $dti->to_datetime;

           The resulting datetime can be either before of after the given base datetime. No
           adjustments are made, besides setting the missing fields.

           This method will use "today" if the object has no base datetime set and none is given
           as an argument.

           This method may die if it results in a datetime that doesn't actually exist, such as
           February 30, for example.

           The fields in the resulting datetime are set in this order: locale, time_zone,
           nanosecond, second, minute, hour, day, month, year.

       ·   to_recurrence

           This method generates the set of all possible datetimes that fit into an incomplete
           datetime definition.

             $dti = DateTime::Incomplete->new( month => 12, day => 24 );
             $dtset1 = $dti->to_recurrence;
             # Christmas recurrence, with _seconds_ resolution

             $dti->truncate( to => 'day' );
             $dtset2 = $dti->to_recurrence;
             # Christmas recurrence, with days resolution (hour/min/sec = 00:00:00)

           Those recurrences are "DateTime::Set" objects:

             $dt_next_xmas = $dti->to_recurrence->next( DateTime->today );

           Incomplete dates that have the year defined will generate finite sets.  This kind of
           set can take a lot of resources (RAM and CPU).  The following incomplete datetime
           would generate the set of all seconds in 2003:

             2003-xx-xxTxx:xx:xx

           Recurrences are generated with up to 1 second resolution.  The "nanosecond" value is
           ignored.

       ·   to_spanset

           This method generates the set of all possible spans that fit into an incomplete
           datetime definition.

             $dti = DateTime::Incomplete->new( month => 12, day => 24 );
             $dtset1 = $dti->to_spanset;
             # Christmas recurrence, from xxxx-12-24T00:00:00
             #                         to xxxx-12-25T00:00:00

       ·   start

       ·   end

       ·   to_span

           These methods view an incomplete datetime as a "time span".

           For example, the incomplete datetime "2003-xx-xxTxx:xx:xx" starts in
           "2003-01-01T00:00:00" and ends in "2004-01-01T00:00:00".

           The "to_span" method returns a "DateTime::Span" object.

           An incomplete datetime without an year spans "forever".  Start and end datetimes are
           "undef".

       ·   contains

           Returns a true value if the incomplete datetime range contains a given datetime value.

           For example:

             2003-xx-xx contains 2003-12-24
             2003-xx-xx does not contain 1999-12-14

       ·   previous / next / closest

             $dt2 = $dti->next( $dt );

           The "next()" returns the first complete date after or equal to the given datetime.

           The "previous()" returns the first complete date before or equal to the given
           datetime.

           The "closest()" returns the closest complete date (previous or next) to the given
           datetime.

           All of these methods return "undef" if there is no matching complete datetime.

           If no datetime is given, these methods use the "base" datetime.

           Note: The definition of "previous()" and "next()" is different from the methods of the
           same name in the "DateTime::Set" class.

           The datetimes are generated with 1 nanosecond precision. The last "time" value of a
           given day is 23:59:59.999999999 (for non leapsecond days).

SUPPORT

       Support for this module is provided via the datetime@perl.org email list.  See
       http://lists.perl.org/ for more details.

AUTHORS

       Flavio S. Glock <fglock[at]cpan.org>

       With Ben Bennett <fiji[at]ayup.limey.net>, Claus Farber <claus[at]xn--frber-gra.muc.de>,
       Dave Rolsky <autarch[at]urth.org>, Eugene Van Der Pijll <pijll[at]gmx.net>, Rick Measham
       <rick[at]isite.net.au>, and the DateTime team.

COPYRIGHT

       Copyright (c) 2003 Flavio S. Glock.  All rights reserved.  This program is free software;
       you can redistribute it and/or modify it under the same terms as Perl itself.

       The full text of the license can be found in the LICENSE file included with this module.

SEE ALSO

       datetime@perl.org mailing list

       http://datetime.perl.org/