NAME

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

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

ERROR HANDLING

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

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

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

"DATETIME::INCOMPLETE" METHODS

• 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

AUTHORS

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

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

SEE ALSO

http://datetime.perl.org/