/ 
DateTime-Incomplete-0.00_07
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 );

    It accepts the same arguments as the set() method in DateTime.pm.

  • 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 previous 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 the undefined fields are replaced by 'xx' or 'xxxx'.

  • 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 DateTime documentation for a list of all possible format specifiers.

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

    The specification %s (epoch) always returns xxxxxx.

  • week week_year week_number week_of_month day_name day_abbr day_of_week wday dow day_of_year doy quarter day_of_quarter doq weekday_of_month jd mjd is_leap_year ce_year era year_with_era last_day_of_month month_name month_abbr hour_1 hour_12 hour_12_0 fractional_second millisecond microsecond offset time_zone_short_name time_zone_long_name

    These are equivalent to DateTime methods with the same name, except that they will return undef if there is not enough data to compute the result.

    For example, is_leap_year returns undef if there is no year.

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

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

  • 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 DateTime::Incomplete object with all fields defined.

  • today( ... )

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

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

  • has_base

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

  • 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 );
$dtset1 = $dti->to_recurrence;   
# Christmas recurrence, with _seconds_ resolution

$dti->set( hour => 0, minute => 0, second => 0, nanosecond => 0 );
$dtset2 = $dti->to_recurrence;   
# Christmas recurrence, with days resolution (hour/min/sec = 00:00:00)

    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.

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

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

These methods are not implemented in DateTime::Incomplete. Some may be implemented in next versions:

epoch
hires_epoch
is_dst
utc_rd_values
utc_rd_as_seconds
local_rd_as_seconds

add_duration, add, subtract_duration, subtract, subtract_datetime

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/