<< datenum Time and Date datevec >>
Scilab Help >> Time and Date > datetime

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:

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

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:

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:

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:

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

History

VersionDescription
2024.0.0 Introduction in Scilab.
2024.1.0 datetime() and datetime("now") handle milliseconds values.

Report an issue
<< datenum Time and Date datevec >>