Hi all. The ISO 8601 standard allows referring to

24:00

as midnight corresponding to the instant occuring at the end of a calendar day. Is there any way we could support doing such a thing in kotlinx-datetime? Currently, it's impossible to model an open end range of data that spans from midnight to midnight with local times, for example, because of this.

LocalTime(hour = 0, minute = 0) ..< LocalTime(hour = 24, minute = 0) // invalid
LocalTime(hour = 0, minute = 0) ..< LocalTime(hour = 0, minute = 0) // empty range 
LocalTime(hour = 0, minute = 0) ..< LocalTime(hour = 23, minute = 59, second = 59, nanosecond = 999999) // technically incorrect

I'm happy to open a github issue if the discussion should continue there.

Technically, that's no longer valid since support for "24:00" was removed in ISO 8601:2019. And looking at local time in that way could be a bad idea in the face of daylight savings.

I suspect the language semantics should be such that: 1.

LocalTime(hour = 0, minute = 0) < LocalTime(hour = 24, minute = 0) == true

2.

LocalDate(year = 2023, monthNumber = 1, dayOfMonth = 1).atTime(LocalTime(hour = 24, minute = 0)) == LocalDateTime(year = 2023, monthNumber = 1, dayOfMonth = 2, hour = 0, minute = 0)

3.

LocalDateTime.time

should always return

00:00

and not

24:00

I feel like I’m definitely missing something, though, as surely the change can’t be this easy. If it is this easy I’m happy to make a PR!

ISO needs to make their money somehow!

You’d think since it’s an industry standard it’d have a foundation!

LocalTime(hour = 0, minute = 0) ..< LocalTime(hour = 23, minute = 59, second = 59, nanosecond = 999_999_999)

Would be a bit cumbersome but not technically incorrect. At least on the JVM,

999_999_999

is the maximum value for

NANO_OF_SECOND

.

LocalTime(hour = 0, minute = 0) ..< LocalTime(hour = 23, minute = 59, second = 59, nanosecond = 999_999_999)

Is not correct because this is an open end range. If we were to represent it as a closed range it would look like this

LocalTime(hour = 0, minute = 0) .. LocalTime(hour = 23, minute = 59, second = 59, nanosecond = 999_999_998)

Good point. I don't see any reason not to use the closed range though. Presumably you want to be able to do contains operators on any time interval, which could be the entire day, so representing it as a closed range is fine. The open range would make sense only for

24:00

. Agreed on ISO, but implementing an

LocalTime.EOD

constant would be useful if there are complexities getting this technically correct for multiple platforms. And knowing dates/times, there almost certainly are.

The open end range happens to be convenient for every other scenario other than ones ending at midnight. But yes I suspect that will be the best method to do so

Maybe the code you're writing could be restructured in a more straightforward manner that also wouldn't rely on

hour = 24

? Working directly with

LocalTime

is itself suspicious, actually: what do you want to happen if, due to a DST transition, 00:30 directly followed 23:30 of the previous day?

@Dmitry Khalanskiy [JB] I'm not the OP, but speaking for myself... If I want to check if an event happened in local time between a certain range of local times, why would I care about DST? It would be impossible for the event to happen between 23:30 and 00:30 local, because those times never existed in local time.

@Dmitry Khalanskiy [JB] The use case is tough. This is representing recurring events in two categories — weekends and weekdays. We generally don’t care about specific dates here, only that there’s a difference between a weekday and a weekend day. A separate use case for us is modeled with

OpenEndRange<Instant>

and that works wonderfully.

@kevin.cianfarini And presumably the recurring event is defined in local time, which translates to whatever Instant is applicable for the relevant zone and date of ocurrence?

Kind of. This is for electricity pricing that tracks something called time of use rates. Certain time of use rates track the wholesale electricity market and thus those rates are date specific. That’s the easy use case represented by

OpenEndRange<Instant>

. Things get more complicated when you have “lower tech” time of use rates that recur each day, on weekdays and weekend, or maybe even something like every wednesday. Generally since electricity prices are highly localized we only ever want to represent this in local time because it’s not local to a customers device — it’s local to where the electricity is being distributed and consumed (a building). We can represent most of our pricing with

OpenEndRange<Instant>

but there are some old fashioned electricity meters that don’t connect to the internet in any fashion and thus use mechanical registers with hard coded local times.

And you don't know the time zone those meters exist in?

We do. But since they’re recurring it’s probably not great to expand those recurrences out into date specific ones, I think?

An interesting use case, thanks! I would assume that these rates can never overlap, and there can't be gaps between them. Is this correct?

If I want to check if an event happened in local time between a certain range of local times, why would I care about DST?

Ok, here's another example of why you would care. If clocks jumped from 19:00 back to 18:00 and you check if a local time is in the range 1100 1830, then, in the span of three hours between 17:30 and 19:30, you get "yes, no, yes, no." There aren't many cases when this logic makes sense.

Yup! Rates can't overlap.

Then the whole idea of using ranges seems suboptimal: you'd have a list of ranges like

[00:00; 04:00), [04:00; 09:30); [09:30; 13:30); [13:30, 18:00); [18:00; 24:00)

. But almost half of this information is useless. Why not look at the rates for the whole day instead?

class RatesForTheDay {
  // the rate from midnight until the first change
  val initialRate: UnitRate
  // the list of changes to the rates throughout the day: the time the new rate starts and the new rate; sorted by the time
  transitions: List<Pair<LocalTime, UnitRate>>
}

This way, you wouldn't have the issues with ensuring the ranges cover the whole day and don't overlap; this works out of the box. You also won't need the notion of midnight.

Let me think on that for a bit.

You could potentially make the data structure easier to use for callers by removing the special case for the

initialRate

, and adding an invariant to check the structure always starts at midnight:

class RatesForTheDay {
  val transitions: List<Pair<LocalTime, UnitRate>>
  init {
    require(transitions.firstOrNull()?.first == LocalTime(0, 0) { "Daily rates must start at midnight" }
  }
}

One of the requirements we have is that rates must not always start at midnight. These timings are a real example of that: • Day Rate:

[05:30, 23:30)

• Night rate:

[23:30, 05:30)

<-- technically invalid range

You could translate that to: 00:00 - 05:30 : night 05:30 - 23:30 : day 23:30 - : night But yeah, now the ranges are one step removed from how the business will define them.

Yup.

So you just remove the invariant then. Same structure works I think.

In any case, even if the invariant held, it's not an obvious improvement. Before deciding how to simplify the life of callers, one would first need to have these callers and look at them. Compare:

fun findRate(time: LocalTime): UnitRate {
  var result = initialRate
  for ((rate, transitionTime) in transitions) {
    if (time >= transitionTime) result = rate
  }
  return result
}

and

fun findRate(time: LocalTime): UnitRate {
  var result: UnitRate? = null
  for ((rate, transitionTime) in transitions) {
    if (time >= transitionTime) result = rate
  }
  return result!! // we know `transitions` is non-empty and starts with 00:00
}

I think the first option is clearer. Don't you?

Indeed

Hey, also, without the invariant, it seems like the first option works as is, with no changes! Nice.

Does it?

initialRate

assumes a start time of midnight, which -- if the rates are defined the way the business will define them -- isn't always true. It seems like the first rate needs a start time too.

initialRate

is the rate at midnight on that day, by definition. In

transitions

, you'd have

05:30

and

23:30

, no explicit

00:00

. In this framework, the

initialRate

is just what the day before this one ended with.

Yeah I'm aware but the point is this data structure is one step removed from how the business will define the rates, which is like this: https://kotlinlang.slack.com/archives/C01923PC6A0/p1696600031664689?thread_ts=1696370008.366449&cid=C01923PC6A0. That's not necessarily a bad thing -- the business definition could be stored in one way, and then translated into the runtime structure used for logic. But the extra translation is something to think about.

I apologize for rising from the ashes, but I think there’s a little more elegant solution with only one modification. You may treat the list of transitions like glued and continuous circular ring. As a result: • you don’t need to explicitly set initial rate, • or to require midnight at the first transition, • and you get the structure at the same form as the business defines it. Like that:

data class RatesForTheDay(
    val transitions: List<Pair<LocalTime, Int>>
) {
    init {
        require(transitions.isNotEmpty())
    }

    fun findRate(time: LocalTime): Int {
        val lastTransition = transitions.last()
        if (transitions.size == 1)
            return lastTransition.second
        for ((transitionTime, rate) in transitions.asReversed()) {
            if (transitionTime <= time)
                return rate
        }
        return lastTransition.second
    }

    // or one-line implementation
    fun findRate2(time: LocalTime): Int =
        (transitions.lastOrNull { it.first <= time } ?: transitions.last()).second
}

Examples:

fun main() {
    val a = RatesForTheDay(
        listOf(
            LocalTime(5, 30) to 100,
            LocalTime(23, 30) to 200,
        )
    )

    val b = RatesForTheDay(
        listOf(
            LocalTime(5, 30) to 100, // set any transition time in case of single rate
        )
    )

    println("a[5,30] : " + a.findRate(LocalTime(5, 30))) // 100
    println("a[20,30]: " + a.findRate(LocalTime(20, 30))) // 100
    println("a[23,30]: " + a.findRate(LocalTime(23, 30))) // 200
    println("a[23,59]: " + a.findRate(LocalTime(23, 59, 59, 999_999_999))) // 200
    println("a[0,0]  : " + a.findRate(LocalTime(0, 0))) // 200 (from the last)

    println()
    println("b[5,30] : " + b.findRate(LocalTime(5, 30))) // 100
    println("b[20,30]: " + b.findRate(LocalTime(20, 30))) // 100
    println("b[23,30]: " + b.findRate(LocalTime(23, 30))) // 100
    println("b[23,59]: " + b.findRate(LocalTime(23, 59, 59, 999_999_999))) // 100
    println("b[0,0]  : " + b.findRate(LocalTime(0, 0))) // 100
}