{
    "mode": "perldoc",
    "parameter": "DateTime::Duration",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/DateTime%3A%3ADuration/json",
    "generated": "2026-06-12T18:22:17Z",
    "synopsis": "use DateTime::Duration;\n$dur = DateTime::Duration->new(\nyears        => 3,\nmonths       => 5,\nweeks        => 1,\ndays         => 1,\nhours        => 6,\nminutes      => 15,\nseconds      => 45,\nnanoseconds  => 12000,\nendofmonth => 'limit',\n);\nmy ( $days, $hours, $seconds )\n= $dur->inunits( 'days', 'hours', 'seconds' );\n# Human-readable accessors, always positive, but consider using\n# DateTime::Format::Duration instead\n$dur->years;\n$dur->months;\n$dur->weeks;\n$dur->days;\n$dur->hours;\n$dur->minutes;\n$dur->seconds;\n$dur->nanoseconds;\n$dur->iswrapmode;\n$dur->islimitmode;\n$dur->ispreservemode;\nprint $dur->endofmonthmode;\n# Multiply all values by -1\nmy $opposite = $dur->inverse;\nmy $bigger  = $dur1 + $dur2;\nmy $smaller = $dur1 - $dur2;    # the result could be negative\nmy $bigger  = $dur1 * 3;\nmy $basedt = DateTime->new( year => 2000 );\nmy @sorted\n= sort { DateTime::Duration->compare( $a, $b, $basedt ) } @durations;\nif ( $dur->ispositive ) {...}\nif ( $dur->iszero )     {...}\nif ( $dur->isnegative ) {...}",
    "sections": {
        "NAME": {
            "content": "DateTime::Duration - Duration objects for date math\n",
            "subsections": []
        },
        "VERSION": {
            "content": "version 1.55\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "use DateTime::Duration;\n\n$dur = DateTime::Duration->new(\nyears        => 3,\nmonths       => 5,\nweeks        => 1,\ndays         => 1,\nhours        => 6,\nminutes      => 15,\nseconds      => 45,\nnanoseconds  => 12000,\nendofmonth => 'limit',\n);\n\nmy ( $days, $hours, $seconds )\n= $dur->inunits( 'days', 'hours', 'seconds' );\n\n# Human-readable accessors, always positive, but consider using\n# DateTime::Format::Duration instead\n$dur->years;\n$dur->months;\n$dur->weeks;\n$dur->days;\n$dur->hours;\n$dur->minutes;\n$dur->seconds;\n$dur->nanoseconds;\n\n$dur->iswrapmode;\n$dur->islimitmode;\n$dur->ispreservemode;\n\nprint $dur->endofmonthmode;\n\n# Multiply all values by -1\nmy $opposite = $dur->inverse;\n\nmy $bigger  = $dur1 + $dur2;\nmy $smaller = $dur1 - $dur2;    # the result could be negative\nmy $bigger  = $dur1 * 3;\n\nmy $basedt = DateTime->new( year => 2000 );\nmy @sorted\n= sort { DateTime::Duration->compare( $a, $b, $basedt ) } @durations;\n\nif ( $dur->ispositive ) {...}\nif ( $dur->iszero )     {...}\nif ( $dur->isnegative ) {...}\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "This is a simple class for representing duration objects. These objects are used whenever you do\ndate math with DateTime.\n\nSee the How DateTime Math Works section of the DateTime documentation for more details. The\nshort course: One cannot in general convert between seconds, minutes, days, and months, so this\nclass will never do so. Instead, create the duration with the desired units to begin with, for\nexample by calling the appropriate subtraction/delta method on a DateTime object.\n",
            "subsections": []
        },
        "METHODS": {
            "content": "Like DateTime itself, \"DateTime::Duration\" returns the object from mutator methods in order to\nmake method chaining possible.\n\n\"DateTime::Duration\" has the following methods:\n\nDateTime::Duration->new( ... )\nThis class method accepts the following parameters:\n\n*   years\n\nAn integer containing the number of years in the duration. This is optional.\n\n*   months\n\nAn integer containing the number of months in the duration. This is optional.\n\n*   weeks\n\nAn integer containing the number of weeks in the duration. This is optional.\n\n*   days\n\nAn integer containing the number of days in the duration. This is optional.\n\n*   hours\n\nAn integer containing the number of hours in the duration. This is optional.\n\n*   minutes\n\nAn integer containing the number of minutes in the duration. This is optional.\n\n*   seconds\n\nAn integer containing the number of seconds in the duration. This is optional.\n\n*   nanoseconds\n\nAn integer containing the number of nanoseconds in the duration. This is optional.\n\n*   endofmonth\n\nThis must be either \"wrap\", \"limit\", or \"preserve\". This parameter specifies how date math\nthat crosses the end of a month is handled.\n\nIn \"wrap\" mode, adding months or years that result in days beyond the end of the new month\nwill roll over into the following month. For instance, adding one year to Feb 29 will result\nin Mar 1.\n\nIf you specify \"limit\", the end of the month is never crossed. Thus, adding one year to Feb\n29, 2000 will result in Feb 28, 2001. If you were to then add three more years this will\nresult in Feb 28, 2004.\n\nIf you specify \"preserve\", the same calculation is done as for \"limit\" except that if the\noriginal date is at the end of the month the new date will also be. For instance, adding one\nmonth to Feb 29, 2000 will result in Mar 31, 2000.\n\nFor positive durations, this parameter defaults to \"wrap\". For negative durations, the\ndefault is \"preserve\". This should match how most people \"intuitively\" expect datetime math\nto work.\n\nAll of the duration units can be positive or negative. However, if any of the numbers are\nnegative, the entire duration is negative.\n\nAll of the numbers must be integers.\n\nInternally, years as just treated as 12 months. Similarly, weeks are treated as 7 days, and\nhours are converted to minutes. Seconds and nanoseconds are both treated separately.\n\n$dur->clone\nReturns a new object with the same properties as the object on which this method was called.\n\n$dur->inunits( ... )\nReturns the length of the duration in the units (any of those that can be passed to\n\"DateTime::Duration->new\") given as arguments. All lengths are integral, but may be negative.\nSmaller units are computed from what remains after taking away the larger units given, so for\nexample:\n\nmy $dur = DateTime::Duration->new( years => 1, months => 15 );\n\n$dur->inunits('years');                # 2\n$dur->inunits('months');               # 27\n$dur->inunits( 'years', 'months' );    # (2, 3)\n$dur->inunits( 'weeks', 'days' );      # (0, 0) !\n\nThe last example demonstrates that there will not be any conversion between units which don't\nhave a fixed conversion rate. The only conversions possible are:\n\n*   years <=> months\n\n*   weeks <=> days\n\n*   hours <=> minutes\n\n*   seconds <=> nanoseconds\n\nFor the explanation of why this is the case, please see the How DateTime Math Works section of\nthe DateTime documentation\n\nNote that the numbers returned by this method may not match the values given to the constructor.\n\nIn list context, \"$dur->inunits\" returns the lengths in the order of the units given. In scalar\ncontext, it returns the length in the first unit (but still computes in terms of all given\nunits).\n\nIf you need more flexibility in presenting information about durations, please take a look a\nDateTime::Format::Duration.\n\n$dur->ispositive, $dur->iszero, $dur->isnegative\nIndicates whether or not the duration is positive, zero, or negative.\n\nIf the duration contains both positive and negative units, then it will return false for all of\nthese methods.\n\n$dur->iswrapmode, $dur->islimitmode, $dur->ispreservemode\nIndicates what mode is used for end of month wrapping.\n\n$dur->endofmonthmode\nReturns one of \"wrap\", \"limit\", or \"preserve\".\n\n$dur->calendarduration\nReturns a new object with the same *calendar* delta (months and days only) and end of month mode\nas the current object.\n\n$dur->clockduration\nReturns a new object with the same *clock* deltas (minutes, seconds, and nanoseconds) and end of\nmonth mode as the current object.\n\n$dur->inverse( ... )\nReturns a new object with the same deltas as the current object, but multiplied by -1. The end\nof month mode for the new object will be the default end of month mode, which depends on whether\nthe new duration is positive or negative.\n\nYou can set the end of month mode in the inverted duration explicitly by passing an\n\"endofmonth\" parameter to the \"$dur->inverse\" method.\n\n$dur->addduration($durationobject), $dur->subtractduration($durationobject)\nAdds or subtracts one duration from another.\n\n$dur->add( ... ), $dur->subtract( ... )\nThese accept either constructor parameters for a new \"DateTime::Duration\" object or an\nalready-constructed duration object.\n\n$dur->multiply($number)\nMultiplies each unit in the \"DateTime::Duration\" object by the specified integer number.\n\nDateTime::Duration->compare( $duration1, $duration2, $basedatetime )\nThis is a class method that can be used to compare or sort durations. Comparison is done by\nadding each duration to the specified DateTime object and comparing the resulting datetimes.\nThis is necessary because without a base, many durations are not comparable. For example, 1\nmonth may or may not be longer than 29 days, depending on what datetime it is added to.\n\nIf no base datetime is given, then the result of \"DateTime->now\" is used instead. Using this\ndefault will give non-repeatable results if used to compare two duration objects containing\ndifferent units. It will also give non-repeatable results if the durations contain multiple\ntypes of units, such as months and days.\n\nHowever, if you know that both objects only consist of one type of unit (months *or* days *or*\nhours, etc.), and each duration contains the same type of unit, then the results of the\ncomparison will be repeatable.\n\n$dur->deltamonths, $dur->deltadays, $dur->deltaminutes, $dur->deltaseconds, $dur->deltananoseconds\nThese methods provide the information DateTime needs for doing date math. The numbers returned\nmay be positive or negative. This is mostly useful for doing date math in DateTime.\n\n$dur->deltas\nReturns a hash with the keys \"months\", \"days\", \"minutes\", \"seconds\", and \"nanoseconds\",\ncontaining all the delta information for the object. This is mostly useful for doing date math\nin DateTime.\n\n$dur->years, $dur->months, $dur->weeks, $dur->days, $dur->hours, $dur->minutes, $dur->seconds, $dur->nanoseconds\nThese methods return numbers indicating how many of the given unit the object represents, after\nhaving done a conversion to any larger units. For example, days are first converted to weeks,\nand then the remainder is returned. These numbers are always positive.\n\nHere's what each method returns:\n\n$dur->years       == abs( $dur->inunits('years') )\n$dur->months      == abs( ( $dur->inunits( 'months', 'years' ) )[0] )\n$dur->weeks       == abs( $dur->inunits( 'weeks' ) )\n$dur->days        == abs( ( $dur->inunits( 'days', 'weeks' ) )[0] )\n$dur->hours       == abs( $dur->inunits( 'hours' ) )\n$dur->minutes     == abs( ( $dur->inunits( 'minutes', 'hours' ) )[0] )\n$dur->seconds     == abs( $dur->inunits( 'seconds' ) )\n$dur->nanoseconds == abs( ( $dur->inunits( 'nanoseconds', 'seconds' ) )[0] )\n\nIf this seems confusing, remember that you can always use the \"$dur->inunits\" method to specify\nexactly what you want.\n\nBetter yet, if you are trying to generate output suitable for humans, use the\n\"DateTime::Format::Duration\" module.\n",
            "subsections": [
                {
                    "name": "Overloading",
                    "content": "This class overloads addition, subtraction, and mutiplication.\n\nComparison is not overloaded. If you attempt to compare durations using \"<=>\" or \"cmp\", then an\nexception will be thrown! Use the \"compare\" class method instead.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "datetime@perl.org mailing list\n",
            "subsections": []
        },
        "SUPPORT": {
            "content": "Support for this module is provided via the datetime@perl.org email list. See\nhttp://lists.perl.org/ for more details.\n\nBugs may be submitted at <https://github.com/houseabsolute/DateTime.pm/issues>.\n\nThere is a mailing list available for users of this distribution, <mailto:datetime@perl.org>.\n",
            "subsections": []
        },
        "SOURCE": {
            "content": "The source code repository for DateTime can be found at\n<https://github.com/houseabsolute/DateTime.pm>.\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "Dave Rolsky <autarch@urth.org>\n",
            "subsections": []
        },
        "COPYRIGHT AND LICENSE": {
            "content": "This software is Copyright (c) 2003 - 2021 by Dave Rolsky.\n\nThis is free software, licensed under:\n\nThe Artistic License 2.0 (GPL Compatible)\n\nThe full text of the license can be found in the LICENSE file included with this distribution.\n",
            "subsections": []
        }
    },
    "summary": "DateTime::Duration - Duration objects for date math",
    "flags": [],
    "examples": [],
    "see_also": []
}