humfmt 0.5.1

Ergonomic human-readable formatting toolkit for Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

//! Relative-time formatting.
//!
//! This module builds on [`crate::duration`] and shares the same locale-aware
//! configuration surface through [`crate::DurationOptions`].
//!
//! # Quick start
//!
//! ```rust
//! use core::time::Duration;
//! use humfmt::{ago, ago_with, DurationOptions};
//!
//! assert_eq!(ago(Duration::from_secs(90)).to_string(), "1m 30s ago");
//! assert_eq!(ago(Duration::from_secs(3661)).to_string(), "1h 1m ago");
//! ```
//!
//! # Locale
//!
//! The "ago" word comes from the active locale:
//! - English: `"ago"`
//! - Russian: `"назад"`
//! - Polish: `"temu"`
//!
//! # Limitations
//!
//! **Past only:** Currently `ago` only formats past durations (time that has
//! already elapsed). Future-time support (`"in 5 minutes"`) is planned.
//!
//! **No "just now" case:** Very small durations (e.g. under 5 seconds) render
//! as `"0s ago"` rather than a special "just now" phrase. A configurable
//! threshold for this case is planned.

mod display;

pub use display::AgoDisplay;

use crate::duration::{DurationLike, DurationOptions};
use crate::locale::{English, Locale};

/// Creates a human-readable relative-time formatter using default options.
///
/// # Examples
///
/// ```rust
/// let elapsed = core::time::Duration::from_secs(3661);
/// assert_eq!(humfmt::ago(elapsed).to_string(), "1h 1m ago");
/// ```
pub fn ago<T: DurationLike>(value: T) -> AgoDisplay<English> {
    AgoDisplay::new(value, DurationOptions::new())
}

/// Creates a human-readable relative-time formatter with custom duration options.
///
/// # Examples
///
/// ```rust
/// use humfmt::DurationOptions;
///
/// let elapsed = core::time::Duration::from_millis(1500);
/// let out = humfmt::ago_with(elapsed, DurationOptions::new().long_units());
/// assert_eq!(out.to_string(), "1 second 500 milliseconds ago");
/// ```
pub fn ago_with<T: DurationLike, L: Locale>(
    value: T,
    options: DurationOptions<L>,
) -> AgoDisplay<L> {
    AgoDisplay::new(value, options)
}