Plurals vs singulars in ordinals

[dkhalanskyjb]

This issue is for gathering inputs from people with an intuitive understanding of English to help us name things.

Preliminaries: we have Instant.epochSeconds, which returns the number of seconds that passed since the Unix epoch. On the epoch itself and after some number of nanoseconds that don't amount to a whole second, Instant.epochSeconds returns 0.

Other libraries, like java.time, provide the same functionality, but with a slightly different name: Instant.epochSecond (note it being singular). We assume that the idea behind this is "the nth second since the epoch".

However, colloquially, the nth second/etc. is the second/etc. that goes on before n whole seconds/etc. have passed. For example, January is the first month of the year, that is, the month that goes on before a whole month has passed.

Questions for the readers:

• If you see Instant.epochSecond == 1, what do you think it means—does it mean that it is the first second since the start of the epoch, or that 1 full second has passed since then?
• The same, but about Instant.epochSeconds. Does this naming seem natural, or slightly odd?
• The same about LocalTime.secondOfDay and LocalTime.secondsOfDay: do they mean the same thing to you, or do you feel the first one is an ordinal, but the second one is the count?

[PeterAttardo]

I think the following generally holds:

• If it is a singular, there is an implied nth {unit} of {time period}. So instant.epochSecond = 5 would naturally translate to 5th second of epoch where epoch is the time period between the start of the Unix epoch and infinity.
• If it is a plural, there is an implied n {units} since {point in time} or n {units} since start of {time period}. So instant.epochSeconds = 5 would naturally translate to 5 seconds since epoch where epoch is the exact point in time that the Unix epoch started.

(Interesting sidenote is that this illustrates the Unix Epoch's ability to refer to either a period or a discrete moment in time, depending on context.)

For this reason LocalTime.secondOfDay works, because it is harmonious with these rules, but LocalTime.secondsOfDay feels off, because the implication of the plural clashes with the explicit use of of in the name.

Ultimately this implies that the singular returns the range between two points in time [In this particular case it would be implied that the range returned is the second (starting and ending at integer seconds since the epoch) in which the Instant is contained], whereas the plural returns a single point in time. There then follows a "collapsing" of sorts from a range to a scalar value in the case of the former. I think ultimately this is a matter of convention. The first month of the year is represented as a 1, as is the first day of the week. But the first hour of a day is represented as 0 (or 00) as is the first minute of an hour, or second of a minute. For the purposes here, I think epochSeconds and secondOfEpoch should always be equal.

[cpovirk]

I recall giving some thought to this in designing some of our own time-related APIs. I don't recall all the details, but I like the look of the post above, which reminds me of this comment from Stephen Colebourne and this other comment from Stephen Colebourne.

My take, which I think may be compatible with the previous post, but I am confusing myself as I dig through old links... :)

• Instant.epochSecond == 1: a full second has passed
• Instant.epochSeconds == 1: probably still that, but I think I'd prefer the singular, and I might expect the plural to return a floating-point number
• LocalTime: same answers, and I'd prefer singular even more, since theoretically someone could expect "secondsOfDay" to return the total number of seconds in that day (which isn't something that a LocalTime or even a LocalDateTime could answer, of course, but someone might expect it to)

My understanding is that the java.time people consistently used the singular for the fields of LocalTime-like objects and erred only in accidentally also using it for the one of the fields of Duration, which should have used plural. And I think that's a good way to go.

[edit: one other link]

[dkhalanskyjb]

Thank you both!

I've read everything you wrote, and I think it can be boiled down to this point:

The first month of the year is represented as a 1, as is the first day of the week. But the first hour of a day is represented as 0 (or 00) as is the first minute of an hour, or second of a minute.

We already have LocalTime.hour, and this represents an hour-of-day (what else?). We don't call it LocalTime.hours, even though this is the number of hours passed since midnight (modulo time zone transitions). Instead, "the hour 0" represents the beginning of the calendar day.

So, this looks like a strong argument for using singulars in such names.

[dkhalanskyjb]

Some other precedents:

• "Month 1" is January, the first month.
• "Year 1" is the first year. "Year 0" is 1 BC.
• "Day 1" is the first day.
• "Hour 1" is the second hour of the day.
• "Hour 12" may be different things, depending on whom you ask.
• "Minute/second 1" is the second minute/second(-of-day).
• "Week 1" is the first week.

Note that months, days, hours, minutes, and seconds are counted cyclically, but differ in rules regarding this. So, the split seems to be between date components and time components. Thus, "second-of-epoch 1" could also sensibly mean that a whole second passed, if we treat it the same way the time components are treated on the clock.

That said, in English, there only seems to be a single commonly known case when we count something continuously from a reference point, and that would be the years, which are denoted by their ordinals. Going by this, for seconds since the epoch, maybe plural is also a sensible choice.

[PeterAttardo]

I think something else that's worth noting is that in all cases where a 0 value exists, the unit is 0-indexed. The time components all have a :00 value, so they are all 0-indexed. Whereas there is no 0th month, 0th day of the week, or 0th year on the calendar, so they are 1-indexed. Admittedly this is a bit of a tautology, but it's still instructive. If 0 is a valid value for secondOfEpoch, then I think that would imply it should be 0-indexed as well.

[dkhalanskyjb]

I think we did find what we were looking for in this discussion. Thank you all again!