Skip to content

Commit 184a377

Browse files
committed
Final touches to the docs
1 parent 30b182b commit 184a377

File tree

5 files changed

+94
-44
lines changed

5 files changed

+94
-44
lines changed

core/common/src/format/DateTimeComponents.kt

Lines changed: 73 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
8080
}
8181

8282
/**
83-
* The entry point for parsing and formatting [DateTimeComponents] values.
83+
* A collection of formats for parsing and formatting [DateTimeComponents] values.
8484
*
8585
* If predefined formats are not sufficient, use [DateTimeComponents.Format] to create a custom
8686
* [kotlinx.datetime.format.DateTimeFormat] for [DateTimeComponents] values.
@@ -91,9 +91,9 @@ public class DateTimeComponents internal constructor(internal val contents: Date
9191
* ISO 8601 extended format for dates and times with UTC offset.
9292
*
9393
* 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`
9797
*
9898
* This format uses the local date, local time, and UTC offset fields of [DateTimeComponents].
9999
*
@@ -168,15 +168,15 @@ public class DateTimeComponents internal constructor(internal val contents: Date
168168

169169
/**
170170
* 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.
172172
*
173173
* If any of the fields are already set, they will be overwritten.
174174
*/
175175
public fun setTime(localTime: LocalTime) { contents.time.populateFrom(localTime) }
176176

177177
/**
178178
* 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.
180180
*
181181
* If any of the fields are already set, they will be overwritten.
182182
*/
@@ -185,7 +185,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
185185
/**
186186
* Writes the contents of the specified [localDateTime] to this [DateTimeComponents].
187187
* 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.
189190
*
190191
* If any of the fields are already set, they will be overwritten.
191192
*/
@@ -196,7 +197,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
196197

197198
/**
198199
* 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.
200202
*
201203
* If any of the fields are already set, they will be overwritten.
202204
*/
@@ -236,23 +238,29 @@ public class DateTimeComponents internal constructor(internal val contents: Date
236238
setOffset(utcOffset)
237239
}
238240

239-
/** Returns the year component of the date. */
241+
/** The year component of the date. */
240242
public var year: Int? by contents.date::year
241243

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+
*/
243248
public var monthNumber: Int? by TwoDigitNumber(contents.date::monthNumber)
244249

245-
/** Returns the month ([Month]) component of the date. */
250+
/** The month ([Month]) component of the date. */
246251
public var month: Month?
247252
get() = monthNumber?.let { Month(it) }
248253
set(value) {
249254
monthNumber = value?.number
250255
}
251256

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+
*/
253261
public var dayOfMonth: Int? by TwoDigitNumber(contents.date::dayOfMonth)
254262

255-
/** Returns the day-of-week component of the date. */
263+
/** The day-of-week component of the date. */
256264
public var dayOfWeek: DayOfWeek?
257265
get() = contents.date.isoDayOfWeek?.let { DayOfWeek(it) }
258266
set(value) {
@@ -261,41 +269,69 @@ public class DateTimeComponents internal constructor(internal val contents: Date
261269
// /** Returns the day-of-year component of the date. */
262270
// public var dayOfYear: Int
263271

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+
*/
265276
public var hour: Int? by TwoDigitNumber(contents.time::hour)
266277

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+
*/
268283
public var hourOfAmPm: Int? by TwoDigitNumber(contents.time::hourOfAmPm)
269284

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+
*/
271289
public var isPm: Boolean? by contents.time::isPm
272290

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+
*/
274295
public var minute: Int? by TwoDigitNumber(contents.time::minute)
275296

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+
*/
277301
public var second: Int? by TwoDigitNumber(contents.time::second)
278302

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+
*/
280307
public var nanosecond: Int?
281308
get() = contents.time.nanosecond
282309
set(value) {
283310
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]."
285312
}
286313
contents.time.nanosecond = value
287314
}
288315

289316
/** True if the offset is negative. */
290317
public var offsetIsNegative: Boolean? by contents.offset::isNegative
291318

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+
*/
293323
public var offsetHours: Int? by TwoDigitNumber(contents.offset::totalHoursAbs)
294324

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+
*/
296329
public var offsetMinutesOfHour: Int? by TwoDigitNumber(contents.offset::minutesOfHour)
297330

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+
*/
299335
public var offsetSecondsOfMinute: Int? by TwoDigitNumber(contents.offset::secondsOfMinute)
300336

301337
/** The timezone identifier, for example, "Europe/Berlin". */
@@ -305,11 +341,12 @@ public class DateTimeComponents internal constructor(internal val contents: Date
305341
* Builds a [UtcOffset] from the fields in this [DateTimeComponents].
306342
*
307343
* This method uses the following fields:
344+
* * [offsetIsNegative] (default value is `false`)
308345
* * [offsetHours] (default value is 0)
309346
* * [offsetMinutesOfHour] (default value is 0)
310347
* * [offsetSecondsOfMinute] (default value is 0)
311348
*
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.
313350
*/
314351
public fun toUtcOffset(): UtcOffset = contents.offset.toUtcOffset()
315352

@@ -331,12 +368,13 @@ public class DateTimeComponents internal constructor(internal val contents: Date
331368
* Builds a [LocalTime] from the fields in this [DateTimeComponents].
332369
*
333370
* This method uses the following fields:
334-
* * [hour]
371+
* * [hour], [hourOfAmPm], and [isPm]
335372
* * [minute]
336373
* * [second] (default value is 0)
337374
* * [nanosecond] (default value is 0)
338375
*
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].
340378
*/
341379
public fun toLocalTime(): LocalTime = contents.time.toLocalTime()
342380

@@ -347,15 +385,15 @@ public class DateTimeComponents internal constructor(internal val contents: Date
347385
* * [year]
348386
* * [monthNumber]
349387
* * [dayOfMonth]
350-
* * [hour]
388+
* * [hour], [hourOfAmPm], and [isPm]
351389
* * [minute]
352390
* * [second] (default value is 0)
353391
* * [nanosecond] (default value is 0)
354392
*
355393
* Also, [dayOfWeek] is checked for consistency with the other fields.
356394
*
357395
* @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.
359397
*
360398
* @see toLocalDate
361399
* @see toLocalTime
@@ -370,7 +408,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
370408
* Almost always equivalent to `toLocalDateTime().toInstant(toUtcOffset())`, but also accounts for cases when
371409
* the year is outside the range representable by [LocalDate] but not outside the range representable by [Instant].
372410
*
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.
374413
*/
375414
public fun toInstantUsingOffset(): Instant {
376415
val offset = toUtcOffset()
@@ -399,7 +438,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
399438
/**
400439
* Uses this format to format an unstructured [DateTimeComponents].
401440
*
402-
* [block] is called on an empty [DateTimeComponents] before formatting.
441+
* [block] is called on an initially-empty [DateTimeComponents] before formatting.
403442
*
404443
* Example:
405444
* ```
@@ -409,6 +448,10 @@ public class DateTimeComponents internal constructor(internal val contents: Date
409448
* setOffset(UtcOffset(hours = 3))
410449
* }
411450
* ```
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.
412455
*/
413456
public fun DateTimeFormat<DateTimeComponents>.format(block: DateTimeComponents.() -> Unit): String = format(DateTimeComponents().apply { block() })
414457

core/common/src/format/DateTimeFormat.kt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,19 +20,19 @@ public sealed interface DateTimeFormat<T> {
2020
public fun format(value: T): String
2121

2222
/**
23-
* Formats the given [value] into the given [appendable], using this format.
23+
* Formats the given [value] into the given [appendable] using this format.
2424
*/
2525
public fun <A : Appendable> formatTo(appendable: A, value: T): A
2626

2727
/**
28-
* Parses the given [input] string as [T], using this format.
28+
* Parses the given [input] string as [T] using this format.
2929
*
3030
* @throws IllegalArgumentException if the input string is not in the expected format or the value is invalid.
3131
*/
3232
public fun parse(input: CharSequence): T
3333

3434
/**
35-
* Parses the given [input] string as [T], using this format.
35+
* Parses the given [input] string as [T] using this format.
3636
*
3737
* @return the parsed value, or `null` if the input string is not in the expected format or the value is invalid.
3838
*/

core/common/src/format/DateTimeFormatBuilder.kt

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,8 @@ public sealed interface DateTimeFormatBuilder {
5454

5555
/**
5656
* A month-of-year number, from 1 to 12.
57+
*
58+
* By default, it's padded with zeros to two digits. This can be changed by passing [padding].
5759
*/
5860
public fun monthNumber(padding: Padding = Padding.ZERO)
5961

@@ -107,7 +109,7 @@ public sealed interface DateTimeFormatBuilder {
107109
public fun hour(padding: Padding = Padding.ZERO)
108110

109111
/**
110-
* The number of hours in the 12-hour clock:
112+
* The hour of the day in the 12-hour clock:
111113
*
112114
* * Midnight is 12,
113115
* * Hours 1-11 are 1-11,
@@ -132,14 +134,14 @@ public sealed interface DateTimeFormatBuilder {
132134
public fun amPmMarker(am: String, pm: String)
133135

134136
/**
135-
* The number of minutes.
137+
* The minute of hour.
136138
*
137139
* By default, it's zero-padded to two digits, but this can be changed with [padding].
138140
*/
139141
public fun minute(padding: Padding = Padding.ZERO)
140142

141143
/**
142-
* The number of seconds.
144+
* The second of minute.
143145
*
144146
* By default, it's zero-padded to two digits, but this can be changed with [padding].
145147
*
@@ -173,6 +175,8 @@ public sealed interface DateTimeFormatBuilder {
173175
* This field has the default value of 0. If you want to omit it, use [optional].
174176
*
175177
* @throws IllegalArgumentException if [fixedLength] is not in the range 1..9.
178+
*
179+
* @see secondFraction that accepts two parameters.
176180
*/
177181
public fun secondFraction(fixedLength: Int) {
178182
secondFraction(fixedLength, fixedLength)
@@ -209,7 +213,7 @@ public sealed interface DateTimeFormatBuilder {
209213
*/
210214
public sealed interface WithUtcOffset : DateTimeFormatBuilder {
211215
/**
212-
* The total number of hours in the UTC offset, with a sign.
216+
* The total number of hours in the UTC offset, including the sign.
213217
*
214218
* By default, it's zero-padded to two digits, but this can be changed with [padding].
215219
*

core/common/src/format/LocalDateFormat.kt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ public class MonthNames(
2525
}
2626

2727
/**
28-
* Create a [MonthNames], accepting the month names in order from January to December.
28+
* Create a [MonthNames] using the month names in order from January to December.
2929
*/
3030
public constructor(
3131
january: String, february: String, march: String, april: String, may: String, june: String,
@@ -76,7 +76,7 @@ public class DayOfWeekNames(
7676
}
7777

7878
/**
79-
* A constructor that takes a list of day of week names, in order from Monday to Sunday.
79+
* A constructor that takes the day of week names, in order from Monday to Sunday.
8080
*/
8181
public constructor(
8282
monday: String,

core/common/src/internal/format/FieldFormatDirective.kt

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,10 @@ internal abstract class NamedUnsignedIntFieldFormatDirective<in Target>(
8686
}
8787
}
8888

89-
private fun getStringValue(target: Target): String = values[field.accessor.getterNotNull(target) - field.minValue]
89+
private fun getStringValue(target: Target): String = field.accessor.getterNotNull(target).let {
90+
values.getOrNull(it-field.minValue)
91+
?: "The value $it of ${field.name} does not have a corresponding string representation"
92+
}
9093

9194
private inner class AssignableString: AssignableField<Target, String> {
9295
override fun trySetWithoutReassigning(container: Target, newValue: String): String? =
@@ -119,10 +122,10 @@ internal abstract class NamedEnumIntFieldFormatDirective<in Target, Type>(
119122

120123
private val reverseMapping = mapping.entries.associate { it.value to it.key }
121124

122-
private fun getStringValue(target: Target): String = mapping[field.accessor.getterNotNull(target)]
123-
?: throw IllegalStateException(
124-
"The value ${field.accessor.getterNotNull(target)} is does not have a corresponding string representation"
125-
)
125+
private fun getStringValue(target: Target): String = field.accessor.getterNotNull(target).let {
126+
mapping[field.accessor.getterNotNull(target)]
127+
?: "The value $it of ${field.name} does not have a corresponding string representation"
128+
}
126129

127130
private inner class AssignableString: AssignableField<Target, String> {
128131
override fun trySetWithoutReassigning(container: Target, newValue: String): String? =

0 commit comments

Comments
 (0)