| Date::Manip::Objects - A description of the various Date::Manip objects |
Date::Manip::Objects - A description of the various Date::Manip objects
The Date::Manip 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.
Date::Manip consists of the following primary modules:
The the Date::Manip::Obj manpage 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 the Date::Manip::Obj manpage class.
A the Date::Manip::Base manpage object does not, of itself, contain any date information. Instead, it contains configuration information which determines how the Date::Manip package performs date operations. The configuration information is documented in the the Date::Manip::Config manpage document.
The the Date::Manip::Base manpage 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 the Date::Manip::Base manpage 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 the Date::Manip::Base manpage object, a the Date::Manip::Base manpage object is embedded in all other objects, and the same Base object can be shared by any number of objects to achieve maximum performance.
Similar to the the Date::Manip::Base manpage object, a great deal of information is cached in the the Date::Manip::TZ manpage 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 the Date::Manip::TZ manpage object relies on a the Date::Manip::Base manpage object (and a the Date::Manip::Base manpage object is always embedded in a the Date::Manip::TZ manpage object). All higher level objects (those listed next) depend on both a the Date::Manip::Base manpage and the Date::Manip::TZ manpage object, so a the Date::Manip::TZ manpage object is embedded in them.
In order to achieve maximum performance, and minimize memory usage, a the Date::Manip::TZ manpage object can be shared by any number of higher level objects, and in fact, it is desirable to reuse the same the Date::Manip::TZ manpage object as often as possible.
The the Date::Manip::Date manpage class performs operations on dates (which includes a date, time, and time zone). The the Date::Manip::Delta manpage class performs operations with deltas (amounts of time). The the Date::Manip::Recur manpage class performs operations on recurring events.
As mentioned above, each of these high level classes rely on both a the Date::Manip::TZ manpage object and a the Date::Manip::Base manpage object, so a the Date::Manip::TZ manpage object is embedded in each one (and the the Date::Manip::TZ manpage object has a the Date::Manip::Base manpage object embedded in it).
A the Date::Manip::Date manpage object contains a single date, so in order to work with multiple dates, multiple the Date::Manip::Date manpage objects will need to be created. In order to make the most effective use of cached information in the the Date::Manip::Base manpage object, the same the Date::Manip::TZ manpage object can be embedded in each of the higher level objects.
The same goes for multiple the Date::Manip::Delta manpage and the Date::Manip::Recur manpage objects.
There are also many secondary modules including:
Date::Manip::TZ_Base Date::Manip::TZdata Date::Manip::Zones Date::Manip::Lang::* Date::Manip::TZ::* Date::Manip::Offset::*
None of these are intended to be used directly.
By far the most common usage of Date::Manip 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 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 OBJECTS (MULTIPLE CONFIGURATION).
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;
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 the Date::Manip::TZ manpage and the Date::Manip::Base manpage objects, use the calls:
$tz = $date->tz(); $base = $date->base();
$tz = new Date::Manip::TZ; $base = new Date::Manip::Base;
To get the base object embedded in a the Date::Manip::TZ manpage object, use:
$base = $tz->base();
For a more complete description of the methods used here, refer to the the Date::Manip::Obj manpage document.
Occasionally, it may be useful to have multiple sets of configurations. In order to do this, multiple the Date::Manip::Base manpage objects must be created (each with their own set of configuration options), and then new Date::Manip objects are created with the appropriate the Date::Manip::Base manpage object embedded in them.
Possible reasons include:
$date_eng1 = new Date::Manip::Date;
$date_eng1->config("language","English");
$date_spa1 = new Date::Manip::Date;
$date_spa1->config("language","Spanish");
Any additional Date::Manip objects created from the first will work with English. Additional objects created from the second will work in Spanish.
The primary issue when dealing with multiple configurations is that it is necessary for the programmer to manually keep track of which Date::Manip objects work with each configuration. For example, refer to the following lines:
$date1 = new Date::Manip::Date [$opt1,$val1]; $date2 = new Date::Manip::Date $date1, [$opt2,$val2]; $date3 = new Date::Manip::Date $date1; $date4 = new Date::Manip::Date $date2;
The first line creates 3 objects: a the Date::Manip::Base manpage object, a
the Date::Manip::TZ manpage object, and a the Date::Manip::Date manpage object). The
the Date::Manip::Base manpage object has the configuration set to contain the
value(s) passed in as the final list reference argument.
The second line creates 3 new objects (a second the Date::Manip::Base manpage object, a second the Date::Manip::TZ manpage object, and a second the Date::Manip::Date manpage object). Since a list reference containing config variables is passed in, a new the Date::Manip::Base manpage object is created, rather than reusing the first one. The second the Date::Manip::Base manpage 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 the Date::Manip::Date manpage object which uses the first the Date::Manip::Base manpage and the Date::Manip::TZ manpage objects embedded in it.
The fourth line creates another the Date::Manip::Date manpage object which uses the second the Date::Manip::Base manpage and the Date::Manip::TZ manpage 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.
$date1 = new Date::Manip::Date; $date2 = new Date::Manip::Date $date1;
This is important for two reasons. First is memory usage. The the Date::Manip::Base manpage 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 the Date::Manip::TZ manpage 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 (the Date::Manip::Date manpage for example), it makes these objects appear quite large.
The second reason to reuse the Date::Manip::Base manpage 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, 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 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.
$date = new Date::Manip::Date;
$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.
Please refer to the the Date::Manip::Problems manpage documentation for information on submitting bug reports or questions to the author.
the Date::Manip manpage - 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 (sbeck@cpan.org)
| Date::Manip::Objects - A description of the various Date::Manip objects |