{
    "mode": "info",
    "parameter": "Date::Manip::Objects",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/info/Date%3A%3AManip%3A%3AObjects/json",
    "generated": "2026-07-05T09:21:16Z",
    "synopsis": "The Date::Manip package consist of several modules, each of which\nperform a set of operations on a specific class of objects.  This\ndocument describes how the various modules work together.",
    "sections": {
        "Date::Manip::Objects(3User Contributed Perl DocumentaDate::Manip::Objects(3pm)": {
            "content": "",
            "subsections": []
        },
        "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\nperform a set of operations on a specific class of objects.  This\ndocument 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\nused as a base class for all other Date::Manip classes described\nbelow.\n\nThe Date::Manip::Obj module contains some functions which are\ninherited by all these classes, so to understand all of the methods\navailable to any of the classes below, you must include those\ndocumented in the Date::Manip::Obj class.\n\nDate::Manip::Base\nThe Date::Manip::Base is used to perform basic operations including\nbasic date operations, management of configuration options,\nhandling the definitions used in different languages, etc.\n\nA Date::Manip::Base object does not, of itself, contain any date\ninformation. Instead, it contains configuration information which\ndetermines how the Date::Manip package performs date operations.\nThe configuration information is documented in the\nDate::Manip::Config document.\n\nThe Date::Manip::Base object has one other property that is very\nimportant. When performing basic date operations, some intermediate\nresults are cached in the object which leads to significant\nperformance increases in later operations. As such, it is important\nto reuse the object as much as possible, rather than creating new\nDate::Manip::Base objects all the time.\n\nMuch of the information in this document is related to this issue,\nand tells how to create various higher-level objects in order to\nget the most efficient reuse of this cached data.\n\nBecause all other objects depend on a Date::Manip::Base object, a\nDate::Manip::Base object is embedded in all other objects, and the\nsame Base object can be shared by any number of objects to achieve\nmaximum performance.\n\nDate::Manip::TZ\nThe Date::Manip::TZ module adds support for time zones. It is used\nto verify date and time zone information, convert dates from one\ntime zone to another, and handle all daylight saving time\ntransitions.\n\nSimilar to the Date::Manip::Base object, a great deal of\ninformation is cached in the Date::Manip::TZ object. This includes\nlists of all time zones, offsets, and abbreviations for all time\nzones. It also includes more a more detailed description of every\ntime zone that has actually been worked used.\n\nA Date::Manip::TZ object relies on a Date::Manip::Base object (and\na Date::Manip::Base object is always embedded in a Date::Manip::TZ\nobject).  All higher level objects (those listed next) depend on\nboth 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,\na Date::Manip::TZ object can be shared by any number of higher\nlevel objects, and in fact, it is desirable to reuse the same\nDate::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\nlevel date operations.\n\nThe Date::Manip::Date class performs operations on dates (which\nincludes a date, time, and time zone). The Date::Manip::Delta class\nperforms operations with deltas (amounts of time). The\nDate::Manip::Recur class performs operations on recurring events.\n\nAs mentioned above, each of these high level classes rely on both a\nDate::Manip::TZ object and a Date::Manip::Base object, so a\nDate::Manip::TZ object is embedded in each one (and the\nDate::Manip::TZ object has a Date::Manip::Base object embedded in\nit).\n\nA Date::Manip::Date object contains a single date, so in order to\nwork with multiple dates, multiple Date::Manip::Date objects will\nneed to be created. In order to make the most effective use of\ncached information in the Date::Manip::Base object, the same\nDate::Manip::TZ object can be embedded in each of the higher level\nobjects.\n\nThe same goes for multiple Date::Manip::Delta and\nDate::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\nlocal time zone, parsing dates in a single language, and having all\nother configuration parameters set to a single value that doesn't\nchange over the course of the program.\n\nWhenever this is the case, you can use the methods listed in this\nsection to create any number of Date::Manip objects. It will\nautomatically optimize the use of cached data to get the best\nperformance.\n\nIf you do need to work with multiple different configurations (such as\nparsing dates from multiple languages), please refer to the next\nsection \"WORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATION)\".\n\nWorking with high level objects\nThe most common situation is one where you will need to use one or\nmore high level objects (Date, Delta, or Recur objects). In\naddition, you may want to use the lower level (Base or TZ) objects.\n\nThe first thing you should do is to create your initial object.\nCreate the highest level object you will be using. For example if\nyou will be working with dates, create the first date object with:\n\n$date = new Date::Manip::Date;\n\nThe next step is to set the configuration values. Use the config\nmethod to do this:\n\n$date->config(ARGS);\n\nAlthough you can call the config method later, it is strongly\nsuggested that the configuration be set soon after the initial\nobject is created and not altered later. Every time you alter the\nconfiguration, 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\nobjects, 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\nwith 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\nDate::Manip::Obj document.\n\nWORKING WITH DATE::MANIP OBJECTS (MULTIPLE CONFIGURATION)\nOccasionally, it may be useful to have multiple sets of configurations.\nIn order to do this, multiple Date::Manip::Base objects must be created\n(each with their own set of configuration options), and then new\nDate::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\nlanguage. If you need to parse dates from two (or more) languages,\na Date::Manip::Base object needs to be created for each one. This\ncould 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\nwith English. Additional objects created from the second will work\nin Spanish.\n\nBusiness modes for different countries and/or businesses\nIf you are doing business mode calculations (see Date::Manip::Calc)\nfor two different businesses which have different holiday lists,\nwork weeks, or business days, you can create different objects\nwhich read different config files (see Date::Manip::Config) with\nthe appropriate description of each.\n\nThe primary issue when dealing with multiple configurations is that it\nis necessary for the programmer to manually keep track of which\nDate::Manip objects work with each configuration. For example, refer to\nthe 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\nDate::Manip::TZ object, and a Date::Manip::Date object). The\nDate::Manip::Base object has the configuration set to contain the\nvalue(s) passed in as the final list reference argument.\n\nThe second line creates 3 new objects (a second Date::Manip::Base\nobject, a second Date::Manip::TZ object, and a second Date::Manip::Date\nobject). Since a list reference containing config variables is passed\nin, a new Date::Manip::Base object is created, rather than reusing the\nfirst one. The second Date::Manip::Base object contains all the config\nfrom the first, as well as the config variables passed in in the list\nreference argument.\n\nThe third line creates another Date::Manip::Date object which uses the\nfirst Date::Manip::Base and Date::Manip::TZ objects embedded in it.\n\nThe fourth line creates another Date::Manip::Date object which uses the\nsecond Date::Manip::Base and Date::Manip::TZ objects embedded in it.\n\nMost of the time there will only be one set of configuration options\nused, so this complexity is really for a very special, and not widely\nused, bit of functionality.\n\nWORKING WITH DATE::MANIP OBJECTS (ADDITIONAL NOTES)\nobject reuse\nIn order to create additional Date::Manip objects, a previously\ncreated object should be passed in as the first argument. This will\nallow the same Base object to be embedded in both in order to\nmaximize data reuse of the cached intermediate results, and will\nresult in much better 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\nDate::Manip::Base object is quite large. It stores a large number\nof precompile regular expressions for language parsing, and as date\noperations are done, intermediate results are cached which can be\nreused later to improve performance. The Date::Manip::TZ object is\neven larger and contains information about all known time zones\nindexed several different ways (by offset, by abbreviation, etc.).\nAs 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,\nrather than to create lots of copies of them. It should be noted\nthat because these objects are embedded in each of the high level\nobject (Date::Manip::Date for example), it makes these objects\nappear quite large.\n\nThe second reason to reuse Date::Manip::Base objects is\nperformance. Since intermediate results are cached there, many date\noperations only need to be done once and then they can be reused\nany number of times. In essence, this is doing the same function as\nthe Memoize module, but in a more efficient manner. Memoize caches\nresults for function calls. For Date::Manip, this would often work,\nbut if you change a config variable, the return value may change,\nso Memoize could cause things to break. In addition, Memoize caches\nprimarily at the function level, but Date::Manip stores caches\nintermediate results wherever performance increase is seen. Every\ntime 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\nsignificant impact, I don't cache it.\n\nBecause the caching is quite finely tuned, it's much more efficient\nthan using a generic (though useful) tool such as Memoize.\n\nconfiguration changes\nAs a general rule, you should only pass in configuration options\nwhen the first object is created. In other words, the following\nbehavior 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\na configuration change is made, some of the cached data must be\ndiscarded necessitating those results to be recalculated.\n\nIf you really need to change configuration in the middle of\nexecution, it is certainly allowed of course, but if you can define\nthe configuration once immediately after the object is first\ncreated, and then leave the configuration alone, performance will\nbe optimized.\n",
            "subsections": []
        },
        "BUGS AND QUESTIONS": {
            "content": "Please refer to the Date::Manip::Problems documentation for information\non submitting bug reports 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\nunder the same terms as Perl itself.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Sullivan Beck (sbeck@cpan.org)\n\nperl v5.32.1                      2021-11-20         Date::Manip::Objects(3pm)",
            "subsections": []
        }
    },
    "summary": "Date::Manip::Objects - A description of the various Date::Manip objects",
    "flags": [],
    "examples": [],
    "see_also": []
}