view release on metacpan or  search on metacpan

lib/DateTime/Incomplete.pm  view on Meta::CPAN

    return join( '|', @data ), [$self->base];
}

sub STORABLE_thaw
{
    my ( $self, $cloning, $data, $base ) = @_;
    my %data = map { split /:/ } split /\|/, $data;
    my $locale = delete $data{locale};
    my $tz =     delete $data{tz};
    $self->{has} = \%data;
    $self->set_time_zone( $tz );
    $self->set( locale => $locale );
    $self->{base} = $base->[0];
    return $self;
}

1;

__END__

=head1 NAME

DateTime::Incomplete - An incomplete datetime, like January 5

=head1 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


=head1 DESCRIPTION

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.

=head1 ERROR HANDLING

Constructor and mutator methods (such as C<new> and C<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 C<set_base> method.

Accessor methods (such as C<day()>) will return either a value or
C<undef>, but will never die.

=head1 THE "BASE" DATETIME

A C<DateTime::Incomplete> object can have a "base" C<DateTime.pm>
object.  This object is used as a default datetime in the
C<to_datetime()> method, and it also used to validate inputs to the
C<set()> method.

The base object must use the year/month/day system.  Most calendars
use this system including Gregorian (C<DateTime>) and Julian.  Note
that this module has not been well tested with base objects from
classes other than C<DateTime.pm> class.

By default, newly created C<DateTime::Incomplete> objects have no
base.

=head1 DATETIME-LIKE METHODS

Most methods provided by this class are designed to emulate the
behavior of C<DateTime.pm> whenever possible.

=over

=item * 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 C<undef>.

Calling the C<new()> method without parameters creates a completely
undefined datetime:

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

=item * from_day_of_year( ... )

This constructor takes the same arguments as can be given to the
C<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 C<DateTime::Incomplete> object with all date fields
defined, but with the time fields (hour, minute, etc.) set to undef.

=item * from_object( object => $object, ... )

This class method can be used to construct a new
C<DateTime::Incomplete> object from any object that implements the
C<utc_rd_values()> method.  All C<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 C<time_zone()> method, that
is used to set the time zone.  Otherwise UTC is used.

It creates a C<DateTime::Incomplete> object with all fields defined.

=item * from_epoch( ... )

This class method can be used to construct a new
C<DateTime::Incomplete> object from an epoch time instead of
components.  Just as with the C<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 C<Time::HiRes>.

It creates a C<DateTime::Incomplete> object with all fields defined.

=item * now( ... )

This class method is equivalent to C<< DateTime->now >>.

It creates a new C<DateTime::Incomplete> object with all fields
defined.

=item * today( ... )

This class method is equivalent to C<now()>, but it leaves hour,
minute, second and nanosecond undefined.

=item * clone

Creates a new object with the same information as the object this
method is called on.

=back

=head2 "Get" Methods

=over 4

=item * year

=item * month

=item * day

=item * hour

=item * minute

=item * second

=item * nanosecond

=item * time_zone

=item * locale