DAY_OF_YEAR definition for non-ISO Chronology #272

masa310 opened this Issue Feb 28, 2013 · 10 comments

3 participants


When I changed the JapaneseChronology implementation, I assumed that DAY_OF_YEAR is actually day-of-year-of-era. But I wonder if it's day-of-prolepric-year. If it is, it's strange that the first day of year of Heisei 1 is 1989-01-01 which is actually Showa 64.01.01.

Strictly speaking, this isn't a JapaneseChronology specific issue. In Thailand, a year started from 04-01 from B.E. 2455 and 2483[1]. If the year boundaries are correctly supported in ThaiBuddhist, then day-of-year numbering may be affected.

So, what's the definition of DAY_OF_YEAR in non-ISO calendars?



The current definition is day of proleptic year. For many calendars it is the same either way.
The methods in Chronology.dateYearDay are proleptic; to change would require either additional methods or an additional argument for the Era.
But day-of-year-of-era may be more useful for a few calendars.


Chronology.dateYearDay has overloads.

public ChronoLocalDate dateYearDay(Era era, int yearOfEra, int dayOfYear)
public abstract ChronoLocalDate dateYearDay(int prolepticYear, int dayOfYear)

It may be OK to use `dayOfYear' for the different definitions. A bit confusing, though.

But there's only one field DAY_OF_YEAR which requires an exact definition. I'd like to define DAY_OF_YEAR as day of year of era for JapaneseChronology. Any objections?


To be useful the definition must apply to all Temporals so it can not be selective about particular Chronologies. I'd like Stephen's input on this before deciding.

ThreeTen member

Does the definition with year of era have more meaning in Japan than the current definition? The current way is certainly more obvious to someone who isn't much aware of non ISO calendars.

More generally, a year is defined as roughly related to the period of the earth rotating around the sun. The alternate Japanese definition proposed would be very different.

On the wider question, we have no support in Chronology/ChronoField for the concept of "new year". It was not my expectation that day-of-year was to align with a concept of "new year". If we are to define "new year" as a concept it will need some broader thought.

On ThaiBuddhist, it is known that year boundaries are not supported (I pointed this out when proposing that maybe Thai calendar should be more fully supported. Note that we also do not support the Julian-Gregorian cutover, which affects date accuracy in Thai, Minguo and Japanese. Ultimately, there are limitations to whatever we define. The question is whether those limitations are acceptable.


I'm not sure about what your "new year" concept is. But the issue is analogous that standard-daylight time transitions create 23- or 25-hour days. In the Japanese calendar, era transitions create years in different lengths which are not in sync with month cycles.

I suspect that there's a misconception about the Japanese calendar. There's no proleptic year concept in the real life Japanese calendar, and people just do conversions between Japanese dates and Gregorian dates. For dates when the Japanese calendar was based on lunisolar calendars, it is the same thing. We need to convert era+year+month+day-of-month from/to a Gregorian or Julian calendar date. I think it'd be further confusing if the proleptic Gregorian year numbering is applied to the lunisolar calendar dates (Meiji 5 or before).

ThreeTen member

You say that there is no proleptic-year, but I'd argue there is. What is (Showa 63.12.01) plus 1 year? It can't be (Showa 64.12.01) as that is an invalid date. Assuming I'm correct, then its clear that there is a valid concept in the Japanese calendar of a period consisting of 12 months known as a "year". The alternative is that (Showa 63.12.01) plus 1 year is the last valid day of Showa, which just seems weird in a variety of ways.

So, the change of era part way through a period of 12 months does change the year-of-era/era numbering/naming but doesn't change the year as exposed through plus/minus.

The real requirements question is whether Japanese users want/need the day-of-year field. Does it actually have real meaning there? Do they actually want it to restart when an era changes? We could even choose to omit the field from JapaneseChronology. Does CLDR/LDML have an opinion (I don't think so)?

If it is a vital concept, then I think we'd have to support an extra ChronoField - DAY_OF_YEAR_OF_ERA - with the two dateYearDay() methods on Chronology behaving differently.

Note that this problem also applies to any other year-linked field, such as ALIGNED_WEEK_OF_YEAR, WEEK_OF_YEAR and WEEK_OF_WEEK_BASED_YEAR.


The DayOfYear field needs to be defined as daysBetween(date, firstDayOfYear) where firstDayOfYear is either, 1, 1) or, year, 1, 1). If it is defined as the former than developers will need to use a workaround by computing using the 'Era' based version. The later pattern works for all Chronologies.


Defining DAY_OF_YEAR relative to the 1st of the year makes sense for the derived fields like weekOfYear, etc. Some calendars are not firmly rooted in the celestial math and have human variations that matter.
The value can be Chronology relative and for most Gregorian and ISO calendars it works out to be the same as the proleptic understanding.

ThreeTen member

I think making JapaneseChronology day-of-year work based on the regnal year will be OK, although anything derived from day-of-year may behave in a different manor to that normally expected.

This will be weird based on the definitions, as _OF_YEAR has always been intended to relate to full YEARS units. But using this field is on balance better than creating a new field.

ThreeTen member

Closed in favour of #299

@jodastephen jodastephen closed this Apr 1, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment