{
    "content": [
        {
            "type": "text",
            "text": "# Date::Manip::Objects (perldoc)\n\n## NAME\n\nDate::Manip::Objects - A description of the various Date::Manip objects\n\n## SYNOPSIS\n\nThe Date::Manip package consist of several modules, each of which perform a set of operations on\na specific class of objects. This document describes how the various modules work together.\n\n## DESCRIPTION\n\nDate::Manip consists of the following primary modules:\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **BUGS AND QUESTIONS**\n- **SEE ALSO**\n- **LICENSE**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "Date::Manip::Objects",
        "section": "",
        "mode": "perldoc",
        "summary": "Date::Manip::Objects - A description of the various Date::Manip objects",
        "synopsis": "The Date::Manip package consist of several modules, each of which perform a set of operations on\na specific class of objects. This document describes how the various modules work together.",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 178,
                "subsections": [
                    {
                        "name": "value",
                        "lines": 73
                    }
                ]
            },
            {
                "name": "BUGS AND QUESTIONS",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "LICENSE",
                "lines": 3,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 2,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "Date::Manip::Objects - A description of the various Date::Manip objects\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "The Date::Manip package consist of several modules, each of which perform a set of operations on\na specific class of objects. This document describes how the various modules work together.\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "Date::Manip consists of the following primary modules:\n\nDate::Manip::Obj\nThe Date::Manip::Obj module is not intended for direct use. It is used as a base class for\nall other Date::Manip classes described below.\n\nThe Date::Manip::Obj module contains some functions which are inherited by all these\nclasses, so to understand all of the methods available to any of the classes below, you must\ninclude those documented in the Date::Manip::Obj class.\n\nDate::Manip::Base\nThe Date::Manip::Base is used to perform basic operations including basic date operations,\nmanagement of configuration options, handling the definitions used in different languages,\netc.\n\nA Date::Manip::Base object does not, of itself, contain any date information. Instead, it\ncontains configuration information which determines how the Date::Manip package performs\ndate operations. The configuration information is documented in the Date::Manip::Config\ndocument.\n\nThe Date::Manip::Base object has one other property that is very important. When performing\nbasic date operations, some intermediate results are cached in the object which leads to\nsignificant performance increases in later operations. As such, it is important to reuse the\nobject as much as possible, rather than creating new Date::Manip::Base objects all the time.\n\nMuch of the information in this document is related to this issue, and tells how to create\nvarious higher-level objects in order to get the most efficient reuse of this cached data.\n\nBecause all other objects depend on a Date::Manip::Base object, a Date::Manip::Base object\nis embedded in all other objects, and the same Base object can be shared by any number of\nobjects to achieve maximum performance.\n\nDate::Manip::TZ\nThe Date::Manip::TZ module adds support for time zones. It is used to verify date and time\nzone information, convert dates from one time zone to another, and handle all daylight\nsaving time transitions.\n\nSimilar to the Date::Manip::Base object, a great deal of information is cached in the\nDate::Manip::TZ object. This includes lists of all time zones, offsets, and abbreviations\nfor all time zones. It also includes more a more detailed description of every time zone\nthat has actually been worked used.\n\nA Date::Manip::TZ object relies on a Date::Manip::Base object (and a Date::Manip::Base\nobject is always embedded in a Date::Manip::TZ object). All higher level objects (those\nlisted next) depend on both a Date::Manip::Base and Date::Manip::TZ object, so a\nDate::Manip::TZ object is embedded in them.\n\nIn order to achieve maximum performance, and minimize memory usage, a Date::Manip::TZ object\ncan be shared by any number of higher level objects, and in fact, it is desirable to reuse\nthe same Date::Manip::TZ object as often as possible.\n\nDate::Manip::Date\nDate::Manip::Delta\nDate::Manip::Recur\nThese are the primary modules which are used to perform all high level date operations.\n\nThe Date::Manip::Date class performs operations on dates (which includes a date, time, and\ntime zone). The Date::Manip::Delta class performs operations with deltas (amounts of time).\nThe Date::Manip::Recur class performs operations on recurring events.\n\nAs mentioned above, each of these high level classes rely on both a Date::Manip::TZ object\nand a Date::Manip::Base object, so a Date::Manip::TZ object is embedded in each one (and the\nDate::Manip::TZ object has a Date::Manip::Base object embedded in it).\n\nA Date::Manip::Date object contains a single date, so in order to work with multiple dates,\nmultiple Date::Manip::Date objects will need to be created. In order to make the most\neffective use of cached information in the Date::Manip::Base object, the same\nDate::Manip::TZ object can be embedded in each of the higher level objects.\n\nThe same goes for multiple Date::Manip::Delta and Date::Manip::Recur objects.\n\nThere are also many secondary modules including:\n\nDate::Manip::TZBase\nDate::Manip::TZdata\nDate::Manip::Zones\nDate::Manip::Lang::*\nDate::Manip::TZ::*\nDate::Manip::Offset::*\n\nNone of these are intended to be used directly.\n\nWORKING WITH DATE::MANIP OBJECTS (SINGLE CONFIGURATION)\nBy far the most common usage of Date::Manip involves setting a single local time zone, parsing\ndates in a single language, and having all other configuration parameters set to a single value\nthat doesn't change over the course of the program.\n\nWhenever this is the case, you can use the methods listed in this section to create any number\nof Date::Manip objects. It will automatically optimize the use of cached data to get the best\nperformance.\n\nIf you do need to work with multiple different configurations (such as parsing dates from\nmultiple languages), please refer to the next section \"WORKING WITH DATE::MANIP OBJECTS\n(MULTIPLE CONFIGURATION)\".\n\nWorking with high level objects\nThe most common situation is one where you will need to use one or more high level objects\n(Date, Delta, or Recur objects). In addition, you may want to use the lower level (Base or\nTZ) objects.\n\nThe first thing you should do is to create your initial object. Create the highest level\nobject you will be using. For example if you will be working with dates, create the first\ndate object with:\n\n$date = new Date::Manip::Date;\n\nThe next step is to set the configuration values. Use the config method to do this:\n\n$date->config(ARGS);\n\nAlthough you can call the config method later, it is strongly suggested that the\nconfiguration be set soon after the initial object is created and not altered later. Every\ntime you alter the configuration, some of the cached data is cleared, so for optimal\nperformance, you don't want to alter the configuration if possible.\n\nAdditional high-level objects can be created using the calls:\n\n$date2 = $date->newdate();\n$delta = $date->newdelta();\n$recur = $date->newrecur();\n\nTo access the embedded Date::Manip::TZ and Date::Manip::Base objects, use the calls:\n\n$tz    = $date->tz();\n$base  = $date->base();\n\nWorking with low level objects only\nIf you will only be working with low level objects, create them with one of the calls:\n\n$tz    = new Date::Manip::TZ;\n$base  = new Date::Manip::Base;\n\nTo get the base object embedded in a Date::Manip::TZ object, use:\n\n$base  = $tz->base();\n\nFor a more complete description of the methods used here, refer to the Date::Manip::Obj\ndocument.\n\nWORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATION)\nOccasionally, it may be useful to have multiple sets of configurations. In order to do this,\nmultiple Date::Manip::Base objects must be created (each with their own set of configuration\noptions), and then new Date::Manip objects are created with the appropriate Date::Manip::Base\nobject embedded in them.\n\nPossible reasons include:\n\nParsing multiple languages\nA Date::Manip::Base object includes information about a single language. If you need to\nparse dates from two (or more) languages, a Date::Manip::Base object needs to be created for\neach one. This could be done as:\n\n$dateeng1 = new Date::Manip::Date;\n$dateeng1->config(\"language\",\"English\");\n\n$datespa1 = new Date::Manip::Date;\n$datespa1->config(\"language\",\"Spanish\");\n\nAny additional Date::Manip objects created from the first will work with English. Additional\nobjects created from the second will work in Spanish.\n\nBusiness modes for different countries and/or businesses\nIf you are doing business mode calculations (see Date::Manip::Calc) for two different\nbusinesses which have different holiday lists, work weeks, or business days, you can create\ndifferent objects which read different config files (see Date::Manip::Config) with the\nappropriate description of each.\n\nThe primary issue when dealing with multiple configurations is that it is necessary for the\nprogrammer to manually keep track of which Date::Manip objects work with each configuration. For\nexample, refer to the following lines:\n\n$date1 = new Date::Manip::Date [$opt1,$val1];\n$date2 = new Date::Manip::Date $date1, [$opt2,$val2];\n$date3 = new Date::Manip::Date $date1;\n$date4 = new Date::Manip::Date $date2;\n\nThe first line creates 3 objects: a Date::Manip::Base object, a Date::Manip::TZ object, and a\nDate::Manip::Date object). The Date::Manip::Base object has the configuration set to contain the",
                "subsections": [
                    {
                        "name": "value",
                        "content": "The second line creates 3 new objects (a second Date::Manip::Base object, a second\nDate::Manip::TZ object, and a second Date::Manip::Date object). Since a list reference\ncontaining config variables is passed in, a new Date::Manip::Base object is created, rather than\nreusing the first one. The second Date::Manip::Base object contains all the config from the\nfirst, as well as the config variables passed in in the list reference argument.\n\nThe third line creates another Date::Manip::Date object which uses the first Date::Manip::Base\nand Date::Manip::TZ objects embedded in it.\n\nThe fourth line creates another Date::Manip::Date object which uses the second Date::Manip::Base\nand Date::Manip::TZ objects embedded in it.\n\nMost of the time there will only be one set of configuration options used, so this complexity is\nreally for a very special, and not widely used, bit of functionality.\n\nWORKING WITH DATE::MANIP OBJECTS (ADDITIONAL NOTES)\nobject reuse\nIn order to create additional Date::Manip objects, a previously created object should be\npassed in as the first argument. This will allow the same Base object to be embedded in both\nin order to maximize data reuse of the cached intermediate results, and will result in much\nbetter performance. For example:\n\n$date1 = new Date::Manip::Date;\n$date2 = new Date::Manip::Date $date1;\n\nThis is important for two reasons. First is memory usage. The Date::Manip::Base object is\nquite large. It stores a large number of precompile regular expressions for language\nparsing, and as date operations are done, intermediate results are cached which can be\nreused later to improve performance. The Date::Manip::TZ object is even larger and contains\ninformation about all known time zones indexed several different ways (by offset, by\nabbreviation, etc.). As time zones are actually used, a description of all of the time\nchange rules are loaded and added to this object.\n\nSince these objects are so large, it is important to reuse them, rather than to create lots\nof copies of them. It should be noted that because these objects are embedded in each of the\nhigh level object (Date::Manip::Date for example), it makes these objects appear quite\nlarge.\n\nThe second reason to reuse Date::Manip::Base objects is performance. Since intermediate\nresults are cached there, many date operations only need to be done once and then they can\nbe reused any number of times. In essence, this is doing the same function as the Memoize\nmodule, but in a more efficient manner. Memoize caches results for function calls. For\nDate::Manip, this would often work, but if you change a config variable, the return value\nmay change, so Memoize could cause things to break. In addition, Memoize caches primarily at\nthe function level, but Date::Manip stores caches intermediate results wherever performance\nincrease is seen. Every time I consider caching a result, I run a test to see if it\nincreases performance. If it doesn't, or it doesn't make a significant impact, I don't cache\nit.\n\nBecause the caching is quite finely tuned, it's much more efficient than using a generic\n(though useful) tool such as Memoize.\n\nconfiguration changes\nAs a general rule, you should only pass in configuration options when the first object is\ncreated. In other words, the following behavior is discouraged:\n\n$date = new Date::Manip::Date;\n$date->config(@opts);\n\n... do some stuff\n\n$date->config(@opts);\n\n... do some other stuff\n\nBecause some of the cached results are configuration specific, when a configuration change\nis made, some of the cached data must be discarded necessitating those results to be\nrecalculated.\n\nIf you really need to change configuration in the middle of execution, it is certainly\nallowed of course, but if you can define the configuration once immediately after the object\nis first created, and then leave the configuration alone, performance will be optimized.\n"
                    }
                ]
            },
            "BUGS AND QUESTIONS": {
                "content": "Please refer to the Date::Manip::Problems documentation for information on submitting bug\nreports or questions to the author.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "Date::Manip - main module documentation\n",
                "subsections": []
            },
            "LICENSE": {
                "content": "This script is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Sullivan Beck (sbeck@cpan.org)\n",
                "subsections": []
            }
        }
    }
}