# Date::Manip::Objects - A description of the various Date::Manip objects - perldoc - [phpMan]

## NAME
    [Date::Manip::Objects](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AObjects/markdown) - A description of the various [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) objects

## SYNOPSIS
    The [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) package consist of several modules, each of which perform a set of operations on
    a specific class of objects. This document describes how the various modules work together.

## DESCRIPTION
    [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) consists of the following primary modules:

    [Date::Manip::Obj](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AObj/markdown)
        The [Date::Manip::Obj](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AObj/markdown) module is not intended for direct use. It is used as a base class for
        all other [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) classes described below.

        The [Date::Manip::Obj](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AObj/markdown) module contains some functions which are inherited by all these
        classes, so to understand all of the methods available to any of the classes below, you must
        include those documented in the [Date::Manip::Obj](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AObj/markdown) class.

    [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown)
        The [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) is used to perform basic operations including basic date operations,
        management of configuration options, handling the definitions used in different languages,
        etc.

        A [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object does not, of itself, contain any date information. Instead, it
        contains configuration information which determines how the [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) package performs
        date operations. The configuration information is documented in the [Date::Manip::Config](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AConfig/markdown)
        document.

        The [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object has one other property that is very important. When performing
        basic date operations, some intermediate results are cached in the object which leads to
        significant performance increases in later operations. As such, it is important to reuse the
        object as much as possible, rather than creating new [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) objects all the time.

        Much of the information in this document is related to this issue, and tells how to create
        various higher-level objects in order to get the most efficient reuse of this cached data.

        Because all other objects depend on a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object, a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object
        is embedded in all other objects, and the same Base object can be shared by any number of
        objects to achieve maximum performance.

    [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown)
        The [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) module adds support for time zones. It is used to verify date and time
        zone information, convert dates from one time zone to another, and handle all daylight
        saving time transitions.

        Similar to the [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object, a great deal of information is cached in the
        [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object. This includes lists of all time zones, offsets, and abbreviations
        for all time zones. It also includes more a more detailed description of every time zone
        that has actually been worked used.

        A [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object relies on a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object (and a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown)
        object is always embedded in a [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object). All higher level objects (those
        listed next) depend on both a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) and [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object, so a
        [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object is embedded in them.

        In order to achieve maximum performance, and minimize memory usage, a [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object
        can be shared by any number of higher level objects, and in fact, it is desirable to reuse
        the same [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object as often as possible.

    [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown)
    [Date::Manip::Delta](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADelta/markdown)
    [Date::Manip::Recur](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ARecur/markdown)
        These are the primary modules which are used to perform all high level date operations.

        The [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) class performs operations on dates (which includes a date, time, and
        time zone). The [Date::Manip::Delta](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADelta/markdown) class performs operations with deltas (amounts of time).
        The [Date::Manip::Recur](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ARecur/markdown) class performs operations on recurring events.

        As mentioned above, each of these high level classes rely on both a [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object
        and a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object, so a [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object is embedded in each one (and the
        [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object has a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object embedded in it).

        A [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) object contains a single date, so in order to work with multiple dates,
        multiple [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) objects will need to be created. In order to make the most
        effective use of cached information in the [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object, the same
        [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object can be embedded in each of the higher level objects.

        The same goes for multiple [Date::Manip::Delta](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADelta/markdown) and [Date::Manip::Recur](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ARecur/markdown) objects.

    There are also many secondary modules including:

       [Date::Manip::TZ_Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZBase/markdown)
       [Date::Manip::TZdata](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZdata/markdown)
       [Date::Manip::Zones](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AZones/markdown)
       [Date::Manip::Lang](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ALang/markdown)::*
       [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown)::*
       [Date::Manip::Offset](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AOffset/markdown)::*

    None of these are intended to be used directly.

WORKING WITH [DATE::MANIP](https://www.chedong.com/phpMan.php/perldoc/DATE%3A%3AMANIP/markdown) OBJECTS (SINGLE CONFIGURATION)
    By far the most common usage of [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) involves setting a single local time zone, parsing
    dates in a single language, and having all other configuration parameters set to a single value
    that doesn't change over the course of the program.

    Whenever this is the case, you can use the methods listed in this section to create any number
    of [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) objects. It will automatically optimize the use of cached data to get the best
    performance.

    If you do need to work with multiple different configurations (such as parsing dates from
    multiple languages), please refer to the next section "WORKING WITH [DATE::MANIP](https://www.chedong.com/phpMan.php/perldoc/DATE%3A%3AMANIP/markdown) OBJECTS
    (MULTIPLE CONFIGURATION)".

    Working with high level objects
        The most common situation is one where you will need to use one or more high level objects
        (Date, Delta, or Recur objects). In addition, you may want to use the lower level (Base or
        TZ) objects.

        The first thing you should do is to create your initial object. Create the highest level
        object you will be using. For example if you will be working with dates, create the first
        date object with:

           $date = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown);

        The next step is to set the configuration values. Use the config method to do this:

           $date->config(ARGS);

        Although you can call the config method later, it is strongly suggested that the
        configuration be set soon after the initial object is created and not altered later. Every
        time you alter the configuration, some of the cached data is cleared, so for optimal
        performance, you don't want to alter the configuration if possible.

        Additional high-level objects can be created using the calls:

           $date2 = $date->new_date();
           $delta = $date->new_delta();
           $recur = $date->new_recur();

        To access the embedded [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) and [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) objects, use the calls:

           $tz    = $date->tz();
           $base  = $date->base();

    Working with low level objects only
        If you will only be working with low level objects, create them with one of the calls:

           $tz    = new [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown);
           $base  = new [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown);

        To get the base object embedded in a [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object, use:

           $base  = $tz->base();

    For a more complete description of the methods used here, refer to the [Date::Manip::Obj](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AObj/markdown)
    document.

WORKING WITH [DATE::MANIP](https://www.chedong.com/phpMan.php/perldoc/DATE%3A%3AMANIP/markdown) OBJECTS (MULTIPLE CONFIGURATION)
    Occasionally, it may be useful to have multiple sets of configurations. In order to do this,
    multiple [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) objects must be created (each with their own set of configuration
    options), and then new [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) objects are created with the appropriate [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown)
    object embedded in them.

    Possible reasons include:

    Parsing multiple languages
        A [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object includes information about a single language. If you need to
        parse dates from two (or more) languages, a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object needs to be created for
        each one. This could be done as:

           $date_eng1 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown);
           $date_eng1->config("language","English");

           $date_spa1 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown);
           $date_spa1->config("language","Spanish");

        Any additional [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) objects created from the first will work with English. Additional
        objects created from the second will work in Spanish.

    Business modes for different countries and/or businesses
        If you are doing business mode calculations (see [Date::Manip::Calc](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ACalc/markdown)) for two different
        businesses which have different holiday lists, work weeks, or business days, you can create
        different objects which read different config files (see [Date::Manip::Config](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AConfig/markdown)) with the
        appropriate description of each.

    The primary issue when dealing with multiple configurations is that it is necessary for the
    programmer to manually keep track of which [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) objects work with each configuration. For
    example, refer to the following lines:

       $date1 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) [$opt1,$val1];
       $date2 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) $date1, [$opt2,$val2];
       $date3 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) $date1;
       $date4 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) $date2;

    The first line creates 3 objects: a [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object, a [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object, and a
    [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) object). The [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object has the configuration set to contain the
### value

    The second line creates 3 new objects (a second [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object, a second
    [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object, and a second [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) object). Since a list reference
    containing config variables is passed in, a new [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object is created, rather than
    reusing the first one. The second [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object contains all the config from the
    first, as well as the config variables passed in in the list reference argument.

    The third line creates another [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) object which uses the first [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown)
    and [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) objects embedded in it.

    The fourth line creates another [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) object which uses the second [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown)
    and [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) objects embedded in it.

    Most of the time there will only be one set of configuration options used, so this complexity is
    really for a very special, and not widely used, bit of functionality.

WORKING WITH [DATE::MANIP](https://www.chedong.com/phpMan.php/perldoc/DATE%3A%3AMANIP/markdown) OBJECTS (ADDITIONAL NOTES)
    object reuse
        In order to create additional [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) objects, a previously created object should be
        passed in as the first argument. This will allow the same Base object to be embedded in both
        in order to maximize data reuse of the cached intermediate results, and will result in much
        better performance. For example:

           $date1 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown);
           $date2 = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) $date1;

        This is important for two reasons. First is memory usage. The [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) object is
        quite large. It stores a large number of precompile regular expressions for language
        parsing, and as date operations are done, intermediate results are cached which can be
        reused later to improve performance. The [Date::Manip::TZ](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ATZ/markdown) object is even larger and contains
        information about all known time zones indexed several different ways (by offset, by
        abbreviation, etc.). As time zones are actually used, a description of all of the time
        change rules are loaded and added to this object.

        Since these objects are so large, it is important to reuse them, rather than to create lots
        of copies of them. It should be noted that because these objects are embedded in each of the
        high level object ([Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown) for example), it makes these objects appear quite
        large.

        The second reason to reuse [Date::Manip::Base](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ABase/markdown) objects is performance. Since intermediate
        results are cached there, many date operations only need to be done once and then they can
        be reused any number of times. In essence, this is doing the same function as the Memoize
        module, but in a more efficient manner. Memoize caches results for function calls. For
        [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown), this would often work, but if you change a config variable, the return value
        may change, so Memoize could cause things to break. In addition, Memoize caches primarily at
        the function level, but [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) stores caches intermediate results wherever performance
        increase is seen. Every time I consider caching a result, I run a test to see if it
        increases performance. If it doesn't, or it doesn't make a significant impact, I don't cache
        it.

        Because the caching is quite finely tuned, it's much more efficient than using a generic
        (though useful) tool such as Memoize.

    configuration changes
        As a general rule, you should only pass in configuration options when the first object is
        created. In other words, the following behavior is discouraged:

            $date = new [Date::Manip::Date](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/markdown);
            $date->config(@opts);

            ... do some stuff

            $date->config(@opts);

            ... do some other stuff

        Because some of the cached results are configuration specific, when a configuration change
        is made, some of the cached data must be discarded necessitating those results to be
        recalculated.

        If you really need to change configuration in the middle of execution, it is certainly
        allowed of course, but if you can define the configuration once immediately after the object
        is first created, and then leave the configuration alone, performance will be optimized.

## BUGS AND QUESTIONS
    Please refer to the [Date::Manip::Problems](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3AProblems/markdown) documentation for information on submitting bug
    reports or questions to the author.

## SEE ALSO
    [Date::Manip](https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip/markdown) - main module documentation

## 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>)