Merge branch 'pr/425_human_format'

book/src/conversion-functions.md

@@ -12,7 +12,7 @@ now() -> unixtime
 # Convert a date and time to a different timezone
 now() -> tz("Asia/Kathmandu")
 
-# Convert a duration to days, hours, minutes, seconds
+# Convert a duration to years, months, days, hours, minutes, seconds
 10 million seconds -> human
 
 # Convert an angle to degrees, minutes, seconds (48° 46′ 32″)

book/src/date-and-time.md

@@ -30,7 +30,7 @@ now() -> unixtime
 # What is the date corresponding to a given UNIX timestamp?
 from_unixtime(1707568901)
 
-# How long are one million seconds in days, hours, minutes, seconds?
+# How long are one million seconds in years, months, days, hours, minutes, seconds
 1 million seconds -> human
 ```
 

examples/tests/human.nbt

@@ -20,19 +20,27 @@ assert_eq((1 day            -> human), "1 day")
 assert_eq((1.37 day         -> human), "1 day + 8 hours + 52 minutes + 48 seconds")
 
 assert_eq((1 week           -> human), "7 days")
-assert_eq((1.5 weeks        -> human), "10 days + 12 hours")
 assert_eq((2 weeks          -> human), "14 days")
+assert_eq((2.5 weeks        -> human), "17 days + 12 hours")
 
-assert_eq((1 sidereal_day   -> human), "23 hours + 56 minutes + 4.0905 seconds")
+assert_eq((2 month          -> human), "60.8737 days (approx. 2 months)")
+assert_eq((2 month + 12 day -> human), "72.8737 days (approx. 2.4 months)")
+assert_eq((3 yr + 2 month   -> human), "1156.6 days (approx. 3 years + 2 months)")
+assert_eq((10 yr + 2 s      -> human), "3652.42 days (approx. 10 years)")
 
-assert_eq((10000 days       -> human), "10000 days")
-assert_eq((50 million days  -> human), "50_000_000 days")
+assert_eq((1 sidereal_day   -> human), "23 hours + 56 minutes + 4.091 seconds")
 
-assert_eq((1e12 days        -> human), "1_000_000_000_000 days")
-assert_eq((1e15 days        -> human), "1.0e+15 days")
+assert_eq((10000 days       -> human), "10000 days (approx. 27 years + 4 months)")
+assert_eq((50 million days  -> human), "50_000_000 days (approx. 136_895 years)")
+
+assert_eq((1e12 days        -> human), "1_000_000_000_000 days (approx. 2_737_909_345 years)")
+assert_eq((1e15 days        -> human), "1.0e+15 days (approx. 2_737_909_345_034 years)")
 
 assert_eq((1 ms             -> human), "0.001 seconds")
 assert_eq((1 µs             -> human), "0.000001 seconds")
-assert_eq((1 ns             -> human), "0.000000001 seconds")
+assert_eq((1 ns             -> human), "1.0e-9 seconds")
 assert_eq((1234 ns          -> human), "0.000001234 seconds")
-assert_eq((1s + 1234 ns     -> human), "1.000001234 seconds")
+assert_eq((1s + 1234 ns     -> human), "1 second")
+
+assert_eq((-1 second        -> human), "1 second ago")
+assert_eq((-7.89 hour       -> human), "7 hours + 53 minutes + 24 seconds ago")

numbat/modules/datetime/human.nbt

@@ -1,39 +1,66 @@
 use core::functions
 use core::strings
 use units::si
+use units::time
 use datetime::functions
 
-fn _human_num_days(time: Time) -> Scalar = floor(time / days)
-
 fn _human_join(a: String, b: String) -> String =
-  if str_slice(a, 0, 2) == "0 " then b else if str_slice(b, 0, 2) == "0 " then a else "{a} + {b}"
+  if a == "" then b else if b == "" then a else "{a} + {b}"
+
+fn _prettier(str: String) -> String =
+  if str_slice(str, 0, 2) == "0 " then ""
+  else if str_slice(str, 0, 2) == "1 " then str_slice(str, 0, str_length(str) - 1)
+  else str
+
+fn _remove_trailing_zero(str: String) -> String =
+  str_replace(str, ".0 ", " ")
+
+fn _human_years(time: Time)   -> String = "{(time -> years)   /  year   |> floor} years"   -> _prettier
+fn _human_months(time: Time)  -> String = "{(time -> months)  /  month  |> floor} months"  -> _prettier
+fn _human_days(time: Time)    -> String = "{(time -> days)    /  day    |> floor} days"    -> _prettier
+fn _human_hours(time: Time)   -> String = "{(time -> hours)   /  hour   |> floor} hours"   -> _prettier
+fn _human_minutes(time: Time) -> String = "{(time -> minutes) /  minute |> floor} minutes" -> _prettier
+# fn _human_years(time: Time)   -> String = "{time |> floor_in(year)} years"   -> _prettier
+# fn _human_months(time: Time)  -> String = "{time |> floor_in(month)} months"  -> _prettier
+# fn _human_days(time: Time)    -> String = "{time |> floor_in(day)} days"    -> _prettier
+# fn _human_hours(time: Time)   -> String = "{time |> floor_in(hour)} hours"   -> _prettier
+# fn _human_minutes(time: Time) -> String = "{time |> floor_in(minute)} minutes" -> _prettier
 
-fn _remove_plural_suffix(str: String) -> String =
-  if str_slice(str, 0, 2) == "1 " then str_slice(str, 0, str_length(str) - 1) else str
+fn _precise_human_months(time: Time)  -> String = "{(time -> months)  /  month } months"  -> _remove_trailing_zero -> _prettier
+fn _precise_human_days(time: Time)    -> String = "{(time -> days)    /  day   } days"    -> _remove_trailing_zero -> _prettier
+fn _precise_human_seconds(time: Time) -> String = "{(time -> seconds) /  second} seconds" -> _remove_trailing_zero -> _prettier
 
-fn _human_seconds(dt: DateTime) -> String =
-  _remove_plural_suffix(format_datetime("%-S%.f seconds", dt))
+fn _human_recurse(t: Time, result: String, time_unit: String) -> String =
+  if time_unit == "day"
+    then _human_recurse(t - (t |> floor_in(day)), _human_join(result, t -> _human_days),    "hour")
+  else if time_unit == "hour"
+    then _human_recurse(t - (t |> floor_in(hour)), _human_join(result, t -> _human_hours),   "minute")
+  else if time_unit == "minute"
+    then _human_recurse(t - (t |> floor_in(min)), _human_join(result, t -> _human_minutes), "second")
+  else _human_join(result, (t |> round_in(ms)) -> _precise_human_seconds)
 
-fn _human_minutes(dt: DateTime) -> String =
-  _remove_plural_suffix(format_datetime("%-M minutes", dt))
+fn _human_approx_recurse(t: Time, result: String, time_unit: String) -> String =
+  if time_unit == "year"
+    then _human_approx_recurse(t - (t |> floor_in(year)) |> round_in(ms), _human_join(result, t -> _human_years),   "month")
+  else _human_join(result, t -> _human_months)
 
-fn _human_hours(dt: DateTime) -> String =
-  _remove_plural_suffix(format_datetime("%-H hours", dt))
+fn _human_manage_past(str: String, time: Time) = str_append(str, if time < 0 s then " ago" else "")
 
-fn _human_days(num_days: Scalar) -> String =
-  _remove_plural_suffix("{num_days} days")
+fn _human_for_long_duration(human_days: String, human_years: String) -> String =
+  "{human_days} (approx. {human_years})"
 
-fn _human_readable_duration(time: Time, dt: DateTime, num_days: Scalar) -> String =
-    _human_join(_human_join(_human_join(_human_days(_human_num_days(time)), _human_hours(dt)), _human_minutes(dt)), _human_seconds(dt))
+fn _abs_human(time: Time) -> String =
+  if time == 0 s then "0 seconds"
+  else if time < 60 seconds then time -> _precise_human_seconds
+  else if time < 2 months then _human_recurse(time, "",  "day")
+  else if time < 1 year
+    then _human_for_long_duration(time -> _precise_human_days, (time |> round_in(month/10)) -> _precise_human_months)
+  else if time < 100 years
+    then _human_for_long_duration(time -> _precise_human_days, _human_approx_recurse(time, "", "year"))
+  else
+    _human_for_long_duration(time -> _precise_human_days, time -> _human_years)
 
-# Implementation details:
-# we skip hours/minutes/seconds for durations larger than 1000 days because:
-#   (a) we run into floating point precision problems at the nanosecond level at this point
-#   (b) for much larger numbers, we can't convert to DateTimes anymore
 @name("Human-readable time duration")
 @url("https://numbat.dev/doc/date-and-time.html")
 @description("Converts a time duration to a human-readable string in days, hours, minutes and seconds.")
-fn human(time: Time) =
-  if _human_num_days(time) > 1000
-    then "{_human_num_days(time)} days" 
-    else _human_readable_duration(time, datetime("0001-01-01T00:00:00Z") + time, _human_num_days(time))
+fn human(time: Time) -> String = _human_manage_past(abs(time) -> _abs_human, time)