Support approximation words, multiple units, customizable precision

[rocketraman]

Great library. I have a mini-lib that does the same thing, and I would love to migrate to Human-Readable, but my mini-lib seems to have a couple features I need that it appears Human-Readable does not. It supports (optional) approximation words and customizable precision. So for example, a duration from

2024-03-19T19:55:18.994Z to 2024-03-19T19:58:26994Z

could output:

"about 3 minutes"

and a negative duration of the same length would output:

"about 3 minutes ago"

It also supports multiple units in some cases where that makes sense. For example, a duration from 2024-03-20T20:14:13.536Z to 2024-03-21T22:14:14.536Z would output:

"about 1 day, 2 hours"

Here are some of my unit tests in my mini-lib for reference:

class TimeServiceTest : FunSpec({
  test("Outputs a human readable duration") {
    val tests = listOf(
      15.seconds to "less than 30 seconds",
      45.seconds to "45 seconds",
      (1.minutes + 45.seconds) to "about 1 minute",
      (2.minutes + 15.seconds) to "about 2 minutes",
      (1.hours + 4.minutes) to "about 1 hour",
      (1.hours + 5.minutes) to "about 1 hour, 5 minutes",
      (1.hours + 55.minutes) to "about 1 hour, 55 minutes",
      (2.hours + 4.minutes) to "about 2 hours",
      (2.hours + 5.minutes) to "about 2 hours, 5 minutes",
      (2.hours + 55.minutes) to "about 2 hours, 55 minutes",
      (24.hours + 4.minutes) to "about 24 hours",
      (24.hours + 5.minutes) to "about 24 hours",
      (24.hours + 55.minutes) to "about 24 hours",
      (26.hours + 4.minutes) to "about 26 hours",
      (26.hours + 5.minutes) to "about 26 hours",
      (26.hours + 55.minutes) to "about 26 hours",
      2.days to "2 days",
      (2.days + 4.minutes) to "about 2 days",
      (2.days + 5.minutes) to "about 2 days",
      (2.days + 1.hours + 4.minutes) to "about 2 days, 1 hour",
      (2.days + 2.hours + 4.minutes) to "about 2 days, 2 hours",
      (3.days) to "3 days",
      (3.days + 4.minutes) to "about 3 days",
      (3.days + 5.minutes) to "about 3 days",
      (3.days + 1.hours + 4.minutes) to "about 3 days, 1 hour",
      (3.days + 2.hours + 4.minutes) to "about 3 days, 2 hours",
      (4.days) to "4 days",
      (4.days + 4.minutes) to "about 4 days",
      (4.days + 5.minutes) to "about 4 days",
      (4.days + 1.hours + 4.minutes) to "about 4 days, 1 hour",
      (4.days + 2.hours + 4.minutes) to "about 4 days, 2 hours",
    )

    tests.forEach { (input, output) ->
      input.asClue {
        it.humanReadable() shouldBe output
      }
    }

    tests.map { (input, output) ->
      -input to "$output ago"
    }.forEach { (reversedInput, reversedOutput) ->
      reversedInput.asClue {
        it.humanReadable() shouldBe reversedOutput
      }
    }
  }
})

and my implementation looks like this:

object TimeService {
  private const val DEFAULT_MULTI_DAY_HOUR_CUTOFF = 23
  private const val DEFAULT_HOUR_MINUTES_CUTOFF = 30
  private const val DEFAULT_MULTI_HOUR_MINUTES_CUTOFF = 5
  private const val DEFAULT_SECONDS_CUTOFF = 30

  /**
   * For the receiver, returns a human-readable string that describes the difference between the receiver and
   * the given instant i.e. the receiver is relative to the given instant.
   *
   * If the receiver is after the given instant, the string will be of the form "expected <human-readable duration> ago".
   * If the receiver is before the given instant, the string will be of the form "expected in <human-readable duration>".
   */
  fun Instant.humanReadableRelativeTo(instant: Instant): String =
    (instant - this).let { "${if (it.isNegative()) "expected" else "expected in"} ${it.humanReadable()}" }

  /**
   * For the receiver, returns a human-readable string that describes the difference between the receiver and
   * the given instant i.e. the receiver is relative to the given instant.
   *
   * If the receiver is after the given instant, the string will be of the form "expected <human-readable duration> ago".
   * If the receiver is before the given instant, the string will be of the form "expected in <human-readable duration>".
   */
  fun LocalDate.humanReadableRelativeTo(date: LocalDate, zone: TimeZone): String =
    atStartOfDayIn(zone).humanReadableRelativeTo(date.atStartOfDayIn(zone))

  fun LocalDateTime.humanReadableRelativeTo(date: LocalDateTime, zone: TimeZone): String =
    date.toInstant(zone).humanReadableRelativeTo(toInstant(zone))

  @Suppress("ComplexMethod")
  fun Duration.humanReadable(
    approximationWord: String = "about ",
    positiveSuffix: String = "",
    negativeSuffix: String = " ago",
    long: Boolean = true,
    multiDayHourCutoff: Int = DEFAULT_MULTI_DAY_HOUR_CUTOFF,
    hourMinutesCutoff: Int = DEFAULT_HOUR_MINUTES_CUTOFF,
    multiHourMinutesCutoff: Int = DEFAULT_MULTI_HOUR_MINUTES_CUTOFF,
    secondsCutoff: Int = DEFAULT_SECONDS_CUTOFF,
  ): String {
    val ds = if (long) " days" else "d"
    val d = if (long) " day" else "d"
    val hs = if (long) " hours" else "h"
    val h = if (long) " hour" else "h"
    val ms = if (long) " minutes" else "m"
    val m = if (long) " minute" else "m"
    val ss = if (long) " seconds" else "s"
    val lt = if (long) "less than " else "< "

    return toComponents { days, hours, minutes, seconds, _ ->
      when {
        isNegative() ->
          "${absoluteValue.humanReadable(
            approximationWord = approximationWord,
            long = long,
            multiDayHourCutoff = multiDayHourCutoff,
            hourMinutesCutoff = hourMinutesCutoff,
            multiHourMinutesCutoff = multiHourMinutesCutoff,
            secondsCutoff = secondsCutoff
          )}$negativeSuffix"
        days >= 2 && hours > 1 ->
          "${approximationWord}$days$ds, $hours$hs$positiveSuffix"
        days >= 2 && hours == 1 ->
          "${approximationWord}$days$ds, 1$h$positiveSuffix"
        // 48 - 49 hours
        days >= 2 && hours == 0 && minutes == 0 && seconds == 0 ->
          "$days$ds$positiveSuffix"
        days == 1L && hours == 0 && minutes == 0 && seconds == 0 ->
          "$days$d$positiveSuffix"
        days >= 2 ->
          "${approximationWord}$days$ds$positiveSuffix"
        // 48 - 49 hours
        days >= 1 && hours >= multiDayHourCutoff && minutes >= hourMinutesCutoff ->
          "${approximationWord}2$ds$positiveSuffix"
        // 24 to 47.5 hours
        days >= 1 ->
          "${approximationWord}$inWholeHours$hs$positiveSuffix"
        // now get progressively more accurate
        hours > 1 && minutes >= multiHourMinutesCutoff ->
          "${approximationWord}$hours$hs, $minutes$ms$positiveSuffix"
        hours == 1 && minutes >= multiHourMinutesCutoff ->
          "${approximationWord}1$h, $minutes$ms$positiveSuffix"
        hours > 1 ->
          "${approximationWord}$hours$hs$positiveSuffix"
        hours == 1 ->
          "${approximationWord}1$h$positiveSuffix"
        minutes > 1 ->
          "${approximationWord}$minutes$ms$positiveSuffix"
        minutes == 1 ->
          "${approximationWord}1$m$positiveSuffix"
        seconds >= secondsCutoff ->
          "$seconds$ss$positiveSuffix"
        seconds >= 0 ->
          "$lt$secondsCutoff$ss$positiveSuffix"
        else -> this.toString()
      }
    }
  }
}

Note that the precision is also customizable.

[rocketraman]

@jacobras What is your policy on backwards compatibility at this stage of the project? I could potentially spend some time on submitting one or more PRs for this issue, but would need to understand the parameters of the work.

[jacobras]

I try to not introduce breaking changes :) Adding more precise output would be interesting, as long as it's fully localized.

Thanks for the suggestions! I'll take a look at it after #47 is fixed (as that's more important now). A configurable precision has been on my ideas list for a while. Approximity not yet, but it's interesting.

I'll get back to this.

[newhinton]

@jacobras

Especially the precision would be greatly appreciated.

I have tried duplicating the formatDuration function to calculate the remainder of any given string and concatenating them, so that i get a long, but exact string, but that does not work since the weeks are regularly overestimated.

Is this wanted behaviour?

    System.err.println("${(30/ 7f).roundToInt()}, {${(30/ 7f)}}")
    System.err.println("${(29/ 7f).roundToInt()}, {${(29/ 7f)}}")
    System.err.println("${(28/ 7f).roundToInt()}, {${(28/ 7f)}}")
    System.err.println("${(27/ 7f).roundToInt()}, {${(27/ 7f)}}")
    System.err.println("${(25/ 7f).roundToInt()}, {${(25/ 7f)}}")
    System.err.println("${(21/ 7f).roundToInt()}, {${(21/ 7f)}}")
    System.err.println("${(14/ 7f).roundToInt()}, {${(14/ 7f)}}")

yields

4, {4.285714}
4, {4.142857}
4, {4.0}
4, {3.857143}
4, {3.5714285}
3, {3.0}
2, {2.0}

which is expected for kotlin's roundToInt-function you are using in said method.

This is also true for the "months" calculation.

Wouldn't it be better to err on the side of caution and round down the value so that the value is always smaller than the true one?
floor

[rocketraman]

Thanks for the suggestions! I'll take a look at it after #47 is fixed (as that's more important now). A configurable precision has been on my ideas list for a while. Approximity not yet, but it's interesting.

I'll get back to this.

Since #47 is now complete, I thought I'd bump this back up @jacobras . Thanks!

[jacobras]

Wouldn't it be better to err on the side of caution and round down the value so that the value is always smaller than the true one? floor

Or make it configurable. For example, a precision float could indicate how to round. I see that this .NET library offers that as well: https://github.com/Humanizr/Humanizer?tab=readme-ov-file#humanize-datetime

So precision = 0.75 means 3.57 weeks would still be "3 weeks" but 3.85 weeks would be "4 weeks". And for the behaviour like flooring it, you could use precision = 1.0. Current precision could be interpreted as 0.5, since it's default rounding. But @rocketraman's example goes further than that, offering configurable precision (in form of cutoff) per second/hour/day.

Looking at how GitHub does it for commit dates, they seem to also round:

This is now 2 years, 5 months ago and shows as "2 years ago" » rounded down

This is now 3 years, 11 months ago, 21 days and shows as "4 years ago" » rounded up

This is 4 years, 9 months ago and shows as "4 years ago" » rounded down

This is now 2 years, 7 months ago (almost 8) and shows as "2 years ago" » rounded down

Maybe this could be interpreted as precision = 0.95 (resulting in 11 months and ~12 days cutoff for a year)

But they also have the cool feature where anything in November 1-30 shows as "last month" and anything in 2024 shows as "last year" 🧐. And "yesterday", "last week". But their "2 days ago" seems to be on the day, ignoring time. Also quite interesting to consider. And challenging, seeing how starting day of week varies per culture.

---

But, getting back to the original question in this issue, there are multiple requests:

• approximation word ("about 3 minutes ago")
• sub-parts ("1 day, 2 hours")
• precision (with second/hour/day cutoff in the example code, but alternatively a precision float)

Right now, I'd prefer the precision approach, since it's simpler to configure for end users. Want rounding? Set it to 0.5. No rounding at all? 1.0. Less abrupt rounding? 0.75. Default value to be considered. Interested in opinions on this.

Maybe the approximation word should kick in based on the precision? But I'm not sure when it feels natural to kick in.

Sub-parts could be configured based on a boolean parameter:

• subParts= true could return "6 years, 9 months"
• subParts= true could return "5 months, 1 week"
• subParts= true could return "3 weeks, 2 days"
• subParts = false would return "3 weeks" like it does now

[rocketraman]

Right now, I'd prefer the precision approach, since it's simpler to configure for end users. Want rounding? Set it to 0.5. No rounding at all? 1.0. Less abrupt rounding? 0.75. Default value to be considered. Interested in opinions on this.

I much prefer cutoffs for defining the preciseness of the output. Cutoffs make it clear what the output will be. My output is human readable. It is therefore natural to say: ignore less than a 5 minute difference on the hour, otherwise include it. It is less natural to say: make my precision 0.083 -- I have no idea what 0.083 means in terms of my human readable output unless I get my calculator out.

In addition, these values will not likely be the same across different units. I may be happy ignoring a 5 minute difference on an hour (precision = 0.083), but not happy with ignoring a 2 hour difference on 24 hours (the same float precision).

In addition, floats will give weird results at the boundaries. A precision of 0.083 will include a duration of 4.98 minutes but exclude a duration of 4.99 minutes. If I want my output to be human readable, why would I set the cutoff at 4.98-something rather than exactly 5?

On the other hand, the advantage of a precision float is, it can give us different results depending on the entire duration. So on a duration of 5 years the weeks don't matter much since there are 260 of them. But on a duration of 1 year, the weeks probably do matter as there are only 52 of them. A precision of .25 on 5 years would be 65 weeks and on 1 years would be 13 weeks, accurately conveying the importance of something like 16 weeks to the overall duration (not important to the former, but important to the latter).

So at the risk of complicating things too much, perhaps both approaches together would work well? The precision would let us round to the correct duration, and then cutoffs would help us make it human readable.

Maybe the approximation word should kick in based on the precision? But I'm not sure when it feels natural to kick in.

Why complicate it? Just use approximation words (if defined) if the output is approximate, and otherwise not. While I think that is pretty natural, we could make it more configurable of course, with reasonable defaults. If this was configurable, I think the same logic as above applies.

Sub-parts could be configured based on a boolean parameter:

To play devil's advocate: if we have configurable precision, why would we want to turn off sub-parts? Wouldn't the precision be sufficient to inform whether a sub-part is shown or not?