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

It emits one chunk, limits to seconds and has no maximum duration.

impl<L: Language> Formatter<L>

pub fn with_language(l: L) -> Self

Constructor for some default formatting with specified language instance

It emits one item (chunk), limits to seconds and has no maximum duration.

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_chrono<Tz1, Tz2>(
    &self,
    from: DateTime<Tz1>,
    to: DateTime<Tz2>
) -> String where
    Tz1: TimeZone,
    Tz2: TimeZone, 

Format the timespan between from and to as a string like "15 days ago".

Requires chrono Cargo feature.

from should come before to, otherwise "???" will be returned.

Currently it doesn't actually take the calendar into account and just converts datetimes into a plain old std::time::Duration, but in future here may be a proper implementation.

extern crate chrono;
extern crate timeago;
let mut f = timeago::Formatter::new();
f.num_items(2);
let from = chrono::DateTime::parse_from_rfc3339("2013-12-19T15:00:00+03:00").unwrap();
let to   = chrono::DateTime::parse_from_rfc3339("2013-12-23T17:00:00+03:00").unwrap();
assert_eq!(f.convert_chrono(from, to), "4 days 2 hours ago");

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

impl Default for Formatter

fn default() -> Self

Returns the "default value" for a type.