NAME
    Date::Manip - Date manipulation routines

DESCRIPTION
    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 data 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 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.
    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.

    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. Most
        people will think of a delta as an amount of time, but the term
        'time' is already used so much in this module that I didn't want to
        use it here in order to avoid confusion.

    recurrence
        A recurring event is something which occurs on a regular recurring
        basis.

    holidays and events
        Holidays and events are basically named dates or recurrences.

    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.

VERSION 5 AND VERSION 6
    Date::Manip version 6.00 was a complete rewrite of the module (for more
    information, please refer to the Date::Manip::Changes5to6 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.

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 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 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.

    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
    three ways:

    Use the default functional interface
        By including:

           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.

    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       - detailed informaion on how date
                                calculations are done
      Date::Manip::Holidays   - information on defining and using
                                holidays and events
      Date::Manip::ConfigFile - sample config file
      Date::Manip::Lang       - information about the languages
                                supported by Date::Manip and how
                                to add a new language

    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); this contains more
                                details than the Migration5to6
                                document
      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)

