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:

GJ ISO
year of era year century of era year of century year century of era 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.