birl

Types

Day

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

Constructors

```
Day(year: Int, month: Int, date: Int)
```

Month

</>

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
```

Time

opaque </>

pub opaque type Time

TimeOfDay

</>

pub type TimeOfDay {
  TimeOfDay(
    hour: Int,
    minute: Int,
    second: Int,
    milli_second: Int,
  )
}

Constructors

TimeOfDay(hour: Int, minute: Int, second: Int, milli_second: Int)

Weekday

</>

pub type Weekday {
  Mon
  Tue
  Wed
  Thu
  Fri
  Sat
  Sun
}

Constructors

```
Mon
```
```
Tue
```
```
Wed
```
```
Thu
```
```
Fri
```
```
Sat
```
```
Sun
```

Constants

Functions

add

</>

pub fn add(value: Time, duration: Duration) -> Time

compare

</>

pub fn compare(a: Time, b: Time) -> Order

difference

</>

pub fn difference(a: Time, b: Time) -> Duration

from_erlang_local_datetime

</>

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

from_erlang_universal_datetime

</>

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

from_http

</>

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

from_naive

</>

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

from_unix

</>

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

from_unix_micro

</>

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

from_unix_milli

</>

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

get_day

</>

pub fn get_day(value: Time) -> Day

get_offset

</>

pub fn get_offset(value: Time) -> String

get_time_of_day

</>

pub fn get_time_of_day(value: Time) -> TimeOfDay

get_timezone

</>

pub fn get_timezone(value: Time) -> Option(String)

legible_difference

</>

pub fn legible_difference(a: Time, b: Time) -> String

monotonic_now

</>

pub fn monotonic_now() -> Int

month

</>

pub fn month(value: Time) -> Month

now

</>

pub fn now() -> Time

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

now_with_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"

now_with_timezone

</>

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

parse

</>

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

parse_month

</>

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

parse_naive_time_of_day

</>

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

parse_relative

</>

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")

parse_time_of_day

</>

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")

parse_weekday

</>

pub fn parse_weekday(value: String) -> Result(Weekday, Nil)

range

</>

pub fn range(
  from a: Time,
  to b: Option(Time),
  step s: Duration,
) -> Yielder(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

set_day

</>

pub fn set_day(value: Time, day: Day) -> Time

set_offset

</>

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"

set_time_of_day

</>

pub fn set_time_of_day(value: Time, time: TimeOfDay) -> Time

set_timezone

</>

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

WARNING: Does not respect daylight saving time!

short_string_month

</>

pub fn short_string_month(value: Time) -> String

short_string_weekday

</>

pub fn short_string_weekday(value: Time) -> String

string_month

</>

pub fn string_month(value: Time) -> String

string_weekday

</>

pub fn string_weekday(value: Time) -> String

subtract

</>

pub fn subtract(value: Time, duration: Duration) -> Time

time_of_day_to_short_string

</>

pub fn time_of_day_to_short_string(value: TimeOfDay) -> String

time_of_day_to_string

</>

pub fn time_of_day_to_string(value: TimeOfDay) -> String

to_date_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

to_erlang_datetime

</>

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

calculates erlang datetime using the offset in the DateTime value

to_erlang_universal_datetime

</>

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

to_http

</>

pub fn to_http(value: Time) -> String

see here

to_http_with_offset

</>

pub fn to_http_with_offset(value: Time) -> String

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

to_iso8601

</>

pub fn to_iso8601(value: Time) -> String

to_naive

</>

pub fn to_naive(value: Time) -> String

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

to_naive_date_string

</>

pub fn to_naive_date_string(value: Time) -> String

like to_date_string except it does not contain the offset

to_naive_time_string

</>

pub fn to_naive_time_string(value: Time) -> String

like to_time_string except it does not contain the offset

to_time_string

</>

pub fn to_time_string(value: Time) -> String

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

to_unix

</>

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

to_unix_micro

</>

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

to_unix_milli

</>

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

utc_now

</>

pub fn utc_now() -> Time

use this to get the current time in utc

weekday

</>

pub fn weekday(value: Time) -> Weekday

weekday_to_short_string

</>

pub fn weekday_to_short_string(value: Weekday) -> String

weekday_to_string

</>

pub fn weekday_to_string(value: Weekday) -> String