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
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.
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 (
returns a scalar datetime array
corresponding to the current date and time. 'now'
)Τ = datetime
(
is the same as 'now'
)Τ = 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,
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.
'InputFormat'
,
INFMT)
Τ = datetime (DateStrings,
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.
'InputFormat'
,
INFMT, 'PivotYear'
, PIVOT)
Τ = 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,
converts the numeric values in X to a datetime array accordinng to
the data type specified by TYPE. The following types are
suppoerted:
'ConvertFrom'
, TYPE)
'datenum'
'excel'
'posixtime'
'epochtime'
Τ = datetime (…,
specifies the display format of the values in the output datetime array.
Currently, only the default display format is implemented.
'Format'
, FMT)
Τ = datetime (…,
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'
, TZ)'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
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
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 , 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
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
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 ,
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 .
'secondofday'
returns the second of the day in a numeric
array, in the range .
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 or ). 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 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
.