Wolfram Research

Function Repository Resource:

FromISOTimestamp

Source Notebook

Parse a string in ISO 8601 format to a DateObject

Contributed by: Jesse Friedman

ResourceFunction["FromISOTimestamp"][str]

parse ISO date/time string str to a DateObject.

ResourceFunction["FromISOTimestamp"][str,gran]

gives the DateObject of granularity gran corresponding to the ISO date/time string str.

ResourceFunction["FromISOTimestamp"][{"str1","str2",},]

parses the ISO date/time strings stri, returning a list.

Details and Options

ResourceFunction["FromISOTimestamp"] parses the most common formats described in ISO 8601.
ResourceFunction["FromISOTimestamp"] accepts the same options as DateObject.
By default, ResourceFunction["FromISOTimestamp"] will return a DateObject with the granularity implied by the input.
If str describes a dateless time value, ResourceFunction["FromISOTimestamp"] will return a TimeObject.
If a timezone is not specified in the input string, ResourceFunction["FromISOTimestamp"] will use the value of the TimeZone option if set, falling back to $TimeZone otherwise.
ResourceFunction["FromISOTimestamp"] supports dates specified in the calendar, ordinal, and weekday formats described in ISO 8601.
ResourceFunction["FromISOTimestamp"] does not support the format with truncated (“implied”) leading components described in some editions of ISO 8601.
ISO 8601-formatted durations (strings starting with the letter “P”) in “time-unit designator” format are parsed to Quantity objects.

Examples

Basic Examples

Parse a timestamp string in ISO 8601 format:

In[1]:=
ResourceFunction["FromISOTimestamp"]["2007-04-05T12:30:23-02:00"]
Out[1]=

Parse a timestamp with manually-specified granularity:

In[2]:=
ResourceFunction[
 "FromISOTimestamp"]["2007-04-05T12:30:23-02:00", "Month"]
Out[2]=

Parse a timestamp describing a dateless time:

In[3]:=
ResourceFunction["FromISOTimestamp"]["20:27:51Z"]
Out[3]=

Scope

Parse a timestamp in local time:

In[4]:=
ResourceFunction["FromISOTimestamp"]["20:27:51"]
Out[4]=

Parse a timestamp in ordinal date format (specifying the number of days since the start of the year):

In[5]:=
ResourceFunction["FromISOTimestamp"]["1988-175"]
Out[5]=

Parse a timestamp describing a week:

In[6]:=
ResourceFunction["FromISOTimestamp"]["2026-W33"]
Out[6]=

Parse a list of timestamp strings:

In[7]:=
ResourceFunction["FromISOTimestamp"][{
  "2007-04-05T12:30:23-02:00",
  "1985-W15-5",
  "20:27Z"
  }]
Out[7]=

Parse a string describing a duration of time:

In[8]:=
ResourceFunction["FromISOTimestamp"]["P3Y6M4DT12H30M5S"]
Out[8]=

Options

CalendarType

Specify a nondefault calendar system to use in the output:

In[9]:=
ResourceFunction["FromISOTimestamp"]["2001-04-18", CalendarType -> "Jewish"]
Out[9]=

DateFormat

Specify a custom format to display the output in:

In[10]:=
ResourceFunction["FromISOTimestamp"]["2007-04-05T12:30:23-02:00", DateFormat -> {"Hour", ":", "Minute", ":", "Second", " (on ", "MonthName", " ", "Day", ", ", "Year", ")"}]
Out[10]=

TimeZone

By default, timestamps that do not specify a timezone are parsed using the value of $TimeZone:

In[11]:=
{ResourceFunction["FromISOTimestamp"]["20:27:51"], $TimeZone}
Out[11]=

Specify a default timezone to use:

In[12]:=
ResourceFunction["FromISOTimestamp"]["20:27:51", TimeZone -> Entity["TimeZone", "America/New_York"]]
Out[12]=

Parse to a value explicitly lacking a timezone:

In[13]:=
ResourceFunction["FromISOTimestamp"]["20:27:51", TimeZone -> None]
Out[13]=

Properties and Relations

DateObject supports limited parsing of ISO 8601-formatted strings:

In[14]:=
DateObject["1988-06-23T12:23:00"]
Out[14]=

DateObject does not, however, currently support parsing ISO 8601-formatted strings that include a timezone value:

In[15]:=
DateObject["1988-06-23T12:23:00+02:30"]
Out[15]=

FromISOTimestamp supports parsing strings with timezone values:

In[16]:=
ResourceFunction["FromISOTimestamp"]["1988-06-23T12:23:00+02:30"]
Out[16]=

FromISOTimestamp is compatible with the "ISODate", "ISOWeekDate", "ISOOrdinalDate", and "ISODateTime" format specifications of DateString:

In[17]:=
date = DateObject[{1988, 6, 23, 12, 23}, "Minute", "Gregorian", "America/Los_Angeles"];
In[18]:=
DateString[date, #] & /@ {"ISODate", "ISOWeekDate", "ISOOrdinalDate", "ISODateTime"}
Out[18]=
In[19]:=
ResourceFunction["FromISOTimestamp"][%]
Out[19]=

Possible Issues

By default, FromISOTimestamp parses ISO 8601-formatted strings containing an integer seconds component with "Seconds" granularity, while DateObject always parses such strings with "Instant" granularity:

In[20]:=
Through[{ResourceFunction["FromISOTimestamp"], DateObject}[
  "1988-06-23T12:23:00"]]
Out[20]=
In[21]:=
#["Granularity"] & /@ %
Out[21]=

Force FromISOTimestamp to use "Instant" granularity:

In[22]:=
ResourceFunction["FromISOTimestamp"]["1988-06-23T12:23:00", "Instant"]
Out[22]=

FromISOTimestamp parses strings containing a fractional seconds component with "Instant" granularity:

In[23]:=
ResourceFunction["FromISOTimestamp"]["1988-06-23T12:23:00.123"]
Out[23]=
In[24]:=
{%["Millisecond"], %["Granularity"]}
Out[24]=

By default, FromISOTimestamp treats times with unspecified timezone as being in local ($TimeZone) time, while TimeObject represents them as explicitly lacking a timezone:

In[25]:=
Through[{ResourceFunction["FromISOTimestamp"], TimeObject}[
  "10:33:00"]]
Out[25]=
In[26]:=
#["TimeZone"] & /@ %
Out[26]=

Set the option TimeZoneNone on FromISOTimestamp to output explicitly timezone-less values:

In[27]:=
ResourceFunction["FromISOTimestamp"]["10:33:00", TimeZone -> None]
Out[27]=
In[28]:=
%["TimeZone"]
Out[28]=

By default, FromISOTimestamp parses time strings using the granularity implied by the format of the string, while TimeObject always uses "Instant" granularity:

In[29]:=
times = {"12:34", "12:34:56", "12:34:56.789"};
Dataset@AssociationMap[
  Function[f, AssociationMap[(Labeled[#, #["Granularity"]] &)[f[#]] &, times]], {ResourceFunction["FromISOTimestamp"], TimeObject}]
Out[30]=

Force FromISOTimestamp to use "Instant" granularity:

In[31]:=
ResourceFunction["FromISOTimestamp"][#, "Instant"] & /@ times
Out[31]=
In[32]:=
#["Granularity"] & /@ %
Out[32]=

“Implied” leading components are not supported by FromISOTimestamp:

In[33]:=
ResourceFunction["FromISOTimestamp"]["--04-05"]
Out[33]=

ISO 8601 treats year 1 BCE as year 0 (and year 2 BCE as year 1, etc.), so negative year values in ISO 8601 timestamps and DateObjects will differ in appearance, although they represent the same dates:

In[34]:=
ResourceFunction["FromISOTimestamp"]["-0043-03-15"]
Out[34]=

DateObject and TimeObject do not support special handling of the leap second, so timestamps including leap seconds will roll over to the next “0” second:

In[35]:=
ResourceFunction["FromISOTimestamp"][{"23:59:60", "00:00:00"}, TimeZone -> "UTC"]
Out[35]=
In[36]:=
SameQ @@ %
Out[36]=

Certain “basic format” ISO timestamps which can be alternatively parsed as either dates or times are always parsed to dates by FromISOTimestamp:

In[37]:=
ResourceFunction["FromISOTimestamp"]["171239"]
Out[37]=

Use “extended format” timestamps to eliminate ambiguity:

In[38]:=
ResourceFunction["FromISOTimestamp"]["17:12:39"]
Out[38]=

Alternatively, prefix “basic format” timestamps with the “T” character:

In[39]:=
ResourceFunction["FromISOTimestamp"]["T171239"]
Out[39]=

“Alternative format” duration strings are not supported:

In[40]:=
ResourceFunction["FromISOTimestamp"]["P0003-06-04T12:30:05"]
Out[40]=

Date/time intervals are not supported:

In[41]:=
ResourceFunction[
 "FromISOTimestamp"]["2007-03-01T13:00:00Z/2008-05-11T15:30:00Z"]
Out[41]=

Create an Interval representing a date/time interval from a string in ISO 8601 “start/end” format by splitting at the “/” character:

In[42]:=
Interval@ResourceFunction["FromISOTimestamp"]@
  StringSplit["2007-03-01T13:00:00Z/2008-05-11T15:30:00Z", "/"]
Out[42]=

Resource History

Source Metadata

License Information