DateTimeParser v0.2.0 DateTimeParser View Source

DateTimeParser is a tokenizer for strings that attempts to parse into a DateTime, NaiveDateTime if timezone is not determined, Date, or Time.

The biggest ambiguity between datetime formats is whether it's ymd (year month day), mdy (month day year), or dmy (day month year); this is resolved by checking if there are slashes or dashes. If slashes, then it will try dmy first. All other cases will use the international format ymd. Sometimes, if the conditions are right, it can even parse dmy with dashes if the month is a vocal month (eg, "Jan").

If the string starts with 10-11 digits with optional precision, then we'll try to parse it as a Unix epoch timestamp.

If the string starts with 1-5 digits with optional precision, then we'll try to parse it as a serial timestamp (spreadsheet time) treating 1899-12-31 as 1. This will cause Excel-produced dates from 1900-01-01 until 1900-03-01 to be incorrect, as they really are. If the string represents an integer, then we will parse a date from it. If it is a flaot, then we'll parse a NaiveDateTime from it.


  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("1564154204")
  {:ok, DateTime.from_naive!(~N[2019-07-26T15:16:44Z], "Etc/UTC")}

  iex> DateTimeParser.parse_datetime("41261.6013888889")
  {:ok, ~N[2012-12-18T14:26:00]}

  iex> DateTimeParser.parse_date("44262")
  {:ok, ~D[2021-03-07]}
  # This is a serial number date, commonly found in spreadsheets, eg: `=VALUE("03/07/2021")`

  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, DateTime.from_naive!(~N[2018-01-01T15:24:00Z], "Etc/UTC")}
  # or ~U[2018-01-01T15:24:00Z] in Elixir 1.9.0+

  iex> DateTimeParser.parse_datetime(~s|"Dec 1, 2018 7:39:53 AM PST"|)
  {:ok, DateTime.from_naive!(~N[2018-12-01T14:39:53Z], "Etc/UTC")}
  # 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]}

  iex> DateTimeParser.parse_time("18:14:21.145851000000Z")
  {:ok, ~T[18:14:21.145851]}

  iex> DateTimeParser.parse_datetime(nil)
  {:error, "Could not parse nil"}

Link to this section Summary


Parse %Date{} from a string.

Parse a %DateTime{} or %NaiveDateTime{} from a string.

Parse %Time{} from a string.

Link to this section Functions

Link to this function

parse_date(string) View Source
parse_date(String.t() | nil) :: {:ok, Date.t()} | {:error, String.t()}

Parse %Date{} from a string.

Link to this function

parse_datetime(string, opts \\ []) View Source
parse_datetime(String.t() | nil, Keyword.t()) ::
  {:ok, DateTime.t() | NaiveDateTime.t()} | {:error, String.t()}

Parse a %DateTime{} or %NaiveDateTime{} from a string.


  • :assume_utc Default false. Only applicable for strings where parsing could not determine a timezone. Instead of returning a NaiveDateTime, this option will assume them to be in UTC timezone, and therefore return a DateTime

  • :to_utc Default true. If there's a timezone detected in the string, then attempt to convert to UTC timezone. This is helpful for storing in databases with Ecto.

Link to this function

parse_time(string) View Source
parse_time(String.t() | nil) :: {:ok, Time.t()} | {:error, String.t()}

Parse %Time{} from a string.