Documentation

This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English verison of the page.

Note: This page has been translated by MathWorks. Please click here
To view all translated materals including this page, select Japan from the country navigator on the bottom of this page.

calendarDuration

Create calendar duration array from numeric values

collapse all in page

The calendarDuration function creates an array that represents elapsed time in calendar units of variable length. For example, the number of days in 1 month depend on the particular month of the year. Calculations with calendar durations account for daylight saving time changes and leap years.

Syntax

  • L = calendarDuration(Y,M,D)
    example
  • L = calendarDuration(Y,M,D,H,MI,S)
  • L = calendarDuration(Y,M,D,T)
    example
  • L = calendarDuration(___,'Format',displayFormat)
    example

Description

example

L = calendarDuration(Y,M,D) creates an array of calendar durations from numeric arrays containing the number of years, months, and days specified by Y, M, and D, respectively. Alternatively, you can specify the input arguments as a matrix with three columns, [Y,M,D].

L = calendarDuration(Y,M,D,H,MI,S) also includes the hours, minutes, and seconds specified by H, MI, and S, respectively. Alternatively, you can specify the input arguments as a matrix with six columns, [Y,M,D,H,MI,S].

example

L = calendarDuration(Y,M,D,T) 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.

example

L = calendarDuration(___,'Format',displayFormat) additionally specifies the format in which L displays, using any of the input arguments from the previous syntaxes.

Examples

collapse all

Open Script
L = calendarDuration(1,3,15)

L = 

  calendarDuration

   1y 3mo 15d
Open Script

Create a 2-by-2 array representing numbers of days.

D = magic(2)

D =

     1     3
     4     2

Create a 2-by-2 duration array of hours.

T = hours([1 2; 25 12])

T = 

  2×2 duration array

    1 hr    2 hr
   25 hr   12 hr

Create a calendarDuration array using scalar values for the year and month inputs.

L = calendarDuration(1,13,D,T)

L = 

  2×2 calendarDuration array

    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. Hour values greater than 24 do not carry over to days in the display, because the number of hours in a calendar day is not necessarily 24 hours.

Open Script

Create a calendarDuration array and specify a format that displays the values in terms of months, weeks, days, and time.

L = calendarDuration(1,1,5:9,12,0,0,'Format','mwdt')

L = 

  1×5 calendarDuration array

Columns 1 through 3

      13mo 5d 12h 0m 0s      13mo 6d 12h 0m 0s      13mo 1w 12h 0m 0s

Columns 4 through 5

   13mo 1w 1d 12h 0m 0s   13mo 1w 2d 12h 0m 0s

Input Arguments

collapse all

Year, month, and day values, specified as scalars, vectors, matrices, or multidimensional arrays. These values must be the same size, or any can be a scalar. Y,M,D should contain only integer values.

If Y,M,D are all scalars or all column vectors, you can specify the input arguments as a matrix with three columns, [Y,M,D].

Specifying month values greater than 12 is equivalent to 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: 2,10,24

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Year, month, day, hour, minute and second values, specified as scalars, vectors, matrices, or multidimensional arrays. These values must be the same size, or any can be a scalar. Specify fractional seconds as part of the seconds input, S. The Y,M,D,H,MI inputs should contain only integer values.

If Y,M,D,H,MI,S are all scalars or all column vectors, you can specify the input arguments as a matrix with six columns, [Y,M,D,H,MI,S].

Specifying month values greater than 12 is equivalent to 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, and 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: 2,10,24,12,45,07.451

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Year, month, day and duration values, specified as scalars, vectors, matrices, or multidimensional arrays. These values must be the same size, or any can be a scalar. Y, M, and D are numeric arrays, and T is a duration array containing elapsed times.

Specifying month values greater than 12 is equivalent to 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 and duration values are not equivalent to a number of days. The number of days in a month and the number of hours in a day are not fixed and cannot be determined until you add the calendar duration to a specific datetime.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Display format of the values in L, specified as a character vector that can include the characters y, q, m, w, d, and t, in this order. The character vector must include m to display the number of months, d to display the number of days, and t to display the number of hours, minutes, and seconds. The y (year), q (quarter), and w (week) characters are optional.

This table describes the date and time components that the characters represent.

CharacterDate or Time UnitDetails
yYearsMultiples of 12 months display as a number of years
qQuartersMultiples of 3 months display as a number of quarters
mMonthsMust be included in displayFormat
wWeeksMultiples of 7 days display as a number of weeks
dDaysMust be included in displayFormat
tTime (hours, minutes, and seconds)Must be included in displayFormat

If the value of a date or time component is zero, it is not displayed.

Changing the display format of a calendarDuration array does not change the values in the array.

Example: 'yqmdt'

Output Arguments

collapse all

Calendar duration, returned as a calendarDuration array.

You can change the display format of a calendar duration by modifying the Format property. For example, to display the calendar duration, L, as a number of months, type:

L.Format = 'm'

More About

collapse all

Tall Array Support

This function fully supports tall arrays. For more information, see Tall Arrays.

Tips

  • When you add a calendarDuration array that contains more than one unit to a datetime, MATLAB® always adds the larger units first. If t is a datetime, then this command:

    t + calendarDuration(1,2,3)
    is the same as:
    t + calyears(1) + calmonths(2) + caldays(3)

See Also

Introduced in R2014b

Was this topic helpful?
MATLAB Documentation
Other Documentation
Support
Tackling Big Data with MATLAB

Tackling Big Data with MATLAB

Watch now