Details and Options

• DateObject represents a location in the temporal axis represented numerically using a calendar, time zone and time system.

• DateObject can represent different resolutions by using day or month granularities, etc.

• In DateObject[date], the following date and time specifications can be given as date:
• dateDateObject specification {y,m,d,h,m,s}DateList specification timeAbsoluteTime specification "string"DateString specification {"string",fmt}date string formed from the specified format
• Values of m, d, h, m, s outside their normal ranges are appropriately reduced. Noninteger values of d, h, m, and s can also be used.
• In the form DateObject[{"string",{"e₁","e₂",…}}], the "e_i" can be any DateString element, such as "Year", "MonthName", "Hour", etc.
• DateObject[{"string",{"e₁","e₂",…}}] uses the "e_i" to fill in elements of {y,m,d,h,m,s}. Those not filled in are taken to have default values {y_c,1,1,0,0,0}, where y_c is the current year.
• In DateObject[{"string",{"e₁","e₂",…}}], the "e_i" are extracted from "string" in the order given, and can be separated by any non-alphanumeric characters.
• DateObject[{"string",{"e₁","sep₁₂","e₂","sep₂₃",…}}] extracts elements using the explicit separators specified.
• DateObject[time] gives a date object corresponding to an AbsoluteTime specification.
• For an image with Exif date time information, DateObject[image] returns that information as a standard DateObject expression.
• DateObject[rdate,gran] represents a discrete calendar element of granularity gran for the reference date rdate. For example, DateObject[{2017,1,16},"Week"] represents the week beginning Monday, January 16, 2017.
• DateObject[rdate,gran] will normalize to the canonical representation of the DateObject for that granularity. For example, DateObject[{2016},"Decade"] will canonicalize to DateObject[{2010},"Decade"].
• In DateObject[rdate,gran], the calendar granularity gran can be any of the following:
• "Millennium"1000-year period beginning with year XX00 "MillenniumBeginning01"1000-year period beginning with year XX01 "Century"100-year period beginning with year XX00 "CenturyBeginning01"100-year period beginning with year XX01 "Decade"10-year period including the date "Year"year including the date "Quarter"3-month quarter including the date "Month"month including the date "Week"week beginning Monday including the date "WeekBeginningSunday"week beginning Sunday including the date "Day"day including the date "Hour"hour including the date "Minute"minute including the date "Second"second including the date "Instant"the exact instant specified
• DateObject[rdate,"MidpointInstant"] can be used to construct a DateObject with granularity "Instant" with a reference date at the mid-point of rdate.
• DateObject[list] is taken to represent a date with granularity as follows:
• DateObject[{y}]"Year" DateObject[{y,m}]"Month" DateObject[{y,m,d}]"Day" DateObject[{y,m,d,h}]"Hour" DateObject[{y,m,d,h,m}]"Minute" DateObject[{y,m,d,h,m,s}]"Instant" DateObject[t]"Instant"
• DateObject["string"] is taken to represent a date with granularity inferred from the information given in the string.
• The following options can be given:
• CalendarType Automaticcalendar system being used DateFormat Automaticformat used to display date DateGranularity Automaticcalendar granularity for the date TimeSystem Automatictime system being used TimeZone Automatictime zone being used
• Possible CalendarType specifications are: Automatic, "Gregorian" and "Julian", with additional calendar types as given by CalendarData.
• The default value of CalendarType is Automatic, which uses the proleptic Gregorian calendar in which there is no year 0. Years prior to the Common Era are negative, and those after are positive.
• TimeZone specifications should be a numerical offset from GMT, a time zone string, None or a geo entity location.
• TimeSystem specifications include "UTC", "TAI", "TT" and others. The default value is "SmearedUTC", a form of UTC that smears leap seconds over the 24 hours before their addition or removal.
• TimeSystem specifications other than "UTC" and "SmearedUTC" make TimeZoneAutomatic be interpreted as TimeZone0 because they are typically always used in the GMT time zone.
• With a typical value for $DateStringFormat, the display of DateObject[{y,m,d,h,m,s}] will truncate fractional seconds.
• DateObject allows addition and subtraction of time quantities.
• Subtracting two DateObject expressions yields a time quantity.
• Functions such as NumericalSort, Greater, Max, etc. work with DateObject.
• Information for a DateObject may include the following properties:
• "Date"string form of the specified date "Granularity"calendar granularity "TimeZone"time zone "CalendarType"calendar type

Examples

Basic Examples  (6)

Find the current date:

Date object expression representing the year 2022:

Date object representing the week beginning Monday, August 1, 2022:

Expand the date to a granularity of "Month":

Convert an absolute time to a date object:

Represent a specific year and month:

Or represent just a year:

Add 2000 weeks to a date:

Subtract two dates to get a time quantity:

Scope  (7)

Date objects are interpreted using their standard normalized form:

This includes normalization for values preceding the first day of the year:

Strings are automatically interpreted when possible:

DateObject automatically chooses the first date compatible with the input information:

The granularity of a date object may be changed by wrapping it in a DateObject expression with an explicit granularity specification:

Date objects including additional elements beyond what are required for a given calendar granularity will be automatically normalized to their canonical form:

Combine a DateObject and a TimeObject into a single expression:

Date and time of an image:

Options  (9)

CalendarType  (2)

Find the current date on the Jewish calendar:

Represent a date on the Islamic calendar:

DateFormat  (2)

Use long date format:

Specify your own format:

DateGranularity  (1)

By default, dates are generated with "Instant" granularity:

Use DateGranularity"Month" to generate a "Month" granular date:

TimeSystem  (2)

Find the current date in International Atomic Time:

Represent the leap second that occurred on December 31, 2016, in Coordinated Universal Time:

The "UTC" and "SmearedUTC" time systems are identical on days with no leap second added:

They differ on days with a leap second, with the difference increasing from 0 to 1 second during the day:

TimeZone  (2)

Find the current date in Greenwich, United Kingdom:

Specify no time zone for a date object:

Represent 11am Eastern Standard Time on March 3, 2001:

TimeZone specifications can be used with all supported calendar types:

For date string inputs, if a time zone is detected, the resulting DateObject will account for the difference in time zone offset:

Properties & Relations  (9)

AbsoluteTime represents dates as seconds since the beginning of 1900:

DateList represents dates as lists of date elements:

DateString represents dates as strings:

DateValue can be used to extract a granular date:

Arithmetic using date objects returns units in the coarsest granularity of the dates:

Granular DateObject expressions with different time zones within the same calendar granularity are considered Equal:

But are not SameQ:

Compare date objects to determine their sequence of occurrence:

GreaterThan, LessThan and related test functions also work with DateObject expressions:

Comparisons of date objects with unequal precision and overlapping time periods will return unevaluated:

Use Max to find the latest date in a list:

NumericalSort will arrange dates in sequence:

ClockGauge can be used to visualize a date on an analog clock: