@@ -1,10 +1,18 @@
use chrono::NaiveDateTime;
+/// Calculates the distance in seconds between two NaiveDateTime objects.
+/// It returns a signed integer denoting the difference. If `date` is earlier than `base_date`, the returned value will be negative.
+///
+/// ## Arguments
+///
+/// * `date` - A NaiveDateTime object representing the date of interest
+/// * `base_date` - A NaiveDateTime object representing the base date against which the comparison is made
fn distance_in_seconds(date: NaiveDateTime, base_date: NaiveDateTime) -> i64 {
let duration = date.signed_duration_since(base_date);
-duration.num_seconds()
}
+/// Generates a string describing the time distance between two dates in a human-readable way.
fn distance_string(distance: i64, include_seconds: bool, add_suffix: bool) -> String {
let suffix = if distance < 0 { " from now" } else { " ago" };
@@ -74,6 +82,33 @@ fn distance_string(distance: i64, include_seconds: bool, add_suffix: bool) -> St
}
}
+/// Get the time difference between two dates into a relative human readable string.
+///
+/// For example, "less than a minute ago", "about 2 hours ago", "3 months from now", etc.
+///
+/// Use [naive_format_distance_from_now] to compare a NaiveDateTime against now.
+///
+/// # Arguments
+///
+/// * `date` - The NaiveDateTime to compare.
+/// * `base_date` - The NaiveDateTime to compare against.
+/// * `include_seconds` - A boolean. If true, distances less than a minute are more detailed
+/// * `add_suffix` - A boolean. If true, result indicates if the time is in the past or future
+///
+/// # Example
+///
+/// ```rust
+/// use chrono::DateTime;
+/// use ui2::utils::naive_format_distance;
+///
+/// fn time_between_moon_landings() -> String {
+/// let date = DateTime::parse_from_rfc3339("1969-07-20T00:00:00Z").unwrap().naive_local();
+/// let base_date = DateTime::parse_from_rfc3339("1972-12-14T00:00:00Z").unwrap().naive_local();
+/// format!("There was {} between the first and last crewed moon landings.", naive_format_distance(date, base_date, false, false))
+/// }
+/// ```
+///
+/// Output: `"There was about 3 years between the first and last crewed moon landings."`
pub fn naive_format_distance(
date: NaiveDateTime,
base_date: NaiveDateTime,
@@ -85,6 +120,29 @@ pub fn naive_format_distance(
distance_string(distance, include_seconds, add_suffix)
}
+/// Get the time difference between a date and now as relative human readable string.
+///
+/// For example, "less than a minute ago", "about 2 hours ago", "3 months from now", etc.
+///
+/// # Arguments
+///
+/// * `datetime` - The NaiveDateTime to compare with the current time.
+/// * `include_seconds` - A boolean. If true, distances less than a minute are more detailed
+/// * `add_suffix` - A boolean. If true, result indicates if the time is in the past or future
+///
+/// # Example
+///
+/// ```rust
+/// use chrono::DateTime;
+/// use ui2::utils::naive_format_distance_from_now;
+///
+/// fn time_since_first_moon_landing() -> String {
+/// let date = DateTime::parse_from_rfc3339("1969-07-20T00:00:00Z").unwrap().naive_local();
+/// format!("It's been {} since Apollo 11 first landed on the moon.", naive_format_distance_from_now(date, false, false))
+/// }
+/// ```
+///
+/// Output: `It's been over 54 years since Apollo 11 first landed on the moon.`
pub fn naive_format_distance_from_now(
datetime: NaiveDateTime,
include_seconds: bool,