Categories &

Functions List

Class Definition: datetime

datatypes: datetime

Array representing points in time using the Gregorian calendar.

A datetime array stores internally the datetime points as double arrays representing whole years, months, days, hours, and minutes, as well as seconds including their fractional part. The underlying implementation relies on the 'date.h' C++ library. The precision of this implementation is set at microseconds, which is substantial for typical times.

A datetime array is a collection of date/time elements, with each element holding a complete date/time. The datetime array also has TimeZone and Format properties associated with it, which apply to all elements in the array.

See also: calendarDuration, duration

Source Code: datetime

Properties

A read-only property specifying the local time zone of the system, where Octave is running.

Display format, specified as a character vector or string scalar. If specified as a string scalar, it is converted and stored internally as a character vector.

Time zone, specified as a character vector or string scalar. If specified as a string scalar, it is converted and stored internally as a character vector.

Methods

datetime: Τ = datetime ('now')
datetime: Τ = datetime ('today')
datetime: Τ = datetime ('tomorrow')
datetime: Τ = datetime ('yesterday')
datetime: Τ = datetime (DateStrings)
datetime: Τ = datetime (DateStrings, 'InputFormat', INFMT)
datetime: Τ = datetime (DateStrings, 'InputFormat', INFMT, 'PivotYear', PIVOT)
datetime: Τ = datetime (DateVectors)
datetime: Τ = datetime (Y, MO, D)
datetime: Τ = datetime (Y, MO, D, H, MI, S)
datetime: Τ = datetime (Y, MO, D, H, MI, S, MS)
datetime: Τ = datetime (X, 'ConvertFrom', TYPE)
datetime: Τ = datetime (…, 'Format', FMT)
datetime: Τ = datetime (…, 'TimeZone', TZ)

Τ = datetime ('now') returns a scalar datetime array corresponding to the current date and time. Τ = datetime ('now') is the same as Τ = datetime (). Except for 'now', the same syntax can be used with 'today', 'tomorrow' and 'yesterday'. These options return the respective date but with time set at midnight.

Τ = datetime (DateStrings) creates a datetime array from the text in DateStrings representing points in time. In current implementation, DateStrings are parsed by Octave’s core datevec function, hence supported text formats are currently those supported by datevec.

Τ = datetime (DateStrings, 'InputFormat', INFMT) also allows to specify a particular input text format to parse DateStrings. It is always preferable to specify the format INFMT if it is known. Formats which do not specify a particular time component will have the value set to zero. Formats which do not a date will default to January 1st of the current year.

Τ = datetime (DateStrings, 'InputFormat', INFMT, 'PivotYear', PIVOT) also allows to specify a pivot year, which refers to the year at the start of the century to which two-digit years will be referenced. When not specified, it defaults to the current years minus 50.

Τ = datetime (DateVectors) creates a column vector of datetime values from the date vectors in DateVectors.

Τ = datetime (Y, MO, D creates an array of datetime values for corresponding elements of the Y, MO, and D arrays, which must be of the same size or scalars, must contain integer values, and they correspond to years, months, and days, respectively.

Τ = datetime (Y, MO, D, H, MI, S) also adds time components to the constructed datetime arrays. H, MI, and S must be of the same size or scalars. H and MI must contain integer values, whereas S may also contain a fractional part.

Τ = datetime (Y, MO, D, H, MI, S, MS) also adds a milliseconds component, MS, which may also have a fractional part.

Τ = datetime (X, 'ConvertFrom', TYPE) converts the numeric values in X to a datetime array accordinng to the data type specified by TYPE. The following types are suppoerted:

  • 'datenum'
  • 'excel'
  • 'posixtime'
  • 'epochtime'

Τ = datetime (…, 'Format', FMT) specifies the display format of the values in the output datetime array. Currently, only the default display format is implemented.

Τ = datetime (…, 'TimeZone', TZ) sets the time zone to the values in the output datetime array. If not specified, the computer’s local timezone is used. Supported time zones are specified in the IANA’s Time Zone Database. You may specify a new time zone by setting the 'TimeZone' property of the datetime array, in which case the new datetime values may include Daylight Saving Time (DST) in their computation.

See also: NaT, datetime, isdatetime, calendarDuration, duration

datetime: cstr = dispstrings (Τ)

cstr = dispstrings (Τ) returns a cellstr array of character vectors, cstr, which has the same size as the input datetime Τ.

datetime: cstr = cellstr (T)
datetime: cstr = cellstr (T, Format)

cstr = cellstr (T) returns a cellstr array of character vectors, cstr, which has the same size as the input datetime T.

datetime: cmat = char (T)
datetime: cmat = char (T, Format)

cmat = char (T) returns a character matrix with one row per element in T.

datetime: [Y, M, D] = ymd (T)

[Y, M, D] = ymd (T) returns the year, month, and day components of the corresponding datetime values in T as separate numeric arrays. Y, M, D contain integer values and have the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output arrays.

datetime: [h, m, s] = hms (T)

[h, m, s] = ymd (T) returns the hour, minute, and second components of the corresponding datetime values in T as separate numeric arrays. h and m contain integer values and s may also contain a fractional part. All outputs have the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output arrays.

datetime: Y = year (T)

Y = year (T) returns the year number for each element of the input datetime array T. The output Y is a double array and it has the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output array.

datetime: Q = quarter (T)

Q = quarter (T) returns the quarter number for each element of the input datetime array T. The output Q is a double array containing integer values in the range [1, 4] and it has the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output array.

datetime: M = month (T)
datetime: M = month (T, monthType)

M = month (T) returns the month number for each element of the input datetime array T. The output M is a double array containing integer values in the range [1, 12] and it has the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output array.

M = month (T, monthType) returns the month number or name for each element of the input datetime array T as specified by monthType, which may have any of the following options:

  • 'monthofyear' (default) returns the month number in a numeric array.
  • 'name' returns the corresponding full name of the month in a cell array of character vectors.
  • 'shortname' returns the corresponding 3-letter abbreviation of the month in a cell array of character vectors.
datetime: D = day (T)
datetime: D = day (T, dayType)

D = day (T) returns the day number for each element of the input datetime array T. The output D is a double array containing integer values in the range [1, 31], depending on the month and year, and it has the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output array.

D = day (T, monthType) returns the day number or name for each element of the input datetime array T as specified by dayType, which may have any of the following options:

  • 'dayofmonth' (default) returns the day-of-month number in a numeric array. Depending on the month and year, it can range from 1 to 28, 29, 30, or 31.
  • 'dayofweek' returns the day-of-week number in a numeric array of double integer values ranging from 1 to 7, where 1 corresponds to Sunday.
  • 'iso-dayofweek' returns the day-of-week number in a numeric array of double integer values ranging from 1 to 7, where 1 corresponds to Monday according to the ISO 8601 standard.
  • 'dayofyear' returns the day-of-year number in a numeric array of double integer values ranging from 1 to 365 or 366, depending on the year.
  • 'name' returns the corresponding full name of the day in a cell array of character vectors.
  • 'shortname' returns the corresponding 3-letter abbreviation of the day in a cell array of character vectors.
datetime: h = hour (T)

h = hour (T) returns the hour number for each element of the input datetime array T. The output h is a double array containing integer values in the range [0, 23] and it has the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output array.

datetime: m = minute (T)

m = minute (T) returns the minute number for each element of the input datetime array T. The output m is a double array containing integer values in the range [0, 59] and it has the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output array.

datetime: s = second (T)
datetime: s = second (T, dayType)

s = second (T) returns the number of seconds for each element of the input datetime array T. The output s is a double array containing values in the range [1, 60), including any fractional part of the second, and it has the same size as T. Not-A-Time (NaT) values in T are returned as NaN in the output array.

D = second (T, secondType) returns the seconds for each element of the input datetime array T as specified by secondType, which may have any of the following options:

  • 'secondofminute' (default) returns the second of the minute in a numeric array, in the range [1, 60).
  • 'secondofday' returns the second of the day in a numeric array, in the range [1, 86400).
datetime: sz = size (T)
datetime: dim_sz = size (T, dim)
datetime: dim_sz = size (T, d1, d2, …)
datetime: [rows, columns, …, dim_n_sz] = size (…)

sz = size (T) returns a row vector with the size (number of elements) of each dimension for the datetime array T.

dim_sz = size (T, dim) returns the size of the corresponding dimension specified in dim. If dim is a vector, then dim_sz is a vector of the same length and with each element corresponding to a specified dimension. Multiple dimensions may also be specified as separate arguments.

With a single output argument, size returns a row vector. When called with multiple output arguments, size returns the size of dimension N in the Nth argument.

datetime: out = ndims (T)

out = ndims (T) returns the number of dimensions of the datetime array T.

datetime: out = numel (T)

For compatibility reasons with Octave’s OOP interface and subsasgn behavior, datetime’s numel is defined to always return 1.

datetime: N = length (T)

N = length (T) returns the size of the longest dimension of the datetime array T, unless any of its dimensions has zero length, in which case length (T) returns 0.

datetime: hey = keyHash (T)

h = keyHash (T) generates a uint64 scalar that represents the input array T. keyHash utilizes the 64-bit FMV-1a variant of the Fowler-Noll-Vo non-cryptographic hash function.

h = keyHash (T), base also generates a 64-bit hash code using base as the offset basis for the FNV-1a hash algorithm. base must be a uint64 integer type scalar. Use this syntax to cascade keyHash on multiple objects for which a single hash code is required.

Note that unlike MATLAB, this implementation does no use any random seed. As a result, keyHash will always generate the exact same hash key for any particular input across different workers and Octave sessions.

datetime: DV = datevec (T)

DV = datevec (T) returns a numeric matrix with one row per element in T.

datetime: TF = iscolumn (T)

TF = iscolumn (T) returns a logical scalar TF, which is true, if the datetime array T is a column vector, and false otherwise. A column vector is a 2-D array for which size (X) returns [N, 1] with non-negative N.

datetime: TF = isempty (T)

TF = isempty (T) returns a logical scalar TF, which is true, if the datetime array T is empty, and false otherwise.

datetime: out = isfinite (T)

TF = isfinite (T) returns a logical array TF of the same size as T containing true for each corresponding element of T that is finite and false otherwise. Finite elements in datetime arrays are those which are neither Inf nor NaT.

datetime: out = isinf (T)

TF = isinf (T) returns a logical array TF of the same size as T containing true for each corresponding element of T that is infinite and false otherwise.

datetime: TF = ismatrix (T)

TF = ismatrix (T) returns a logical scalar TF, which is true, if the datetime array T is a matrix, and false otherwise. A matrix is an array of any type where ndims (X) == 2 and for which size (X) returns [H, W] with non-negative H and W.

datetime: out = isinf (T)

TF = isinf (T) returns a logical array TF of the same size as T containing true for each corresponding element of T that is Not-A-Time (NaT) and false otherwise. NaT is the equivalent of NaN in numeric arrays.

datetime: TF = isrow (T)

TF = isrow (T) returns a logical scalar TF, which is true, if the datetime array T is a row vector, and false otherwise. A row vector is a 2-D array for which size (X) returns [1, N] with non-negative N.

datetime: TF = isscalar (T)

TF = isscalar (T) returns a logical scalar TF, which is true, if the datetime array T is also a scalar, and false otherwise. A scalar is a single element object for which size (X) returns [1, 1].

datetime: TF = isvector (T)

TF = isvector (T) returns a logical scalar TF, which is true if the datetime array T is a vector and false otherwise. A vector is a 2-D array for which one of the dimensions is equal to 1 (either 1×N or N×1). By definition, a scalar is also a vector.

datetime: C = cat (dim, A, B, …)

C = cat (dim, A, B, …) concatenates datetime arrays A, B, … along dimension dim. All input arrays must be datetime arrays and have the same size except along the operating dimension dim.

datetime: C = horzcat (A, B, …)

C = horzcat (A, B, … is the equivalent of the syntax B = [A, B, …] and horizontally concatenates the datetime arrays A, B, …. All input arrays must be datetime arrays and have the same size except along the second dimension.

datetime: C = vertcat (A, B, …)

C = vertcat (A, B, … is the equivalent of the syntax B = [A; B; …] and vertically concatenates the datetime arrays A, B, …. All input arrays must be datetime arrays and have the same size except along the second dimension.

datetime: B = repmat (A, n)
datetime: B = repmat (A, d1, …, dN)
datetime: B = repmat (A, dimvec)

B = repmat (A, n) returns a datetime array B containing n copies of the input datetime array A along every dimension of A.

B = repmat (A, d1, …, dN) returns an array B containing copies of A along the dimensions specified by the list of scalar integer values d1, …, dN, which specify how many copies of A are made in each dimension.

B = repmat (A, dimvec) is equivalent to the previous syntax with dimvec = [d1, …, dN].

datetime: B = repelem (A, n)
datetime: B = repelem (A, d1, …, dN)

B = repelem (A, n) returns a datetime vector B containing repeated elements of the input A, which must be a datetime vector. If n is a scalar, each element of A is repeated n times along the non-singleton dimension of A. If n is a vector, it must have the same elemnts as A, in which case it specifies the number of times to repeat each corresponding element of A.

B = repelem (A, d1, …, dN returns an array B with each element of A repeated according to the the list of input arguments d1, …, dN each corresponding to a different dimension 1:ndims (A) of the input array A. d1, …, dN must be either scalars or vectors with the same length as the corresponding dimension of A containing non-negative integer values specifying the number of repetitions of each element along the corresponding dimension.

datetime: B = repelems (A, R)

B = repelems (A, R) returns a datetime vector B containing repeated elements of the input A, which must be a datetime vector. R must be a 2×N matrix of integers. Entries in the first row of R correspond to the linear indexing of the elements in A to be repeated. The corresponding entries in the second row of R specify the repeat count of each element.

datetime: B = reshape (A, d1, …, dN)
datetime: B = reshape (A, …, [], …)
datetime: B = reshape (A, dimvec)

B = reshape (A, d1, …, dN) returns a datetime array B with specified dimensions d1, …, dN, whose elements are taken columnwise from the datetime array A. The product of d1, …, dN must equal the total number of elements in A.

B = reshape (A, …, [], …) returns a datetime array B with one dimension unspecified which is calculated automatically so that the product of dimensions in B matches the total elements in A, which must be divisible the product of specified dimensions. An empty matrix ([]) is used to flag the unspecified dimension.

datetime: B = circshift (A, n)
datetime: B = circshift (A, n, dim)

B = circshift (A, n) circularly shifts the elements of the datetime array A according to n. If n is a nonzero integer scalar, then the elements of A are shifted by n elements along the first non-singleton dimension of A. If n is a vector, it must not be longer that the number of dimensions of A with each value of n corresponding to a dimension in A. The sign of the value(s) in n specify the direction in the elements of A are shifted.

B = circshift (A, n, dim) circularly shifts the elements of the datetime array A along the dimension specified by dim. In this case, n must be a scalar integer value.

datetime: B = permute (A, dims)

B = permute (A, dims) returns the generalized transpose of the datetime array A by rearranging its dimensions according to the permutation vector specified in dims.

dims must index all the dimensions 1:ndims (A) of the input array A, in any order, but only once. The Nth dimension of A gets remapped to the dimension in B specified by dims(N).

datetime: A = ipermute (B, dims)

A = ipermute (B, dims) returns the inverse of the generalized transpose performed by the permute function. The expression ipermute (permute (A, dims), dims) returns the original array A.

dims must index all the dimensions 1:ndims (B) of the input array B, in any order, but only once. The dimension of B specified in dims(N) gets remapped to the Nth dimension of A.

datetime: B = transpose (A)

B = transpose (A) is the equivalent of the syntax B = A.' and returns the transpose of the datetime matrix A.

datetime: B = ctranspose (A)

B = ctranspose (A) is the equivalent of the syntax B = A' and returns the transpose of the datetime matrix A. For datetime arrays, ctranspose is identical to transpose.