view release on metacpan or  search on metacpan

lib/Date/Gregorian.pm  view on Meta::CPAN

I<get_string> returns a plaintext representation of the date represented
by an object.

=head2 set_string

I<set_string> restores a date value from a string returned by I<get_string>.
Strings of the form "YYYY-MM-DD" are also accepted.  The return value
is B<undef> if the syntax could not be recognized, otherwise the object.
I<set_string> handles values out of range the same way I<set_ymd> does.

=head2 DateTime interoperability

Date::Gregorian objects can be converted to DateTime objects and
vice versa.  From the view of DateTime, Date::Gregorian implements
a calendar operating in the floating timezone.  From the view of
Date::Gregorian, DateTime objects represent days in history in a
way suitable for object initialization.  Higher precision
components of DateTime objects, i.e. seconds and nanoseconds,
are preserved for reverse conversion but otherwise ignored.

=over 4

=item set_datetime

I<set_datetime> sets a Date::Gregorian object to the day represented
by a given DateTime object.  It returns the updated object.

=item from_object

I<from_object> is a DateTime compatible constructor.  Arguments are
mapped to a hash.  The value in the 'object' slot is taken to be a
DateTime object.  The result is a Date::Gregorian object.  Note
that Date::Gregorian is not a subclass of DateTime.

=item utc_rd_values

I<utc_rd_values> returns a list of rata die, seconds and nanoseconds
values corresponding to the date currently represented by the object.
Seconds and nanoseconds will default to zero if not initialized from
some DateTime object, and will be ignored by all other Date::Gregorian
methods.  In particular, date objects differing only in their hidden
seconds or nanoseconds values are considered equivalent by I<compare>.

=item truncate_to_day

I<truncate_to_day> drops seconds and nanoseconds from a date.  This
will have an effect on DateTime objects subsequently initialized
from that object.  Return value is the object.

=back

=head1 EXPORTS

By default, nothing is exported into the caller's namespace.  Optionally,
uppercase English weekday and month names may be imported individually
or using the C<:weekdays> and C<:months> tags.  These constants should be
preferred over their numerical values as documented above for readability
and in order not to depend on zero or one being the smallest value.

=head1 BUGS AND LIMITATIONS

This library works with integer arithmetic only.  Do not call methods
expecting days, months, years, etc. with non-integer values.

Bug reports and suggestions are always welcome
E<8212> please submit them through the CPAN RT,
L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Date-Gregorian>.

=head1 ROADMAP

The author intends to re-factor this library and combine its
algorithms with a better API, addressing these issues:

=over 4

=item *

Make date objects immutable.

=item *

Add time arguments to gmtime and localtime conversions.

=item *

Add more business calendars.

=item *

Name days and holidays.

=item *

Unify simple date arithmetic and business day arithmetic.

=item *

Comply more strictly with ISO 8601.  Notably, use 1-based weekday numbers.

=back

The new API will live in the Date::Gregorian namespace but use different
module names.  That way, old and new APIs can co-exist while downstream
applications prepare for the transition.

=head1 SEE ALSO

The sci.astro Calendar FAQ, L<Date::Calc>, L<Date::Gregorian::Business>,
L<DateTime>.

=head1 AUTHOR

Martin Becker C<< <becker-cpan-mp (at) cozap.com> >>

=head1 LICENSE AND COPYRIGHT

Copyright (c) 1999-2019 by Martin Becker, Blaubeuren.

This library is free software; you can distribute it and/or modify it
under the terms of the Artistic License 2.0 (see the LICENSE file).