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.

When a display Format contains a time-zone name field (z/zz/zzz), the name is rendered according to a session-wide style set by datetime.zoneNameStyle. The default, 'iana', is an Octave-specific extension that shows the IANA abbreviation for every zone (e.g. EEST); 'matlab' restores MATLAB’s behaviour of naming only North American zones and showing a numeric UTC+3-style offset elsewhere. A single Format may override the session style with zzzz (force 'iana') or zzzzz (force 'matlab'). See datetime.zoneNameStyle.

See also: calendarDuration, duration

Source Code: datetime

The datetime class contains the following 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.

The value 'default' is a data-dependent sentinel: a date-only format ('dd-MMM-uuuu') is used when every element sits at midnight, and a date and time format ('dd-MMM-uuuu HH:mm:ss') otherwise. The value 'defaultdate' always selects the date-only format. Reading the property returns the resolved pattern, never the sentinel itself.

A custom pattern is built from the following Unicode (LDML) fields; repeating a letter widens or names the field. Any other text is copied verbatim, and text in single quotes is always literal.

y, uYear; yy uses the last two digits.
MMonth: number (M, MM), abbreviated (MMM), full (MMMM), or initial (MMMMM).
dDay of the month.
DDay of the year.
eDay of the week: number (Sunday is 1), abbreviated (eee), full (eeee), or initial (eeeee).
H, hHour, 24-hour and 12-hour clock.
mMinute.
sWhole second (fractional seconds are truncated).
SFractional second, one digit per S.
aAM or PM.
QQuarter of the year.
GEra.
WWeek of the month.
zTime-zone name (style set by datetime.zoneNameStyle; zzzz/zzzzz force it).
Z, X, xNumeric time-zone offset.

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.

Besides the zones of the IANA Time Zone Database, the value 'UTCLeapSeconds' selects UTC with its inserted leap seconds made representable, so that the 60th second of a minute exists on the 27 dates that have one. It is not an IANA zone and timezones does not list it. An array in that zone counts elapsed SI seconds, which is what makes its arithmetic differ from a UTC array’s across an inserted second, and for that reason it cannot be combined or compared with an array that does not have leap seconds. Its Format is fixed to "uuuu-MM-dd'T'HH:mm:ss'Z'", optionally with one to nine fractional-second digits, since no other pattern can write a 60th second; moving such an array to any other zone folds an inserted second back onto the 59th and restores the ordinary default format.

The datetime class offers the following public methods:

datetime Create a new array of datetime values.
dispstrings Get display formatted strings for each element of a datetime object.
cellstr Convert datetime array to a cell array of character vectors.
char Convert datetime array to a character matrix.
ymd Year, Month, and Day components of datetime array.
hms Hour, Minute, and Second components of a datetime array.
year Year component of a datetime array.
quarter Quarter component of a datetime array.
month Month component of a datetime array.
day Day component of a datetime array.
hour Hour component of a datetime array.
minute Minute component of a datetime array.
second Seconds component of a datetime array.
week Week component of a datetime array.
timeofday Elapsed time since midnight of a datetime array.
tzoffset Time zone offset of a datetime array.
size Size of a datetime array.
ndims Number of dimensions in a datetime array.
numel Total number of elements in a datetime array.
length Length of a datetime vector.
keyHash Generate a hash code for datetime array.
posixtime Convert datetime array to POSIX time.
datevec Convert datetime array to date vectors.
datestr Convert datetime array to a character array of date strings.
string Convert datetime array to a string array.
yyyymmdd Convert datetime array to ‘YYYYMMDD’ numeric form.
datenum Convert datetime array to serial date numbers.
exceltime Convert datetime array to Excel serial date numbers.
juliandate Convert datetime array to Julian dates.
convertTo Convert datetime array to a numeric representation.
isdst Determine which datetime values fall in daylight saving time.
isregular Determine whether a datetime vector is regularly spaced.
isweekend Determine which datetime values fall on a weekend.
isbetween Determine which datetime values lie within an interval.
issorted Determine whether a datetime array is sorted.
issortedrows Determine whether the rows of a datetime array are sorted.
iscolumn Return true if datetime array is a column vector.
isempty Return true if datetime array is empty.
isequal Test datetime arrays for equality.
isequaln Test datetime arrays for equality, treating Not-A-Time as equal.
isfinite Test for finite elements in datetime array.
isinf Test for infinite elements in datetime array.
ismatrix Return true if datetime array is a 2-D array.
ismissing Test for missing elements in datetime array.
isnat Test for Not-A-Time elements in datetime array.
isrow Return true if datetime array is a row vector.
isscalar Return true if datetime array is a scalar.
isvector Return true if datetime array is a vector.
maxk Find the latest elements in a datetime array.
mink Find the earliest elements in a datetime array.
sort Sort a datetime array.
sortrows Sort the rows of a datetime array.
min Minimum of a datetime array.
max Maximum of a datetime array.
topkrows Top K sorted rows of a datetime array.
unique Unique values in a datetime array.
intersect Set intersection of two datetime arrays.
union Set union of two datetime arrays.
setdiff Set difference of two datetime arrays.
setxor Set exclusive-or of two datetime arrays.
ismember Test for datetime elements in a set.
interp1 One-dimensional interpolation involving datetime arrays.
mean Mean of a datetime array.
median Median of a datetime array.
mode Most frequent value of a datetime array.
std Standard deviation of a datetime array.
discretize Group datetimes into bins.
histcounts Histogram bin counts for datetimes.
colon Create a range of datetime values.
linspace Create linearly spaced datetime values.
plus Addition for datetime arrays.
minus Subtraction for datetime arrays.
diff Differences between successive datetime elements.
caldiff Calendar differences between successive datetime elements.
between Calendar difference between two datetime arrays.
dateshift Shift datetime values to calendar boundaries.
lt Less-than comparison for datetime arrays.
le Less-than-or-equal comparison for datetime arrays.
gt Greater-than comparison for datetime arrays.
ge Greater-than-or-equal comparison for datetime arrays.
eq Equality comparison for datetime arrays.
ne Inequality comparison for datetime arrays.
cat Concatenate datetime arrays.
horzcat Horizontal concatenation of datetime arrays.
vertcat Vertical concatenation of datetime arrays.
repmat Repeat copies of a datetime array.
repelem Repeat copies of datetime array elements.
repelems Construct a vector of repeated elements from a datetime array.
reshape Reshape datetime array.
circshift Circularly shift the elements in a datetime array.
permute Generalized transpose for a datetime N-D array.
ipermute Inverse of the generalized transpose for a datetime N-D array.
transpose Transpose a datetime matrix.
ctranspose Transpose a datetime matrix.
empty Create an empty datetime array.
zoneNameStyle Query or set the session-wide style used to render time-zone names.
setDefaultFormats Set the default display formats of datetime arrays.