Is Duration#toDays and Duration#toDaysPart redundant?

Question

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?

Answer 1

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.

Answer 2

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.