Timestamps and Datetime strings in Faxe

In Faxe we deal a lot with timestamps and datetime strings, in fact, every message that flows through all the nodes, has a timestamp with it.

Its inner representation of points in time is always an integer denoting the milliseconds that past since 1.1.1970. There is currently no timezone handling in Faxe.

Datetime string parsing

Faxe uses its own library to parse datetime strings (from the outside) into it's internal timestamp format. This is done in different nodes such as the mqtt_subscribe and the amqp_consume node. Furthermore, datetime parsing can be done in lambda-expression with the dt_parse function.

When parsing datetime strings with subsecond values smaller than milliseconds (microseconds and nanoseconds), if present, will be rounded to millisecond values.

Parsing examples

datetime matching format string
'Mon, 15 Jun 2009 20:45:30 GMT' 'a, d b Y H:M:S Z'
'19.08.01 17:33:44,867000 ' 'd.m.y H:M:S,u '
'8/28/2033 8:03:45.576000 PM' 'n/d/Y l:M:S.u p'

Conversion Specification

The format used to parse and format dates closely resembles the one used in strftime()[1]. The most notable exception is that meaningful characters are not prefixed with a percentage sign (%) in datestring.

Characters not matching a conversion specification will be copied to the output verbatim when formatting and matched against input when parsing. Meaningful characters can be escaped with a backslash (\).

Character Sequence Parsing Formatting Description
a Yes* Yes Abbreviated weekday name ("Mon", "Tue")
A Yes Yes Weekday name ("Monday", "Tuesday")
b Yes* Yes Abbreviated month name ("Jan", "Feb")
B Yes* Yes Month name ("January", "February")
d Yes Yes Day of month with leading zero ("01", "31")
e Yes Yes Day of month without leading zero ("1", "31")
F No Yes ISO 8601 date format (shortcut for "Y-m-d")
H Yes Yes Hour (24 hours) with leading zero ("01", "23")
I Yes Yes Hour (12 hours) with leading zero ("01", "11")
k Yes Yes Hour (24 hours) without leading zero ("1", "23")
l Yes Yes Hour (12 hours) without leading zero ("1", "11")
m Yes Yes Month with leading zero ("1", "12")
M Yes Yes Minute with leading zero ("00", "59")
n Yes Yes Month without leading zero ("1", "12")
o Yes Yes Ordinal number suffix abbreviation (st, nd, rd, th)
p Yes* Yes AM/PM
P Yes* Yes a.m./p.m.
R No Yes The time as H:M (24 hour format) ("23:59")
S Yes Yes Seconds with leading zero ("00", "59")
T No Yes The time as H:M:S (24 hour format) ("23:49:49")
c Yes No Milliseconds, 3 digits with leading zero ("034")
u Yes Yes Microseconds, 6 digits with leading zero ("000034")
f Yes No Nanoseconds, 9 digits with leading zero ("000034000")
y Yes** Yes Year without century ("02", "12")
Y Yes Yes Year including century ("2002", "2012")
z Yes No UTC offset (+0100, +01:00, +01, -0100, -01:00, -01)
Z Yes No Abbreviated timezone (UTC, GMT, CET etc)

* Case-insensitive when parsing

** Falls back on current century of system when parsing years without century.

Special formats

dt_format description example
'millisecond' timestamp UTC in milliseconds 1565343079000
'microsecond' timestamp UTC in microseconds 1565343079000123
'nanosecond' timestamp UTC in nanoseconds 1565343079000123456
'second' timestamp UTC in seconds 1565343079
'float_nano' timestamp UTC float with nanosecond precision 1565343079.173588126
'float_micro' timestamp UTC float with microsecond precision 1565343079.173588
'float_millisecond' timestamp UTC float with millisecond precision 1565343079.173
'ISO8601' ISO8601 Datetime format string '2011-10-05T14:48:00.000Z'
'RFC3339' RFC3339 Datetime format string '2018-02-01 15:18:02.088Z'