datenum

The datenum function creates a
numeric array that represents each point in time as the number of
days from January 0, 0000. The numeric values also can represent
elapsed time in units of days. However, the best way to represent
points in time is by using the datetime data type.
The best way to represent elapsed time is by using the duration or calendarDuration data
types.

Description

A serial date number represents the whole and fractional number
of days from a fixed, preset date (January 0, 0000) in the proleptic
ISO calendar.

DateNumber = datenum(DateString)
converts text representing dates and times to serial date numbers.
If the format used in the text is known, specify the format as formatIn.
Syntaxes without formatIn are significantly slower
than syntaxes that include it.

DateNumber = datenum(DateString,PivotYear) uses PivotYear to
interpret text that specifies the year as two characters. If the format
used in the text is known, specify the format as formatIn.
Syntaxes without formatIn are significantly slower
than syntaxes that include it.

DateNumber = datenum(DateString,formatIn,PivotYear) uses formatIn to
interpret the dates and times represented by DateString,
and PivotYear to interpret text that specifies
the year as two characters. You can specify formatIn and PivotYear in
either order.

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

DateNumber = datenum(Y,M,D,H,MN,S) additionally
returns the serial date numbers for corresponding elements of the H, MN,
and S (hour, minute, and second) arrays. The arrays
must be of the same size (or any can be a scalar). You also can specify
the input arguments as a date vector, [Y,M,D,H,MN,S].

Convert Year, Month, and Day to Date Number

Input Arguments

t — datetime valuesscalar | vector | matrix | multidimensional array

datetime values, specified as a scalar, vector,
matrix, or multidimensional datetime array. datenum does
not account for time zone information in t and
does not adjust datetime values that occur during Daylight Saving
Time. That is, datenum treats the TimeZone property
of t as empty and converts the remaining date and
time information to a serial date number.

DateVector — Date vectorsmatrix

Date vectors, specified as 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 DateVector should be a positive
or negative integer value except for the seconds element, which can
be fractional. If an element falls outside the conventional range, datenum adjusts
both that date vector element and the previous element. For example,
if the minutes element is 70, datenum adjusts
the hours element by 1 and sets the minutes element
to 10. If the minutes element is -15,
then datevec decreases the hours element by 1 and
sets the minutes element to 45. Month values are
an exception. datenum sets month values less than 1 to 1.

Text representing dates and times, specified as a character array where each row contains text
representing one point in time, as a cell vector of character vectors, or as a string
vector. All rows of a character array, or all elements of a cell vector or string
vector, must have the same format.

Example: '24-Oct-2003 12:45:07'

Example: ['19-Sep-2013';'20-Sep-2013';'21-Sep-2013']

Example: {'15-Oct-2010' '20-Nov-2012'}

If the format used in the text is known, you should also specify formatIn.
If you do not specify formatIn, DateString must
be in one of the following formats.

Format of Text Representing
Dates and Times

Example

'dd-mmm-yyyy HH:MM:SS'

01-Mar-2000 15:45:17

'dd-mmm-yyyy'

01-Mar-2000

'mm/dd/yyyy'

03/01/2000

'mm/dd/yy'

03/01/00

'mm/dd'

03/01

'mmm.dd,yyyy HH:MM:SS'

Mar.01,2000 15:45:17

'mmm.dd,yyyy'

Mar.01,2000

'yyyy-mm-dd HH:MM:SS'

2000-03-01 15:45:17

'yyyy-mm-dd'

2000-03-01

'yyyy/mm/dd'

2000/03/01

'HH:MM:SS'

15:45:17

'HH:MM:SS PM'

3:45:17 PM

'HH:MM'

15:45

'HH:MM PM'

3:45 PM

Note

The symbolic identifiers describing date and time formats are
different from those that describe the display formats of datetime arrays.

Certain formats might not contain enough information to convert
text representations of dates and times. In those cases, hours, minutes,
and seconds default to 0, days default to 1, months default to January,
and years default to the current year. datevec and datenum consider
two-character years (e.g., '79') to fall within
the 100-year range centered around the current year.

When you do not specify formatIn, note the
following:

For the formats that specify the month as two digits
(mm), the month value must not be greater than
12.

However, for the format 'mm/dd/yy',
if the first entry in the text is greater than 12 and the second entry
is less than or equal to 12, then datenum considers
the text to be in 'yy/mm/dd' format.

Format of the input text representing dates and times, specified as a character vector or
string scalar of symbolic identifiers.

Example: 'dddd, mmm dd, yyyy'

The following table shows symbolic identifiers that you can
use to construct the formatIn character vector.
You can include characters such as a hyphen, space, or colon to separate
the fields.

Note

The symbolic identifiers describing date and time formats are
different from the identifiers that describe the display formats of datetime arrays.

Symbolic Identifier

Description

Example

yyyy

Year in full

1990, 2002

yy

Year in two digits

90, 02

QQ

Quarter year using letter Q and one
digit

Q1

mmmm

Month using full name

March, December

mmm

Month using first three letters

Mar, Dec

mm

Month in two digits

03, 12

m

Month using capitalized first letter

M, D

dddd

Day using full name

Monday, Tuesday

ddd

Day using first three letters

Mon, Tue

dd

Day in two digits

05, 20

d

Day using capitalized first letter

M, T

HH

Hour in two digits
(no leading zeros
when symbolic identifier AM or PM is
used)

05, 5AM

MM

Minute in two digits

12, 02

SS

Second in two digits

07, 59

FFF

Millisecond in three digits

057

AM or PM

AM or PM inserted
in text representing time

3:45:02PM

The formatIn value must follow these guidelines:

You cannot specify any field more than once. For example,
you cannot use 'yy-mmm-dd-m' because it has two
month identifiers. The one exception to this is that you can combine
one instance of dd with one instance of any of
the other day identifiers. For example, 'dddd mmm dd yyyy' is
a valid input.

Start year of the 100-year date range in which a two-character
year resides, specified as an integer. Use a pivot year to interpret
dates that specify the year as two characters.

If formatIn contains the time of day, the
pivot year is computed from the current time of the current day, month,
and year. Otherwise it is computed from midnight of the current day,
month, and year.

Example: 2000

Note

If the input date format specifies a four-character year, then
the last two characters are truncated, and the first two
characters specify the year. For example, if the date and pivot year
are specified as ('25122015','ddmmyyyy',2000),
then the resulting date is 25-12-2020, not 25-12-2015.

Data Types: double

Y,M,D — Year, month, and day arraysscalar | vector | matrix | array

Year, month, and day arrays specified as a scalar, vector, matrix,
or array. These must be the same size, or any one can be a scalar. Y,M,D should
be integer values.

If Y,M,D are all scalars or all column vectors,
you can specify the input arguments as a date vector, [Y,M,D].

Year, month, day, hour, minute, and second arrays specified
as a scalar, vector, matrix, or array. These must be the same size,
or any one can be a scalar. datenum does not accept
milliseconds as a separate input, but as a fractional part of the
seconds input, S. Y,M,D,H,MN should
be integer values.

If Y,M,D,H,MN,S are all scalars or all column
vectors, you can specify the input arguments as a date vector[Y,M,D,H,MN,S].