86 By contrast, fields are mini-calculations, defining a value. |
86 By contrast, fields are mini-calculations, defining a value. |
87 For example, month-of-year, day-of-week and hour-of-day are all fields. |
87 For example, month-of-year, day-of-week and hour-of-day are all fields. |
88 The set of supported units and fields can be extended by applications if desired. |
88 The set of supported units and fields can be extended by applications if desired. |
89 </p> |
89 </p> |
90 <p> |
90 <p> |
91 It also contains the basic part of the calendar neutral API. |
|
92 This is intended for use by applications that need to use localized calendars. |
|
93 Ensure that you read the class documentation of {@link java.time.temporal.ChronoLocalDate} |
|
94 before using non-ISO calendar systems. |
|
95 </p> |
|
96 <p> |
|
97 {@link java.time.format} contains the API to print and parse fields into date-time |
91 {@link java.time.format} contains the API to print and parse fields into date-time |
98 objects and to customize parsing and printing. |
92 objects and to customize parsing and printing. |
99 Formatters can be created in a variety of ways, including constants, patterns, |
93 Formatters can be created in a variety of ways, including constants, patterns, |
100 localized styles and a builder. |
94 localized styles and a builder. |
101 Formatters are immutable and thread-safe. |
95 Formatters are immutable and thread-safe. |
103 <p> |
97 <p> |
104 {@link java.time.zone} contains the API to handle time-zones. |
98 {@link java.time.zone} contains the API to handle time-zones. |
105 Detailed information is made available about the rules of each time-zone. |
99 Detailed information is made available about the rules of each time-zone. |
106 </p> |
100 </p> |
107 <p> |
101 <p> |
108 The {@link java.time.calendar} package contains alternate calendar systems. |
102 {@link java.time.chrono} contains the basic part of the calendar neutral API |
|
103 and alternate calendar systems. |
109 This is intended for use by applications that need to use localized calendars. |
104 This is intended for use by applications that need to use localized calendars. |
110 Support is provided for the Hijrah, Japanese, Minguo, and Thai Buddhist Calendars. |
105 Support is provided for the Hijrah, Japanese, Minguo, and Thai Buddhist Calendars. |
111 </p> |
106 </p> |
112 <h3>Design notes</h3> |
107 <h3>Design notes</h3> |
113 <p> |
108 <p> |
134 hour-minute, hour-minute-second and hour-minute-second-nanosecond. |
129 hour-minute, hour-minute-second and hour-minute-second-nanosecond. |
135 While logically pure, this was not possible in practice, as the additional classes would have |
130 While logically pure, this was not possible in practice, as the additional classes would have |
136 excessively complicated the API. Notably, there would be additional combinations at the offset |
131 excessively complicated the API. Notably, there would be additional combinations at the offset |
137 and date-time levels, such as offset-date-hour-minute. |
132 and date-time levels, such as offset-date-hour-minute. |
138 To avoid this explosion of types, {@link java.time.LocalTime} is used for all precisions of time. |
133 To avoid this explosion of types, {@link java.time.LocalTime} is used for all precisions of time. |
139 By contrast, some additional classes were used for dates, such as {@link java.time.temporal.YearMonth}. |
134 By contrast, some additional classes were used for dates, such as {@link java.time.YearMonth}. |
140 This proved necessary, as the API for year-month is significantly different to that for a date, whereas |
135 This proved necessary, as the API for year-month is significantly different to that for a date, whereas |
141 an absence of nanoseconds in a time can be approximated by returning zero. |
136 an absence of nanoseconds in a time can be approximated by returning zero. |
142 </p> |
137 </p> |
143 <p> |
138 <p> |
144 Similarly, full type-safety might argue for a separate class for each field in date-time, |
139 Similarly, full type-safety might argue for a separate class for each field in date-time, |
159 The calendar system would be stored separately in the user preferences. |
154 The calendar system would be stored separately in the user preferences. |
160 </p> |
155 </p> |
161 <p> |
156 <p> |
162 There are, however, some limited use cases where users believe they need to store and use |
157 There are, however, some limited use cases where users believe they need to store and use |
163 dates in arbitrary calendar systems throughout the application. |
158 dates in arbitrary calendar systems throughout the application. |
164 This is supported by {@link java.time.temporal.ChronoLocalDate}, however it is vital to read |
159 This is supported by {@link java.time.chrono.ChronoLocalDate}, however it is vital to read |
165 all the associated warnings in the Javadoc of that interface before using it. |
160 all the associated warnings in the Javadoc of that interface before using it. |
166 In summary, applications that require general interoperation between multiple calendar systems |
161 In summary, applications that require general interoperation between multiple calendar systems |
167 typically need to be written in a very different way to those only using the ISO calendar, |
162 typically need to be written in a very different way to those only using the ISO calendar, |
168 thus most applications should just use ISO and avoid {@code ChronoLocalDate}. |
163 thus most applications should just use ISO and avoid {@code ChronoLocalDate}. |
169 </p> |
164 </p> |