Struct timeago::Formatter

pub struct Formatter<L: Language = English> { /* fields omitted */ }

Main formatter struct. Build it with new() and maybe modify some options, then use convert.

let f = timeago::Formatter::new();
let d = std::time::Duration::from_secs(3600);
assert_eq!(f.convert(d), "1 hour ago");

Methods

impl Formatter

pub fn new() -> Formatter

Constructor for some default formatting in English

impl<L: Language> Formatter<L>

pub fn with_language(l: L) -> Self

Constructor for some default formatting with specified language instance

pub fn num_items(&mut self, x: usize) -> &mut Self

Set number of time unit items to emit (for example, 1 item is for "1 year"; 3 items is for "1 year 3 months 17 days"). Zero chunks like "0 minutes" are not emitted, expect of at the end if too_low is "0". Default is 1.

let mut f = timeago::Formatter::new();
f.num_items(1);
let d = std::time::Duration::from_secs(3600+60+3);
assert_eq!(f.convert(d), "1 hour ago");
f.num_items(2);
assert_eq!(f.convert(d), "1 hour 1 minute ago");
f.num_items(3);
assert_eq!(f.convert(d), "1 hour 1 minute 3 seconds ago");
f.num_items(4);
assert_eq!(f.convert(d), "1 hour 1 minute 3 seconds ago");

pub fn max_unit(&mut self, x: TimeUnit) -> &mut Self

Set maximum used unit. Not to be confused with max_duration. Should not affect appearance of "old" or other too_high values.

let mut f = timeago::Formatter::new();
f.max_unit(timeago::TimeUnit::Hours);
let d = std::time::Duration::from_secs(60);
assert_eq!(f.convert(d), "1 minute ago");
let d = std::time::Duration::from_secs(3600);
assert_eq!(f.convert(d), "1 hour ago");
let d = std::time::Duration::from_secs(24*3600);
assert_eq!(f.convert(d), "24 hours ago");
let d = std::time::Duration::from_secs(30*24*3600);
assert_eq!(f.convert(d), "720 hours ago");

pub fn min_unit(&mut self, x: TimeUnit) -> &mut Self

Set minimum used unit. Durations below minimally representable by that unit emit too_low value like "now", or like "0 days" instead of normal output. When num_items > 1, it also acts as precision limiter.

let mut f = timeago::Formatter::new();
f.min_unit(timeago::TimeUnit::Minutes);
let d = std::time::Duration::from_secs(30);
assert_eq!(f.convert(d), "now");
let d = std::time::Duration::from_secs(90);
assert_eq!(f.convert(d), "1 minute ago");

let mut f = timeago::Formatter::new();
f.num_items(99);
let d = std::time::Duration::new(1*3600*24 + 2*3600 + 3*60 + 4, 500_000_000);
assert_eq!(f.convert(d), "1 day 2 hours 3 minutes 4 seconds ago");
f.min_unit(timeago::TimeUnit::Hours);
assert_eq!(f.convert(d), "1 day 2 hours ago");
f.min_unit(timeago::TimeUnit::Microseconds);
assert_eq!(f.convert(d), "1 day 2 hours 3 minutes 4 seconds 500 milliseconds ago");
f.min_unit(timeago::TimeUnit::Months);
assert_eq!(f.convert(d), "now");

pub fn too_low(&mut self, x: &'static str) -> &mut Self

Override what is used instead of "now" for too short durations (not representable with the time unit configures as min_unit). Setting this to special value "0" causes emitting output like "0 days", depending on min_unit property. Note that Language's too_low is not used in this case, except of for "0".

let mut f = timeago::Formatter::new();
f.min_unit(timeago::TimeUnit::Months)
 .too_low("this month");
let d = std::time::Duration::from_secs(24*3600);
assert_eq!(f.convert(d), "this month");

let mut f = timeago::Formatter::new();
f.min_unit(timeago::TimeUnit::Minutes);
let d = std::time::Duration::from_secs(30);
assert_eq!(f.convert(d), "now");
f.too_low("-");
assert_eq!(f.convert(d), "-");
f.too_low("");
assert_eq!(f.convert(d), "");
f.too_low("0");
assert_eq!(f.convert(d), "0 minutes ago");

pub fn too_high(&mut self, x: &'static str) -> &mut Self

Override what is used instead of "old" for too high units. Note that Language's too_high is not used in this case.

let mut f = timeago::Formatter::new();
f.max_duration(std::time::Duration::from_secs(3600*24*30));
f.too_high("ancient");
let d = std::time::Duration::from_secs(1000_000_000_000);
assert_eq!(f.convert(d), "ancient");

pub fn max_duration(&mut self, x: Duration) -> &mut Self

Maximum duration before it start giving "old" (or other too_high value)

let mut f = timeago::Formatter::new();
f.max_duration(std::time::Duration::new(3600*24*30, 0));
let d = std::time::Duration::from_secs(1000_000_000);
assert_eq!(f.convert(d), "old");

pub fn ago(&mut self, x: &'static str) -> &mut Self

Override what is used instead of "ago". Empty string literal "" is a bit special in the space handling.

let mut f = timeago::Formatter::new();
let d = std::time::Duration::from_secs(60);
assert_eq!(f.convert(d), "1 minute ago");
f.ago("later");
assert_eq!(f.convert(d), "1 minute later");
f.ago("");
assert_eq!(f.convert(d), "1 minute");

pub fn convert(&self, d: Duration) -> String

Convert specified Duration to a String representing approximation of specified timespan as a string like "5 days ago", with specified by other methods settings. See module-level doc for more info.

let f = timeago::Formatter::new();
let d = std::time::Duration::from_secs(3600*24);
assert_eq!(f.convert(d), "1 day ago");

Trait Implementations