Function Repository Resource:

RelativeTimeString

Source Notebook

Convert a date to a human-readable string relative to the current time

Contributed by: Richard Hennigan (Wolfram Research)

ResourceFunction["RelativeTimeString"][date]

gives a human-readable string representation of date relative to the current time.

ResourceFunction["RelativeTimeString"][base,date]

uses base instead of the current time.

Details and Options

The value for date can either be a Quantity of time or a valid DateObject specification.

If date is a Quantity object, then it is interpreted as a time offset relative to the current time.

ResourceFunction["RelativeTimeString"][date] is effectively equivalent to ResourceFunction["RelativeTimeString"][Now,date] when date corresponds to a DateObject specification.

Dates can be specified as any of the following:

DateObject[…]

a DateObject

{y,m,d,h,m,s}

a DateList specification

time

an AbsoluteTime specification

"string"

a DateString specification

{"string",fmt}

a date string formed from the specified format

ResourceFunction["RelativeTimeString"][Quantity[…]] is effectively equivalent to ResourceFunction["RelativeTimeString"][Now+Quantity[…]].

A valid time Quantity has UnitDimensions of {{"TimeUnit",1}}.

Examples

Basic Examples (3)

Get a simple text representation of a date relative to the current time:

In[1]:=

Out[1]=

In[2]:=

Out[2]=

In[3]:=

Out[3]=

Get a relative time string for a Quantity object:

In[4]:=

Out[4]=

In[5]:=

Out[5]=

In[6]:=

Out[6]=

In[7]:=

Out[7]=

A sample of relative times in the future:

In[8]:=

Out[8]=

A sample of relative times in the past:

In[9]:=

Out[9]=

Scope (6)

Specify the base time:

In[10]:=

Out[10]=

In[11]:=

Out[11]=

Use an absolute time:

In[12]:=

Out[12]=

Compare:

In[13]:=

Out[13]=

Strings are interpreted as dates:

In[14]:=

Out[14]=

RelativeTimeString accepts any Quantity that corresponds to a time unit:

In[15]:=

Out[15]=

In[16]:=

Out[16]=

In[17]:=

Out[17]=

Quantity intervals:

In[18]:=

Out[18]=

In[19]:=

Out[19]=

In[20]:=

Out[20]=

Date intervals:

In[21]:=

Out[21]=

In[22]:=

ResourceFunction["RelativeTimeString"][
DateObject[{2022, 6, 20, 20, 59, 28.4283995`9.206327322677087}, "Instant", "Gregorian", -4.`], DateInterval[{{{2022, 6, 20, 20, 59, 23.428}, {2022, 6, 20, 20, 59, 25.428}}}, "Instant", "Gregorian", -4.]]

Out[22]=

Applications (1)

Express the age of the current kernel in plain text:

In[23]:=

$kernelAge := StringTemplate["This `1` kernel started `2`."][
ToLowerCase[
ResourceFunction["FromCamelCase"][$EvaluationEnvironment]],
ResourceFunction[
"RelativeTimeString"][-Quantity[SessionTime[], "Seconds"]]
]

In[24]:=

Out[24]=

In[25]:=

Out[25]=

In[26]:=

Out[26]=

Properties and Relations (5)

Some outputs are dependent on the current time:

In[27]:=

Out[27]=

Equivalently:

In[28]:=

Out[28]=

In[29]:=

Out[29]=

If the current time were closer, a more reasonable approximation would be given instead:

In[30]:=

Out[30]=

This avoids suddenly switching to outputs like "yesterday" just after midnight for relatively small differences:

In[31]:=

Out[31]=

See a timeline of some of these number-free outputs for the current time of day:

In[32]:=

dates = DateRange[Now - Quantity[36, "Hours"], Now + Quantity[36, "Hours"], "Hour"];
TimelinePlot[
DateInterval@*MinMax /@ KeySelect[GroupBy[dates, ResourceFunction["RelativeTimeString"]], StringFreeQ[DigitCharacter]]]

Out[33]=

Possible Issues (2)

RelativeTimeString gives approximations with varying precision:

In[34]:=

Out[34]=

In[35]:=

Out[35]=

Results may also be sensitive to the current time:

In[36]:=

Out[36]=

For more predictable and precise strings (at the cost of some readability), consider using SecondsToQuantity:

In[37]:=

$relTimeString[q_Quantity] := With[{str = ToString[ResourceFunction["SecondsToQuantity"][Abs[q]]]}, If[TrueQ[Positive[q]], "in " <> str, str <> " ago"]];$