pub struct Format { /* private fields */ }Expand description
Format allows formatting an Epoch with some custom arrangement of the Epoch items. This provides almost all of the options from the 1989 C standard.
Construct a format with Format::from_str (no allocation needed) where the string
contains a succession of tokens (each starting with %) and up to two separators between tokens.
Then this format can then be provided to the Formatter for formatting. This is also no-std.
Supported tokens
Any token may be followed by ? to make it optional. For integer values, an optional token will only be printed
if its value is non-zero. For time scales, only non-UTC time scale will be printed.
C89 standard tokens
| Token | Explanation | Example | Notes |
|---|---|---|---|
%Y | Proleptic Gregorian year, zero-padded to 4 digits | 2022 | (1) |
%m | Month number, zero-padded to 2 digits | 03 for March | N/A |
%b | Month name in short form | Mar for March | N/A |
%B | Month name in long form | March | N/A |
%d | Day number, zero-padded to 2 digits | 07 for the 7th day of the month | N/A |
%j | Day of year, zero-padded to 3 digits | 059 for 29 February 2000 | N/A |
%A | Weekday name in long form | Monday | N/A |
%a | Weekday name in short form | Mon for Monday | N/A |
%H | Hour number, zero-padded to 2 digits | 02 for the 2nd hour of the day | N/A |
%M | Minute number, zero-padded to 2 digits | 39 for the 39th minutes of the hour | N/A |
%S | Seconds, zero-padded to 2 digits | 27 for the 27th second of the minute | N/A |
%f | Sub-seconds, zero-padded to 9 digits | 000000007 for the 7th nanosecond past the second | (2) |
%w | Weekday in decimal form with C89 standard | 01 for Dynamical barycentric time | (3) |
%z | Offset timezone if the formatter is provided with an epoch. | +15:00 For GMT +15 hours and zero minutes | N/A |
- (1): Hifitime supports years from -34668 to 34668. If your epoch is larger than +/- 9999 years, the formatting of the years will show all five digits of the year.
- (2): Hifitime supports exactly nanosecond precision, and this is not lost when formatting.
Hifitime specific tokens
These are chosen to not conflict with strptime/strfime of the C89 standard.
| Token | Explanation | Example | Notes
| :– | :– | :– | :– |
| %T | Time scale used to represent this date | TDB for Dynamical barycentric time | (3) |
| %J | Full day of year as a double | 59.62325231481524 for 29 February 2000 14:57:29 UTC | N/A |
- (3): Hifitime supports many time scales and these should not be lost when formatting. This is a novelty compared to other time management libraries as most do not have any concept of time scales.
Example
use hifitime::prelude::*;
use hifitime::efmt;
use hifitime::efmt::consts;
use core::str::FromStr;
let bday = Epoch::from_gregorian_utc(2000, 2, 29, 14, 57, 29, 37);
let fmt = efmt::Format::from_str("%Y-%m-%d").unwrap();
assert_eq!(fmt, consts::ISO8601_DATE);
let fmtd_bday = Formatter::new(bday, fmt);
assert_eq!(format!("{fmtd_bday}"), format!("2000-02-29"));
let fmt = Format::from_str("%Y-%m-%dT%H:%M:%S.%f %T").unwrap();
assert_eq!(fmt, consts::ISO8601);
let fmtd_bday = Formatter::new(bday, fmt);
// ISO with the timescale is the default format
assert_eq!(format!("{fmtd_bday}"), format!("{bday}"));
let fmt = Format::from_str("%Y-%j").unwrap();
assert_eq!(fmt, consts::ISO8601_ORDINAL);
let fmt_iso_ord = Formatter::new(bday, consts::ISO8601_ORDINAL);
assert_eq!(format!("{fmt_iso_ord}"), "2000-059");
let fmt = Format::from_str("%A, %d %B %Y %H:%M:%S").unwrap();
assert_eq!(fmt, consts::RFC2822_LONG);
let fmt = Formatter::new(bday, consts::RFC2822_LONG);
assert_eq!(
format!("{fmt}"),
format!("Tuesday, 29 February 2000 14:57:29")
);
let fmt = Format::from_str("%a, %d %b %Y %H:%M:%S").unwrap();
assert_eq!(fmt, consts::RFC2822);
let fmt = Formatter::new(bday, consts::RFC2822);
assert_eq!(format!("{fmt}"), format!("Tue, 29 Feb 2000 14:57:29"));