{
    "mode": "perldoc",
    "parameter": "Date::Manip::Date",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADate/json",
    "generated": "2026-06-11T10:29:32Z",
    "synopsis": "use Date::Manip::Date;\n$date = new Date::Manip::Date;",
    "sections": {
        "NAME": {
            "content": "Date::Manip::Date - Methods for working with dates\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Date::Manip::Date;\n$date = new Date::Manip::Date;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module works specifically with date objects.\n\nAlthough the word date is used extensively here, it is actually somewhat misleading. Date::Manip\nworks with the full calendar date (year, month, day, and week when appropriate), time of day\n(hour, minute, second), and time zone. It doesn't work with fractional seconds.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "base\nconfig\nerr\nisdate\nisdelta\nisrecur\nnew\nnewconfig\nnewdate\nnewdelta\nnewrecur\ntz  Please refer to the Date::Manip::Obj documentation for these methods.\n\ncalc\n$date2 = $date->calc($delta [,$subtract]);\n$delta = $date->calc($date2 [,$subtract] [,$mode]);\n\nPlease refer to the Date::Manip::Calc documentation for details.\n\ncmp\n$val = $date1->cmp($date2);\n\nThis compares two different dates (both of which must be valid date objects). It returns -1,\n0, or 1 similar to the cmp or <=> operators in perl. The comparison will automatically\nhandle time zone differences between the two dates (i.e. they will be sorted in order as\nthey appear in the GMT zone).\n\nA warning is printed if either of the date objects does not include a valid date.\n\ncomplete\n$flag = $date->complete([$field]);\n\nThis tests the date stored in the object to see if it is complete or truncated (see below\nfor a discussion of this).\n\nIf no $field is passed in, it returns 1 if the date is complete, or 0 if it was truncated\nand default values have been supplied.\n\nIf $field is passed in, it may be one of: m, d, h, mn, s . It will return 1 if the value for\nthat field was specified, or 0 if a default was used.\n\nconvert\n$err = $date->convert([$zone]);\n\nThis converts the date stored in the object to a different time zone. $zone can be the name\nof a time zone. If it is not passed in, the date is converted to the local time zone.\n\nholiday\n$name = $date->holiday();\n@name = $date->holiday();\n$name = $date->event();\n\nThis returns the name of the holiday if $date is a holiday. If $date is not a holiday, undef\nis returned. If $date is an unnamed holiday, an empty string is returned.\n\nIn scalar context, holiday returns the name of one holiday that occurs on that date (the one\nfirst defined in the config file). In list context, it returns all holidays on that date.\n\ninput\n$str = $date->input();\n\nThis returns the string that was parsed to form the date.\n\nisbusinessday\n$flag = $date->isbusinessday($checktime);\n\nThis returns 1 if $date is a business day.\n\n$checktime may be passed in. If it is non-zero, the time is checked to see if the date is a\nbusiness day and falls within work hours.\n\nlistholidays\n@date = $date->listholidays([$y]);\n\nThis returns a list of Date::Manip::Date objects containing all dates during a year which\nare holidays. The times will all be 00:00:00.\n\nIf $y is not passed in, it will list the holidays in the same year as the date stored in\n$date (if any) or in the current year otherwise.\n\nlistevents\n@list = $date->listevents(       [$format] );\n@list = $date->listevents(0      [,$format]);\n@list = $date->listevents($date1 [,$format]);\n\nThis returns a list of events. Events are defined in the Events section of the config file\n(discussed in the Date::Manip::Holidays manual).\n\nIn the first form, a list of all events active at the precise time stored in $date will be\nreturned.\n\nIf the first argument evaluates to 0, a list of all events active at any time during that\nday (Y,M,D) are returned.\n\nIf the first argument is another date object, all events that are active at any time between\nthe two dates (inclusive) are returned.\n\nBy default, the list returned is of the form:\n\n( [START, END, NAME],\n[START, END, NAME],\n...\n)\n\nwhere START is a date object when an event starts, END is a date object when it ends, and\nNAME is the name of the event. Note that START and END are the actual start and end date of\nthe event and may be outside the range of dates being examined (though the event will\nobviously overlap the range or it wouldn't be included in the list).\n\nIf $format is included, it can specify an alternate format for the output. Currently, the\nonly supported format is named \"dates\" and it returns a list in the form:\n\n( [DATE1, NAME1a, NAME1b, ...],\n[DATE2, NAME2a, NAME2b, ...],\n...\n)\n\nThis includes a list of all dates during the range when there is a change in what events are\nactive. DATE1 will always be the start of the range being considered, and (NAME1a, NAME1b,\n...) are the list of all events that will be active at that time. At DATE2, the list of\nactive events changes with (NAME2a, NAME2b, ...) being active.\n\nIt is quite possible that a date be included which has no active events, and in that case,\nthe list of names will be empty.\n\nnearestbusinessday\n$date->nearestbusinessday([$tomorrowfirst]);\n\nThis looks for the work day nearest to $date. If $date is a work day, it is left unmodified.\nOtherwise, it will look forward or backwards in time 1 day at a time until a work day is\nfound. If $tomorrowfirst is non-zero (or if it is omitted and the config variable\nTomorrowFirst is non-zero), we look to the future first. Otherwise, we look in the past\nfirst. In other words, in a normal week, if $date is Wednesday, $date is returned. If $date\nis Saturday, Friday is returned. If $date is Sunday, Monday is returned. If Wednesday is a\nholiday, Thursday is returned if $tomorrowfirst is non-nil or Tuesday otherwise.\n\nnextbusinessday\nprevbusinessday\n$date->nextbusinessday($off [,$checktime]);\n$date->prevbusinessday($off [,$checktime]);\n\nThe nextbusinessday method sets the given date to $off (which can be a positive integer or\nzero) business days in the future. The prevbusinessday method sets the date to $off\nbusiness days in the past.\n\nFirst, $date is tested. If $checktime is nonzero, the date must fall on a business date, and\nduring business hours. If $checktime is zero, the time check is not done, and the date must\nsimply fall on a business date.\n\nIf the check fails, the date is moved to the start of the next business day (if $checktime\nis nonzero) or the next business day at the current time (if $checktime is zero). Otherwise,\nit is left unmodified.\n\nNext, if $off is greater than 0, the day $off work days from now is determined.\n\nOne thing to note for the prevbusinessday method is that if $date check fails, the date is\nset to the next business date, exactly like nextbusinessday. In other words, if $date is\nnot a business day, the call:\n\n$date->prevbusinessday(0 [,$checktime]);\n\nmoves $date forward in time instead of backward which is nonintuitive, but you just have to\nthink of day 0 as being the next business day if $date is not a business day.\n\nAs a result, the following two calls ALWAYS give the same result:\n\n$date->nextbusinessday(0 [,$checktime]);\n$date->prevbusinessday(0 [,$checktime]);\n\nno matter what date is stored in $date.\n\nparse\n$err = $date->parse($string [,@opts]);\n\nThis parses a string which should include a valid date and stores it in the object. If the\nstring does not include a valid date, an error is returned. Use the err method to see the\nfull error message.\n\nA full date may include a calendar date (year, month, day), a time of day (hour, minute,\nsecond), and time zone information. All of this can be entered in many different formats.\n\nFor information on valid date formats, refer to the section VALID DATE FORMATS. For\ninformation on valid time zone information, refer to the section VALID TIME ZONE FORMATS.\n\nIf no time zone information is included in the date, it is treated as being in the local\ntime zone.\n\nIf time zone information is included, the date will be kept in that time zone, and all\noperations will be done in that time zone. The convert method can be used to change the time\nzone to the local time zone, or to another time zone.\n\nSome things to note:\n\nAll strings are case insensitive. \"December\" and \"DEceMBer\" are equivalent.\n\nWhen a part of the date is not given, defaults are used. This is described below in the\nsection \"Complete vs. truncated dates and times\".\n\nThe year may be entered as 2 or 4 digits. If entered as 2 digits, it will be converted to a\n4 digit year. There are several ways to do this based on the value of the YYtoYYYY config\nvariable. Refer to the Date::Manip::Config documentation for more details.\n\nDates are always checked to make sure they are valid.\n\nIf any other arguments are passed in, they act as options which may improve the speed of\nparsing. These include:\n\nnoiso8601  Do not try to parse the\ndate as an ISO 8601 date\nor time.\nnodow      Do not try to parse a\nday-of-week (Monday) in\nthe string.\nnocommon   Do not try to parse the\ndate using the formats\nin the \"Common date\nformats\" section.\nnoother    Do not try to parse the\ndate using the \"Less common\ndate formats\" or a time\nusing the \"Other time\nformats\".\nnospecial  Do not try to parse the\ndate using the \"Special\ndate strings\" formats\nor a time using the\n\"Special time strings\"\nformats, or as a\ncombined date/time using\nthe \"Additional combined\ndate and time\" formats.\nnodelta    Do not treat deltas as\na date relative to now.\nnoholidays Do not parse holiday\nnames as dates.\n\nparsedate\n$err = $date->parsedate($string [,@opts]);\n\nThis parses a string which contains a valid date and sets the date part of the object.\n\nIf the object contained a valid date, the time is kept unchanged. If the object did NOT\ncontain a valid date, a time of 00:00:00 is used.\n\n@opts can be any of the strings described in the parse method above.\n\nparsetime\n$err = $date->parsetime($string [,@opts]);\n\nThis parses a string and sets the time portion of $date to contain it.\n\nIf the object contained a valid date, the Y/M/D portion is left unchanged. Otherwise, the\ncurrent date is used.\n\n@opts can be 'noiso8601' or 'noother'.\n\nparseformat\n$err          = $date->parseformat($format,$string);\n($err,%match) = $date->parseformat($format,$string);\n\nThis will parse a date contained in $string based on explicit format information contained\nin $format.\n\nIf the format is invalid, $err will contain an error message. If the format is valid, but\nstring doesn't match, an error code of 1 is returned.\n\nIf called in array context, a hash will be returned containing %+. This is primarily useful\nif the $format string contains some named capture groups that you define. This is discussed\nbelow.\n\n$format is a string containing a regular expression with some special directives (based on\nthe printf directives). These directives are turned into regular expression components, and\nthen the entire string is turned into a regular expression which, if $string matches it,\nwill return the date.\n\nThe directives available are identical to the printf directives. So, if your $format string\ncontains the directive '%Y', it will match a 4-digit year.\n\nAll of the printf directives are available here with a few caveats:\n\n%l        This directive is NOT available.\n\n%b,%h,%B  These will all match a month name or abbreviation.\n\n%v,%a,%A  These will all match a day name or abbreviation.\n\n%z,%Z,%N  These will match any time zone string.\n\n%n        Multi-line matching is not currently supported,\nso this directive is not allowed.\n\n%x        All format directives are converted to a regular\nexpression and then cached (so that a format\ncan be reused without the penalty of doing the\nconversion to a regular expression with each use).\nAs a result, if you need to set the DateFormat config\nvariable (which determines the meaning of the %x\ndirective), it must be done before a format string\ncontaining %x is used. If the DateFormat config variable\nis set afterwards, the format string will reflect the\nold, NOT THE NEW, value of DateFormat.\n\nThe format string may not over-specify the date. In other words, you may not include both a\n%y and %Y directive or both a %j and %m directive.\n\nA valid format string will specify any of the following sets of data:\n\nRequired          Optional\n\nM D H Mn S        Y Zone Day-of-week\nM D H Mn          Y Zone Day-of-week\nM D               Y Zone Day-of-week\nH Mn S            Zone\nH Mn              Zone\n\nFor example, if you had a date stored as:\n\nYYYY.MM-DD\n\nyou could match it using the following:\n\n$date->parseformat('%Y\\\\.%m\\\\-%d',$string);\n\nIf you wanted to extract the date from an apache log line:\n\n10.11.12.13 - - [17/Aug/2009:12:33:30 -0400] \"GET /favicon.ico ...\n\nyou could use:\n\n$date->parseformat('.*?\\\\[%d/%b/%Y:%T %z\\\\].*',$line);\n\nWhen matching months, days, and hours, there are two directives that could be used (for\nnumerical versions). For the month, you may use %m or %f. If your date is known to have a\ntwo-digit month, you should use %m. If it contains a one- or two-digit month, you must use\n%f (and it is safe to use %f for two-digit months). Similarly, for days, you can use %d or\n%e and for hours you can use %H or %k. In both cases, the first can only be used if you are\nguaranteed a 2-digit value.\n\nIn your format string, you may use capture groups (or back references to them) in the\nregular expression using all of the rules of normal regular expressions. Since Date::Manip\nuses named capture groups internally, it is suggested that you also use named groups. Mixing\nnumbered and named groups will work... but it'll be entirely up to you to keep track of what\nnumbers refer to which capture groups.\n\nEvery printf directive adds one or more named capture groups to the regular expression. If\nyou use named groups in the format string, they must not conflict with the ones used\ninternally, or else the date will probably not be parsed correctly.\n\nThe following named capture groups are used internally:\n\ny\nm\nd\nh\nmn\ns\nmonname\nmonabb\ndowname\ndowabb\ndowchar\ndownum\ndoy\nnth\nampm\nepochs\nepocho\ntzstring\noff\nabb\nzone\ng\nw\nl\nu\n\nTo be safe, it is suggested that any additional named capture groups introduced by the\nprogrammer start with a capital letter. This is guaranteed to never conflict with any\nexisting, or future named capture groups.\n\nIn order to get access to the values stored in the additional named capture groups, the\nparseformat function must be called in list context, and the %+ array will be returned as\nthe second value.\n\nAs an example:\n\n$string = \"before 2014-01-25 after\";\n($err,%m) = $date->parseformat('(?<PRE>.*?)%Y-%m-%d(?<POST>.*)',$string);\n\nwould return a hash (%m) with the following key/value pairs:\n\n'PRE'  => 'before '\n'POST' => ' after'\n\nprev\nnext\nThe prev method changes the date to the previous (or current) occurrence of either a day of\nthe week, a certain time of day, or both. The next method changes the date to the next (or\ncurrent) occurrence. The examples below illustrate the prev method, but the next one is\nidentical in operation.\n\nThere are two different ways to use this method. The first is to pass in a day of week and\npossibly a time:\n\n$err = $date->prev($dow, $curr [,$time]);\n\nIf $curr = 0, this means to look for the previous occurrence of the day of week, and set the\ntime to the value passed in (or current time if no time was passed in). The day is ALWAYS\nless than the current day. If the current day is the same day of week as $dow, then the date\nreturned will be one week earlier.\n\nIf $curr = 1, it means to look for the current or previous occurrence of the day of week,\nand set the time to the value passed in (or 00:00:00 if none was passed in). If the current\nday of week is the same as $dow, the date will remain unchanged. Since the time is then set,\nthe new date may actually occur after the original date depending on the value of $time.\n\nIf $curr = 2, it means to look for the last time (not counting now) that the day of week at\nthe given time occurred. The date may be the same as the original date.\n\n$time may be a list reference of [H,MN,S], [H,MN], or [H].\n\nThe following examples should illustrate the use of this function.\n\nOriginal Date = Fri Nov 22 18:15:00\n\ndow      curr   time       new date\n\n4 (Thu)  0/1/2  undef      Thu Nov 21 00:00:00\n4        0/1/2  [12,30,0]  Thu Nov 21 12:30:00\n\n5 (Fri)  0/2    undef      Fri Nov 15 18:15:00\n5        1      undef      Fri Nov 22 18:15:00\n\n5        0      [12,30,0]  Fri Nov 15 12:30:00\n5        1/2    [12,30,0]  Fri Nov 22 12:30:00\n\n5        0/2    [19,30,0]  Fri Nov 15 19:30:00\n5        1      [19,30,0]  Fri Nov 22 19:30:00\n\nThe second way to use this method is by passing in undef for the day of week.\n\n$err = $date->prev(undef,$curr,$time);\n\nIn this case, a time is required and it must be a list reference of 3 elements: [H, MN, S].\nAny or all of the elements may be undef.\n\nThe new date is the previous occurrence of the time.\n\nIf you define hours, then minutes and seconds may be defined, or default to 0 and you are\nlooking for a previous time that the specified time (HH:00:00) occurred (which might be as\nmuch as 24 hours in the past).\n\nIf hours are undefined and minutes are defined, then seconds may be defined, or default to\n0, and you are looking for the last time the minutes/seconds (MN:SS) appeared on the digital\nclock, which will be sometime in the past hour.\n\nFinally, if hours and minutes are undefined, seconds must be defined (or default to zero)\nand the last time that that second occurred will be returned (which will be sometime in the\npast minute).\n\nIf $curr is non-zero, the current time is returned if it matches the criteria passed in, so\nthe returned value will be now or in the past. If $curr is zero, the time returned will\ndefinitely be in the past.\n\nDATE = Fri Nov 22 18:15:00\n\ncurr  hr     min    sec      returns\n0/1   18     undef  undef    Nov 22 18:00:00\n0/1   18     30     0        Nov 21 18:30:00\n0     18     15     undef    Nov 21 18:15:00\n1     18     15     undef    Nov 22 18:15:00\n0     undef  15     undef    Nov 22 17:15:00\n1     undef  15     undef    Nov 22 18:15:00\n\nprintf\n$out = $date->printf($in);\n@out = $date->printf(@in);\n\nThis takes a string or list of strings which may contain any number of special formatting\ndirectives. These directives are replaced with information contained in the date. Everything\nelse in the string is returned unmodified.\n\nA directive always begins with '%'. They are described in the section below in the section\nPRINTF DIRECTIVES.\n\nsecssince1970GMT\n$secs = $date->secssince1970GMT();\n\nThis returns the number of seconds that have elapsed since Jan 1, 1970 00:00:00 GMT\n(negative if the date is earlier).\n\nThe reverse is also allowed:\n\n$err = $date->secssince1970GMT($secs);\n\nwhich sets the date to $secs seconds from Jan 1, 1970 00:00:00 GMT in the local time zone.\n\nset\n$err = $date->set($field,@vals [,$isdst]);\n\nThis explicitly sets one or more fields in a date.\n\n$field can be any of the following:\n\n$field   @vals\n\nzone     [ZONE]         ZONE can be any zone or alias\n\nzdate    [ZONE,]DATE    sets the zone and entire date\n\ndate     DATE           sets the entire date\n\ntime     TIME           sets the entire time\n\ny        YEAR           sets one field\nm        MONTH\nd        DAY\nh        HOUR\nmn       MINUTE\ns        SECOND\n\nHere, DATE is a list reference containing [Y,M,D,H,MN,S] and TIME is a list reference\ncontaining [H,MN,S].\n\nZONE is optional (it defaults to the local zone as defined either by the system clock, or\nthe SetDate or ForceDate config variables). If it is passed in, it can be any zone name,\nabbreviation, or offset. An offset can be expressed either as a valid offset string, or as a\nlist reference. Refer to the join/split functions of Date::Manip::Base for information on\nvalid offset strings.\n\nAn optional last argument is $isdst (which must be 0 or 1) is included when setting a date\nwhich could be in either standard time or daylight saving time. It is ignored in all other\nsituations. If it is not included, and the resulting date could be in either, it will\ndefault to standard time.\n\nThe $date object must contain a valid date (unless the entire date is being set with $field\nset to either \"zdate\" or \"date\").\n\nIf $field is \"zone\", the time zone of the date will be set. If ZONE is not passed in, it\nwill be set to the local time zone. When setting the time zone, no conversion is done!\nWhatever date and time is stored in the $date object prior to this remains unchanged...\nexcept it will be that date and time in the new time zone.\n\nIf $field is \"zdate\", the entire date and time zone is set. If ZONE is not passed in, it is\nset to the local time zone.\n\nIf $field is \"date\", the entire date will be set, but the time zone of the date will not be\nchanged.\n\nIf $field is \"time\", or one of the individual fields, only those fields will be modified.\n\nAn error is returned if an invalid argument list is passed in, or if the resulting date is\nchecked and found to be invalid.\n\nvalue\n$val = $date->value([$type]);\n@val = $date->value([$type]);\n\nThese return the value of the date stored in the object.\n\nIn scalar context, a printable string in the form YYYYMMDDHH:MN:SS is returned. In list\ncontext, a list is returned of (Y,M,D,H,MN,S).\n\nIf $type is omitted, the date is returned in the time zone it was parsed in.\n\nIf $type is \"local\", it is returned in the local time zone (which is either the system time\nzone, or the zone specified with the SetDate or ForceDate config variables).\n\nIf $type is \"gmt\", the date is returned in the GMT time zone.\n\nAn empty string or list is returned in the case of an error (and an error code is set).\n\nweekofyear\n$wkno = $date->weekofyear([$first]);\n\nThis figures out the week number. If $first is passed in, it must be between 1 and 7 and\nrefers to the first day of the week. If $first is not passed in, the FirstDay config\nvariable is used.\n\nNOTE: This routine should only be called in rare cases. Use printf with the %W, %U, %J, %L\nformats instead. This routine returns a week between 0 and 53 which must then be \"fixed\" to\nget into the ISO 8601 weeks from 1 to 53. A date which returns a week of 0 actually belongs\nto the last week of the previous year. A date which returns a week of 53 may belong to the\nfirst week of the next year.\n",
            "subsections": []
        },
        "ISSUES WITH PARSING DATES": {
            "content": "The following issues may occur when parsing dates that should be understood to make full use of\nthis module.\n\nComplete vs. truncated dates and times\nDate formats are either complete or truncated. A complete date fully specifies the year,\nmonth, and day and a complete time fully specifies the hour, minute, and second.\n\nIt should be understood that in many instances, the information may be implied rather than\nexplicitly stated, but it is still treated as complete.\n\nFor example, the date \"January 3\" is complete because it implies the current year.\n\nA truncated calendar date or time does not include information about some of the fields.\nDate::Manip will never work with a partial date or time, so defaults will be supplied.\n\nFor example, the date \"2009-01\" is missing a day field, so a default will be used. In this\ncase, the day will be the 1st, so this is equivalent to \"Jan 1st 2009\". If only the year is\ngiven, it will default to Jan 1.\n\nIf the time, or any of it's components is missing, they default to 00. So the time \"12:30\"\nand \"12:30:00\" are equivalent.\n\nThe \"complete\" method can be used to check what type of date was parsed, and which values\nwere specified (either explicitly or implied) and which were provided as a default. It\nshould be noted that there is no way to differentiate between an explicit and implied value.\n\nA string with a date and/or time may consist of any of the following:\n\na complete date and a time (complete or truncated)\na truncated date with no time\na time (complete or truncated) with no date\n\nIn other words, the date \"Jan 2009 12:30\" is not valid since it consists of a time with a\ntruncated date.\n",
            "subsections": []
        },
        "VALID TIME ZONE FORMATS": {
            "content": "When specifying a time zone, it can be done in three different ways. One way is to specify the\nactual time zone. The second is to supply a valid time zone abbreviation. The third is to\nspecify an offset (with an optional abbreviation). The following dates illustrate the these\nformats.\n\nThe timezone information always follows the time immediately, and may only be included if a time\nis included. The following examples use an ISO 8601 format for the date/time, but any of the\nother date and time formats may be used.\n\nThe first way to specify the time zone is to specify it by complete name (or using one of the\nstandard aliases):\n\n2001-07-01-00:00:00 America/NewYork\n\nAlthough this is unambiguous when it comes to determining the time zone, the time is ambiguous\nin most zones for one hour of the year. When a time change occurs during which the clock is\nmoved back, the same wall clock time occurs twice.\n\nFor example, in America/NewYork, on Sunday, Nov 2, 2008, at 02:00 in the morning, the clock was\nset back to 01:00. As a result, the date Nov 2, 2008 at 01:30 is ambiguous. It is impossible to\ndetermine if this refers to the 01:30 that occurred half an hour before the time change, or the\none 30 minute after the change.\n\nIn practice, if this form is used, the date will be assigned to standard time, meaning that\nthere will be some times (typically 1 hour per year) which cannot be expressed this way. As\nsuch, this method is discouraged.\n\nThe second way to specify the time zone, which is the most common, is to use a time zone\nabbreviation:\n\n2001-07-01-00:00:00 EDT\n\nUnfortunately, the abbreviation does not uniquely determine the time zone except in a few cases.\nIn order to assign a time zone, Date::Manip will refer to a list of all time zones which use the\nabbreviation. They will be tested, in the order given in the Date::Manip::Zones documentation,\nand the first match (i.e. the one in which the given date/time and abbreviation are valid)\ndetermines the time zone which will be used. A great deal of effort has been made to ensure that\nthe most likely time zone will be obtained (i.e. the most common time zones are tested before\nless common ones), so in most cases, the desired results will be obtained.\n\nIf the default order does not yield the desired time zone, the order of testing can be modified\nusing the abbrev method described in the Date::Manip::TZ documentation.\n\nAlthough the time zone is ambiguous, the date is not, since only time zones for which the date\nare valid will be used.\n\nThe third way to specify the time zone is by specifying an offset and an optional abbreviation:\n\n2001-07-01-00:00:00 -04\n2001-07-01-00:00:00 -0400\n2001-07-01-00:00:00 -040000\n2001-07-01-00:00:00 -04:00\n2001-07-01-00:00:00 -04:00:00\n\n2001-07-01-00:00:00 -04 (EDT)\n2001-07-01-00:00:00 -0400 (EDT)\n2001-07-01-00:00:00 -040000 (EDT)\n2001-07-01-00:00:00 -04:00 (EDT)\n2001-07-01-00:00:00 -04:00:00 (EDT)\n\n2001-07-01-00:00:00 -04 EDT\n2001-07-01-00:00:00 -0400 EDT\n2001-07-01-00:00:00 -040000 EDT\n2001-07-01-00:00:00 -04:00 EDT\n2001-07-01-00:00:00 -04:00:00 EDT\n\nThe offset almost never sufficient to uniquely determine the time zone (and it is not even\nguaranteed that both the offset and abbreviation will, though in practice, it is probably\nsufficient). In this instance, the time zone will be determined by testing all time zones which\nhave the given offset (and abbreviation if it is included) until one is found which matches both\npieces of information. For more information about how this testing is done, refer to the\ndefzone method of the Date::Manip::TZ documentation.\n",
            "subsections": []
        },
        "VALID DATE FORMATS": {
            "content": "There are several categories of date formats supported by Date::Manip. These are strings which\nspecify only the year/month/day fields.\n\nThese formats explicitly set the date, but not the time. These formats may be combined with a\ntime string (as specified below) to set both the date and time. If this is not done, the default\ntime is determined by the DefaultTime config variable.\n\nISO 8601 dates\nThe preferred date formats are those specified by ISO 8601. The specification includes valid\ncalendar date and valid time formats. Date::Manip will handle all of these formats, but does\nnot require that the dates rigidly adhere to the specification since the ultimate goal of\nDate::Manip is to handle dates as they are represented in real life and some common\nvariations exist which are similar to, but not identical to, those from the specification.\n\nA calendar date includes the following fields:\n\nCC    2-digit representation of the century\nYY    2-digit representation of the year in\na century\nMM    2-digit representation of a month\nDD    2-digit representation of a day of month\nDoY   3-digit representation of a day of year\n(001-366)\nWww   the character \"W\" followed by a 2-digit\nweek of the year (01-53)\nD     the day of the week (1-7)\n\nThe following date formats are considered complete by Date::Manip. In the following, the\ndate Thu Mar 5 2009 is used as an example. This is the 64th day of the year. Thu is the 4th\nday of the week. The week starting Mon, Mar 2 is the 10th week of the year (according the\nthe ISO 8601 definition). Obviously, some of the formats are only valid when used at some\ntimes. For example, the format --MMDD refers to a month and day in the current year, so the\ndate Mar 5, 2009 can only be specified using this format during 2009.\n\nFormat      Notes   Examples\n\nCCYYMMDD            20090305\nCCYY-MM-DD          2009-03-05\n\nYYMMDD      1,2,4   090305\nYY-MM-DD            09-03-05\n\n-YYMMDD     3,4     -090305\n-YY-MM-DD           -09-03-05\n\n--MMDD      1       --0305\n--MM-DD             --03-05\n\n---DD       1       ---05\n\n\nCCYYDoY             2009064\nCCYY-DoY            2009-064\n\nYYDoY       1,4     09064\nYY-DoY              09-064\n\n-YYDoY      3,4     -09064\n-YY-DoY             -09-064\n\n-DoY        1       -064\n\n\nCCYYWwwD            2009W104\nCCYY-Www-D          2009-W10-4\n\nYYWwwD      1,4     09W104\nYY-Www-D            09-W10-4\n\n-YYWwwD     3,4     -09W104\n-YY-Www-D           -09-W10-4\n\n-YWwwD      1       -9W104\n-Y-Www-D            -9-W10-4\nY is the year (0-9) in\ncurrent decade\n\n-WwwD       1       -W104\n-Www-D              -W10-4\n\n-W-D        1       -W-4\nD is day (1-7) in\ncurrent week\n\n---D        1       ---4\nsame as -W-D\n\nThe following date formats are truncated:\n\nCCYY-MM     2       2009-03   (2009-03-01)\n\nCCYY                2009      (2009-01-01)\n\nCC          2       20        (2000-01-01)\n\n-YYMM       4       -0903\n-YY-MM              -09-03\n\n-YY         4       -09\n\n--MM                --03\n\nCCYYWww             2009W10\nCCYY-Www            2009-W10\n\nYYWww       4       09W10\nYY-Www              09-W10\n\n-YYWww      3,4     -09W10\n-YY-Www             -09-W10\n\n-Www                -W10\n\nNotes:\n\n1 These formats are considered truncated in the standard, but since they do include (or\nimply, using the current date for defaults) all of the fields, and since they do not\nintroduce any parsing complexities, the standard is relaxed, and they are treated as\ncomplete.\n\n2 These formats are treated differently than in Date::Manip 5.xx as described below.\n\n3 These formats are not defined in the ISO 8601 spec, but are added for the sake of\ncompleteness since they do not add any parsing incompatibilities.\n\n4 Formats where the century is not given are described as a year in the current century in\nthe specification. Date::Manip treats this more generically using the YYtoYYYY config\nvariable. This will be used to determine how to determine the full year.\n\nDate::Manip 5.xx handled ISO 8601 dates in a less rigid fashion, and deviated from the\nspecification in several formats. As of 6.00, the specification is followed much more\nclosely so that all of the date formats included in it should produce valid dates. This\nchanges, in a backwards incompatible way, the way a few strings will be interpreted as\ndates.\n\nAs of 6.00, a two-digit date will be treated as CC. Previously, it was treated as YY.\n\nA six-digit date will be treated as YYMMDD. Previously, it was treated as YYYYMM.\n\nPreviously, dashes were treated as optional in many cases. According to the specification,\ndates may be written in expanded form (with all dashes present) or abbreviate form (with no\ndashes). As of 6.00, this is the behavior, so the formats: YYMMDD and YY-MM-DD are allowed,\nas per the specification, but the format YY-MMDD is NOT allowed (though it was previously).\n\nThe Www-D formats require a bit of explanation. According to the specification, the date:\n\n1996-w02-3\n\nrefers to the day with an ordinal number of 3 within the calendar week in the 2nd week of\n1996.\n\nIn the specification, the days of the week are numbered from 1 to 7 (Monday to Sunday), and\nthe week always begins on Monday, so day 1 (Monday) is always the first day of the week, day\n2 (Tuesday) is always the second day of the week, etc.\n\nIn Date::Manip, the constraint that the week must start with Monday is relaxed, allowing the\nweek to begin with Sunday (a far more common start of the week in calendars, at least in\nsome parts of the world).\n\nThis presents a problem though in that the above date could be interpreted as Wednesday (day\n3) of the 2nd week of 1996, or as the 3rd day of the 2nd week of 1996 (which would normally\nbe Wednesday, but would be Tuesday if the week begins on Sunday).\n\nAs of Date::Manip 6.00, the above date will be interpreted as the 3rd day of the 2nd week.\nThis is a reversal from Date::Manip 5.xx, but I believe is what the specification would\nrequire. For more information, refer to the Date::Manip::Changes document.\n\nCommon date formats\nDate::Manip supports a number of common date formats. The following fields may be included\nin a date:\n\nYY    2-digit representation of the year\nYYYY  4-digit representation of the year\nM     1- or 2- digit representation of the month\nMM    2-digit representation of the month\nD     1- or 2- digit representation of the day\nDD    2-digit representation of the day\nmmm   The abbreviated or full month name (i.e. Jan)\n\nThe following date formats are supported:\n\nFormat      Notes   Examples\n\nM/D         1,2,3   3/5\nM/D/YY      1       3/5/09\nM/D/YYYY    1       3/5/2009\n\nYYYY/M/D            2009/3/5\n\nmmm/D               Mar/5\nmmm/D/YY            Mar/5/09\nmmm/D/YYYY          Mar/5/2009\nD/mmm               5/Mar\nD/mmm/YY            5/Mar/09\nD/mmm/YYYY          5/Mar/2009\nYYYY/mmm/D          2009/Mar/5\n\nmmmD                Mar5\nmmmDDYY     4       Mar0509\nmmmDDYYYY           Mar052009\nDmmm                5Mar\nDmmmYY              5Mar09\nDmmmYYYY            5Mar2009\nYYYYmmmD            2009Mar5\n\nmmmD YY             Mar5 09\nmmmD YYYY           Mar5 2009\nDmmm YY             5Mar 09\nDmmm YYYY           5Mar 2009\n\nmmm/D YY            Mar/5 09\nmmm/D YYYY          Mar/5 2009\nD/mmm YY            5/Mar 09\nD/mmm YYYY          5/Mar 2009\n\nYY   mmmD           09   Mar5\nYYYY mmmD           2009 Mar5\nYY   Dmmm           09   5Mar\nYYYY Dmmm           2009 5Mar\n\nYY   mmm/D          09   Mar/5\nYYYY mmm/D          2009 Mar/5\nYY   D/mmm          09   5/Mar\nYYYY D/mmm          2009 5/Mar\n\nYYYY:MM:DD          2010:01:15 (EXIF format)\n\nmmmYYYY     4       Jun 2010\nYYYYmmm     4       2010 June\nmmm/YYYY    4       Jun/2010\nYYYY/mmm    4       2010/Jun\n\nIn the formats above, the slash (/) can be replace by any of the valid separators:\nwhitespace, slash (/), period (.), or dash (-). The dash, though allowed, is discouraged\nsince it may conflict with an ISO 8601 format. For example, the format MM/DD/YY is just\nfine, but MM-DD-YY does not work since it conflicts with YY-MM-DD. To be safe, if \"-\" is\nused as a separator in a non-ISO format, they should be turned into \"/\" before calling the\nDate::Manip routines or you should use the 'noiso8601' option with the parse or parsedate\nmethods.\n\nNo matter what separator is used, the same separator must be used throughout the date. For\nexample, MM/DD/YY is valid and MM.DD.YY is also valid, but MM/DD.YY is NOT valid.\n\nNotes:\n\n1 With these formats, Americans tend to write month first, but many other countries tend to\nwrite day first. The latter behavior can be obtained by setting the config variable\nDateFormat to something other than \"US\".\n\n2 The dot (.) separator may not be used in the M/D format since it will be interpreted as\nthe H12,H+ format described below.\n\n3 The M/D format should not use the period (.) separator as that will incorrectly match the\nHH,H+ time format.\n\n4 Historically, I have not supported partial dates (i.e. dates that were not fully\nspecified), but it has been argued that something like 'Jun 1910' would be interpreted by\nalmost everyone as a day in June of 1910 instead of June 19, 2010. And it has been shown\nthat in some applications, dates are specified in that way. I have added the new config\nvariable FormatMMMYYYY which will change this. If this variable is not set, the formats\nallowed are:\n\nmmmDDYY\n\nIf it is set, the formats allowed are:\n\nmmmYYYY\nYYYYmmm\n\nThe day of week may not be included with these formats.  When\nparsing a full date/time, if FormatMMMYYYY is set to 'first',\nit returns the 1st of the month at midnight.  If it is set to\n'last', it returns the last day at 23:59:59.  If parsing only\nonly a date, it will be set to the first or last day of the\nmonth at midnight.\n\nThese formats explicitly set the date, but not the time. The default time is determined by\nthe DefaultTime config variable.\n\nLess common date formats\nThe following formats are also supported by Date::Manip:\n\nDoW\nThe day of week of the current week\nFriday\nFriday at 12:40\n\nMMM Nth [YYYY]\nNth MMM [YYYY]\nYYYY MMM Nth\nYYYY Nth MMM\nDec 1st 1970\n1st Dec 1970\n1970 Dec 1st\n1970 1st Dec\n\nnext/prev DoW\nThe next or last occurrence of DoW\nnext Friday\nlast Friday at 12:40\n\nnext/last week/month/year\nThe day one week/month/year from now\nor in the past\nnext week\nlast month at 15:00\n\nlast day in MMM [YYYY]\nThe last day of the month\nlast day in October\nlast day in October 1996\n\nlast DoW in MMM [YYYY]\nThe last DoW in the month\nlast Tuesday in October\nlast Tuesday in October 1996\n\nlast DoW in YYYY\nThe last DoW in the year\nlast Tuesday in 1997\n\nNOTE: \"last DoW\" doesn't work in\nEnglish since the word \"last\"\nis used for both this expression\nand for \"prev DoW\", which gets\nparsed first. \"last DoW\" MAY\nwork in other languages.\n\nNth DoW in MMM [YYYY]\nThe Nth DoW in the month\n3rd Tuesday in October\n3rd Tuesday in October 1996\n\nNth DoW [YYYY]\nThe Nth DoW in the year\n22nd Sunday\n22nd Sunday in 1996\n\nNth day in MMM [YYYY]\nThe Nth day of the month\n1st day of February\n1st day of February 2012\n\nDoW week\nBritish: same as \"in 1 week on DoW\"\nMonday week\n\nDoW week N [YYYY]\nDow Nth week [YYYY]\nSunday week 22\nSunday 22nd week\nThese refer to the day of week\nof the Nth week of the year.\n\nNth\n12th\nThis refers to the Nth day of the\ncurrent month.\n\nNote that the formats \"Sunday week 22\" and \"22nd Sunday\" give different behaviors. \"Sunday\nweek 22\" returns the Sunday of the 22nd week of the year based on how week 1 is defined. ISO\n8601 defines week one to contain Jan 4, so \"Sunday week 1\" might be the first or second\nSunday of the current year, or the last Sunday of the previous year. \"22nd Sunday\" gives the\nactual 22nd time Sunday occurs in a given year, regardless of the definition of a week.\n\nSpecial date strings\nMost languages have strings which can be used to specify the date (relative to today). In\nEnglish, these include the strings:\n\ntoday\ntomorrow\nyesterday\n\nThere is also support for the British formats:\n\ntoday week\ntomorrow week\nyesterday week\n\nwhich refer to one week after today/tomorrow/yesterday respectively.\n\nOther languages have similar strings.\n\nHolidays\nYou can parse holiday names as dates (including timezones). For example:\n\nChristmas\nChristmas 2010\nChristmas 2010 at noon\nChristmas 2010 at noon PST\nSaturday Christmas 2010 at noon\n\nIn all of the formats (except for ISO 8601 formats), the day of week (\"Friday\") can be entered\nanywhere in the date and it will be checked for accuracy. In other words,\n\n\"Tue Jul 16 1996 13:17:00\"\n\nwill work but\n\n\"Jul 16 1996 Wednesday 13:17:00\"\n\nwill not (because Jul 16, 1996 is Tuesday, not Wednesday).\n",
            "subsections": []
        },
        "A NOTE ABOUT FOREIGN LANGUAGE DATES": {
            "content": "Although Date::Manip has some support for parsing dates in foreign languages, it must be noted\nthat the formats supported are largely based on English equivalents.\n\nThere are probably many different dates that are perfectly valid, and in common usage, in other\nlanguages which do not have an equivalent in the English language, and unfortunately,\nDate::Manip will probably not parse these.\n\nYou are free to send these to me, and I'll see if there is a way to add them in, but I do not\nguarantee anything. Without having a full-blown language parser (or at least the portion of the\nlanguage that is devoted to calendar and time), most of these formats will simply not be\nsupportable.\n",
            "subsections": []
        },
        "VALID TIME FORMATS": {
            "content": "There are several categories of time formats supported by Date::Manip. These are strings which\nspecify only the hour/minute/second fields.\n\nISO 8601 times\nA time may be also be complete or truncated. Again, Date::Manip treats some formats as\ncomplete even though the specification calls them truncated.\n\nA time may include the following fields:\n\nHH    2-digit representation of the hour\nMN    2-digit representation of the minutes\nSS    2-digit representation of the seconds\nH+    1+ digit representation of fractional hours\nM+    1+ digit representation of fractional minutes\nS+    1+ digit representation of fractional seconds\n\nThe following time formats are considered complete by Date::Manip. The time 12:30:15 will be\nexpressed in the examples.\n\nFormat      Notes   Examples\n\nHHMNSS      2       123015\n\nHH:MN:SS            12:30:15\n\nHHMNSS,S+           123015,5\nHH:MN:SS,S+         12:30:15,5\nFractional seconds are ignored\n\nHHMN,M+             1230,25\nHH:MN,M+            12:30,25\nThis is 12:30:00 + 0.25 minutes\n\nHH,H+               12,5\nThis is 12:00:00 + 0.5 hours, so\nthis is equivalent to 12:30:00\n\n-MNSS       1       -3015\n-MN:SS              -30:15\n\n--SS        1       --15\n\n-MNSS,S+    1       -3015,5\n-MN:SS,S+           -30:15,5\n\n-MN,M+      1       -30,25\n\n--SS,S+     1       --15,5\n\nHHMN        3       1230\nHH:MN               12:30\n\nThe following time formats are truncated:\n\nHH                  12\n\n-MN                 -30\n\nNotes:\n\n1 These formats are considered truncated in the standard, but since they do include (or\nimply, using the current time for defaults) all of the fields, and since they do not\nintroduce any parsing complexities, the standard is relaxed, and they are treated as\ncomplete.\n\n2 The HHMNSS format will not be correctly parsed since it is impossible to distinguish\nbetween it and YYMMDD. In order to parse an all-digit time, add the string \",0\" to the end\nto force it to be interpreted as a time or include time zone information (either a zone name\nor abbreviation... an offset will not work in this case).\n\n3 The HH:MN format will be treated as complete, even though it is incomplete due to missing\nthe seconds. In real life, expressing a time in the HH:MN format is very common, and is\nregarded as complete, and might include time zone information.\n\nISO 8601 times may be followed by a time zone unless they are truncated. Truncated times may\nnot include a timezone. Date::Manip relaxes the constraints placed on the time zone format\nand allows any of the methods used to specify the time zone including time zone name,\nabbreviation, or offset. The time zone may be separated from the time by a space, but it is\nnot required.\n\nAnother constraint that is relaxed is that the fractional part may be specified using a\nperiod. In other words, the following are equivalent:\n\n12:30,25\n12:30.25\n\nIt should be noted (as it is in the specification) that using a negative time zone offset\nmay cause confusion. In addition to visually confusing, it may not be parsed correctly. For\nexample, the time:\n\n123005-0300\n\nmay not be parsed correctly. When using an offset time zone, you should always use the colon\nseparators in the time:\n\n12:30:05-0300\n\nOther time formats\nA time may include any of the following fields:\n\nH24   1- or 2-digit representation of the hour (0-23)\nH12   1- or 2-digit representation of the hour (1-12)\nMN    2-digit representation of the minutes\nSS    2-digit representation of the seconds\nH+    1+ digit representation of fractional hours\nM+    1+ digit representation of fractional minutes\nS+    1+ digit representation of fractional seconds\nAM    A language specific AM/PM string\n\nThe following time formats are accepted:\n\nFormat              Examples\n\nH24:MN:SS           17:30:15\nH12:MN:SS AM        5:30:15 PM\nH12:MN:SS\n\nH24:MN:SS,S+        17:30:15,5\nH12:MN:SS,S+ AM     5:30:15,5 PM\nH12:MN:SS,S+        Fractional seconds are ignored\n\nH24:MN,M+           17:30,25\nH12:MN,M+ AM        5:30,25 PM\nH12:MN,M+           This is 17:30:00 + 0.25 minutes\n\nH24,H+              17,5\nH12,H+ AM           5,5 PM\nH12,H+              This is 17:00:00 + 0.5 hours, so\nthis is equivalent to 17:30:00\n\nH24:MN              17:30\nH12:MN AM           5:30 PM\nH12:MN\n\nH12 AM              5 PM\n\nThe fractional part may be specified using a comma or a period. Fractional seconds may also\nbe separated using a colon. A language specific fractional separator may also be available\nfor some languages.\n\nIn other words, the following are equivalent:\n\n12:30:20,25\n12:30:20.25\n12:30:20:25\n\nSome languages have alternate H:MN and MN:S separators. For example, one H:MN separator in\nFrench is 'h' (the MN:S separator is still a colon), so the following are equivalent:\n\n12:30:00\n12h30:00\n\nTime zone information can be included immediately following the time. It can be separated by\nwhitespace from the time, or it can be immediately adjacent.\n\nSpecial time strings\nDifferent languages may have some words which can be used to specify a certain time of day.\nIn English, for example, the following words are equivalent to the time listed:\n\nnoon        12:00:00\nmidnight    00:00:00\n\nSo, the following are equivalent:\n\nJan 2 2009 at noon\nJan 2 2009 12:00:00\n\nThere were two possible ways to interpret midnight. One was at the start of the day\n(00:00:00) and the other was at the end of the day (24:00:00 which would actually mean at\n00:00:00 of the following day). The first has been used to maintain backwards compatibility\nwith Date::Manip 5.xx .\n\nOther languages have similar strings.\n\nIn most languages, a word similar to \"at\" may precede the time (this does NOT apply to ISO 8601\ntime formats). This word (which must be separate from all other parts of the date with\nwhitespace) is optional, and the following are equivalent:\n\n12:30\nat 12:30\n\nThe times \"12:00 am\", \"12:00 pm\", and \"midnight\" are not well defined. Date::Manip uses the\nfollowing convention:\n\nmidnight = 12:00am = 00:00:00\nnoon     = 12:00pm = 12:00:00\n\nand the day goes from 00:00:00 to 23:59:59. In other words, midnight is the beginning of a day\nrather than the end of one. The time 24:00:00 is also allowed (though it is automatically\ntransformed to 00:00:00 of the following day). This gives the unusual result of parsing:\n\nWed Feb 8 2006 24:00:00\n\nwhich gives the date of:\n\nThu Feb 9 2006 00:00:00\n",
            "subsections": []
        },
        "VALID COMBINED DATE AND TIME FORMATS": {
            "content": "There are several categories of strings which specify both the date and time. These include the\nfollowing:\n\nISO 8601 combined date and time\nA combined ISO 8601 date and time is a string containing a complete ISO 8601 date and a\ncomplete or truncated ISO 8601 time. It may also include a timezone, provided a complete\ntime is included.\n\nDate::Manip relaxes the restrictions on how the two are combined. The time may be separated\nfrom the date by space, dash, or the letter T, or the two may be joined with nothing\nseparating them.\n\nWhen the time immediately follows the date, or when the two are separated by a dash, the\nresulting string MUST be unambiguous. Provided the date includes all of the dashes in it\n(i.e. YY-MM-DD instead of YYMMDD), it is rare that there is any ambiguity. If the date does\nnot include dashes, the strings may be ambiguous, and in this case, separating the date and\ntime with a space or the letter T is useful (and perhaps necessary) to correctly interpret\nthe string.\n\nThe DoY formats should always be separated from the time by something. They are visually\nconfusing if they are not separated from the time.\n\nTime zone information can be included immediately following a complete time. It may not be\nincluded if no time is given, or if a truncated time is included. The time zone may be\nseparated from the time with whitespace, or it can be immediately adjacent to it (since the\nISO 8601 specification allows it in some cases).\n\nNon-ISO 8601 combined date and time\nA date from any of the non-ISO 8601 formats above may be combined with any of the non-ISO\n8601 time formats above in any combination to form a valid combined date and time.\n\nDeltas\nDates are often specified in terms of a delta from \"now\". For example, \"in 2 days\".\n\nMost valid deltas can be used to specify a date, and the date is defined as that delta added\nto \"now\". Refer to the Date::Manip::Delta documentation for a list of valid delta formats.\n\nIf the delta itself does not include a time part, the time may be specified explicitly. For\nexample:\n\nin 3 days at 12:00:00\nin 3 days at 12:00:00 PST\n\nwill take the delta part \"in 3 days\" and add it to the current time, then set the time to\n12:00:00.\n\nIt is NOT allowed to include an explicit time if any time segment was included in the delta.\nFor example, the following is invalid:\n\nin 3 days 2 hours at 12:00:00\n\nOne additional format that is supported is to include only week (or higher) components in\nthe delta and to set the day of week. For example:\n\nFriday in 2 weeks\nin 2 weeks on Friday\nFriday 2 weeks ago\n2 weeks ago on Friday at 13:45\n\nThese first apply the delta (of weeks, months, and years) to the current time, and then set\nthe day to the given day-of-week in that week.\n\nSpecial date and time strings\nMost language have strings which can be used to specify the full date and time (relative to\nthe current date and time). In English, these include the string:\n\nnow\n\nThey may also have a timezone attached:\n\nnow PST\n\nAdditional combined date and time formats\nThe following formats are also supported:\n\nepoch SECS\nThe number of seconds since the epoch\n(Jan 1, 1970 00:00:00 GMT). SECS may\nbe negative to give time before the\nepoch.\n\nor\n\nepoch SECS TIMEZONE\n\nA couple of notes:\n\nCommas may be included in all date formats arbitrarily (except for ISO 8601 formats where they\nmay only be included when allowed by the specification).\n\nThe time/time zone is removed from the date before the date is parsed, so the time may appear\nbefore or after the date, or between any two parts of the date.\n\nThe time and the zone do not need to be adjacent, so the string:\n\nJan 21 17:13:27 2010 -0400\n\nwill work. If the timezone is separate from the date, it MUST be separated from any other\nportion of the date by whitespace.\n\nCertain words such as \"on\", \"in\", \"at\", \"of\", etc. which commonly appear in a date or time are\nignored (except in ISO 8601 formats).\n",
            "subsections": []
        },
        "PRINTF DIRECTIVES": {
            "content": "The following printf directives are replaced with information from the date.\n\nYear\n%y     year                     - 00 to 99\n%Y     year                     - 0001 to 9999\n\nMonth, Week\n%m     month of year            - 01 to 12\n%f     month of year            - \" 1\" to \"12\"\n%b,%h  month abbreviation       - Jan to Dec\n%B     month name               - January to December\n\nDay\n%j     day of the year          - 001 to 366\n%d     day of month             - 01 to 31\n%e     day of month             - \" 1\" to \"31\"\n%v     weekday abbreviation     - \" S\",\" M\",\" T\", ...\n%a     weekday abbreviation     - Sun to Sat\n%A     weekday name             - Sunday to Saturday\n%w     day of week              - 1 to 7 (1=Monday)\n%E     day of month with\nsuffix                   - 1st, 2nd, 3rd...\n\nHour\n%H     hour                     - 00 to 23\n%k     hour                     - \" 0\" to \"23\"\n%i     hour                     - \" 1\" to \"12\"\n%I     hour                     - 01 to 12\n%p     AM or PM\n\nMinute, Second, Time zone\n%M     minute                   - 00 to 59\n%S     second                   - 00 to 59\n%Z     time zone abbreviation   - EDT\n%z     time zone as GMT offset  - +0100 (see Note 4)\n%N     time zone as GMT offset  - +01:00:00\n\nEpoch (see NOTE 3 below)\n%s     seconds from\n1/1/1970 GMT             - negative if before\n%o     seconds from 1/1/1970\nin the current time\nzone\n\nDate, Time\n%c     %a %b %e %H:%M:%S %Y     - Fri Apr 28 17:23:15 1995\n%C,%u  %a %b %e %H:%M:%S %Z %Y  - Fri Apr 28 17:25:57 EDT 1995\n%g     %a, %d %b %Y %H:%M:%S %Z - Fri, 28 Apr 1995 17:23:15 EDT\n%D     %m/%d/%y                 - 04/28/95\n%x     %m/%d/%y or %d/%m/%y     - 04/28/95 or 28/04/95\n(Depends on DateFormat variable)\n%l     date in ls(1) format (see NOTE 1 below)\n%b %e %H:%M            - Apr 28 17:23 (*)\n%b %e  %Y              - Apr 28  1993 (*)\n%r     %I:%M:%S %p              - 05:39:55 PM\n%R     %H:%M                    - 17:40\n%T,%X  %H:%M:%S                 - 17:40:58\n%V     %m%d%H%M%y               - 0428174095\n%Q     %Y%m%d                   - 19961025\n%q     %Y%m%d%H%M%S             - 19961025174058\n%P     %Y%m%d%H:%M:%S           - 1996102517:40:58\n%O     %Y-%m-%dT%H:%M:%S        - 1996-10-25T17:40:58\n%F     %A, %B %e, %Y            - Sunday, January  1, 1996\n%K     %Y-%j                    - 1997-045\n\nSpecial Year/Week formats (see NOTE 2 below)\n%G     year, Monday as first\nday of week              - 0001 to 9999\n%W     week of year, Monday\nas first day of week     - 01 to 53\n%L     year, Sunday as first\nday of week              - 0001 to 9999\n%U     week of year, Sunday\nas first day of week     - 01 to 53\n%J     %G-W%W-%w                - 1997-W02-2\n\nOther formats\n%n     insert a newline character\n%t     insert a tab character\n%%     insert a `%' character\n%+     insert a `+' character\n\nAll other characters are currently unused, but may be used in the\nfuture.  They currently insert the character following the %.\n\nThe following multi-character formats also exist:\n\nExtended formats\n%<A=NUM>   These returns the NUMth value of the %A, %a, and %v formats\n%<a=NUM>   respectively.  In English, that would yield:\n%<v=NUM>      %<A=2>   => Tuesday\n%<a=2>   => Tue\n%<v=2>   => T\nNUM must be in the range 1-7.\n\n%<B=NUM>   These return the NUMth value of the %B and %b formats\n%<b=NUM>   respectively.  In English, that would yield:\n%<B=2>   => February\n%<b=2>   => Feb\nNUM must be in the range 1-12 (or 01-12).\n\n%<p=NUM>   These return the NUMth value of the %p format.  In\nEnglish, that would yield:\n%<p=1>   => AM\n%<p=2>   => PM\nNUM must be in the range 1-2.\n\n%<E=NUM>   These return the NUMth value of the %E format.  In\nEnglish, that would yield:\n%<E=1>   => 1st\n%<E=53>  => 53rd\nNUM must be in the range 1-53.\n\nIf a lone percent is the final character in a format, it is ignored.\n\nThe formats used in this routine were originally based on date.pl (version 3.2) by Terry\nMcGonigal, as well as a couple taken from different versions of the Solaris date(1) command.\nAlso, several have been added which are unique to Date::Manip.\n\nNOTE 1:\n\nThe ls format (%l) applies to date within the past OR future 6 months! Any date that is before\nthe date NOW - 6 months, or that is on or after the date NOW + 6 months will have the year\nprinted out.\n\nThe later time must be on or after so that there is no ambiguity. If it is now\n2000-06-06-12:00:00, then the date 1999-12-06-12:00:00 will be written as \"Dec 6 12:00\" but the\ndate 2000-12-06-12:00:00 will be written as \"Dec 6 2000\".\n\nNOTE 2:\n\nThe %U, %W, %L, %G, and %J formats are used to support the ISO-8601 format: YYYY-wWW-D. In this\nformat, a date is written as a year, the week of the year, and the day of the week. Technically,\nthe week may be considered to start on any day of the week, but Sunday and Monday are the both\ncommon choices, so both are supported.\n\nThe %W and %G formats return the week-of-year and the year treating weeks as starting on Monday.\n\nThe %U and %L formats return the week-of-year and the year treating weeks as starting on Sunday.\n\nMost of the time, the %L and %G formats returns the same value as the %Y format, but there is a\nproblem with days occurring in the first or last week of the year.\n\nThe ISO-8601 representation of Jan 1, 1993 written in the YYYY-wWW-D format is actually\n1992-W53-5. In other words, Jan 1 is treated as being in the last week of the preceding year.\nDepending on the year, days in the first week of a year may belong to the previous year, and\ndays in the final week of a year may belong to the next year. The week is assigned to the year\nwhich has most of the days. For example, if the week starts on Sunday, then the last week of\n2003 is 2003-12-28 to 2004-01-03. This week is assigned to 2003 since 4 of the days in it are in\n2003 and only 3 of them are in 2004. The first week of 2004 starts on 2004-01-04.\n\nThe %U and %W formats return a week-of-year number from 01 to 53. %L and %G return the\ncorresponding year, and to get this type of information, you should always use the (%W,%G)\ncombination or (%U,%L) combination. %Y should not be used as it will yield incorrect results.\n\n%J returns the full ISO-8601 format (%G-W%W-%w).\n\nNOTE 3:\n\nThe %s and %o formats return negative values if the date is before the start of the epoch. Other\nUnix utilities would return an error, or a zero, so if you are going to use Date::Manip in\nconjunction with these, be sure to check for a negative value.\n\nNOTE 4:\n\nThe %z format returns the offset in the RFC 822 specified format +0500 . Most offsets are full\nhour amounts, so this is not a problem, but some offsets are irregular (+05:17:30). In this\ncase, the string returned is +051730 which isn't RFC 822 compliant, but since RFC 822 ignores\nthis situation, I had to decide between returning an incorrect value, or breaking strict\ncompliance, and I chose the second option.\n",
            "subsections": []
        },
        "KNOWN BUGS": {
            "content": "None known.\n",
            "subsections": []
        },
        "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": []
        }
    },
    "summary": "Date::Manip::Date - Methods for working with dates",
    "flags": [],
    "examples": [],
    "see_also": []
}