{
    "mode": "perldoc",
    "parameter": "Date::Manip::Delta",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Date%3A%3AManip%3A%3ADelta/json",
    "generated": "2026-06-09T22:47:46Z",
    "synopsis": "use Date::Manip::Delta;\n$date = new Date::Manip::Delta;",
    "sections": {
        "NAME": {
            "content": "Date::Manip::Delta - Methods for working with deltas\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use Date::Manip::Delta;\n$date = new Date::Manip::Delta;\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This module contains functions useful in parsing and manipulating deltas. As used in this\nmodule, the term delta refers to an amount of time elapsed. It includes no information about a\nstarting or ending time.\n\nThere are several concepts involved in understanding the properties of a delta.\n\nstandard and business delta\nThere are two different modes for working with deltas: standard and business. The mode used\ndepends on how you treat the calendar.\n\nStandard deltas use the full calendar without any modifications.\n\nA business delta uses a calendar in the way a business might. In a business calendar,\nanything outside of a business day is ignored. Typically, this includes holidays and\nweekends. In addition, the part of the day outside of business hours is also ignored, so a\nday may only run from 08:00 to 17:00 and everything outside of this is ignored.\n\nThe length of a work day is usually not 24 hours. It is defined by the start and end of the\nwork day and is set using the config variables: WorkDayBeg and WorkDayEnd (WorkDay24Hr may\nbe used to specify a 24-hour work day). The work week is defined using the config variables:\nWorkWeekBeg and WorkWeekEnd.\n\nDaylight saving time are ignored with business calculations because time changes occur at\nnight (usually on the weekends) outside of business hours. This may yield unexpected results\nif the work day is defined to be 24-hours and the work week includes a day when a time\nchange occurs.\n\nfields\nA delta consists of 7 fields: years, months, weeks, days, hours, minutes, and seconds,\nusually expressed as a colon-separated string. For example:\n\n1:2:3:4:5:6:7\n\nrefers to an elapsed amount of time 1 year, 2 months, 3 weeks, 4 days, 5 hours, 6 minutes,\nand 7 seconds long.\n\nnormalized\nA delta can be normalized or not. A normalized delta has values which have been simplified\nbased on how a human would think of them. As an example, the delta:\n\n0:0:0:0:0:10:70\n\nis not normalized since 70 seconds is typically thought of as 1 minute 10 seconds. The\nnormalized form of this delta would be:\n\n0:0:0:0:0:11:10\n\nBy default, deltas are converted to a normalized form in most functions that create/modify a\ndelta, but this can be overridden.\n\nTypes of deltas\nThere are 4 type of deltas that are available.\n\nExact deltas\nThe most common type (and the default in most situations) is an exact delta. An\nexact delta is one where only fields which have exactly known lengths are allowed to\nbe non-zero.\n\nFor standard calculations, there are only three exactly known fields (hours,\nminutes, and seconds). The lengths are defined as:\n\n1 hour   = 3600 seconds\n1 minute = 60 seconds\n\nNote that since a day is NOT always 24 hours (due to daylight saving time changes),\na day is not an exactly known field.\n\nFor business calculations, a day IS an exactly known field. Since business mode\nignores daylight saving time, the length of the day can be calculated based on the\nconfig variables listed above. So, for example, if the work day is 08:00-17:00, the\nlength of the day is 9 hours. The length of the week is still unknown since some\nwork weeks may have fewer days than others due to holidays.\n\nAll fields which are not exactly known will always have zero value.\n\nSemi-exact deltas\nA semi-exact delta treats the day/week fields as if they were exactly known.\n\nFor standard calculations, this is done by using the relationships:\n\n1 day  = 24 hours\n1 week = 7 days\n\nFor business calculations, it is done by treating a week as a constant length\n(determined by the config variables listed above) ignoring holidays. So if a typical\nwork week is Mon-Fri, the length of the week is 5 days.\n\nFor semi-exact deltas, the value of the year/month must be zero.\n\nAlthough this may yield some values that are not exactly accurate around daylight\nsaving time transitions, strictly speaking, they yield results that are useful in\nterms of how humans think of deltas.\n\nApproximate deltas\nAn approximate delta can have non-zero values for all fields. When normalizing the\nfields, the year/month fields are treated as one set using the relationship\n\n1 year  = 12 months\n\nThe remaining fields are normalized using the semi-exact relationships.\n\nEstimated deltas\nThe final type of delta are estimated deltas. These are deltas where an estimated\nlength is applied to all the approximate fields.\n\nFor standard deltas, the additional relationship:\n\n1 year = 365.2425 days\n\nis used. For business deltas, the additional relationship:\n\n1 year   = X/7 * 365.2425 days\n\n(where X is the number of work days in a week) is used.\n\nFractional seconds will be discarded (not rounded).\n\nNOTE: it is not possible to look at a delta and determine what type it is. For example, a\nstandard delta with a non-zero day value might be approximate or semi-exact. The type will\nneed to be explicitly selected, or determined by the context of the operation.\n\nsigns\nEach field has a sign associated with it. For example, the delta \"1 year ago\" is written as:\n\n-1:0:0:0:0:0:0\n\nThe sign of any field is optional, and if omitted, it is the same as the next higher field.\nSo, the following are identical:\n\n+1:2:3:4:5:6:7\n+1:+2:+3:+4:+5:+6:+7\n\nIn a normalized delta, all fields in a set will have the same sign. So the standard delta:\n\n0:0:+3:-2:0:0:0:0   (3 weeks -2 days)\n\nis not normalized. The normalized version would be:\n\n0:0:+2:5:0:0:0:0    (2 weeks, 5 days)\n\nSince an approximate delta has two sets (the y/m set and the w/d/h/mn/s set), these deltas\nmay have two signs. So, the following is a fully normalized approximate delta:\n\n+1:0:-3:3:1:0:0\n\nfractional values\nFractional fields are allowed such as:\n\n1.25 days\n1.1 years\n\nbut whenever parsing a delta with fractional fields, the delta will be normalized using the\nestimated relationships described above. Fractional seconds will be discarded.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "new\nnewconfig\nnewdate\nnewdelta\nnewrecur\nbase\ntz\nisdate\nisdelta\nisrecur\nconfig\nerr Please refer to the Date::Manip::Obj documentation for these methods.\n\nparse\n$err = $delta->parse($string, \\%opts);\n$err = $delta->parse($string [,$business] [,$nonormalize]);\n\nThe second format is supported for backward compatibility, but is deprecated and will be\nremoved in Date::Manip 7.00. The second form is equivalent to:\n\n$err = $delta->parse($string, { business => $business,\nnonorm   => $nonormalize });\n\nThis takes a string and parses it to see if it is a valid delta. If it is, an error code of\n0 is returned and $delta now contains the value of the delta. Otherwise, an error code of 1\nis returned and an error condition is set in the delta.\n\nRecognized options are:\n\nmode      : standard/business\nto specify if it is a business delta or a standard delta\nnonorm    : 0/1\n1 if the delta should not be normalized\ntype      : exact, semi, approx, estimated\n\nWhen specifying the type, the delta given must satisfy the requirements of the type (i.e. no\nyear field for an exact delta).\n\nA delta string is usually specified in compact notation which consists of a colon separated\nlist of numbers (with optional signs):\n\nExamples:\n0:0:0:0:4:3:-2\n+4:3:-2\n+4::3\n\nIn compact notation, from 1 to 7 of the fields may be given. For example D:H:MN:S may be\ngiven to specify only four of the fields. No spaces may be present in the string, but it is\nallowed to omit some of the fields. For example 5::3:30 is valid. In this case, missing\nfields default to the value 0.\n\nThe delta string may also be specified using common field abbreviations. This is described\nbelow in the \"ADDITIONAL DELTA NOTATIONS\" section.\n\ninput\n$str = $delta->input();\n\nThis returns the string that was parsed to form the delta.\n\nset\n$err = $delta->set(\\%opts);\n$err = $delta->set($field,$val [,$nonormalize]);\n\nThe second format is supported for backward compatibility, but is deprecated and will be\nremoved in Date::Manip 7.00. The second form is equivalent to:\n\n$err = $delta->set( $field => $val, 'nonorm' => $nonormalize );\n\nThis explicitly sets one or more parts of a delta. %opts is a set of key/value pairs:\n\n$key     $val\n\ndelta    [Y,M,W,D,H,MN,S]  sets the entire delta\nbusiness [Y,M,W,D,H,MN,S]  sets the entire delta\nstandard [Y,M,W,D,H,MN,S]  sets the entire delta\ny        YEAR              sets one field\nM        MONTH\nw        WEEK\nd        DAY\nh        HOUR\nm        MINUTE\ns        SECOND\n\nnonorm   0/1\nmode     business, standard\ntype     exact, semi, estimated, approx\n\nAn error is returned if an invalid data is passed in.\n\n%opts can only include a single key that affects each field (i.e. you can set delta or\nbusiness but not both, and you cannot set both delta and y, but you CAN set both y and w).\n\nWhen setting the entire delta with business or standard, it flags the delta as a business or\nstandard mode delta respectively. In those cases, you are not allowed to set the mode\noption. Partial deltas are allowed (i.e. [H,MN,S]) in which case zeros are added for all\nfields not specified.\n\nWhen setting the entire delta with delta, the flag is left unchanged (unless the mode option\nis also passed in).\n\nAlso, when setting the entire delta, signs are not carried from one field to another, so\n[-1,2,...] is equivalent to [-1,+2,...].\n\nBy default, a delta is normalized, but setting the nonorm key to a true value will not do\nthat.\n\nFor backwards compatibility, normal can be used in place of standard, both as $field or as\n$val. This is deprecated and will be removed in Date::Manip 7.00.\n\nWhen setting any field in the delta, the type of delta will be determined automatically as\neither exact (if only fields that are exactly known are have non-zero fields), semi (if only\nfields that are semi-exact or exact are included), or approx otherwise. If the type option\nis set, it will be used provided it is valid (i.e. you cannot set it to exact if fields that\nare not exactly known are set).\n\nprintf\n$out = $delta->printf($in);\n@out = $delta->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 delta.\nEverything else in the string is returned unmodified.\n\nA directive always begins with '%'. They are described in the section below in the section\n\"PRINTF DIRECTIVES\".\n\ncalc\nPlease refer to the Date::Manip::Calc documentation for details.\n\ntype\n$flag = $delta->type($op);\n\nThis tests to see if a delta is of a certain type. $op can be;\n\nbusiness  : returns 1 if it is a business delta\nstandard  : returns 1 if it is a standard (non-business delta)\n\nexact     : returns 1 if it is exact\nsemi      : returns 1 if it is semi-exact\napprox    : returns 1 if it is approximate\nestimated : returns 1 if it is estimated\n\nvalue\n$val = $delta->value();\n@val = $delta->value();\n\nThis returns the value of the delta. In scalar context, it returns the printable string\n(equivalent to the printf directive '%Dt'). In list context, it returns a list of fields.\n\nAn empty string/list is returned if there is no valid delta stored in $delta.\n\nconvert\n$delta->convert($to);\n\nThis converts a delta from one type to another. $to can be 'exact', 'semi', or 'approx'. The\nconversion uses the approximate and estimated relationships listed above to convert the\ndelta.\n\nFor example, if the exact non-business delta $delta contains:\n\n0:0:0:0:44:0:0\n\nthen the following call:\n\n$delta->convert('semi')\n\nwould produce the semi-exact delta:\n\n0:0:0:1:20:0:0\n\nThe result will always be normalized.\n\nConverting from one type to another that is less exact (i.e. exact to semi-exact or\nsemi-exact to approx) is supported. Converting the other direction is supported for backward\ncompatibility, but will be removed in 7.00 because that operation is not one that is well\ndefined.\n\nThere is currently no support for converting business to non-business (or vice-versa).\n\ncmp\n$flag = $delta1->cmp($delta2);\n\nThis compares two deltas (using the approximate relationships listed above) and returns -1,\n0, or 1 which could be used to sort them by length of time.\n\nBoth deltas must be valid, and both must be either business or non-business deltas. They do\nnot need to be the same out of exact, semi-exact, and approximate.\n\nundef will be returned if either delta is invalid, or you try to compare a business and\nnon-business delta.\n",
            "subsections": []
        },
        "ADDITIONAL DELTA NOTATIONS": {
            "content": "When parsing a delta, the string may be specified with the field spelled out, rather than using\nthe colon separated fields.\n\nThis expanded notation has the fields spelled out in some language specific form:\n\nExamples:\n+4 hours +3mn -2second\n+ 4 hr 3 minutes -2\n4 hour + 3 min -2 s\n4 hr 2 s\n\nA field in the expanded notation has an optional sign, a number, and a string specifying the\ntype of field. If the sign is absent, it defaults to the sign of the next larger element. So the\nfollowing are equivalent:\n\n-4 hr 3 min 2 sec\n-4 hr -3 min -2 sec\n\nThe valid strings describing each of the fields is contained in \"Delta field names\" section of\nthe appropriate Date::Manip::Lang::<LANGUAGE> document. Refer to the Date::Manip::Lang document\nfor a list of languages.\n\nFor example, for English, the document is Date::Manip::Lang::English and the field names include\nstrings like:\n\ny:  y, yr, year, years\nm:  m, mon, mons, month, months\nw:  w, wk, ws, wks, week, weeks\nd:  d, day, days\nh:  h, hr, hrs, hour, hours\nmn: mn, min, mins, minute, minutes\ns:  s, sec, secs, second, seconds\n\nThis list may not be complete. You should refer to the language document for the full list.\n\nThe \"seconds\" string may be omitted. The sign, number, and string may all be separated from each\nother by any amount of whitespace. The string specifying the unit must be separated from a\nfollowing number by whitespace or a comma, so the following example will NOT work:\n\n4hours3minutes\n\nAt minimum, it must be expressed as:\n\n4hours 3minutes\n4 hours, 3 minutes\n\nIn the the expanded format, all fields must be given in the order: Y M W D H MN S. Any number of\nthem may be omitted provided the rest remain in the correct order. Small numbers may be spelled\nout, so\n\nin two weeks\nin 2 weeks\n\nboth work (but do not rely on this to work for large numbers).\n\nMost languages also allow a word to specify whether the delta is an amount of time after or\nbefore a fixed point. In English, the word \"in\" refers to a time after a fixed point, and \"ago\"\nrefers to a point before a fixed point. So, the following deltas are equivalent:\n\n1:0:0:0:0:0:0\nin 1 year\n\nand the following are equivalent\n\n-1:0:0:0:0:0:0\n1 year ago\n\nThe word \"in\" is completely ignored. The word \"ago\" has the affect of reversing all signs that\nappear in front of the components of the delta. In other words, the following two strings are\nidentical:\n\n-12 yr  6 mon ago\n+12 yr +6 mon\n\n(don't forget that there is an implied minus sign in front of the 6 in the first string because\nwhen no sign is explicitly given, it carries the previously entered sign).\n\nThe in/ago words only apply to the expanded format, so the following is invalid:\n\n1:0:0 ago\n\nA delta may be standard (non-business) or business. By default, a delta is treated as a\nnon-business delta, but this can be changed in two different ways.\n\nThe first way to make a delta be business is to pass in the appropriate option. For example:\n\n$delta->parse($string, { 'mode' => 'business' });\n$delta->parse($string, { 'mode' => 'standard' });\n\nThe second way to specify whether a delta is business or non-business is to include a key word\nin the string that is parsed. If this string is included, it should not conflict with the value\nof a 'mode' option.\n\nMost languages include a word like \"business\" which can be used to specify that the resulting\ndelta is a business delta or a non-business delta. Other languages have equivalent words. The\nplacement of the word is not important. Also, the \"business\" word can be included with all types\nof deltas, and in both compact and expanded notation, so the following are valid and equivalent:\n\nin 4 hours business\n4:0:0 business\nbusiness 0:0:0:0:4:0:0\n\nThere are also words \"exact\" or \"approximate\" which may be included in the delta for backward\ncompatibility. However, they will be ignored. They will be removed in Date::Manip 7.00. The\naccuracy of delta (exact, semi-exact, approximate) will be determined only by what fields are\npresent in the delta and the options passed in. When a delta is parsed, it is automatically\nnormalized, unless the 'nonorm' option is passed in.\n",
            "subsections": []
        },
        "PRINTF DIRECTIVES": {
            "content": "The following printf directives are replaced with information from the delta. Directives may be\nreplaced by the values of a single field in the delta (i.e. the hours or weeks field), the value\nof several fields expressed in terms of one of them (i.e. the number of years and months\nexpressed in terms of months), or the directive may format either the entire delta, or portions\nof it.\n\nSimple directives\nThese are directives which print simple characters. Currently, the only one is:\n\n%%    Replaced by a single '%'\n\nAs an example:\n\n$delta->printf('|%%|');\n=> |%|\n\nDirectives to print out a single field\nThe following directive is used to print out the value of a single field. Spaces are\nincluded here for clarity, but are not in the actual directive.\n\n% [+] [pad] [width] Xv\n\nHere, X is one of (y,M,w,d,h,m,s). The directive will print out the value for that field.\n\nIf a '+' is included immediately after the '%', a sign will always be included. By default,\nonly negative values will include a sign.\n\n'width' and 'pad' are used to set the width of the string containing the field as well as\nhow it is padded.\n\n'width' is any positive integer (without a sign). If 'width' is included, it sets the length\nof the output string (unless the string is already longer than that, in which case the\n'width' is ignored).\n\nIf 'pad' is included, it may be the character '<', '>', or '0'. It will be ignored if\n'width' is not included, or the string is already longer than 'width'. If the formatted\ndelta field is shorter than 'width', it will be padded with spaces on the left (if 'pad' is\n'<'), or right (if 'pad' is '>'), or it will be padded on the left (after any sign) with\nzeroes (if 'pad' is '0').\n\nIn the following examples, $delta contains the delta: 1:2:3:4:5:6:7\n\n$delta->printf('|Month: %Mv|');\n=> |Month: 2|\n\n$delta->printf('|Day: %+05dv|');\n=> |Day: +0004|\n\n$delta->printf('|Day: %+<5dv|');\n=> |Day:    +4|\n\n$delta->printf('|Day: %>5sv|');\n=> |Day: 7    |\n\nDirectives to print out several fields in terms of one of them\nThe following directive is used to print out the value of several different fields,\nexpressed in terms of a single field.\n\n% [+] [pad] [width] [.precision] XYZ\n\nHere, X, Y, and Z are each one of (y,M,w,d,h,m,s). The directive will print out the value\nfor fields Y through Z expressed in terms of field X.\n\nY must come before Z in the sequence (y,M,w,d,h,m,s) or it can be the same as Z.\n\nSo, to print the day and hour fields in terms of seconds, use the directive:\n\n%sdh\n\nAny time all of X, Y, and Z are from a single set of fields, exact relationships are used.\n\nIf the X, Y, and Z fields do not all belong to the same set of fields, approximate\nrelationships are used.\n\nFor non-business deltas, an approximate relationship is needed to link the Y/M part of the\ndelta to the W/D part and a semi-approximate relationship is needed to link the W/D part\nwith the H/MN/S part. These relationships are:\n\n1 day    = 24 hours\n1 year   = 365.2425\n\nFor business deltas, the approximate and semi-approximate relationships used to link the\nfields together are:\n\n1 week   = X    (length of business week in days)\n1 year   = X/7 * 365.2425\n\nFor business deltas, the length of the day is defined using WorkDayStart and WorkDayEnd. For\nnon-business deltas, a day is 24 hours long (i.e. daylight saving time is ignored).\n\nIf 'precision' is included, it is the number of decimal places to print. If it is not\nincluded, but 'width' is included, precision will be set automatically to display the\nmaximum number of decimal places given 'width'.\n\nIf 'pad' is included, it may be the character '<', '>', or '0', and is used in the same way\nas printing out a single field.\n\nIn the following examples, $delta contains the delta: 1:2:3:4:5:6:7\n\n$delta->printf('|%.4Myw|');\n=> |14.6900|\n1 year, 2 months, 3 weeks is approximately\n14.6900 months\n\nDirectives to print out portions of the delta\nThe following directives may be used to print out some or all of a delta.\n\n% [+] [pad] [width] Dt\n% [+] [pad] [width] DXY\n\nThe first directive will print out the entire delta.\n\nThe second will print out the delta from the X to Y fields inclusive (where X and Y are each\none of (y,M,w,d,h,m,s) and X must come before Y in the sequence).\n\n'pad' is optional and can be either '<' or '>' meaning to pad on the left or right with\nspaces. It defaults to '<'.\n\nIf a '+' is included immediately following the '%', every field will have a sign attached.\nOtherwise, only the leftmost field in each set of fields will include a sign.\n\n$delta->printf('|%Dt|');\n=> |+1:2:+3:+4:5:6:7|\n\n$delta->printf('|%+Dyd|');\n=> |+1:+2:+3:+4|\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::Delta - Methods for working with deltas",
    "flags": [],
    "examples": [],
    "see_also": []
}