Function Repository Resource:

# RelativeTimeString

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[…] {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]:=
 Out[22]=

### Applications (1)

Express the age of the current kernel in plain text:

 In[23]:=
 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]:=
 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]:=
 In[38]:=
 Out[38]=
 In[39]:=
 Out[39]=
 In[40]:=
 Out[40]=

Values smaller than one second are considered insignificant:

 In[41]:=
 Out[41]=
 In[42]:=
 Out[42]=
 In[43]:=
 Out[43]=

If negative, the output reflects that it represents a time in the past:

 In[44]:=
 Out[44]=

### Neat Examples (1)

Group files by relative dates:

 In[45]:=
 Out[45]=

## Version History

• 1.0.0 – 27 June 2022