Date::Manip::Interfaces - A description of functional and OO interfaces
There are three different ways to use Date::Manip . A complete description of
each is included below. They are:
- Functional interface (version 5)
- Date::Manip version 5 runs on very old versions of perl. If
you need to use Date::Manip with a version of perl older than 5.10, this
is the only interface available.
- Functional interface (version 6)
- When Date::Manip was rewritten (version 6), it made use of
some features of perl 5.10 . This is the recommended interface if you are
supporting a script that uses the functional interface, but where a newer
version of perl is available.
- Object-oriented interface
- The OO interface is the recommended interface wherever
possible. It is the only one with access to the full functionality of the
Date::Manip version 5.xx was available for many years, but suffered from several
weaknesses. It was slow, and did not handle timezones or daylight saving time
correctly. It was written as a functional interface, even though an
object-oriented interface would have been better. It did have the advantage of
running on very old versions of perl (it is known to work on perl 5.6 and may
work on even older versions of perl).
Date::Manip version 6.00 was a complete rewrite of the module. For detailed
information about the differences, please refer to the
Date::Manip::Changes5to6 document. The rewrite was needed in order to handle
timezone operations, in addition to many other improvements including much
better performance and more robust parsing.
The rewrite made use of features introduced in perl 5.10 which made the date
parsing routines significantly cleaner. In addition, the 6.xx release was
written as an object oriented set of modules which are much more powerful than
the older functional interface. For backward compatibility, a new functional
interface was rewritten (which is simply a set of wrapper functions which call
the OO methods) which is almost entirely backward compatible with the version
The Date::Manip distribution includes all three of these interfaces: the older
version 5 interface, and both the new OO interface and the backward compatible
functional interface. Also, all three are installed, so you can use whichever
interface is appropriate.
Since there are three different interfaces available, choosing the interface is
If you are running on a system with a very old version of perl (older than
5.10), the version 5 interface is your only option.
If you are on a system running a newer version of perl, but need to support a
script that was written using the functional interface, then you can use the
version 6 functional interface.
For everyone else, it is strongly recommended that you use the object-oriented
A more detailed description of each interface is included below. If you already
know which interface you want to use, just go to the "SEE ALSO" in
Date::Manip section for documentation for each interface.
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:
- Limited Support
- The version 5 functional interface is no longer being
developed, and only limited support is available for 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.
- Limited Time Zone Support
- Time zone support is extremely limited, and is often
incorrect. The lack of time zone support was the primary reason for
The version 5 interface does not handle daylight saving time changes
- 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.
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.
As of 6.00, Date::Manip consists of a set of OO modules. Each have their own
document (see the "SEE ALSO" in Date::Manip section).
The OO interface consists of the following modules: Date::Manip::Date,
Date::Manip::Delta, Date::Manip::Recur, Date::Manip::TZ, and
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
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:
- Using the OO interface
- By including any of the following:
you have access to the OO interface for the appropriate types of
- Use the default functional interface
- By including:
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.
- 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
$Date::Manip::Backend = 'DM5';
Once a functional interface is loaded, you cannot switch between the version 5
and version 6 interfaces.
Date::Manip - main module documentation
This script is free software; you can redistribute it and/or modify it under the
same terms as Perl itself.
Sullivan Beck (firstname.lastname@example.org)