Search documentation of jhn_stdlib

# jhn_timestamp (jhn_stdlib v5.10.3)

View Source

A timestamp library based on: Date and Time on the Internet: Timestamps (rfc3339) Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content (rfc7231)

The timestamp is represented as follows:

posix : -62167219200..253402300799

stamp : #{year := year(), month := month(), day := day(), hour := hour(), minute := minute(), second := second(), fraction => pos_integer(), offset => offset() }

offset() : 'Z' | #{sign := '+' | '-', hours := hours(), minutes := minutes()}

datetime : {{year(), month(), day()}, {hour(), minute(), second() | float()}}

The datetime is the usual calendar one extended with float seconds to represent fractions (you have to know the precision used, default seconds).

year() : 0..9999. month() : 1..12. day() : 1..31. hour() : 0..23. minute() : 0..59. second() : 0..59.

The fraction and offset parts are optional and defaults to 0 and Z. The precision of the fraction is default seconds, hence default fraction 0.

# Summary

## Types

datetime/0
day/0
hour/0
minute/0
month/0
offset/0
opt/0
posix/0
precision/0
return_type/0
second/0
stamp/0
year/0

## Functions

decode(Binary)

Decodes the binary, posix integer or datetime tuple timestamp into a map representing a timestamp. Equivalent of decode(Binary, [])

decode(D, Opts)

Decodes the binary, posix integer or datetime timestamp into a map representing a timestamp. Decode will give an exception if the binary is not well formed timestamp. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision nano -> nano second precision rfc7231 -> the binary is a rfc7231 compatible continue -> all remaining indata is returned when decoding a binary

encode(Stamp)

Encodes the map as an iolist. Equivalent of encode(Stamp, [])

encode(Stamp, ParsedOpts)

Encodes the stamp and encode as an iolist, list, binary, integer posix timestamp or a nested datetime tuple. Encode will give an exception if the Stamp is not well formed. Options are: seconds (default) -> second precision (no fraction generated) milli -> milli second precision micro -> micro second precision nano -> nano second precision binary -> a binary is returned list -> a flat list is returned iolist -> an iolist is returned datetime -> a datetime nested tuple is returned rfc7231 -> the returned string is rfc7231 compatible posix -> a posix integer timestamp is returned

gen()

Generates the timestamp as an iolist of precision seconds Equivalent of gen([])

gen(Opts)

Generates a timestamp and encode as an iolist, list, binary, integer posix timestamp or a nested datetime tuple. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision nano -> nano second precision binary -> a binary is returned list -> a flat list is returned iolist (default) -> an iolist is returned datetime -> a datetime nested tuple is returned rfc7231 -> the returned string is rfc7231 compatible, and precision is seconds, e.g., ~"Sun, 08 Mar 2026 13:19:52 GMT" posix -> a posix integer timestamp is returned

valid(Time)

Validates that a timestamp is correct, precision seconds and in the format of a rfc3339 binary; posix integer; datetime or a stamp map. Equivalent of valid(TimeStamp, [])

valid(Stamp, Opts)

Validates that a timestamp is correct in the format of a rfc3339 or rfc7231 binary; posix integer; datetime or a stamp map. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision nano -> nano second precision rfc7231 -> rfc7231 format of the binary

# Types

# datetime/0

    -type datetime() :: {{year(), month(), day()}, {hour(), minute(), second()}}.

# day/0

    -type day() :: 1..31.

# hour/0

    -type hour() :: 0..23.

# minute/0

    -type minute() :: 0..59.

# month/0

    -type month() :: 1..12.

# offset/0

    -type offset() :: 'Z' | #{sign := '+' | '-', hours := hour(), minutes := minute()}.

# opt/0

    -type opt() :: precision() | rfc7231 | return_type() | continue.

# posix/0

    -type posix() :: -62167219200..253402300799.

# precision/0

    -type precision() :: seconds | milli | micro | nano.

# return_type/0

    -type return_type() :: iolist | binary | list | posix | datetime.

# second/0

    -type second() :: 0..59.

# stamp/0

    -type stamp() ::
              #{year := year(),
                month := month(),
                day := day(),
                hour := hour(),
                minute := minute(),
                second := second(),
                fraction => pos_integer(),
                offset => offset()}.

# year/0

    -type year() :: 0..9999.

# Functions

# decode(Binary)

    -spec decode(binary() | posix()) -> stamp().

Decodes the binary, posix integer or datetime tuple timestamp into a map representing a timestamp. Equivalent of decode(Binary, [])

# decode(D, Opts)

    -spec decode(binary() | posix() | datetime(),
                 [opt()] |
                 #opts{precision :: precision(),
                       continue :: boolean(),
                       rfc7231 :: boolean(),
                       return_type :: return_type()}) ->
                    stamp() | {stamp(), binary()}.

Decodes the binary, posix integer or datetime timestamp into a map representing a timestamp. Decode will give an exception if the binary is not well formed timestamp. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision nano -> nano second precision rfc7231 -> the binary is a rfc7231 compatible continue -> all remaining indata is returned when decoding a binary

# encode(Stamp)

    -spec encode(stamp() | posix() | datetime()) -> iolist().

Encodes the map as an iolist. Equivalent of encode(Stamp, [])

# encode(Stamp, ParsedOpts)

    -spec encode(stamp() | posix() | datetime(),
                 [opt()] |
                 #opts{precision :: precision(),
                       continue :: boolean(),
                       rfc7231 :: boolean(),
                       return_type :: return_type()}) ->
                    iolist() | binary() | list() | posix() | datetime().

Encodes the stamp and encode as an iolist, list, binary, integer posix timestamp or a nested datetime tuple. Encode will give an exception if the Stamp is not well formed. Options are: seconds (default) -> second precision (no fraction generated) milli -> milli second precision micro -> micro second precision nano -> nano second precision binary -> a binary is returned list -> a flat list is returned iolist -> an iolist is returned datetime -> a datetime nested tuple is returned rfc7231 -> the returned string is rfc7231 compatible posix -> a posix integer timestamp is returned

# gen()

    -spec gen() -> iolist().

Generates the timestamp as an iolist of precision seconds Equivalent of gen([])

# gen(Opts)

    -spec gen([opt()] |
              #opts{precision :: precision(),
                    continue :: boolean(),
                    rfc7231 :: boolean(),
                    return_type :: return_type()}) ->
                 list() | iolist() | binary() | posix().

Generates a timestamp and encode as an iolist, list, binary, integer posix timestamp or a nested datetime tuple. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision nano -> nano second precision binary -> a binary is returned list -> a flat list is returned iolist (default) -> an iolist is returned datetime -> a datetime nested tuple is returned rfc7231 -> the returned string is rfc7231 compatible, and precision is seconds, e.g., ~"Sun, 08 Mar 2026 13:19:52 GMT" posix -> a posix integer timestamp is returned

# valid(Time)

    -spec valid(stamp() | posix() | datetime() | binary() | posix()) -> boolean().

Validates that a timestamp is correct, precision seconds and in the format of a rfc3339 binary; posix integer; datetime or a stamp map. Equivalent of valid(TimeStamp, [])

# valid(Stamp, Opts)

    -spec valid(stamp() | posix() | datetime() | binary() | posix(),
                [opt()] |
                #opts{precision :: precision(),
                      continue :: boolean(),
                      rfc7231 :: boolean(),
                      return_type :: return_type()}) ->
                   boolean().

Validates that a timestamp is correct in the format of a rfc3339 or rfc7231 binary; posix integer; datetime or a stamp map. Options are: seconds (default) -> second precision milli -> milli second precision micro -> micro second precision nano -> nano second precision rfc7231 -> rfc7231 format of the binary

N.B. for binary format in rfc7231 format the rfc7231 options must provided and any precision other than seconds that must be provided as an option otherwise the answer may be false.