Is Duration#toDays and Duration#toDaysPart redundant?

Viewed 697

In Java 8, the Duration class offered the toDays method, returning a total number of days as a count of 24-hour chunks of time unrelated to calendar days.

In Java 9, the Duration class gained handy to…Part methods: toDaysPart, toHoursPart, toMinutesPart, toSecondsPart, toMillisPart, toNanosPart. I understand the need for the hours, minutes, etc. But I wonder about toDaysPart.

My question is:

➥ Will Duration#toDays and Duration#toDaysPart ever return different values for a particular Duration object?

3 Answers

In Java 11, these lines of source code in OpenJDK are exactly the same.

Duration#toDays:

public long toDays() {
    return seconds / SECONDS_PER_DAY;
}

Duration#toDaysPart

public long toDaysPart(){
    return seconds / SECONDS_PER_DAY;
}

As of Java 16, no indication is made as to which is deprecated or which is not. So...keep your eyes peeled for it, is the best advice I could give you here.

These methods don't just do the same thing; they are specified as doing the same thing in the documentation (linked in your question):

public long toDays()

Gets the number of days in this duration. This returns the total number of days in the duration by dividing the number of seconds by 86400. This is based on the standard definition of a day as 24 hours. This instance is immutable and unaffected by this method call.

Returns: the number of days in the duration, may be negative

public long toDaysPart()

Extracts the number of days in the duration. This returns the total number of days in the duration by dividing the number of seconds by 86400. This is based on the standard definition of a day as 24 hours. This instance is immutable and unaffected by this method call.

Returns: the number of days in the duration, may be negative

The only difference is the word "gets" vs. "extracts" in the descriptive summary. These words don't have different meanings in this context, and the rest is word-for-word identical, in particular the parts specifying what the methods return are identical. In fact, the (OpenJDK) documentation for toDaysPart was recently changed to clarify that these methods do the same thing. So yes, they are redundant.

According to the relevant issue on the issue tracker, all of the to...Part methods were added together and there wasn't any comment on the fact that toDaysPart would be redundant; so we can only speculate about the rationale for adding the redundant method.

The purpose of get(TemporalUnit) inherited from TemporalAmount, (and getSeconds() and the curiously named getNano()), are to support the extraction of the temporal components of a composed value. Duration actually only supports SECONDS and NANOS component access because a Duration is the composition of just a long seconds component with an int nanoseconds component, which together provide nanosecond resolution and representation of directed values of up to 2^63 seconds in magnitude (both positive and negative). The get_ accessors return just the named components, while the to_ methods return the composite whole value floored to the target unit. Finally the to_Part methods on Duration emulate the behaviour of the get_ methods if Duration were imagined to be composed of one instance of each ChronoUnit value. The odd one out in this virtual component access is toDaysPart. I suspect the reason for this is that while HOURS, MINUTES, SECONDS, MILLIS, MICROS and NANOS could be considered discrete and non-overlapping in terms of the components they reference, when considering DAYS as a component value it is not clear if we mean day of the week, day of the month or day of the year - all three are common conventions. Similarly MONTHS and YEARS each have variable length. So it appears the author chose to be unambiguous and consider DAYS to represent the coarsest component in that hierarchy. Personally I think its all a bit of a dog's breakfast and wondered why those two methods were identical for a while myself before reaching this conclusion.

Related