Date and Time fields
The library breaks up the date and time into a number of fields. This document defines what those fields mean.
A naming convention is used to define the fields. These correspond to the common names given to date and time concepts in the Gregorian calendar.
Most fields are a view over part of the total time. These fields are expressed as XxxOfYyy where Xxx and Yyy are two date time units. Yyy will always be larger than Xxx. For example, DayOfWeek or SecondOfMinute. A side effect of this is that these field values cannot be negative.
Certain fields extend over all time, and do not include the word 'Of' in their names. For example, year and weekyear. These fields can have negative values (see the table for details).
The fields are explained in more detail below (for the GJChronology):
| Name | Min value (GJ) | Max value (GJ) | Notes |
|---|---|---|---|
| millisOfSecond | 0 | 999 | |
| millisOfDay | 0 | 86 399 999 | |
| secondOfMinute | 0 | 59 | |
| secondOfDay | 0 | 86 399 | |
| minuteOfHour | 0 | 59 | |
| minuteOfDay | 0 | 1439 | |
| hourOfDay | 0 | 23 | |
| hourOfHalfday | 0 | 11 | |
| clockhourOfDay | 1 | 24 | |
| clockhourOfHalfday | 1 | 12 | |
| halfdayOfDay | 0 (AM) | 1 (PM) | |
| dayOfWeek | 1 (Monday) | 7 (Sunday) | |
| weekOfWeekyear | 1 | 53 | |
| weekyear | -292 000 000 | 292 000 000 | |
| dayOfMonth | 1 | 31 | |
| dayOfYear | 1 | 366 | |
| monthOfYear | 1 (January) | 12 (December) | |
| year | -292 000 000 | 292 000 000 | |
| yearOfCentury | 1 | 100 | [1] |
| yearOfEra | 1 | 292 000 000 | |
| centuryOfEra | 1 | 2 920 000 | [2] |
| era | 0 (BC/BCE) | 1 (AD/CE) |
[1] For the ISOChronology, the year of century range is from 0 to 99.
[2] For the ISOChronology, the century of era range is from 0.
MillisOfSecond
The number of milliseconds in the specified time once the second and larger parts are removed.
MillisOfDay
The number of milliseconds in the specified time once the day and larger parts are removed.
SecondOfMinute
The number of seconds in the specified time once the minute and larger parts are removed.
SecondOfDay
The number of seconds in the specified time once the day and larger parts are removed.
MinuteOfHour
The number of minutes in the specified time once the hour and larger parts are removed.
MinuteOfDay
The number of minutes in the specified time once the day and larger parts are removed.
HourOfDay
The number of hours in the specified time once the day and larger parts are removed. The clockhour value represents midnight of the current day as 24 instead of 0.
HourOfHalfday
The number of hours within the half day. The clockhour value represents midnight or noon of the current day as 12 instead of 0.
HalfdayOfDay
The AM/PM value of the day.
DayOfWeek
The day of week is defined by constants in DateTimeConstants. The values used are from the ISO8601 standard. Monday is defined as 1, through to Sunday as 7.
WeekOfWeekyear and Weekyear
A week based year is one where dates are expressed as a day of week, week number and year (week based). The following description is of the ISO8601 standard used by implementations of this method in this library.
Weeks run from 1 to 52-53 in a week based year. The first day of the week is defined as Monday and given the value 1.
The first week of a year is defined as the first week that has at least four days in the year. As a result of this definition, week 1 may extend into the previous year, and week 52/53 may extend into the following year. Hence the need for the year of weekyear field.
For example, 2003-01-01 was a Wednesday. This means that five days, Wednesday to Sunday, of that week are in 2003. Thus the whole week is considered to be the first week of 2003. Since all weeks start on Monday, the first week of 2003 started on 2002-12-30, ie. in 2002.
The week based year has a specific text format.
2002-12-30 (Monday 30th December 2002) would be represented as 2003-W01-1.
2003-01-01 (Wednesday 1st January 2003) would be represented as 2003-W01-3.
DayOfMonth
The day of the month. For the GJ and ISO chronologies, this will run from 1 through to 28 or 29 in February, 30 in April, June, September and November and 31 otherwise.
DayOfYear
The day of the year. This runs from 1 to 365, or 366 in leap years. The exception is when a Julian to Gregorian cutover has occurred. In that case, the count is from 1 to 355 (typically) and is unbroken.
MonthOfYear
The month of year defined by constants in DateTimeConstants. The values used are from the ISO8601 standard. January is defined as 1, through to December as 12.
Year
The year, using negative values to represent years in the previous era. For the GJ chronology, year zero is not included, unless the cutover to Gregorian is specified at or before 1 BCE. The ISO chronology always includes the year zero.
CenturyOfEra and YearOfCentury
The definition of these varies by chronology:
| year of era | GJ year | GJ century of era | GJ year of century | ISO year | ISO century of era | ISO year of century |
|---|---|---|---|---|---|---|
| 101 BCE | -101 | 2 | 1 | -100 | 1 | 0 |
| 100 BCE | -100 | 1 | 100 | -99 | 0 | 99 |
| 99 BCE | -99 | 1 | 99 | -98 | 0 | 98 |
| ... | ... | ... | ... | ... | ... | ... |
| 2 BCE | -2 | 1 | 2 | -1 | 0 | 1 |
| 1 BCE | -1 | 1 | 1 | 0 | 0 | 0 |
| 1 CE | 1 | 1 | 1 | 1 | 0 | 1 |
| 2 CE | 2 | 1 | 2 | 2 | 0 | 2 |
| ... | ... | ... | ... | ... | ... | ... |
| 99 CE | 99 | 1 | 99 | 99 | 0 | 99 |
| 100 CE | 100 | 1 | 100 | 100 | 1 | 0 |
| 101 CE | 101 | 2 | 1 | 101 | 1 | 1 |
| ... | ... | ... | ... | ... | ... | ... |
| 1999 CE | 1999 | 20 | 99 | 1999 | 19 | 99 |
| 2000 CE | 2000 | 20 | 100 | 2000 | 20 | 0 |
| 2001 CE | 2001 | 21 | 1 | 2001 | 20 | 1 |
For GJ this is consistent with phrases such '2003 is in the 21st century'.
For ISO this represents a straight split of a textual ISO8601 year.
YearOfEra
The year as generally known (always positive). Both the GJ and ISO chronologies return 1 for 1BC/BCE, 2 for 2BC/BCE etc. In other words there is no year zero and no negative value for this field.
Era
The era expressed as a constant, zero for BC/BCE, one for AD/CE.
Other chronologies should respect the convention that one is the current era and zero is the previous era. If more eras are required the values should increase numerically over time.