datetime

Arguments

keyword

string with possible values:"now", "today", "yesterday" and "tomorrow"

datestr

matrix of strings representing date and time (i.e: "2022-12-08 16:14:42").

x

m-by-3 matrix, [Y, M, D] or m-by-6 matrix, [Y, M, D, H, m, S]

Y, M, D, H, m, S, MS

year, month, day, hour, minute, second, millisecond

those arguments can be real scalars or matrices of the same size.

infmt

string, format of datestr.

depfmt

string, format of x.

Possible values: 'datenum', 'excel', 'posixtime', 'yyyymmdd'

outfmt

string, display format.

dt

datetime object.

Description

Create a datetime object representing points in time (dates and times in hours, minutes and seconds).

dt = datetime(Y, M, D) creates a datetime object based on Y, M, D (year, month, day).

dt = datetime(Y, M, D, H, m, S [, MS]) returns a datetime object based on Y, M, D, H, m, S and optionaly MS (year, month, day, hour, minute, second and millisecond).

dt = datetime(x) creates a column vector of datetime. x can be:

• m-by-3 matrix containing Y, M, D (year, month, day), one information per column.

• m-by-6 matrix containing Y, M, D, H, MI, S (year, month, day, hour, minute and second), one information per column.

dt = datetime(keyword) creates a datetime object from keywords: 'now', 'today', 'yesterday', 'tomorrow'.

• dt = datetime('now') or dt = datetime() returns the current date and time.

• dt = datetime('today'|'yersterday'|'tomorrow') returns the current|previous|next date at midnight.

dt = datetime(datestr) creates a datetime object from formatted strings. By default, the accepted formats for strings are "yyyy-MM-dd", "yyyy-MM-dd HH:mm:ss and "dd-MMM-yyyy", "dd-MMM-yyyy HH:mm:ss". If the format of datestr does not match the default formats, then dt = datetime(datestr, 'InputFormat', infmt) has to be used. For more details, see Format section below.

dt = datetime(x, 'ConvertFrom', depfmt) converts x to a datetime object. depfmt specifies the format of x. The available values are:

• 'datenum': number of days since 0000-01-01.

• 'excel': number of days since 1900-01-01.

• 'posixtime': number of seconds since 1970-01-01.

• 'yyyymmdd': dates as YYYYMMDD values.

The default display format is yyyy-mm-dd HH:mm:ss, but it is possible to change it by specifying the OuputFormat option: datetime(..., 'OutputFormat', outfmt). For more details, see Format section below.

datetime([]) creates a 0x0 datetime object.

datetime("") creates a NaT datetime.

Input/Output Format

To specify your input/output format, you must use the following letters:

• 'yy', 'yyyy' is for year.

• 'M', 'MM', 'MMM', 'MMMM' is for month.

  'MMM' corresponds to the first three letters of the month (for example, Dec for December).

  'MMMM' must be used for the full month name.

  Warning: the months must be in English.

• 'd' or 'dd' is for day.

• 'H' or 'HH' is for hour, 24 hours format.

• 'h' or 'hh' is for hour, 12 hours format.

  With this format, you must add 'a' to specify 'AM'/'PM.

• 'mm' is for minutes.

• 'ss' or 'ss.SSS' is for second with or without millisecond.

• 'eee' or 'eeee' is for day of week.

  'eee' corresponds to the first three letters of the day (for example, Mon for Monday).

  'eeee' must be used for the full day name.

  Warning: the days of week must be in English.

To separate each group, you can use '-', '/', '.', ..., space or tabulation.

Examples

No argument

dt = datetime()

Datetime with keyword

dt = datetime("yesterday")
dt = datetime("today")
dt = datetime("tomorrow")

Datetime with datestr - default formats: 'yyyy-MM-dd HH:mm:ss' or 'dd-MMM-yyyy HH:mm:ss'

If the format of datestr does not match with the default format, 'InputFormat' has to be specified.

// default formats managed by datetime
dt = datetime("2022-09-01")
dt = datetime("01-Sep-2022")
dt = datetime("2022-09-01 09:53:30")
dt = datetime("01-Sep-2022 09:53:30")

dt = datetime(["2022-09-01" "2022-09-15"])
dt = datetime(["10-Apr-2022" "20-Aug-2022"])
dt = datetime(["2022-09-01 09:53:30"; "2022-09-01 11:46:15"])
dt = datetime(["01-Dec-2022 09:53:30"; "31-Dec-2022 23:59:59"])

// with ""
dt = datetime(["01-Dec-2022 09:53:30"; ""; "31-Dec-2022 23:59:59"])

Datetime with InputFormat

dt = datetime("14.07.1789", "InputFormat", "dd.MM.yyyy")
dt = datetime("14.07.1789 14:37:54.123", "InputFormat", "dd.MM.yyyy HH:mm:ss.SSS")
dt = datetime("14.07.1789 14:37", "InputFormat", "dd.MM.yyyy HH:mm")
dt = datetime(["Wednesday, December 7, 2022 00:41 AM"], "InputFormat", "eeee, MMMM d, yyyy hh:mm a")
dt = datetime(["01:23:45.678" "12:34:56.789" "23:45:01.234"], "InputFormat", "HH:mm:ss.SSS")
dt = datetime("15:54:51", "InputFormat", "HH:mm:ss")
dt = datetime("15:54", "InputFormat", "HH:mm")
dt = datetime("2022-12-25 15:54:01.456", "InputFormat", "yyyy-MM-dd HH:mm:ss.SSS")

Datetime with X

// X: matrix m-by-3 or m-b-6
dt = datetime([2022 9 1])
dt = datetime([2022 9 1; 2022 9 15])
dt = datetime([2022 12 1 9 53 30])
dt = datetime([2022 12 1 9 53 30; 2022 12 31 23 59 59])

Datetime with Y, M, D

dt = datetime(1789, 7, 14)
dt = datetime([1789 2022], 7, 14)
dt = datetime(2022,1:12, 1)
dt = datetime(2022, 1, [1 14; 15 31])
dt = datetime([1990:5:2000]', 1, 1)

Datetime with Y, M, D, H, MI, S

dt = datetime(2010, 6, 14, 12, 47, 5)
dt = datetime(2010, 6, 14, 12, 47:2:59, 5)
dt = datetime([2010; 2020], 6, [14; 23], 12, 47, 5)

Datetime with Y, M, D, H, MI, S, MS

dt = datetime(2010, 6, 14, 12, 47, 5, 300)
dt = datetime(2010, 6, 14, 12, 47:2:59, 5, 300)
dt = datetime([2010; 2020], 6, [14; 23], 12, 47, 5, [300; 234])

Datetime with ConvertFrom

// With ConvertFrom
dt = datetime(datenum(), "ConvertFrom", "datenum")
dt = datetime(44819.3834418981, "ConvertFrom", "excel")
dt = datetime(1663226303.936, "ConvertFrom", "posixtime")
dt = datetime(20140402, "ConvertFrom", "yyyymmdd")

Datetime with OutputFormat

dt = datetime("2022-09-01", "OutputFormat", "dd MMMM yyyy")
dt = datetime("2022-09-01", "OutputFormat", "eeee, dd MMMM yyyy")
dt = datetime("2022-09-01", "OutputFormat", "MMMM d, yyyy")
dt = datetime("2022-09-01", "OutputFormat", "dd/MM/yy")

dt = datetime("2022-09-01 08:10", "OutputFormat", "dd MMMM yyyy HH:mm")
dt = datetime("2022-09-01 08:10", "OutputFormat", "eeee, dd MMMM yyyy HH:mm")
dt = datetime("2022-09-01 08:10:30", "OutputFormat", "MMMM d, yyyy HH:mm:ss")
dt = datetime("2022-09-01 00:41 AM", "OutputFormat", "dd/MM/yy hh:mm a")

Datetime with InputFormat and OutputFormat

dt = datetime("12 December 2022", "InputFormat", "dd MMMM yyyy", "OutputFormat", "MM/dd/yy")
dt = datetime("12 December 2022 09:50 PM", "InputFormat", "dd MMMM yyyy hh:mm a", "OutputFormat", "MM/dd/yy HH:mm:ss")

Extraction - Insertion - Computation

dt = datetime(2022, 08, 31):calmonths(2):datetime(2022, 12, 31)
dt(2)
dt($+1) = dt($) + calmonths(2)
size(dt)
dt = matrix(dt, 2, 2)
dt(1,2) = dt(1,2) + duration(12, 0, 0)
dt(2,1) = duration(9,45,12) + dt(2,1)

See also

• duration — create a duration - duration in hours, minutes and seconds
• calendarDuration — create a calendarDuration - duration in days, months and years
• NaT — Not a Time function used to create empty datetime
• isnat — check if a variable contains "Not a Time" values

History