Main Content

NaT

Not-a-Time

collapse all in page

Syntax

NaT
t = NaT(n)
t = NaT(sz1,...,szN)
t = NaT(sz)
t = NaT(___,'Format',fmt)
t = NaT(___,'TimeZone',tz)

Description

NaT is the representation for Not-a-Time, a value that can be stored in a datetime array to indicate an unknown or missing datetime value.

The datetime function creates a NaT value automatically when it cannot convert text to a datetime value, or for elements in a datetime array where the Year, Month, Day, Hour, Minute, or Second properties are set to NaN. You also can assign missing values to elements of an existing datetime array. Use the NaT function to create a new datetime array containing only NaT values.

NaT returns a scalar Not-a-Time (NaT) datetime value.

example

t = NaT(n) returns an n-by-n matrix of NaT values.

t = NaT(sz1,...,szN) returns a sz1-by-...-by-szN array of NaT values where sz1,...,szN indicates the size of each dimension. For example, NaT(3,4) returns a 3-by-4 array of NaT values.

t = NaT(sz) returns an array of NaT values where the size vector, sz, defines size(t). For example, NaT([3,4]) returns a 3-by-4 array of NaT values.

t = NaT(___,'Format',fmt) returns a datetime array with the specified display format. Use this syntax to initialize a datetime array. Not-a-Time values always display as NaT, but non-NaT values assigned to the array will display using the specified format.

example

t = NaT(___,'TimeZone',tz) returns an array of NaT values in the time zone specified by tz.

Examples

collapse all

Open Live Script

Create a 3-by-3 matrix of NaT values. 

t = NaT(3)
t = 3x3 datetime
   NaT   NaT   NaT
   NaT   NaT   NaT
   NaT   NaT   NaT
Open Live Script

Create a 2-by-3 array of NaT values and specify a date format. 

t = NaT(2,3,'Format','dd/MM/yyyy')
t = 2x3 datetime
   NaT   NaT   NaT
   NaT   NaT   NaT

Assign a datetime value to an element of t. 

t(1,2) = datetime('today')
t = 2x3 datetime
   NaT          05/09/2024   NaT       
   NaT          NaT          NaT

Input Arguments

collapse all

Size of square matrix, specified as an integer.

  • If n is 0, then t is an empty matrix.

  • If n is negative, then it is treated as 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Size of each dimension, specified as separate arguments of integer values.

  • If the size of any dimension is 0, then t is an empty array.

  • If the size of any dimension is negative, then it is treated as 0.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Size of each dimension, specified as a row vector of integer values. Each element of this vector indicates the size of the corresponding dimension:

  • If the size of any dimension is 0, then t is an empty array.

  • If the size of any dimension is negative, then it is treated as 0.

Example: sz = [2,3,4] creates a 2-by-3-by-4 array.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Date format, specified as a character vector or string scalar. Use the letters A-Z and a-z to define the format. For a complete list of valid letter identifiers, see the Format property for datetime arrays.

Alternatively, use one of the following character vectors to specify a default format.

Value of fmtDescription

'default'

Use the default display format.

'defaultdate'

Use the default display format for datetime values created without time components.

Example: 'yyyy MMM dd'

Data Types: char | string

Time zone region, specified as a character vector or string scalar.

The value of tz can be:

  • '', to create an “unzoned” datetime array that does not belong to a specific time zone.

  • The name of a time zone region from the IANA Time Zone Database, for example, 'America/Los_Angeles'. The name of a time zone region accounts for the current and historical rules for standard and daylight offsets from UTC that are observed in a geographic region.

  • An ISO 8601 character vector of the form +HH:mm or -HH:mm, for example, '+01:00', to specify a time zone that is a fixed offset from UTC.

  • 'UTC', to create a datetime array in Coordinated Universal Time.

  • 'UTCLeapSeconds', to create a datetime array in Coordinated Universal Time that accounts for leap seconds. For the list of leap seconds supported by the datetime data type, see leapseconds.

  • 'local', to create a datetime array in the system time zone.

This table lists some common names of time zone regions from the IANA Time Zone Database.

Value of TimeZoneUTC OffsetUTC DST Offset
'Africa/Johannesburg'+02:00+02:00
'America/Chicago'−06:00−05:00
'America/Denver'−07:00−06:00
'America/Los_Angeles'−08:00−07:00
'America/New_York'−05:00−04:00
'America/Sao_Paulo'−03:00−02:00
'Asia/Hong_Kong'+08:00+08:00
'Asia/Kolkata'+05:30+05:30
'Asia/Tokyo'+09:00+09:00
'Australia/Sydney'+10:00+11:00
'Europe/London'+00:00+01:00
'Europe/Zurich'+01:00+02:00

Data Types: char | string

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

Introduced in R2015b

See Also

| | |