Struct Format
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) |
%y | Proleptic Gregorian year after 2000, on two digits | 23 | N/A |
%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-060");
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"));
Implementations§
Trait Implementations§
impl Copy for Format
impl StructuralPartialEq for Format
Auto Trait Implementations§
impl Freeze for Format
impl RefUnwindSafe for Format
impl Send for Format
impl Sync for Format
impl Unpin for Format
impl UnwindSafe for Format
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
🔬This is a nightly-only experimental API. (
clone_to_uninit
)§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
Converts
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
Converts
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read more§impl<T> Pointable for T
impl<T> Pointable for T
§impl<SS, SP> SupersetOf<SS> for SPwhere
SS: SubsetOf<SP>,
impl<SS, SP> SupersetOf<SS> for SPwhere
SS: SubsetOf<SP>,
§fn to_subset(&self) -> Option<SS>
fn to_subset(&self) -> Option<SS>
The inverse inclusion map: attempts to construct
self
from the equivalent element of its
superset. Read more§fn is_in_subset(&self) -> bool
fn is_in_subset(&self) -> bool
Checks if
self
is actually part of its subset T
(and can be converted to it).§fn to_subset_unchecked(&self) -> SS
fn to_subset_unchecked(&self) -> SS
Use with care! Same as
self.to_subset
but without any property checks. Always succeeds.§fn from_subset(element: &SS) -> SP
fn from_subset(element: &SS) -> SP
The inclusion map: converts
self
to the equivalent element of its superset.