DateObject

DateObject[]

gives the current local date.

DateObject[{y,m,d,h,m,s}]

gives a date object of standard normalized form.

DateObject["string"]

converts a date string to a date object.

DateObject[{"string",{"e1","e2", }}]

gives the date object obtained by extracting elements "ei" from "string".

DateObject[rdate,gran]

gives the date object of calendar granularity gran that includes the reference date rdate.

Details and Options

  • DateObject[] uses whatever date and time have been set on your computer system by default.
  • 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",{"e1","e2",}}], the "ei" can be "Year", "YearShort", "Quarter", "Month", "MonthName", "Day", "DayName", "Hour", "Hour12", "AMPM", "Minute", "Second", or "Millisecond".
  • DateObject[{"string",{"e1","e2",}}] uses the "ei" to fill in elements of {y,m,d,h,m,s}. Those not filled in are taken to have default values {yc,1,1,0,0,0}, where yc is the current year.
  • In DateObject[{"string",{"e1","e2",}}], the "ei" are extracted from "string" in the order given, and can be separated by any non-alphanumeric characters.
  • DateObject[{"string",{"e1","sep12","e2","sep23",}}] 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:
  • CalendarTypeAutomaticcalendar system being used
    DateFormatAutomaticformat used to display date
    TimeZoneAutomatictime zone being used
  • Possible CalendarType specifications are: Automatic, "Gregorian", "Julian", "Jewish", and "Islamic".
  • 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.
  • 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 Sort, 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

open allclose all

Basic Examples  (6)

Find the current date:

Date object expression representing the year 2015:

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

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 1000 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  (5)

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:

TimeZone  (1)

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:

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:

Sort will arrange dates in sequence:

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

Introduced in 2014
 (10.0)
 |
Updated in 2016
 (11.0)
2017
 (11.1)
2017
 (11.2)
2019
 (12.0)