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" 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".

  Note: There is no "language" or "locale" parameter.

  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.

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

  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.

• 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".

"DATETIME::INCOMPLETE" METHODS

• get

  $kin = $dti->get( 'kin' );  # a Mayan time

  Return the datetime field value, or undef.

• has

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

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

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

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

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_month, mday
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
min, sec
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
truncate
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.

The new method doesn't have the 'language' parameter.

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/