calendarDuration - Lengths of time in variable-length calendar units - MATLAB (original) (raw)
Lengths of time in variable-length calendar units
Description
The values in calendar duration arrays represent elapsed time in calendar units of variable length. For example, the number of days in a month depends on the particular month of the year. Calculations with calendar durations account for daylight saving time changes and leap years. Use calendar duration arrays to simplify calculations on datetime arrays that involve calendar units, such as days and months.
Creation
You can create calendar duration arrays that have specified time units using thecalyears, calquarters, calmonths, calweeks, and caldays functions. For example, to create an array that has elapsed times of 1, 2, and 3 calendar months, use thecalmonths function.
M =
1×3 calendarDuration array
1mo 2mo 3mo
You also can create a calendar duration array using thecalendarDuration function, described below.
Syntax
Description
L = calendarDuration([Y,M,D](#d126e170280)) creates an array of calendar durations from numeric arraysY, M, and D, containing the number of years, months, and days, respectively.
L = calendarDuration(Y,M,D,[H,MI,S](#d126e170306)) also includes hours, minutes, and seconds specified by H,MI, and S, respectively.
L = calendarDuration(Y,M,D,[T](#d126e170336)) creates an array of calendar durations from numeric arrays containing the number of years, months, and days, and a duration array T containing elapsed times.
L = calendarDuration([X](#d126e170370)) creates an array of calendar durations from a numeric matrix.
L = calendarDuration(___,'Format',displayFormat) additionally specifies displayFormat as the value of theFormat property of L. TheFormat property changes the display ofL but not its values. You can use this syntax with any of the arguments from the previous syntaxes.
Input Arguments
Years, months, and days, specified as numeric arrays. These arrays either must be the same size, or any can be a scalar.Y,M,D must contain only integer values.
Specifying month values greater than 12 is equivalent to specifying a number of years plus a number of months. For example, 25 months are equal to 2 years and 1 month. However, day values are not equivalent to a number of months because the number of days in a month is not fixed, and cannot be determined until you add the calendar duration to a specific datetime.
Example: L = calendarDuration(2,10,24) returns a calendar duration of 2 years, 10 months, and 24 days.
Hours, minutes, and seconds, specified as numeric arrays. These arrays either must be the same size, or any can be a scalar. Specify fractional seconds as part of S. The H andMI arrays must contain only integer values.
Specifying month values greater than 12 is equivalent to specifying a number of years plus a number of months. For example, 25 months are equal to 2 years and 1 month. Minute values greater than 60 carry over to a number of hours. Second values greater than 60 carry over to a number of minutes. However, day values are not equivalent to a number of months because the number of days in a month is not fixed and cannot be determined until you add the calendar duration to a specific datetime. Similarly, hour values are not equivalent to a number of calendar days.
Example: L = calendarDuration(2,10,24,12,45,07.451) returns a calendar duration of 2 years, 10 months, 24 days, 12 hours, 45 minutes, and 7.451 seconds.
Elapsed times, specified as a duration array. T either must be the same size as the Y,M, and D input arguments or be a scalar.
Example: T = hours(5); L = calendarDuration(2,10,24,T) adds a duration of 5 hours toL.
Years, months, days, and optionally, times, specified as a numeric matrix. X must have either three or six columns. The first three columns contain the number of years, months, and days, respectively. If X has six columns, then the last three columns contain the number of hours, minutes, and seconds, respectively.
All columns must contain integer values, except for the sixth column. You can specify fractional seconds in the sixth column.
Example: L = calendarDuration([2 10 24]) returns a calendar duration of 2 years, 10 months, and 24 days.
Example: L = calendarDuration([2 10 24 12 45 07.451]) returns a calendar duration of 2 years, 10 months, 24 days, 12 hours, 45 minutes, and 7.451 seconds.
Properties
Display format for calendar durations, specified as a combination of the characters y, q, m,w, d, and t, in that order. The format must include m,d, and t.
| Character | Unit | Required? |
|---|---|---|
| y | Years (multiples of 12 months) | no |
| q | Quarters (multiples of 3 months) | no |
| m | Months | yes |
| w | Weeks (multiples of 7 days) | no |
| d | Days | yes |
| t | Time (hours, minutes, and seconds) | yes |
To specify the number of digits displayed for fractional seconds, use the format function.
If the value of a date or time component is zero, then it is not displayed.
Example: L.Format = 'yqmdt' displays each value inL as the number of calendar years, quarters, months, and days, along with its time component.
Examples
Create a datetime value.
Create a datetime array in which each value starts on the first day of a different month. One convenient way to create such an array is to add an array of calendar months to D.
First, create an array of calendar months using the calmonths function.
C = 1×4 calendarDuration 0mo 1mo 2mo 3mo
Then, add D and C. Since C is a calendar duration array, this operation accounts for the fact that months can have different numbers of days.
M = 1×4 datetime 01-Jul-2017 01-Aug-2017 01-Sep-2017 01-Oct-2017
Due to leap years and Daylight Saving Time, calendar years, months, and days can have varying lengths. To accommodate these varying lengths of time, use calendar duration arrays for arithmetic operations on datetime arrays.
L = calendarDuration(1,3,15)
L = calendarDuration 1y 3mo 15d
Create a numeric array representing numbers of days.
Create a duration array representing elapsed times in hours. One element specifies 25 hours, which is longer than one day.
T = 2×2 duration 1 hr 2 hr 25 hr 12 hr
Create a calendar duration array. Specify input arguments D, T, and scalar values for the year and month. The second input, 13, specifies more months than there are in one year.
L = calendarDuration(1,13,D,T)
L = 2×2 calendarDuration 2y 1mo 1d 1h 0m 0s 2y 1mo 3d 2h 0m 0s 2y 1mo 4d 25h 0m 0s 2y 1mo 2d 12h 0m 0s
Month values greater than 12 carry over to years in the display. However, hour values greater than 24 do not carry over to days in the display. Due to Daylight Saving Time, the number of hours in a calendar day is not necessarily 24 hours.
Create a calendar duration array and specify a format that displays the values in terms of months, weeks, days, and time.
L = calendarDuration(1,1,5:9,'Format','mwdt')
L = 1×5 calendarDuration 13mo 5d 13mo 6d 13mo 1w 13mo 1w 1d 13mo 1w 2d
Since the format does not include 'y' for years, the input values of 1 year and 1 month display as their sum, 13mo. While 't' must be specified, the time component is not displayed if the hours, minutes, and seconds are all zero.
Tips
- For more information on functions that accept or return calendar duration arrays, see Dates and Time.
- When you add a
calendarDurationarray that contains more than one unit to a datetime, MATLAB® always adds the larger units first. Iftis a datetime, then this command:
t + calendarDuration(1,2,3)
is the same as:
t + calyears(1) + calmonths(2) + caldays(3)
Extended Capabilities
ThecalendarDuration function fully supports tall arrays. For more information, see Tall Arrays.
Version History
Introduced in R2014b