Date::Manip - Date manipulation routines |
Date::Manip - Date manipulation routines
Date::Manip is a series of modules designed to make any common date/time operation easy to do. Operations such as comparing two times, determining a date a given amount of time from another, or parsing international times are all easily done. It deals with time as it is used in the Gregorian calendar (the one currently in use) with full support for time changes due to daylight saving time.
From the very beginning, the main focus of Date::Manip has been to be able to do ANY desired date/time operation easily. Many other modules exist which may do a subset of these operations quicker or more efficiently, but no other module can do all of the operations available in Date::Manip.
Since many other date/time modules exist, some of which may do the
specific operation(s)
you need faster, be sure to read
SHOULD I USE DATE::MANIP in the Date::Manip::Misc manpage before
deciding which of the Date and Time modules from CPAN is for you.
However, if you want one module to do it all, Date::Manip is the
one to use.
Date::Manip has functionality to work with several fundamental types of data.
Among other things, Date::Manip allow you to:
Each of these tasks is trivial (one or two lines at most) with this package.
Date::Manip version 6.00 was a complete rewrite of the module (for more information, please refer to the the Date::Manip::Changes5to6 manpage document). The rewrite made use of features introduced in perl 5.10 which made the date parsing routines significantly more robust. However, since not everyone has access to a new version of perl where Date::Manip is needed, the Date::Manip distribution actually includes two different versions of the module. It includes the older (5.xx) release and the newer (6.xx) release.
In addition, the 6.xx release was written with both a functional and an object-oriented interface, so there are actually three different ways to use Date::Manip (though only one is available if you have a version of perl older than 5.10).
For those who still run an older version of perl, the 5.xx functional interface is still available. It is known to work with perl 5.6 (and probably works with even older versions of perl). There are some limitations to this as described below.
Version 6.xx was rewritten as a series of object-oriented modules, but a functional interface (which is mostly backward compatible with the version 5 functional interface) is included. The functional interface is simply wrapper functions which call the OO modules.
A more detailed description of each interface is included below (to help you decide which interface is right for you). If you already know which interface you want to use, just go to the SEE ALSO section below for instructions on using each interface.
It should be noted that all three interfaces will be installed, but they will only all be usable with a recent version of perl.
When using a version of perl older than 5.10, this is the only interface available. This interface is documented in the Date::Manip::DM5 document. This interface has several weaknesses that need to be understood when using it:
As of December 2012, no development will be done, and I will not correct any remaining bugs in version 5. If a patch is supplied by someone else to fix bugs, I will apply it, provided it applies cleanly, and the resulting code continues to pass all tests. I will not apply patches to add features.
I will continue to distribute version 5 for several years. I do not have a date in mind where version 5 will be removed.
Time zone information for 5.xx is now automatically generated from the 6.xx time zone list, and every time time zones are updated in 6.xx, the 5.xx release will be similarly updated.
Prior to the release of 6.00, time zones were added manually to Date::Manip upon request. Since time zone information in 5.xx is now automatically generated, I no longer take requests for time zones.
The version 5 interface does not handle daylight saving time changes properly.
Feel free to email me concerns and comments.
The version 6 functional interface is almost completely identical to the version 5 functional interface, except that it uses the object-oriented modules to do all the real work.
Time zone support is greatly improved, but is still somewhat limited. Since the version 6 interface is backward compatible, dates do not store time zone information in them, so the programmer is responsible for keeping track of what time zone each date is in. If you want full access to the time zone support offered in Date::Manip, you have to use the object-oriented interface.
For the most part, scripts written for older versions of Date::Manip will continue to work (and scripts written for the version 6 functional interface will run with the version 5 interface), however in a few cases, you may need to modify your scripts. Please refer to the the Date::Manip::Migration5to6 manpage document for a list of changes which may be necessary.
As of 6.00, Date::Manip consists of a set of OO modules. Each have their own document (see the SEE ALSO section below).
The OO interface consists of the following modules: the Date::Manip::Date manpage, the Date::Manip::Delta manpage, the Date::Manip::Recur manpage, the Date::Manip::TZ manpage, and the Date::Manip::Base manpage.
The object-oriented interface is the only way to get the full functionality of Date::Manip. It fully support time zones (and daylight saving time).
If you are running an older version of perl, the version 5 functional interface is the only one available to you, and it will automatically be used.
If you are running a newer version of perl (5.10 or higher), you can use the object-oriented modules by loading them directly, or you can use a functional interface.
If you use a functional interface, it will default to the version 6 interface, but you can choose to run the version 5 interface in one of three ways:
use Date::Manip;
in your script, one of the functional interfaces will be loaded. If you are running a version of perl older than 5.10, it will automatically be the version 5 interface. If you are running a newer version of perl, it will automatically load the version 6 interface.
BEGIN { $Date::Manip::Backend = 'DM5'; } use Date::Manip;
Once a functional interface is loaded, you cannot switch between the version 5 and version 6 interfaces.
The following documents describe various parts of Date::Manip. The following documents describe the basic operation of the Date::Manip package:
An introduction to the Date::Manip classes used by the object-oriented interface and how to configure them:
These are the modules for using the object-oriented interface.
=item L<Date::Manip::Lang>
Information about the languages supported by Date::Manip and how to add a new language.
This script is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Sullivan Beck (sbeck@cpan.org)
Date::Manip - Date manipulation routines |