NAME
Date::Manip - Date manipulation routines
DESCRIPTION
Date::Manip is a series of modules designed to make any common date/time
manipulation easy to do. Operations such as comparing two times,
calculating a time a given amount of time from another, or parsing
international times are all easily done. From the very beginning, the
main focus of Date::Manip has been to be able to do ANY desired
date/time operation easily, not necessarily quickly. Also, it is
definitely oriented towards the type of operations we (as people) tend
to think of rather than those operations used routinely by computers.
There are other modules that can do a subset of the operations available
in Date::Manip much quicker than those presented here, so be sure to
read the section SHOULD I USE DATE::MANIP in the Date::Manip::Misc
document before deciding which of the Date and Time modules from CPAN is
for you.
Date::Manip 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.
Date::Manip has functionality to work with several fundamental types of
data.
dates
The word date is used extensively here and is somewhat misleading.
In Date::Manip, a date consists of three pieces of information: a
calendar date, a time of day, and time zone information. Calendar
dates and times are fully handled. Time zones are handled as well,
but depending on how you use Date::Manip, there may be some
limitations as discussed below.
delta
A delta is an amount of time (i.e. the amount of time between two
different dates). A delta refers only to an amount of time. It
includes no information about a starting or ending date/time.
recurrence
A recurring event is something which occurs on a regular recurring
basis.
holidays and events
Holidays and events are basically named dates.
Among other things, Date::Manip allow you to:
* Enter a date in practically any format you choose.
* Compare two dates, entered in widely different formats to determine
which is earlier.
* Extract any information you want from a date using a format string
similar to the Unix date command.
* Determine the amount of time between two dates, or add an amount of
time to a date to get a second date.
* Work with dates with dates using international formats (foreign
month names, 12/10/95 referring to October rather than December,
etc.).
* To find a list of dates where a recurring event happens.
Each of these tasks is trivial (one or two lines at most) with this
package.
Date::Manip may be run in three different ways. All three interfaces are
bundled into one module, so with a modern version of perl, you can
choose whichever interface you want.
Functional interface (version 5)
Date::Manip 5.xx runs on pretty much any version of perl. It is
known to work with perl 5.6, and probably runs under even older
versions of perl.
Functional form (version 6)
Object-Oriented interface
Date::Manip 6.xx represents a complete rewrite of Date::Manip. It
only runs on more recent versions of perl (5.10 or higher), so it
may not be available to all users.
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.
FUNCTIONAL INTERFACE (VERSION 5)
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 before using it:
Limited Support
The version 5 functional interface is no longer being developed, and
only limited support is available for it.
I will continue to do limited bug fixes provided they do not require
a lot of changes. Anything to do with time zone handling will not be
fixed, and other problems (especially those that have already been
fixed in the 6.xx release) may not be patched if they require
significant changes to 5.xx.
Limited bug fixes will be supported until December 2012. At that
point, I will reevaluate things and decide whether or not to
continue this or not. The most likely outcome is that, at that
point, I will cease providing bug fixes for the 5.xx release
entirely.
Whether or not I continue to do bug fixes, I will continue to
distribute the version 5 functional interface until at least
December 2013. After that, I will evaluate the need for a perl
5.6/5.8 version of Date::Manip in order to decide whether or not to
continue distributing it.
Limited Time Zone Support
Time zone support is extremely limited, and is often broken. The
lack of good time zone support was the primary reason for rewriting
Date::Manip .
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.
No Further Development
No functionality will be added to 5.xx .
Performance Issues
Considerable time has been spent speeding up Date::Manip, and fairly
simple benchmarks show that version 6 is around twice as fast as
version 5.
Feel free to email me concerns and comments.
FUNCTIONAL INTERFACE (VERSION 6)
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
Date::Manip::Migration5to6 document for a list of changes which may be
necessary.
OBJECT-ORIENTED INTERFACE
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: Date::Manip::Date,
Date::Manip::Delta, Date::Manip::Recur, Date::Manip::TZ, and
Date::Manip::Base .
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).
SELECTING AN INTERFACE
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
two ways:
DATE_MANIP ENVIRONMENT VARIABLE
By setting the DATE_MANIP environment variable to 'DM5' before
running the perl script, the version 5 interface will be used.
Date::Manip::Backend VARIABLE
Alternately, you can set the Date::Manip::Backend variable to be
'DM5' before loading the module. Typically, this will be done in the
following way:
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.
SEE ALSO
The following documents describe various parts of Date::Manip. The
following documents describe the basic operation of the Date::Manip
package:
A description of the functional interfaces:
Date::Manip::DM5 - the version 5 functional interface
Date::Manip::DM6 - the version 6 functional interface
An introduction to the Date::Manip classes used by the object-oriented
interface and how to configure them:
Date::Manip::Objects - an overview of the various
Date::Manip modules, and how
to use them
Date::Manip::Config - information for configuring
Date::Manip
The methods available in each class:
Date::Manip::Obj - base class (modules listed below
inherit the methods defined in this
class)
Date::Manip::Base - module for doing low-level date
operations
Date::Manip::TZ - module for working with time zones
Date::Manip::Date - date operations
Date::Manip::Delta - delta operations
Date::Manip::Recur - recurrence operations
Timezone information:
Date::Manip::DM5abbrevs - time zone abbreviations used in the
version 5 interface
Date::Manip::Zones - time zone data included in Date::Manip
used in the version 6 interface and
the object-oriented interface
Miscellaneous information:
Date::Manip::Calc - date calculations
Date::Manip::Holidays - information on defining and using
holidays and events
Information about the module and administrative things:
Date::Manip::Migration5to6
- information on changes necessary
to scripts when upgrading from
5.xx to 6.xx
Date::Manip::Changes5 - change log for Date::Manip 5.xx
Date::Manip::Changes5to6- differences between version 5.xx
and 6.00 (including information
on upgrading)
Date::Manip::Changes6 - change log for Date::Manip 6.xx
Date::Manip::Misc - miscellaneous information about
Date::Manip (who should use it;
acknowledgements)
Date::Manip::Problems - common problems and instructions
for reporting bugs
Date::Manip::Examples - examples of how to use Date::Manip
LICENSE
This script is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
AUTHOR
Sullivan Beck (sbeck@cpan.org)