DateTimeParser - Parse DateTime, NaiveDateTime, Time, or Date from strings

Your Libraries & OS Mentoring Libraries
1

I’m excited to announce that TaxJar has developed and open-sourced DateTimeParser. We developed it because we found a need to parse user input into DateTimes or NaiveDateTimes. I didn’t find any existing libraries that did this not without knowing the format of the string in advance. Maybe it could help you out too?

Check out the repo:

Check it out at Hex:

https://hexdocs.pm/date_time_parser

Learn more about TaxJar: https://www.taxjar.com. Special thanks to them for investing in my time to develop this and allowing me to open-source it! Also thanks to nimble_parsec for making this much easier to develop.

Examples

iex> DateTimeParser.parse_datetime("19 September 2018 08:15:22 AM")
{:ok, ~N[2018-09-19 08:15:22]}

iex> DateTimeParser.parse_datetime("2034-01-13")
{:ok, ~N[2034-01-13 00:00:00]}

iex> DateTimeParser.parse_date("2034-01-13")
{:ok, ~D[2034-01-13]}

iex> DateTimeParser.parse_date("01/01/2017")
{:ok, ~D[2017-01-01]}

iex> DateTimeParser.parse_datetime("1/1/18 3:24 PM")
{:ok, ~N[2018-01-01T15:24:00]}

iex> DateTimeParser.parse_datetime("1/1/18 3:24 PM", assume_utc: true)
{:ok, ~U[2018-01-01T15:24:00Z]}
# the ~U is a DateTime sigil introduced in Elixir 1.9.0

iex> DateTimeParser.parse_datetime(~s|"Dec 1, 2018 7:39:53 AM PST"|)
{:ok, ~U[2018-12-01T14:39:53Z]}
# Notice that the date is converted to UTC by default

iex> {:ok, datetime} = DateTimeParser.parse_datetime(~s|"Dec 1, 2018 7:39:53 AM PST"|, to_utc: false)
iex> datetime
#DateTime<2018-12-01 07:39:53-07:00 PDT PST8PDT>

iex> DateTimeParser.parse_time("10:13pm")
{:ok, ~T[22:13:00]}

iex> DateTimeParser.parse_time("10:13:34")
{:ok, ~T[10:13:34]}
11 Likes
2

1.0 is releasing soon! Yesterday, I published 1.0.rc-1 as a means to dogfood the recent changes. It’ll stay there for a bit to ensure no bugs pop up.

Changes since initial release:

  • Unix epoch times are now parsed
  • Serial (spreadsheet) times are now parsed
  • Added DateTimeParser.parse/2 to give the best answer it can give. Previously, you’d have to use parse_datetime, parse_date, or parse_time. Now you can throw strings into parse and get the most specific struct for what it could parse. For example, 2019-01-01 will give you a %Date{}; something @ 9:30pm will give you a %Time{}, etc.
  • [Breaking] some defaults changed. Previously, the lib would assume too much for you by default. For example if you used DateTimeParser.parse_datetime("2019-01-01") it would give you 2019-01-01T00:00:00. Where did the time come from? It was assumed. Now in 1.x this will not be the default. Also, it would auto-convert timezone’d timestamps to UTC; now you have to opt-in to that behavior.

if you’re interested, give it a shot and let me know what you think. https://hex.pm/packages/date_time_parser

4 Likes
3

1.0 has released!

The theme of this release is no information is better than assumed information. So the breaking changes are simply to undo some defaults that we had set in pre-1.x. The biggest one was assuming a 00:00:00 time when no time was found, another was converting to UTC automatically. This no longer happens by default, but you can still have these behaviors through an option.

This release was dogfooded for a while, and we found some bugs in it during the RC phase, so if you’re using the library pre-1.x I recommend that you upgrade as soon as you can.

Here’s the changelog:

Breaking

  • Change parse_datetime to no longer assume time. Previously, it would assume 00:00:00 if time could not be parsed. This is replaced with an opt-in option assume_time . See next point. If you relied on this, to upgrade add the option; eg: DateTimeParser.parse_datetime(string, assume_time: true)
  • Change parse_datetime to no longer convert DateTime to UTC timezone. If you relied on this, to upgrade add the option; eg: DateTimeParser.parse_datetime(string, to_utc: true)
  • Change parse_date to no longer assume a date. Previously, it would assume the current date, and replace the found information from the string. This is replaced with an opt-in option of assume_date . If you relied on this, to upgrade add the option; eg: DateTimeParser.parse_date(string, assume_date: true)

Bugs

  • Fix a UTC conversion bug between Daylight/Standard time (#20). If you’re using an earlier version and converting to UTC, please upgrade to >= 1.0.0-rc2 immediately.
  • Fix an epoch subsecond parsing bug (#16) (thanks @tmr08c)
  • Updated for compatibility with Elixir 1.10.0

Features

  • Add parse/2 that will respond with the best match. This function accepts all options introduced below.
  • Add parse_datetime/2 to accept options:
    • assume_time: true | %Time{} | false with the default of false.
  • Add parse_date/2 to accept options:
    • assume_date: true | %Date{} | false with the default of false.
  • Add support for parsing negative epoch times. (#24) (thanks @tmr08c)
  • Add bang variants, parse!/2 , parse_datetime!/2 , parse_time!/2 , and parse_date!/2
  • Added parsers: [] option to add or disable parsers. This is helpful if you are don’t want to consider Serial or Epoch timestamps
5 Likes
4

Awesome parser, thank you.

1 Like