handlebars-chrono

chrono DateTime helper for handlebars-rust

Quick Start

Developed and tested with handlebars-rust v5.1.0 and chrono v0.4.35.

Optional features:

• locale includes unstable-locales in chrono and enables the locale parameter to produce localized timestamps
• timezone includes chrono-tz and enables parsing IANA timezone names passed as timezone parameter

Versions

Versions 0.1.* are compatible with handlebars 5.
Versions 0.2.* are compatible with handlebars 6.

Include

Add to Cargo.toml:

handlebars-chrono = { version = "^0", features = [ "locale", "timezone" ] }

Registration

    use handlebars::Handlebars;
    use handlebars_chrono::HandlebarsChronoDateTime;
    
    let mut h = Handlebars::new();
    h.register_helper("datetime", Box::new(HandlebarsChronoDateTime));

Behavior

By default, if no parameters are supplied to the helper it produces a RFC3339 current UTC timestamp.

Parameters

There are 3 groups of possible parameters in various different combinations:

• Initializers: Parameters controlling how the chrono::DateTime is being constructed. All initializers produce a DateTime<Utc> internally.
• Modifiers: Parameters modifying the internally constructed DateTime<Utc>. At this stage the internal DateTime gets converted to DateTime<FixedOffset> to support all possible modifiers and finalizers. By default, the FixedOffset remains tied to UTC.
• Finalizers: Parameters determining how the internal DateTime will get output as String

Initializers

The default initializer is equivalent to Utc::now() and produces a DateTime<Utc> of the current time.

Other possible initializers:

• from_timestamp: taking UNIX timestamp in seconds as value
• from_timestamp_millis: taking UNIX timestamp in milli-seconds as value
• from_timestamp_micros: taking UNIX timestamp in micro-seconds as value
• from_timestamp_nanos: taking UNIX timestamp in nano-seconds as value
• from_rfc2822: taking a valid RFC2822 formatted string as value
• from_rfc3339: taking a valid RFC3339 formatted string as value
• from_str + input_format: taking an arbitrarily formatted datetime string and its corresponding format as values

If the selected initializer holds a timezone or offset information it will be dropped and converted to the equivalent DateTime in UTC.

Modifiers

By default, no modifiers are being applied. Each modifier can be applied only once. Any variations of modifiers can be used together.

Possible modifiers:

• with_timezone: Sets the offset of the internal DateTime. Possible values are: local (for local time), valid fixed offset (ex. -06:00) or a valid IANA timezone, if the timezone feature is enabled (ex. America/Edmonton).
• with_ordinal: Sets the date to a specific day of the year, starting from 1.
• with_ordinal0: Sets the date to a specific day of the year, starting from 0.
• with_year: Sets the date to a specific year.
• with_month: Sets the date to a specific month, starting from 1.
• with_month0: Sets the date to a specific month, starting from 0.
• with_day: Sets the date to a specific day of the month, starting from 1.
• with_day0: Sets the date to a specific day of the month, starting from 0.
• with_hour: Sets the time to a specific hour of the day.
• with_minute: Sets the time to a specific minute of the hour.
• with_second: Sets the time to a specific second of the minute.
• with_nanosecond: Sets the nano-seconds segment of the DateTime.
• add_months: Adds a given number of months.
• add_weeks: Adds a given number of weeks.
• add_days: Adds a given number of days.
• add_hours: Adds a given number of hours.
• add_minutes: Adds a given number of minutes.
• add_seconds: Adds a given number of seconds.
• add_milliseconds: Adds a given number of milli-seconds.
• add_microseconds: Adds a given number of micro-seconds.
• add_nanoseconds: Adds a given number of nano-seconds.
• sub_months: Subtracts a given number of months.
• sub_weeks: Subtracts a given number of weeks.
• sub_days: Subtracts a given number of days.
• sub_hours: Subtracts a given number of hours.
• sub_minutes: Subtracts a given number of minutes.
• sub_seconds: Subtracts a given number of seconds.
• sub_milliseconds: Subtracts a given number of milli-seconds.
• sub_microseconds: Subtracts a given number of micro-seconds.
• sub_nanoseconds: Subtracts a given number of nano-seconds.

Finalizers

The default finalizer is equivalent to DateTime::to_rfc3339() and produces a valid RFC3339 String.

Other possible finalizers:

• output_format + locale: Takes a strftime date time format to use as an output format. The locale parameter works only if the locale feature is enabled. In that case it accepts a valid locale name.
• to_rfc2822: Makes the helper output a valid RFC2822 string. To be a valid hash parameter you must supply a value. For example true, or 1. The value is being ignored.
• to_timestamp: Makes the helper output a UNIX timestamp in seconds. To be a valid hash parameter you must supply a value. For example true, or 1. The value is being ignored.
• to_timestamp_millis: Makes the helper output a UNIX timestamp in milli-seconds. To be a valid hash parameter you must supply a value. For example true, or 1. The value is being ignored.
• to_timestamp_micros: Makes the helper output a UNIX timestamp in micro-seconds. To be a valid hash parameter you must supply a value. For example true, or 1. The value is being ignored.
• to_timestamp_nanos: Makes the helper output a UNIX timestamp in nano-seconds. To be a valid hash parameter you must supply a value. For example true, or 1. The value is being ignored.
• years_since: Takes a RFC3339 formatted date time to compare against the internal DateTime and calculate the years difference. The years_since value must be the further in the past.

Examples

Current date and time in RFC3339:

{{datetime}}

Current date and time in format like 2024-03-16 15:39:42:

{{datetime output_format="%Y-%m-%d %H:%M:%S"}}

Calendar date in French, for example samedi, mars 16:

{{datetime output_format="%A, %B %e" locale="fr_FR"}}

Current date and time in RFC2822, like Sat, 16 Mar 2024 21:43:31 +0000:

{{datetime to_rfc2822=true}}

Current UNIX timestamp:

{{datetime to_timestamp=true}}

Years since June 1985:

{{datetime years_since="1985-06-16T12:00:00Z"}}

Reformat a UNIX timestamp to MySQL datetime:

{{datetime from_timestamp="618658211" output_format="%Y-%m-%d %H:%M:%S"}}

Years between two dates in the past:

{{datetime from_timestamp="618658211" years_since="1985-06-16T12:00:00Z"}}

Years between two dates in the past, but with UNIX timestamps only:

{{datetime from_timestamp="618658211" years_since=(datetime from_timestamp="487771200")}}

From UNIX timestamp in milli-seconds to calendar date in French (ex. mercredi, août 9):

{{datetime from_timestamp_millis="618658211123" output_format="%A, %B %e" locale="fr_FR"}}

From RFC2822 date time to MySQL datetime:

{{datetime from_rfc2822="Wed, 09 Aug 1989 09:30:11 +0200" output_format="%Y-%m-%d %H:%M:%S"}}

From RFC3339 to RFC2822:

{{datetime from_rfc3339="1989-08-09T09:30:11+02:00" to_rfc2822=true}}

From MySQL datetime to RFC2822:

{{datetime from_str="1989-08-09 09:30:11" input_format="%Y-%m-%d %H:%M:%S" to_rfc2822=true}}

From/To RFC3339 with timezone change:

{{datetime from_rfc3339="1989-08-09T09:30:11+02:00" with_timezone="America/Edmonton"}}

Switch from August to November:

{{datetime from_timestamp="618658211" with_month="11" to_timestamp=true}}

Switch from the 9th to the 11th:

{{datetime from_timestamp="618658211" with_day="11" to_timestamp=true}}

Add 24 months:

{{datetime from_timestamp="618658211" add_months="24" to_timestamp=true}}

Subtract 4 weeks:

{{datetime from_timestamp="618658211" sub_weeks="4" to_timestamp=true}}

License

This library (handlebars-chrono) is open sourced under the BSD 2 License.