/ 
DateTime-Incomplete-0.00_05
River stage two • 7 direct dependents • 12 total dependents
/ DateTime::Incomplete

NAME

DateTime::Incomplete - The partial date & time thing

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.

Such values are generated by expressions like '10:30', '2003', and 'dec-14'.

"DATETIME" METHODS

  • 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 a "time_zone", a "locale" parameter, and a "base" parameter.

    The "base" parameter is used as a default base datetime in the "to_datetime" method. It is also used for validating inputs to the "set" method. There is no default "base".

    new without parameters creates a completely undefined datetime:

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

    The parameters can be explicitly undefined:

    my $dti = DateTime::Incomplete->new( year => 2003, day => undef );

  • set

    Use this to define or undefine a datetime field:

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

  • clone

    Creates a new object with the same datetime.

  • 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().

    Incomplete dates don't know the "local time" concept: If the new time zone's offset is different from the old time zone, no local time adjust is made.

  • year, month, day, hour, minute, second, nanosecond

    Return the field value, or undef.

    These values can also be accessed using the methods: mon, day_of_month, mday, min, sec.

  • has_year, has_month, has_day, has_hour, has_minute, has_second, has_nanosecond, has_time_zone, has_locale

    Returns 1 if the value is defined; otherwise it returns 0.

  • time_zone

    This returns the DateTime::TimeZone object for the datetime object, or undef.

  • locale

    This returns the DateTime::Locale object for the datetime object, or undef.

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

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

  • is_finite, is_infinite

    These methods allow you to distinguish normal datetime objects from infinite ones. Infinite datetime objects are documented in DateTime::Infinite.

    Incomplete dates are not "Infinite".

  • truncate( to => ... )

    This method allows you to define some of the 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 day becomes 1, and the hour, minute, and second all become 0.

"DATETIME::INCOMPLETE" METHODS

  • set_base

    $dti->set_base( $dt );

    The "base" parameter is used as a default base datetime in the "to_datetime" method. It is also used for validating inputs to the "set" method.

    The base object must use the year/month/day system. Most calendars use this system: Gregorian (DateTime), Julian, and others.

  • base

    Returns the base datetime value, or undef.

  • is_undef

    Returns true if the datetime is completely undefined.

  • to_datetime

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

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

    Returns a "complete" datetime.

    The resulting datetime is in the same Calendar as base.

    The following example creates a Julian Calendar date, within year 1534:

     $dtj = DateTime::Calendar::Julian->new( ... );
 $dti = DateTime::Incomplete->new( year => 1534 );
 $dtj2 = $dti->to_datetime( base => $dtj );

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

    This method may die if it results in a datetime that doesn't exist.

  • to_recurrence

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

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

    Those recurrences are DateTime::Set objects:

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

    Recurrence generation has only been tested with Gregorian dates so far.

    This method will die if the DateTime::Event::Recurrence package is not installed.

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

    2003-xx-xxTxx:xx:xx

  • contains

    $bool = $dti->contains( $dt );

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

    Note: the incomplete-datetime time-zone value is ignored, that is, the value of "local time" is compared. This may lead to unexpected results if the time zone field is set.

    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 );

    next returns the first complete date after or equal to the given datetime.

    previous returns the first complete date before or equal to the given datetime.

    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 in 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).

  • get

    $month = $dti->get( 'month' );

    Returns the datetime field value, or undef.

    You may want to use get_month instead.

  • has

    $isfrac = $dti->has( 'nanosecond' );

    Returns 1 if the datetime field value is defined; otherwise it returns 0. You may want to use has_nanosecond instead.

DIFFERENCES BETWEEN "DATETIME" AND "DATETIME::INCOMPLETE"

These methods are not implemented in DateTime::Incomplete (some will be implemented in next versions):

from_epoch, epoch, hires_epoch
now, today
from_object
last_day_of_month
from_day_of_year
ce_year, era, year_with_era
month_name, month_abbr
day_of_week, wday, dow
day_name, day_abbr
day_of_year, doy
quarter, day_of_quarter, doq
weekday_of_month
hour_1, hour_12, hour_12_0
fractional_second, millisecond, microsecond
is_leap_year
week, week_year, week_number, week_of_month
jd, mjd
offset, is_dst, time_zone_short_name
strftime
utc_rd_values, utc_rd_as_seconds, local_rd_as_seconds
add_duration, add, subtract_duration, subtract, subtract_datetime

There are no class methods. The following are not implemented:

DefaultLanguage
compare, compare_ignore_floating

There are no "Storable" class hooks.

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>, 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/