Contract
Parameter key	Default value	Type
years	0	number
months	0	number
days	0	number
hours	0	number
minutes	0	number
seconds	0	number
milliseconds	0	number

Water Contract
<class duration years =0=number months =0=number days =0=number hours =0=number minutes =0=number seconds =0=number milliseconds=0=number />

See also: datetime, plus, minus

A duration is an amount of time. You create a duration by passing in any number of years, months, days, hours, minutes, seconds, milliseconds. These values are summed to create the duration. Note that the values passed in need not conform to their normal range _vector_fieldsrictions. For example, you can create a duration of 45 days, or 14 months and 92 minutes. If you use durations that do not have months or years, durations are consistent. Because months can have between 28 and 31 days, some care in using durations containing months and years must be exercised since the actual time in the duration is dependent on WHEN the duration is. Working with durations and their relationship between dates will sometimes produce unexpected results. If you create a duration of exactly 1 month, the duration object will maintain that it is of 1 month. The other fields will be zero. Now say you add that duration to a date of Feb 1, 2000. You will get a new date of Mar 1, 2000. That is correct since we are adding one month to Feb 1, we expect Mar 1. But it happens because the duration to be added is taken to be the duration relative to Feb 1. Now we subtract Mar 1 from Feb 1 to get a new duration. This duration will have to "stand alone" from what date it was generated from, so Water makes it a definitive 29 days. If we compare this duration to our original duration, we find that they are not equal. To perform this comparison we must convert our 1 month duration into a definitive number of days. Since we don't have a reference date from within the computation, Water uses the default reference date of Aug 1, 2002. [This date has been carefully chosen to yield durations and dates closest to your expectation, but it will often be somewhat off.] Adding a month to Aug 1 will yield Sep 1, we get the duration between Aug 1 and Sep 1 as 30 days which is not equal to 29 days.

<set orig_dt=<datetime 2004 2/>/>
<set orig_dur=<duration months=1/>/>
<set new_dt=<orig_dt/>.<plus orig_dur/>/> <!-- Feb 1, 2004 -->
<set new_dur=new_dt.<minus orig_dt/>/>    <!-- duration of 29 days sionce 2004 is a leap year -->
orig_dur.<equal new_dur/>  <!-- false -->
new_dt.<plus new_dur/> <!-- datetime of Mar 1 plus 29 days yields Mar 30, not Apr 1. Mar has 31 days -->

When Water is "normalizing" a duration it will restrict milliseconds to the range 0 through 999, seconds; minutes 0 through 59; hours 0 through 23. Any excess will be passed to the next higher level up. But for days, Water does NOT pass the "overlap" of more than 31 days up since the conversion between days and months is ambiguous. So days can grow to be a large integer. If you don't use months and years in your durations, you'll be consistent, though that may become so inconvenient that you'll want to use years and months. Beware that doing arithmetic with such durations will often lead to inaccuracies. When you are getting values out of a duration you may use plural nouns: years, months, days, hours, minutes, seconds, milliseconds to get the "limited" version [i.e. months will always be between 1 and 12 inclusive] or the methods of in_years, in_months, in_days, in_hours, in_minutes, in_seconds, in_milliseconds to get the full duration in terms of those units. Should a number be higher than an integer can represent, a double will be returned of the amount, which may lead to round-off errors in large computations.

<duration months=18/>.years

1

<duration months=18/>.months

6

<duration months=18/>.<in_years/>

1.5031941592516542

Note that last result is not 1.5 since 6 months isn't always exactly half a year. Durations have comparators: equal, less, more less_or_equal, more_or_equal and arithmetic: plus, minus, times, divide.