Joda Time
Key concepts
Chronologies
Development
Joda
Project Documentation
Website
Last Published: 2013-03-08
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.
The number of milliseconds in the specified time once the second and larger parts are removed.
The number of milliseconds in the specified time once the day and larger parts are removed.
The number of seconds in the specified time once the minute and larger parts are removed.
The number of minutes in the specified time once the hour and larger parts are removed.
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.
The number of hours within the half day. The clockhour value represents midnight or noon of the current day as 12 instead of 0.
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.
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.
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.
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.
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.
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.
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.
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.