datetime
create points in time
Syntax
dt = datetime() dt = datetime(keyword) dt = datetime(datestr) dt = datetime(datestr, "InputFormat", infmt) dt = datetime(Y, M, D) dt = datetime(Y, M, D, H, m, S) dt = datetime(Y, M, D, H, m, S, MS) dt = datetime(x) dt = datetime(x, "ConvertFrom", depfmt) dt = datetime(..., "OutputFormat", outfmt)
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. For more details, see Hour time format section.
'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.
Hour time Format
The symbols h
and hh
represent hours in
12-hour format (from 1 to 12). They must be combined with
a
to specify AM or PM.
hh:mm[:ss[.SSS]] a datetime("2025-10-07 14:05:32.250", "OutputFormat", "hh:mm:ss.SSS a") // Result: 02:05:32.250 PM
where:
h
: hour in 12-hour format without leading zero (1-12)hh
: hour in 12-hour format with leading zero (01-12)mm
: minutes (00-59)ss
: seconds (00-59), optionalSSS
: milliseconds, optionala
: AM/PM indicator
To display time in 24-hour format, use H
or HH
:
HH:mm[:ss[.SSS]] datetime("2025-10-07 14:05:00", "OutputFormat", "HH:mm") // Result: 14:05
Examples
No argument
dt = datetime()
--> dt = datetime() dt = [datetime] 2025-10-07 15:16:07.789
Datetime with keyword
dt = datetime("yesterday") dt = datetime("today") dt = datetime("tomorrow")
--> dt = datetime("yesterday") dt = [datetime] 2025-10-06 --> dt = datetime("today") dt = [datetime] 2025-10-07 --> dt = datetime("tomorrow") dt = [datetime] 2025-10-08
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"])
--> dt = datetime("2022-09-01") dt = [datetime] 2022-09-01 --> dt = datetime("01-Sep-2022") dt = [datetime] 2022-09-01 --> dt = datetime("2022-09-01 09:53:30") dt = [datetime] 2022-09-01 09:53:30 --> dt = datetime("01-Sep-2022 09:53:30") dt = [datetime] 2022-09-01 09:53:30 --> --> dt = datetime(["2022-09-01" "2022-09-15"]) dt = [1x2 datetime] 2022-09-01 2022-09-15 --> dt = datetime(["10-Apr-2022" "20-Aug-2022"]) dt = [1x2 datetime] 2022-04-10 2022-08-20 --> dt = datetime(["2022-09-01 09:53:30"; "2022-09-01 11:46:15"]) dt = [2x1 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"]) dt = [2x1 datetime] 2022-12-01 09:53:30 2022-12-31 23:59:59 --> --> // with "" --> dt = datetime(["01-Dec-2022 09:53:30"; ""; "31-Dec-2022 23:59:59"]) dt = [3x1 datetime] 2022-12-01 09:53:30 NaT 2022-12-31 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 12-hour time format
val = ["14:40:51"; "14:40:56"; "14:41:01"; "14:41:06"; "14:41:11"; "14:41:16"]; d = datetime(val, "InputFormat", "HH:mm:ss", "OutputFormat", "hh:mm:ss a") d = datetime(2025, 10, 7, 8, (1:10)', 0, "OutputFormat", "h:mm a")
--> val = ["14:40:51"; "14:40:56"; "14:41:01"; "14:41:06"; "14:41:11"; "14:41:16"]; --> d = datetime(val, "InputFormat", "HH:mm:ss", "OutputFormat", "hh:mm:ss a") d = [6x1 datetime] 02:40:51 PM 02:40:56 PM 02:41:01 PM 02:41:06 PM 02:41:11 PM 02:41:16 PM --> --> d = datetime(2025, 10, 7, 8, (1:10)', 0, "OutputFormat", "h:mm a") d = [10x1 datetime] 8:01 AM 8:02 AM 8:03 AM 8:04 AM 8:05 AM 8:06 AM 8:07 AM 8:08 AM 8:09 AM 8:10 AM
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])
--> dt = datetime([2022 9 1]) dt = [datetime] 2022-09-01 --> dt = datetime([2022 9 1; 2022 9 15]) dt = [2x1 datetime] 2022-09-01 2022-09-15 --> dt = datetime([2022 12 1 9 53 30]) dt = [datetime] 2022-12-01 09:53:30 --> dt = datetime([2022 12 1 9 53 30; 2022 12 31 23 59 59]) dt = [2x1 datetime] 2022-12-01 09: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)
--> dt = datetime(1789, 7, 14) dt = [datetime] 1789-07-14 --> dt = datetime([1789 2022], 7, 14) dt = [1x2 datetime] 1789-07-14 2022-07-14 --> dt = datetime(2022,1:12, 1) dt = [1x12 datetime] 2022-01-01 2022-02-01 2022-03-01 2022-04-01 2022-05-01 2022-06-01 2022-07-01 2022-08-01 2022-09-01 2022-10-01 2022-11-01 2022-12-01 --> dt = datetime(2022, 1, [1 14; 15 31]) dt = [2x2 datetime] 2022-01-01 2022-01-14 2022-01-15 2022-01-31 --> dt = datetime([1990:5:2000]', 1, 1) dt = [3x1 datetime] 1990-01-01 1995-01-01 2000-01-01
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)
--> dt = datetime(2010, 6, 14, 12, 47, 5) dt = [datetime] 2010-06-14 12:47:05 --> dt = datetime(2010, 6, 14, 12, 47:2:59, 5) dt = [1x7 datetime] 2010-06-14 12:47:05 2010-06-14 12:49:05 2010-06-14 12:51:05 2010-06-14 12:53:05 2010-06-14 12:55:05 2010-06-14 12:57:05 2010-06-14 12:59:05 --> dt = datetime([2010; 2020], 6, [14; 23], 12, 47, 5) dt = [2x1 datetime] 2010-06-14 12:47:05 2020-06-23 12:47:05
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])
--> dt = datetime(2010, 6, 14, 12, 47, 5, 300) dt = [datetime] 2010-06-14 12:47:05.300 --> dt = datetime(2010, 6, 14, 12, 47:2:59, 5, 300) dt = [1x7 datetime] column 1 to 6 2010-06-14 12:47:05.300 2010-06-14 12:49:05.300 2010-06-14 12:51:05.300 2010-06-14 12:53:05.300 2010-06-14 12:55:05.300 2010-06-14 12:57:05.300 column 7 to 7 2010-06-14 12:59:05.300 --> dt = datetime([2010; 2020], 6, [14; 23], 12, 47, 5, [300; 234]) dt = [2x1 datetime] 2010-06-14 12:47:05.300 2020-06-23 12:47:05.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")
--> dt = datetime(datenum(), "ConvertFrom", "datenum") dt = [datetime] 2025-10-07 15:30:30.415 --> dt = datetime(44819.3834418981, "ConvertFrom", "excel") dt = [datetime] 2022-09-15 09:12:09.380 --> dt = datetime(1663226303.936, "ConvertFrom", "posixtime") dt = [datetime] 2022-09-15 09:18:23.936 --> dt = datetime(20140402, "ConvertFrom", "yyyymmdd") dt = [datetime] 2014-04-02
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")
--> dt = datetime("2022-09-01", "OutputFormat", "dd MMMM yyyy") dt = [datetime] 01 September 2022 --> dt = datetime("2022-09-01", "OutputFormat", "eeee, dd MMMM yyyy") dt = [datetime] Thursday, 01 September 2022 --> dt = datetime("2022-09-01", "OutputFormat", "MMMM d, yyyy") dt = [datetime] September 1, 2022 --> dt = datetime("2022-09-01", "OutputFormat", "dd/MM/yy") dt = [datetime] 01/09/22 --> --> dt = datetime("2022-09-01 08:10", "OutputFormat", "dd MMMM yyyy HH:mm") dt = [datetime] 01 September 2022 08:10 --> dt = datetime("2022-09-01 08:10", "OutputFormat", "eeee, dd MMMM yyyy HH:mm") dt = [datetime] Thursday, 01 September 2022 08:10 --> dt = datetime("2022-09-01 08:10:30", "OutputFormat", "MMMM d, yyyy HH:mm:ss") dt = [datetime] September 1, 2022 08:10:30 --> dt = datetime("2022-09-01 00:41 AM", "OutputFormat", "dd/MM/yy hh:mm a") dt = [datetime] 01/09/22 12:41 AM
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")
--> dt = datetime("12 December 2022", "InputFormat", "dd MMMM yyyy", "OutputFormat", "MM/dd/yy") dt = [datetime] 12/12/22 --> dt = datetime("12 December 2022 09:50 PM", "InputFormat", "dd MMMM yyyy hh:mm a", "OutputFormat", "MM/dd/yy HH:mm:ss") dt = [datetime] 12/12/22 21:50:00
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)
--> dt = datetime(2022, 08, 31):calmonths(2):datetime(2022, 12, 31) dt = [1x3 datetime] 2022-08-31 2022-10-31 2022-12-31 --> dt(2) ans = [datetime] 2022-10-31 --> dt($+1) = dt($) + calmonths(2) dt = [1x4 datetime] 2022-08-31 2022-10-31 2022-12-31 2023-03-03 --> size(dt) ans = [1x2 double] 1. 4. --> dt = matrix(dt, 2, 2) dt = [2x2 datetime] 2022-08-31 2022-12-31 2022-10-31 2023-03-03 --> dt(1,2) = dt(1,2) + duration(12, 0, 0) dt = [2x2 datetime] 2022-08-31 00:00:00 2022-12-31 12:00:00 2022-10-31 00:00:00 2023-03-03 00:00:00 --> dt(2,1) = duration(9,45,12) + dt(2,1) dt = [2x2 datetime] 2022-08-31 00:00:00 2022-12-31 12:00:00 2022-10-31 09:45:12 2023-03-03 00:00:00
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
Version | Description |
2024.0.0 | Introduction in Scilab. |
2024.1.0 | datetime() and datetime("now") handle milliseconds values. |
Report an issue | ||
<< datenum | Time and Date | datevec >> |