birl

Types

pub type Day {
  Day(year: Int, month: Int, date: Int)
}

Constructors

  • Day(year: Int, month: Int, date: Int)
pub type Month {
  Jan
  Feb
  Mar
  Apr
  May
  Jun
  Jul
  Aug
  Sep
  Oct
  Nov
  Dec
}

Constructors

  • Jan
  • Feb
  • Mar
  • Apr
  • May
  • Jun
  • Jul
  • Aug
  • Sep
  • Oct
  • Nov
  • Dec
pub opaque type Time
pub type TimeOfDay {
  TimeOfDay(
    hour: Int,
    minute: Int,
    second: Int,
    milli_second: Int,
  )
}

Constructors

  • TimeOfDay(hour: Int, minute: Int, second: Int, milli_second: Int)
pub type Weekday {
  Mon
  Tue
  Wed
  Thu
  Fri
  Sat
  Sun
}

Constructors

  • Mon
  • Tue
  • Wed
  • Thu
  • Fri
  • Sat
  • Sun

Constants

pub const unix_epoch: Time

starting point of unix timestamps

Functions

pub fn add(value: Time, duration: Duration) -> Time
pub fn compare(a: Time, b: Time) -> Order
pub fn difference(a: Time, b: Time) -> Duration
pub fn from_erlang_local_datetime(
  erlang_datetime: #(#(Int, Int, Int), #(Int, Int, Int)),
) -> Time

calculates the DateTime value from the erlang datetime using the local offset of the system

pub fn from_erlang_universal_datetime(
  erlang_datetime: #(#(Int, Int, Int), #(Int, Int, Int)),
) -> Time

calculates the DateTime value from the erlang datetime in UTC

pub fn from_http(value: String) -> Result(Time, Nil)

see here

also supports other similar formats:

  • Tue, 01-Nov-2016 08:49:37 GMT

  • Tue, 01 Nov 2016 08:49:37 +0630

  • Tue, 01-November-2016 08:49:37 Z

  • Tuesday, 01-Nov-2016 08:49:37 +330

  • Tuesday, 01 November 2016 08:49:37 +06:30

pub fn from_naive(value: String) -> Result(Time, Nil)

accepts fromats similar to the ones listed for parse except that there shoundn’t be any offset information

pub fn from_unix(value: Int) -> Time

unix timestamps are the number of seconds that have elapsed since 00:00:00 UTC on January 1st, 1970

pub fn from_unix_micro(value: Int) -> Time

unix micro timestamps are the number of microseconds that have elapsed since 00:00:00 UTC on January 1st, 1970

pub fn from_unix_milli(value: Int) -> Time

unix milli timestamps are the number of milliseconds that have elapsed since 00:00:00 UTC on January 1st, 1970

pub fn get_day(value: Time) -> Day
pub fn get_offset(value: Time) -> String
pub fn get_time_of_day(value: Time) -> TimeOfDay
pub fn get_timezone(value: Time) -> Option(String)
pub fn legible_difference(a: Time, b: Time) -> String
pub fn monotonic_now() -> Int
pub fn month(value: Time) -> Month
pub fn now() -> Time

use this to get the current time in the local timezone offset

pub fn now_with_offset(offset: String) -> Result(Time, Nil)

use this to get the current time with a given offset.

some examples of acceptable offsets:

"+330", "03:30", "-8:00","-7", "-0400", "03"

pub fn now_with_timezone(timezone: String) -> Result(Time, Nil)
pub fn parse(value: String) -> Result(Time, Nil)

if you need to parse an ISO8601 string, this is probably what you’re looking for.

given the huge surface area that ISO8601 covers, it does not make sense for birl to support all of it in one function, so this function parses only strings for which both day and time of day can be extracted or deduced. Some acceptable examples are given below:

  • 2019t14-4 -> 2019-01-01T14:00:00.000-04:00

  • 2019-03-26t14:00.9z -> 2019-03-26T14:00:00.900Z

  • 2019-03-26+330 -> 2019-03-26T00:00:00.000+03:30

  • 20190326t1400-4 -> 2019-03-26T14:00:00.000-04:00

  • 19051222T16:38-3 -> 1905-12-22T16:38:00.000-03:00

  • 2019-03-26 14:30:00.9Z -> 2019-03-26T14:30:00.900Z

  • 2019-03-26T14:00:00.9Z -> 2019-03-26T14:00:00.900Z

  • 1905-12-22 16:38:23-3 -> 1905-12-22T16:38:23.000-03:00

  • 2019-03-26T14:00:00,4999Z -> 2019-03-26T14:00:00.499Z

  • 1905-12-22T163823+0330 -> 1905-12-22T16:38:23.000+03:30

  • 1905-12-22T16:38:23.000+03:30 -> 1905-12-22T16:38:23.000+03:30

pub fn parse_month(value: String) -> Result(Month, Nil)
pub fn parse_naive_time_of_day(
  value: String,
) -> Result(#(TimeOfDay, String), Nil)

accepts fromats similar to the ones listed for parse_time_of_day except that there shoundn’t be any offset information

pub fn parse_relative(
  origin: Time,
  legible_difference: String,
) -> Result(Time, Nil)

you could say this is the opposite of legible_difference

> parse_relative(birl.now(), "8 minutes ago")
pub fn parse_time_of_day(
  value: String,
) -> Result(#(TimeOfDay, String), Nil)

this function parses ISO8601 strings in which no date is specified, which means such inputs don’t actually represent a particular moment in time. That’s why the result of this function is an instance of TimeOfDay along with the offset specificed in the string. Some acceptable examples are given below:

  • t25z -> #(TimeOfDay(2, 5, 0, 0), "Z")

  • 14-4 -> #(TimeOfDay(14, 0, 0, 0), "-04:00")

  • T145+4 -> #(TimeOfDay(14, 5, 0, 0), "+04:00")

  • 16:38-3 -> #(TimeOfDay(16, 38, 0, 0), "-03:00")

  • t14:65.9z -> #(TimeOfDay(14, 6, 5, 900), "-04:00")

  • 163823+0330 -> #(TimeOfDay(16, 38, 23, 0), "+03:30")

  • T16:38:23.050+03:30 -> #(TimeOfDay(16, 38, 23, 50), "+03:30")

pub fn parse_weekday(value: String) -> Result(Weekday, Nil)
pub fn range(
  from a: Time,
  to b: Option(Time),
  step s: Duration,
) -> Iterator(Time)

can be used to create a time range starting from time a with step s

if b is option.None the range will be infinite

pub fn set_day(value: Time, day: Day) -> Time
pub fn set_offset(
  value: Time,
  new_offset: String,
) -> Result(Time, Nil)

use this to change the offset of a given time value.

some examples of acceptable offsets:

"+330", "03:30", "-8:00","-7", "-0400", "03", "Z"

pub fn set_time_of_day(value: Time, time: TimeOfDay) -> Time
pub fn set_timezone(
  value: Time,
  new_timezone: String,
) -> Result(Time, Nil)

WARNING: Does not respect daylight saving time!

pub fn short_string_month(value: Time) -> String
pub fn short_string_weekday(value: Time) -> String
pub fn string_month(value: Time) -> String
pub fn string_weekday(value: Time) -> String
pub fn subtract(value: Time, duration: Duration) -> Time
pub fn time_of_day_to_short_string(value: TimeOfDay) -> String
pub fn time_of_day_to_string(value: TimeOfDay) -> String
pub fn to_date_string(value: Time) -> String

returns a string which is the date part of an ISO8601 string along with the offset

pub fn to_erlang_datetime(
  value: Time,
) -> #(#(Int, Int, Int), #(Int, Int, Int))

calculates erlang datetime using the offset in the DateTime value

pub fn to_erlang_universal_datetime(
  value: Time,
) -> #(#(Int, Int, Int), #(Int, Int, Int))

calculates the universal erlang datetime regardless of the offset in the DateTime value

pub fn to_http(value: Time) -> String

see here

pub fn to_http_with_offset(value: Time) -> String

like to_http but assumes the offset in the DateTime value instead of GMT

pub fn to_iso8601(value: Time) -> String
pub fn to_naive(value: Time) -> String

the naive format is the same as ISO8601 except that it does not contain the offset

pub fn to_naive_date_string(value: Time) -> String

like to_date_string except it does not contain the offset

pub fn to_naive_time_string(value: Time) -> String

like to_time_string except it does not contain the offset

pub fn to_time_string(value: Time) -> String

returns a string which is the time part of an ISO8601 string along with the offset

pub fn to_unix(value: Time) -> Int

unix timestamps are the number of seconds that have elapsed since 00:00:00 UTC on January 1st, 1970

pub fn to_unix_micro(value: Time) -> Int

unix micro timestamps are the number of microseconds that have elapsed since 00:00:00 UTC on January 1st, 1970

pub fn to_unix_milli(value: Time) -> Int

unix milli timestamps are the number of milliseconds that have elapsed since 00:00:00 UTC on January 1st, 1970

pub fn utc_now() -> Time

use this to get the current time in utc

pub fn weekday(value: Time) -> Weekday
pub fn weekday_to_short_string(value: Weekday) -> String
pub fn weekday_to_string(value: Weekday) -> String
Search Document