DateTime::Incomplete - An incomplete datetime, like January 5
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
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.
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.
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.
Most methods provided by this class are designed to emulate the
behavior of DateTime.pm whenever possible.
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();
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.
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.
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.
This class method is equivalent to DateTime->now.
It creates a new DateTime::Incomplete object with all fields
defined.
now(), but it leaves hour,
minute, second and nanosecond undefined.
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.
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_date = $dti->has( 'year', 'month', 'day' );
Returns a boolean value indicating whether all fields in the argument list are defined.
@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.
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.
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.
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
The following DateTime.pm methods are not implemented in
DateTime::Incomplete, though some of them may be implemented in
future versions:
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.
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.
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 objects also have a number of methods unique
to this class.
undef if the object has none.
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
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.
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.
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.
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
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.
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
$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 for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.
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 (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.
datetime@perl.org mailing list
http://datetime.perl.org/