--- title: "TimeObject" language: "en" type: "Symbol" summary: "TimeObject[] represents the current time. TimeObject[{h, m, s}] represents a time object of standard normalized form. TimeObject[date] gives the time component of the specified date representation. TimeObject[rtime, gran] gives the time object of granularity gran that includes the reference time rtime." keywords: - time object - clock - hour minute second - time comparison - current time - now - chronology canonical_url: "https://reference.wolfram.com/language/ref/TimeObject.html" source: "Wolfram Language Documentation" related_guides: - title: "Date & Time" link: "https://reference.wolfram.com/language/guide/DateAndTime.en.md" - title: "Time Series Processing" link: "https://reference.wolfram.com/language/guide/TimeSeries.en.md" - title: "Free-Form & External Input" link: "https://reference.wolfram.com/language/guide/FreeFormAndExternalInput.en.md" - title: "Scientific Data Analysis" link: "https://reference.wolfram.com/language/guide/ScientificDataAnalysis.en.md" - title: "WDF (Wolfram Data Framework)" link: "https://reference.wolfram.com/language/guide/WDFWolframDataFramework.en.md" --- # TimeObject TimeObject[] represents the current time. TimeObject[{h, m, s}] represents a time object of standard normalized form. TimeObject[date] gives the time component of the specified date representation. TimeObject[rtime, gran] gives the time object of granularity gran that includes the reference time rtime. ## Details and Options * ``TimeObject[]`` uses whatever time has been set on your computer system by default. * Shorter lists can be used in ``TimeObject[{h, m, s}]``, which represents the time to whatever accuracy is specified: ``{h}`` is not treated as being equivalent to ``{h, 0, 0}``. * ``TimeObject[n]`` gives an object representing ``n`` hours from midnight and is equivalent to ``TimeObject[{n}]``. * ``TimeObject[rtime, gran]`` represents a granular element of time ``gran`` for the reference time ``rtime``. For example, ``TimeObject[{10, 4}, "Minute"]`` represents the minute corresponding to 10:04 am. * In ``TimeObject[rtime, gran]``, the granularity ``gran`` can be any of the following: | | | | ------------- | -------------------------------- | | "Hour" | hour of the reference time | | "Minute" | minute of the reference time | | "Second" | second of the reference time | | "Decisecond" | moment accurate to 0.1 seconds | | "Centisecond" | moment accurate to 0.01 seconds | | "Millisecond" | moment accurate to 0.001 seconds | | "Microsecond" | moment accurate to 10^-6 seconds | | "Nanosecond" | moment accurate to 10^-9 seconds | | "Instant" | the exact specified time | * ``TimeObject[rdate, n]`` where ``n`` is a non-negative ``Integer`` represents a date accurate to ``10^-n`` seconds (e.g. ``TimeObject[rdate, 6]`` corresponds to ``10^-6`` seconds accuracy, the same as ``TimeObject[rdate, "Microsecond"]``). * The maximum available value for ``n`` in ``TimeObject[rdate, n]`` is 9. * ``TimeObject`` allows addition and subtraction of time quantities. * Subtracting two ``TimeObject`` constructs yields a time quantity. * The following options can be given: | | | | | ---------------- | --------- | ---------------------- | | DateGranularity | Automatic | granularity being used | | TimeZone | None | time zone being used | * ``TimeZone`` specifications should be a numerical offset from GMT, a time zone string or ``None``. * ``Information`` of a ``TimeObject`` may include the following properties: | | | | ------------- | --------------------------------- | | "Time" | string form of the specified time | | "Granularity" | time granularity | | "TimeZone" | time zone | --- ## Examples (6) ### Basic Examples (2) Represent the current time: ```wl In[1]:= TimeObject[] Out[1]= TimeObject[{15, 30, 49.092389}, "Instant", None] ``` Represent 11:30am: ```wl In[2]:= TimeObject[{11, 30}] Out[2]= TimeObject[{11, 30}, "Minute"] ``` Represent 15 seconds past 8:04pm: ```wl In[3]:= TimeObject[{20, 4, 15}] Out[3]= TimeObject[{20, 4, 15}, "Instant", None] ``` --- Add 13 hours to a time object: ```wl In[1]:= TimeObject[{10, 30}, "Minute", -5.] + Quantity[13, "Hours"] Out[1]= TimeObject[{23, 30}, "Minute", -5.] ``` Subtracting time objects gives a time quantity: ```wl In[2]:= TimeObject[{16, 17, 21}, "Instant"] - TimeObject[{10, 12, 34}, "Instant"] Out[2]= Quantity[6.079722222222222, "Hours"] ``` ### Scope (1) Time objects are interpreted using their standard normalized form: ```wl In[1]:= TimeObject[{26, 2, 12}] Out[1]= TimeObject[{2, 2, 12}, "Instant", None] ``` ### Options (2) #### DateGranularity (1) By default, dates are generated with ``"Instant"`` granularity: ```wl In[1]:= TimeObject[] Out[1]= TimeObject[{10, 45, 27.688059}, "Instant"] ``` Use ``DateGranularity -> "Hour"`` to generate an hour: ```wl In[2]:= TimeObject[DateGranularity -> "Hour"] Out[2]= TimeObject[{10}, "Hour"] ``` #### TimeZone (1) Represent a specific time in Greenwich, United Kingdom: ```wl In[1]:= TimeObject[{20, 10}, TimeZone -> 0] Out[1]= TimeObject[{20, 10}, "Minute", 0.] ``` Represent 11am Central Time: ```wl In[2]:= TimeObject[{11}, TimeZone -> "America/Chicago"] Out[2]= TimeObject[{11}, "Hour", "America/Chicago"] ``` ### Properties & Relations (1) Compare time objects to determine their sequence of occurrence: ```wl In[1]:= TimeObject[{11, 0}] > TimeObject[{10, 30}] Out[1]= True In[2]:= Sort[{TimeObject[{8, 45}], TimeObject[{11, 15}], TimeObject[{9, 30}]}] Out[2]= {TimeObject[{8, 45}, "Minute", None], TimeObject[{9, 30}, "Minute", None], TimeObject[{11, 15}, "Minute", None]} ``` Comparisons of time objects with unequal precision and overlapping time periods will return unevaluated: ```wl In[3]:= TimeObject[{10}] < TimeObject[{10, 30}] ``` Less::nordol: 10:00GMT-6. and 10:30GMT-6. cannot be compared because they are overlapping. ```wl Out[3]= TimeObject[{10}, TimeZone -> -6.] < TimeObject[{10, 30}, TimeZone -> -6.] In[4]:= TimeObject[{10, 0}] < TimeObject[{10, 30}] Out[4]= True In[5]:= TimeObject[{9}] < TimeObject[{10, 30}] Out[5]= True ``` ## See Also * [`DateObject`](https://reference.wolfram.com/language/ref/DateObject.en.md) * [`Now`](https://reference.wolfram.com/language/ref/Now.en.md) * [`TimeZoneConvert`](https://reference.wolfram.com/language/ref/TimeZoneConvert.en.md) * [`DateValue`](https://reference.wolfram.com/language/ref/DateValue.en.md) * [`DateString`](https://reference.wolfram.com/language/ref/DateString.en.md) * [`DateList`](https://reference.wolfram.com/language/ref/DateList.en.md) * [`TimeSeries`](https://reference.wolfram.com/language/ref/TimeSeries.en.md) * [`EventSeries`](https://reference.wolfram.com/language/ref/EventSeries.en.md) * [`SiderealTime`](https://reference.wolfram.com/language/ref/SiderealTime.en.md) * [`Time`](https://reference.wolfram.com/language/ref/interpreter/Time.en.md) * [`DateTime`](https://reference.wolfram.com/language/ref/interpreter/DateTime.en.md) * [`UnixTime`](https://reference.wolfram.com/language/ref/interpreter/UnixTime.en.md) ## Related Guides * [Date & Time](https://reference.wolfram.com/language/guide/DateAndTime.en.md) * [Time Series Processing](https://reference.wolfram.com/language/guide/TimeSeries.en.md) * [Free-Form & External Input](https://reference.wolfram.com/language/guide/FreeFormAndExternalInput.en.md) * [Scientific Data Analysis](https://reference.wolfram.com/language/guide/ScientificDataAnalysis.en.md) * [WDF (Wolfram Data Framework)](https://reference.wolfram.com/language/guide/WDFWolframDataFramework.en.md) ## History * [Introduced in 2014 (10.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn100.en.md) \| [Updated in 2019 (12.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn120.en.md) ▪ [2023 (13.3)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn133.en.md) ▪ [2024 (14.1)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn141.en.md)