datenum (MATLAB Functions)

Convert date and time to serial date number

Syntax

N = datenum(V)
N = datenum(S, F)
N = datenum(S, F, P)
N = datenum(S, P, F)
N = datenum(Y, M, D)
N = datenum(Y, M, D, H, MI, S)
N = datenum(S)
N = datenum(S, P)

Description

datenum is one of three conversion functions that enable you to express dates and times in any of three formats in MATLAB: a string (or date string), a vector of date and time components (or date vector), or as a numeric offset from a known date in time (or serial date number). Here is an example of a date and time expressed in the three MATLAB formats:

Date String:           '24-Oct-2003 12:45:07'
Date Vector:           [2003  10  24  12  45  07]
Serial Date Number:    7.3188e+005

A serial date number represents the whole and fractional number of days from 1-Jan-0000 to a specific date. The year 0000 is merely a reference point and is not intended to be interpreted as a real year in time.

N = datenum(V) converts one or more date vectors V to serial date numbers N. Input V can be an m-by-6 or m-by-3 matrix containing m full or partial date vectors respectively. A full date vector has six elements, specifying year, month, day, hour, minute, and second, in that order. A partial date vector has three elements, specifying year, month, and day, in that order. Each element of V must be a positive double-precision number. datenum returns a column vector of m date numbers, where m is the total number of date vectors in V.

N = datenum(S, F) converts one or more date strings S to serial date numbers N using format string F to interpret each date string. Input S can be a one-dimensional character array or cell array of date strings. All date strings in S must have the same format, and that format must match one of the date string formats shown in the help for the datestr function. datenum returns a column vector of m date numbers, where m is the total number of date strings in S. MATLAB considers date string years that are specified with only two characters (e.g., '79') to fall within 100 years of the current year.

See the datestr reference page to find valid string values for F. These values are listed in Table 1 in the column labeled "Dateform String." You can use any string from that column except for those that include the letter Q in the string (for example, 'QQ-YYYY'). Certain formats may not contain enough information to compute a date number. In these cases, hours, minutes, and seconds default to 0, the month defaults to January, the day to 1, and the year to the current year.

N = datenum(S, F, P) converts one or more date strings S to date numbers N using format F and pivot year P. The pivot year is used in interpreting date strings that have the year specified as two characters. It is the starting year of the 100-year range in which a two-character date string year resides. The default pivot year is the current year minus 50 years.

N = datenum([S, P, F]) is the same as the syntax shown above, except the order of the last two arguments are switched.

N = datenum(Y, M, D) returns the serial date numbers for corresponding elements of the Y, M, and D (year, month, day) arrays. Y, M, and D must be arrays of the same size (or any can be a scalar) of type double. You can also specify the input arguments as a date vector, [Y M D].

For this and the following syntax, values outside the normal range of each array are automatically carried to the next unit. Values outside the normal range of each array are automatically carried to the next unit. For example, month values greater than 12 are carried to years. Month values less than 1 are set to be 1. All other units can wrap and have valid negative values.

N = datenum(Y, M, D, H, MI, S) returns the serial date numbers for corresponding elements of the Y, M, D, H, MI, and S (year, month, day, hour, minute, and second) array values. Y, M, D, H, MI, and S must be arrays of the same size (or any can be a scalar) of type double. You can also specify the input arguments as a date vector, [Y M D H MI S].

N = datenum(S) converts date string S into a serial date number. String S must be in one of the date formats 0, 1, 2, 6, 13, 14, 15, 16, or 23, as defined in the reference page for the datestr function. MATLAB considers date string years that are specified with only two characters (e.g., '79') to fall within 100 years of the current year. If the format of date string S is known, use the syntax N = datenum(S, F).

N = datenum(S, P) converts date string S, using pivot year P. If the format of date string S is known, use the syntax N = datenum(S, F, P).

Note The last two calling syntaxes are provided for backward compatibility and are significantly slower than the syntaxes that include a format argument F.

Examples

Convert a date string to a serial date number:

n = datenum('19-May-2001', 'dd-mmm-yyyy')

n =
      730990

Specifying year, month, and day, convert a date to a serial date number:

n = datenum(2001, 12, 19)

n =
      731204

Convert a date vector to a serial date number:

format bank
n = datenum([2001 5 19 18 0 0])

n =
  730990.75

Convert a date string to a serial date number using the default pivot year:

n = datenum('12-jun-17', 'dd-mmm-yy')

n =
      736858

Convert the same date string to a serial date number using 1400 as the pivot year:

n = datenum('12-jun-17', 'dd-mmm-yy', 1400)

n =
      517712

Specify format 'dd.mm.yyyy' to be used in interpreting a nonstandard date string:

n = datenum('19.05.2000', 'dd.mm.yyyy')

n =
      730625

See Also

datestr, datevec, date, clock, now, datetick

date datestr