@@ -80,7 +80,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
80
80
}
81
81
82
82
/* *
83
- * The entry point for parsing and formatting [DateTimeComponents] values.
83
+ * A collection of formats for parsing and formatting [DateTimeComponents] values.
84
84
*
85
85
* If predefined formats are not sufficient, use [DateTimeComponents.Format] to create a custom
86
86
* [kotlinx.datetime.format.DateTimeFormat] for [DateTimeComponents] values.
@@ -91,9 +91,9 @@ public class DateTimeComponents internal constructor(internal val contents: Date
91
91
* ISO 8601 extended format for dates and times with UTC offset.
92
92
*
93
93
* Examples of valid strings:
94
- * * `2020-01-01T23:59:59+01:00`
95
- * * `2020-01-01T23:59:59+01`
96
- * * `2020 -01-01T23 :59:59Z`
94
+ * * `2020-01-01T23:59:59.106 +01:00`
95
+ * * `2020-01-01T23:59:59.123456789 +01`
96
+ * * `+12020 -01-31T23 :59:59Z`
97
97
*
98
98
* This format uses the local date, local time, and UTC offset fields of [DateTimeComponents].
99
99
*
@@ -168,15 +168,15 @@ public class DateTimeComponents internal constructor(internal val contents: Date
168
168
169
169
/* *
170
170
* Writes the contents of the specified [localTime] to this [DateTimeComponents].
171
- * The [localTime] is written to the [hour], [minute], [second] and [nanosecond] fields.
171
+ * The [localTime] is written to the [hour], [hourOfAmPm], [isPm], [ minute], [second] and [nanosecond] fields.
172
172
*
173
173
* If any of the fields are already set, they will be overwritten.
174
174
*/
175
175
public fun setTime (localTime : LocalTime ) { contents.time.populateFrom(localTime) }
176
176
177
177
/* *
178
178
* Writes the contents of the specified [localDate] to this [DateTimeComponents].
179
- * The [localDate] is written to the [year], [monthNumber] and [dayOfMonth ] fields.
179
+ * The [localDate] is written to the [year], [monthNumber], [dayOfMonth], and [dayOfWeek ] fields.
180
180
*
181
181
* If any of the fields are already set, they will be overwritten.
182
182
*/
@@ -185,7 +185,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
185
185
/* *
186
186
* Writes the contents of the specified [localDateTime] to this [DateTimeComponents].
187
187
* The [localDateTime] is written to the
188
- * [year], [monthNumber], [dayOfMonth], [hour], [minute], [second] and [nanosecond] fields.
188
+ * [year], [monthNumber], [dayOfMonth], [dayOfWeek],
189
+ * [hour], [hourOfAmPm], [isPm], [minute], [second] and [nanosecond] fields.
189
190
*
190
191
* If any of the fields are already set, they will be overwritten.
191
192
*/
@@ -196,7 +197,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
196
197
197
198
/* *
198
199
* Writes the contents of the specified [utcOffset] to this [DateTimeComponents].
199
- * The [utcOffset] is written to the [offsetHours], [offsetMinutesOfHour] and [offsetSecondsOfMinute] fields.
200
+ * The [utcOffset] is written to the [offsetHours], [offsetMinutesOfHour], [offsetSecondsOfMinute], and
201
+ * [offsetIsNegative] fields.
200
202
*
201
203
* If any of the fields are already set, they will be overwritten.
202
204
*/
@@ -236,23 +238,29 @@ public class DateTimeComponents internal constructor(internal val contents: Date
236
238
setOffset(utcOffset)
237
239
}
238
240
239
- /* * Returns the year component of the date. */
241
+ /* * The year component of the date. */
240
242
public var year: Int? by contents.date::year
241
243
242
- /* * Returns the number-of-month (1..12) component of the date. */
244
+ /* *
245
+ * The number-of-month (1..12) component of the date.
246
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
247
+ */
243
248
public var monthNumber: Int? by TwoDigitNumber (contents.date::monthNumber)
244
249
245
- /* * Returns the month ([Month]) component of the date. */
250
+ /* * The month ([Month]) component of the date. */
246
251
public var month: Month ?
247
252
get() = monthNumber?.let { Month (it) }
248
253
set(value) {
249
254
monthNumber = value?.number
250
255
}
251
256
252
- /* * Returns the day-of-month component of the date. */
257
+ /* *
258
+ * The day-of-month component of the date.
259
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
260
+ */
253
261
public var dayOfMonth: Int? by TwoDigitNumber (contents.date::dayOfMonth)
254
262
255
- /* * Returns the day-of-week component of the date. */
263
+ /* * The day-of-week component of the date. */
256
264
public var dayOfWeek: DayOfWeek ?
257
265
get() = contents.date.isoDayOfWeek?.let { DayOfWeek (it) }
258
266
set(value) {
@@ -261,41 +269,69 @@ public class DateTimeComponents internal constructor(internal val contents: Date
261
269
// /** Returns the day-of-year component of the date. */
262
270
// public var dayOfYear: Int
263
271
264
- /* * Returns the hour-of-day time component of this date/time value. */
272
+ /* *
273
+ * The hour-of-day time component.
274
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
275
+ */
265
276
public var hour: Int? by TwoDigitNumber (contents.time::hour)
266
277
267
- /* * Returns the 12-hour time component of this date/time value. */
278
+ /* *
279
+ * The 12-hour time component.
280
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
281
+ * @see isPm
282
+ */
268
283
public var hourOfAmPm: Int? by TwoDigitNumber (contents.time::hourOfAmPm)
269
284
270
- /* * Returns the AM/PM state of the time component: `true` if PM, `false` if `AM`. */
285
+ /* *
286
+ * The AM/PM state of the time component: `true` if PM, `false` if `AM`.
287
+ * @see hourOfAmPm
288
+ */
271
289
public var isPm: Boolean? by contents.time::isPm
272
290
273
- /* * Returns the minute-of-hour time component of this date/time value. */
291
+ /* *
292
+ * The minute-of-hour component.
293
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
294
+ */
274
295
public var minute: Int? by TwoDigitNumber (contents.time::minute)
275
296
276
- /* * Returns the second-of-minute time component of this date/time value. */
297
+ /* *
298
+ * The second-of-minute component.
299
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
300
+ */
277
301
public var second: Int? by TwoDigitNumber (contents.time::second)
278
302
279
- /* * Returns the nanosecond-of-second time component of this date/time value. */
303
+ /* *
304
+ * The nanosecond-of-second component.
305
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..999_999_999` range.
306
+ */
280
307
public var nanosecond: Int?
281
308
get() = contents.time.nanosecond
282
309
set(value) {
283
310
require(value == null || value in 0 .. 999_999_999 ) {
284
- " Nanosecond must be in the range [0, 999,999,999 ]."
311
+ " Nanosecond must be in the range [0, 999_999_999 ]."
285
312
}
286
313
contents.time.nanosecond = value
287
314
}
288
315
289
316
/* * True if the offset is negative. */
290
317
public var offsetIsNegative: Boolean? by contents.offset::isNegative
291
318
292
- /* * The total amount of full hours in the UTC offset, in the range [0; 18]. */
319
+ /* *
320
+ * The total amount of full hours in the UTC offset, in the range [0; 18].
321
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
322
+ */
293
323
public var offsetHours: Int? by TwoDigitNumber (contents.offset::totalHoursAbs)
294
324
295
- /* * The amount of minutes that don't add to a whole hour in the UTC offset, in the range [0; 59]. */
325
+ /* *
326
+ * The amount of minutes that don't add to a whole hour in the UTC offset, in the range [0; 59].
327
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
328
+ */
296
329
public var offsetMinutesOfHour: Int? by TwoDigitNumber (contents.offset::minutesOfHour)
297
330
298
- /* * The amount of seconds that don't add to a whole minute in the UTC offset, in the range [0; 59]. */
331
+ /* *
332
+ * The amount of seconds that don't add to a whole minute in the UTC offset, in the range [0; 59].
333
+ * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
334
+ */
299
335
public var offsetSecondsOfMinute: Int? by TwoDigitNumber (contents.offset::secondsOfMinute)
300
336
301
337
/* * The timezone identifier, for example, "Europe/Berlin". */
@@ -305,11 +341,12 @@ public class DateTimeComponents internal constructor(internal val contents: Date
305
341
* Builds a [UtcOffset] from the fields in this [DateTimeComponents].
306
342
*
307
343
* This method uses the following fields:
344
+ * * [offsetIsNegative] (default value is `false`)
308
345
* * [offsetHours] (default value is 0)
309
346
* * [offsetMinutesOfHour] (default value is 0)
310
347
* * [offsetSecondsOfMinute] (default value is 0)
311
348
*
312
- * Since all of these fields have default values, this method never fails .
349
+ * @throws IllegalArgumentException if any of the fields has an out-of-range value .
313
350
*/
314
351
public fun toUtcOffset (): UtcOffset = contents.offset.toUtcOffset()
315
352
@@ -331,12 +368,13 @@ public class DateTimeComponents internal constructor(internal val contents: Date
331
368
* Builds a [LocalTime] from the fields in this [DateTimeComponents].
332
369
*
333
370
* This method uses the following fields:
334
- * * [hour]
371
+ * * [hour], [hourOfAmPm], and [isPm]
335
372
* * [minute]
336
373
* * [second] (default value is 0)
337
374
* * [nanosecond] (default value is 0)
338
375
*
339
- * @throws IllegalArgumentException if hours or minutes are not present, or if any of the fields are invalid.
376
+ * @throws IllegalArgumentException if hours or minutes are not present, if any of the fields are invalid, or
377
+ * [hourOfAmPm] and [isPm] are inconsistent with [hour].
340
378
*/
341
379
public fun toLocalTime (): LocalTime = contents.time.toLocalTime()
342
380
@@ -347,15 +385,15 @@ public class DateTimeComponents internal constructor(internal val contents: Date
347
385
* * [year]
348
386
* * [monthNumber]
349
387
* * [dayOfMonth]
350
- * * [hour]
388
+ * * [hour], [hourOfAmPm], and [isPm]
351
389
* * [minute]
352
390
* * [second] (default value is 0)
353
391
* * [nanosecond] (default value is 0)
354
392
*
355
393
* Also, [dayOfWeek] is checked for consistency with the other fields.
356
394
*
357
395
* @throws IllegalArgumentException if any of the required fields are not present,
358
- * or if any of the fields are invalid.
396
+ * any of the fields are invalid, or there's inconsistency .
359
397
*
360
398
* @see toLocalDate
361
399
* @see toLocalTime
@@ -370,7 +408,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
370
408
* Almost always equivalent to `toLocalDateTime().toInstant(toUtcOffset())`, but also accounts for cases when
371
409
* the year is outside the range representable by [LocalDate] but not outside the range representable by [Instant].
372
410
*
373
- * @throws IllegalArgumentException if any of the required fields are not present.
411
+ * @throws IllegalArgumentException if any of the required fields are not present, out-of-range, or inconsistent
412
+ * with one another.
374
413
*/
375
414
public fun toInstantUsingOffset (): Instant {
376
415
val offset = toUtcOffset()
@@ -399,7 +438,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
399
438
/* *
400
439
* Uses this format to format an unstructured [DateTimeComponents].
401
440
*
402
- * [block] is called on an empty [DateTimeComponents] before formatting.
441
+ * [block] is called on an initially- empty [DateTimeComponents] before formatting.
403
442
*
404
443
* Example:
405
444
* ```
@@ -409,6 +448,10 @@ public class DateTimeComponents internal constructor(internal val contents: Date
409
448
* setOffset(UtcOffset(hours = 3))
410
449
* }
411
450
* ```
451
+ *
452
+ * @throws IllegalStateException if some values needed for the format are not present or can not be formatted:
453
+ * for example, trying to format [DateTimeFormatBuilder.WithDate.monthName] using a [DateTimeComponents.monthNumber]
454
+ * value of 20.
412
455
*/
413
456
public fun DateTimeFormat<DateTimeComponents>.format (block : DateTimeComponents .() -> Unit ): String = format(DateTimeComponents ().apply { block() })
414
457
0 commit comments