NaT

Not-a-Time

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.

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.

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

Examples

Square NaT Matrix

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

t = NaT(3)

t = 3x3 datetime
   NaT   NaT   NaT
   NaT   NaT   NaT
   NaT   NaT   NaT

Initialize Rectangular datetime Array and Specify Format

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

n — Size of square matrix

integer

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

sz1,...,szN — Size of each dimension (as separate arguments)

integer values

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

sz — Size of each dimension (as a row vector)

integer values

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

fmt — Date format

'default' (default) | 'defaultdate' | character vector | string scalar

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 fmt	Description
'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

tz — Time zone region

'' (default) | character vector | string scalar

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 TimeZone	UTC Offset	UTC 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™.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Version History

Introduced in R2015b