Calendar.DateTime.Parse

Summary

httpdate(rfc2616_string)

Parses a timestamp in RFC 2616 format

js_ms!(millisec)

Parse JavaScript style milliseconds since epoch

rfc2822_utc(string)

Parses an RFC 2822 or RFC 1123 datetime string

rfc3339(rfc3339_string, time_zone)

Parses an RFC 3339 timestamp and shifts it to the specified time zone

rfc3339_utc(rfc3339_string)

Parse RFC 3339 timestamp strings as UTC. If the timestamp is not in UTC it will be shifted to UTC

rfc822_utc(string, year_guessing_base \\ 2015)

Parses an RFC 822 datetime string and shifts it to UTC

unix!(unix_time_stamp)

Takes unix time as an integer or float. Returns a DateTime struct

Functions

httpdate(rfc2616_string)

Parses a timestamp in RFC 2616 format.

iex> httpdate("Sat, 06 Sep 2014 09:09:08 GMT")
{:ok, %Calendar.DateTime{year: 2014, month: 9, day: 6, hour: 9, min: 9, sec: 8, timezone: "Etc/UTC", abbr: "UTC", std_off: 0, utc_off: 0}}

iex> httpdate("invalid")
{:bad_format, nil}

iex> httpdate("Foo, 06 Foo 2014 09:09:08 GMT")
{:error, :invalid_datetime}
js_ms!(millisec)

Parse JavaScript style milliseconds since epoch.

Examples

iex> js_ms!("1000000000123")
%Calendar.DateTime{abbr: "UTC", day: 9, usec: 123000, hour: 1, min: 46, month: 9, sec: 40, std_off: 0, timezone: "Etc/UTC", utc_off: 0, year: 2001}

iex> js_ms!(1_000_000_000_123)
%Calendar.DateTime{abbr: "UTC", day: 9, usec: 123000, hour: 1, min: 46, month: 9, sec: 40, std_off: 0, timezone: "Etc/UTC", utc_off: 0, year: 2001}

iex> js_ms!(1424102000000)
%Calendar.DateTime{abbr: "UTC", day: 16, hour: 15, usec: 0, min: 53, month: 2, sec: 20, std_off: 0, timezone: "Etc/UTC", utc_off: 0, year: 2015}
rfc2822_utc(string)

Parses an RFC 2822 or RFC 1123 datetime string.

The datetime is shifted to UTC.

Examples

iex> rfc2822_utc("Sat, 13 Mar 2010 11:23:03 -0800")
{:ok,
      %Calendar.DateTime{abbr: "UTC", day: 13, hour: 19, min: 23, month: 3, sec: 3, std_off: 0,
       timezone: "Etc/UTC", usec: nil, utc_off: 0, year: 2010}}

# PST is the equivalent of -0800 in the RFC 2822 standard
iex> rfc2822_utc("Sat, 13 Mar 2010 11:23:03 PST")
{:ok,
      %Calendar.DateTime{abbr: "UTC", day: 13, hour: 19, min: 23, month: 3, sec: 3, std_off: 0,
       timezone: "Etc/UTC", usec: nil, utc_off: 0, year: 2010}}

# Z is the equivalent of UTC
iex> rfc2822_utc("Sat, 13 Mar 2010 11:23:03 Z")
{:ok,
      %Calendar.DateTime{abbr: "UTC", day: 13, hour: 11, min: 23, month: 3, sec: 3, std_off: 0,
       timezone: "Etc/UTC", usec: nil, utc_off: 0, year: 2010}}
rfc3339(rfc3339_string, time_zone)

Parses an RFC 3339 timestamp and shifts it to the specified time zone.

iex> rfc3339("1996-12-19T16:39:57Z", "Etc/UTC")
{:ok, %Calendar.DateTime{year: 1996, month: 12, day: 19, hour: 16, min: 39, sec: 57, timezone: "Etc/UTC", abbr: "UTC", std_off: 0, utc_off: 0}}

iex> rfc3339("1996-12-19T16:39:57.1234Z", "Etc/UTC")
{:ok, %Calendar.DateTime{year: 1996, month: 12, day: 19, hour: 16, min: 39, sec: 57, timezone: "Etc/UTC", abbr: "UTC", std_off: 0, utc_off: 0, usec: 123400}}

iex> rfc3339("1996-12-19T16:39:57-8:00", "America/Los_Angeles")
{:ok, %Calendar.DateTime{abbr: "PST", day: 19, hour: 16, min: 39, month: 12, sec: 57, std_off: 0, timezone: "America/Los_Angeles", utc_off: -28800, year: 1996}}

iex> rfc3339("invalid", "America/Los_Angeles")
{:bad_format, nil}

iex> rfc3339("1996-12-19T16:39:57-08:00", "invalid time zone name")
{:invalid_time_zone, nil}
rfc3339_utc(rfc3339_string)

Parse RFC 3339 timestamp strings as UTC. If the timestamp is not in UTC it will be shifted to UTC.

Examples

iex> rfc3339_utc("fooo")
{:bad_format, nil}

iex> rfc3339_utc("1996-12-19T16:39:57Z")
{:ok, %Calendar.DateTime{year: 1996, month: 12, day: 19, hour: 16, min: 39, sec: 57, timezone: "Etc/UTC", abbr: "UTC", std_off: 0, utc_off: 0}}

iex> rfc3339_utc("1996-12-19T16:39:57-08:00")
{:ok, %Calendar.DateTime{year: 1996, month: 12, day: 20, hour: 0, min: 39, sec: 57, timezone: "Etc/UTC", abbr: "UTC", std_off: 0, utc_off: 0}}

# No seperation chars between numbers. Not RFC3339, but we still parse it.
iex> rfc3339_utc("19961219T163957-08:00")
{:ok, %Calendar.DateTime{year: 1996, month: 12, day: 20, hour: 0, min: 39, sec: 57, timezone: "Etc/UTC", abbr: "UTC", std_off: 0, utc_off: 0}}

# Offset does not have colon (-0800). That makes it ISO8601, but not RFC3339. We still parse it.
iex> rfc3339_utc("1996-12-19T16:39:57-0800")
{:ok, %Calendar.DateTime{year: 1996, month: 12, day: 20, hour: 0, min: 39, sec: 57, timezone: "Etc/UTC", abbr: "UTC", std_off: 0, utc_off: 0}}
rfc822_utc(string, year_guessing_base \\ 2015)

Parses an RFC 822 datetime string and shifts it to UTC.

Takes an RFC 822 string and year_guessing_base. The year_guessing_base argument is used in case of a two digit year which is allowed in RFC 822. The function tries to guess possible four digit versions of the year and chooses the one closest to year_guessing_base. It defaults to 2015.

Examples

# 2 digit year
iex> "5 Jul 15 20:26:13 PST" |> rfc822_utc
{:ok,
      %Calendar.DateTime{abbr: "UTC", day: 6, hour: 4, min: 26, month: 7,
       sec: 13, std_off: 0, timezone: "Etc/UTC", usec: nil, utc_off: 0,
       year: 2015}}
# 82 as year
iex> "5 Jul 82 20:26:13 PST" |> rfc822_utc
{:ok,
      %Calendar.DateTime{abbr: "UTC", day: 6, hour: 4, min: 26, month: 7,
       sec: 13, std_off: 0, timezone: "Etc/UTC", usec: nil, utc_off: 0,
       year: 1982}}
# 1982 as year
iex> "5 Jul 82 20:26:13 PST" |> rfc822_utc
{:ok,
      %Calendar.DateTime{abbr: "UTC", day: 6, hour: 4, min: 26, month: 7,
       sec: 13, std_off: 0, timezone: "Etc/UTC", usec: nil, utc_off: 0,
       year: 1982}}
# 2 digit year and we use 2099 as the base guessing year
# which means that 15 should be interpreted as 2115 no 2015
iex> "5 Jul 15 20:26:13 PST" |> rfc822_utc(2099)
{:ok,
      %Calendar.DateTime{abbr: "UTC", day: 6, hour: 4, min: 26, month: 7,
       sec: 13, std_off: 0, timezone: "Etc/UTC", usec: nil, utc_off: 0,
       year: 2115}}
unix!(unix_time_stamp)

Takes unix time as an integer or float. Returns a DateTime struct.

Examples

iex> unix!(1_000_000_000)
%Calendar.DateTime{abbr: "UTC", day: 9, usec: nil, hour: 1, min: 46, month: 9, sec: 40, std_off: 0, timezone: "Etc/UTC", utc_off: 0, year: 2001}

iex> unix!("1000000000")
%Calendar.DateTime{abbr: "UTC", day: 9, usec: nil, hour: 1, min: 46, month: 9, sec: 40, std_off: 0, timezone: "Etc/UTC", utc_off: 0, year: 2001}

iex> unix!(1_000_000_000.9876)
%Calendar.DateTime{abbr: "UTC", day: 9, usec: 987600, hour: 1, min: 46, month: 9, sec: 40, std_off: 0, timezone: "Etc/UTC", utc_off: 0, year: 2001}

iex> unix!(1_000_000_000.999999)
%Calendar.DateTime{abbr: "UTC", day: 9, usec: 999999, hour: 1, min: 46, month: 9, sec: 40, std_off: 0, timezone: "Etc/UTC", utc_off: 0, year: 2001}