More samples

Author: dkhalanskyjb

core/common/src/format/DateTimeComponents.kt

@@ -17,58 +17,34 @@ import kotlin.reflect.*
  * A collection of date-time fields, used specifically for parsing and formatting.
  *
  * Its main purpose is to provide support for complex date-time formats that don't correspond to any of the standard
- * entities in the library. For example, a format that includes only the month and the day of the month, but not the
- * year, can not be represented and parsed as a [LocalDate], but it is valid for a [DateTimeComponents].
- *
- * Example:
- * ```
- * val input = "2020-03-16T23:59:59.999999999+03:00"
- * val components = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET.parse(input)
- * val localDateTime = components.toLocalDateTime() // LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999)
- * val instant = components.toInstantUsingOffset() // Instant.parse("2020-03-16T20:59:59.999999999Z")
- * val offset = components.toUtcOffset() // UtcOffset(hours = 3)
- * ```
+ * entities in the library. For example, a format that includes only the month and the day of the month but not the
+ * year cannot be represented and parsed as a [LocalDate], but it is valid for a [DateTimeComponents].
+ * See sample 1.
  *
  * Another purpose is to support parsing and formatting data with out-of-bounds values. For example, parsing
  * `23:59:60` as a [LocalTime] is not possible, but it is possible to parse it as a [DateTimeComponents], adjust the value by
  * setting [second] to `59`, and then convert it to a [LocalTime] via [toLocalTime].
- *
- * Example:
- * ```
- * val input = "23:59:60"
- * val extraDay: Boolean
- * val time = DateTimeComponents.Format {
- *   time(LocalTime.Formats.ISO)
- * }.parse(input).apply {
- *   if (hour == 23 && minute == 59 && second == 60) {
- *     hour = 0; minute = 0; second = 0; extraDay = true
- *   } else {
- *     extraDay = false
- *   }
- * }.toLocalTime()
- * ```
+ * See sample 2.
  *
  * Because this class has limited applications, constructing it directly is not possible.
  * For formatting, use the [format] overload that accepts a lambda with a [DateTimeComponents] receiver.
- *
- * Example:
- * ```
- * // Mon, 16 Mar 2020 23:59:59 +0300
- * DateTimeComponents.Formats.RFC_1123.format {
- *    setDateTimeOffset(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
- *    setDateTimeOffset(UtcOffset(hours = 3))
- * }
- * ```
+ * See sample 3.
  *
  * Accessing the fields of this class is not thread-safe.
  * Make sure to apply proper synchronization if you are using a single instance from multiple threads.
+ *
+ * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.parsingComplexInput
+ * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.parsingInvalidInput
+ * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.simpleFormatting
  */
 public class DateTimeComponents internal constructor(internal val contents: DateTimeComponentsContents = DateTimeComponentsContents()) {
     public companion object {
         /**
          * Creates a [DateTimeFormat] for [DateTimeComponents] values using [DateTimeFormatBuilder.WithDateTimeComponents].
          *
          * There is a collection of predefined formats in [DateTimeComponents.Formats].
+         *
+         * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.customFormat
          */
         @Suppress("FunctionName")
         public fun Format(block: DateTimeFormatBuilder.WithDateTimeComponents.() -> Unit): DateTimeFormat<DateTimeComponents> {
@@ -120,6 +96,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
          * val localDateTime = components.toLocalDateTime() // 2020-08-30T18:43:00.123456789
          * val offset = components.toUtcOffset() // UtcOffset(hours = 3)
          * ```
+         *
+         * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.Formats.iso
          */
         public val ISO_DATE_TIME_OFFSET: DateTimeFormat<DateTimeComponents> = Format {
             date(ISO_DATE)
@@ -153,6 +131,9 @@ public class DateTimeComponents internal constructor(internal val contents: Date
          * * `30 Jun 2008 11:05:30 UT`
          *
          * North American and military time zone abbreviations are not supported.
+         *
+         * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.Formats.rfc1123parsing
+         * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.Formats.rfc1123formatting
          */
         public val RFC_1123: DateTimeFormat<DateTimeComponents> = Format {
             alternativeParsing({
@@ -192,6 +173,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      * The [localTime] is written to the [hour], [hourOfAmPm], [amPm], [minute], [second] and [nanosecond] fields.
      *
      * If any of the fields are already set, they will be overwritten.
+     *
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.time
      */
     public fun setTime(localTime: LocalTime) {
         contents.time.populateFrom(localTime)
@@ -202,6 +185,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      * The [localDate] is written to the [year], [monthNumber], [dayOfMonth], and [dayOfWeek] fields.
      *
      * If any of the fields are already set, they will be overwritten.
+     *
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.date
      */
     public fun setDate(localDate: LocalDate) {
         contents.date.populateFrom(localDate)
@@ -214,6 +199,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      * [hour], [hourOfAmPm], [amPm], [minute], [second] and [nanosecond] fields.
      *
      * If any of the fields are already set, they will be overwritten.
+     *
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.setDateTime
      */
     public fun setDateTime(localDateTime: LocalDateTime) {
         contents.date.populateFrom(localDateTime.date)
@@ -226,6 +213,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      * [offsetIsNegative] fields.
      *
      * If any of the fields are already set, they will be overwritten.
+     *
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.offset
      */
     public fun setOffset(utcOffset: UtcOffset) {
         contents.offset.populateFrom(utcOffset)
@@ -242,6 +231,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      * However, this also works for instants that are too large to be represented as a [LocalDateTime].
      *
      * If any of the fields are already set, they will be overwritten.
+     *
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.setDateTimeOffsetInstant
      */
     public fun setDateTimeOffset(instant: Instant, utcOffset: UtcOffset) {
         val smallerInstant = Instant.fromEpochSeconds(
@@ -259,24 +250,31 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      *
      * If [localDateTime] is obtained from an [Instant] using [LocalDateTime.toInstant], it is recommended to use
      * [setDateTimeOffset] that accepts an [Instant] directly.
+     *
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.setDateTimeOffset
      */
     public fun setDateTimeOffset(localDateTime: LocalDateTime, utcOffset: UtcOffset) {
         setDateTime(localDateTime)
         setOffset(utcOffset)
     }
 
-    /** The year component of the date. */
+    /**
+     * The year component of the date.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.date
+     */
     public var year: Int? by contents.date::year
 
     /**
      * The number-of-month (1..12) component of the date.
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.date
      */
     public var monthNumber: Int? by TwoDigitNumber(contents.date::monthNumber)
 
     /**
      * The month ([Month]) component of the date.
      * @throws IllegalArgumentException during getting if [monthNumber] is outside the `1..12` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.date
      */
     public var month: Month?
         get() = monthNumber?.let { Month(it) }
@@ -287,10 +285,14 @@ public class DateTimeComponents internal constructor(internal val contents: Date
     /**
      * The day-of-month component of the date.
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.date
      */
     public var dayOfMonth: Int? by TwoDigitNumber(contents.date::dayOfMonth)
 
-    /** The day-of-week component of the date. */
+    /**
+     * The day-of-week component of the date.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.dayOfWeek
+     */
     public var dayOfWeek: DayOfWeek?
         get() = contents.date.isoDayOfWeek?.let { DayOfWeek(it) }
         set(value) {
@@ -302,37 +304,43 @@ public class DateTimeComponents internal constructor(internal val contents: Date
     /**
      * The hour-of-day (0..23) time component.
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.time
      */
     public var hour: Int? by TwoDigitNumber(contents.time::hour)
 
     /**
      * The 12-hour (1..12) time component.
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
      * @see amPm
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.timeAmPm
      */
     public var hourOfAmPm: Int? by TwoDigitNumber(contents.time::hourOfAmPm)
 
     /**
      * The AM/PM state of the time component.
      * @see hourOfAmPm
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.timeAmPm
      */
     public var amPm: AmPmMarker? by contents.time::amPm
 
     /**
      * The minute-of-hour component.
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.time
      */
     public var minute: Int? by TwoDigitNumber(contents.time::minute)
 
     /**
      * The second-of-minute component.
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.time
      */
     public var second: Int? by TwoDigitNumber(contents.time::second)
 
     /**
      * The nanosecond-of-second component.
      * @throws IllegalArgumentException during assignment if the value is outside the `0..999_999_999` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.time
      */
     public var nanosecond: Int?
         get() = contents.time.nanosecond
@@ -343,28 +351,37 @@ public class DateTimeComponents internal constructor(internal val contents: Date
             contents.time.nanosecond = value
         }
 
-    /** True if the offset is negative. */
+    /**
+     * True if the offset is negative.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.offset
+     */
     public var offsetIsNegative: Boolean? by contents.offset::isNegative
 
     /**
      * The total amount of full hours in the UTC offset, in the range [0; 18].
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.offset
      */
     public var offsetHours: Int? by TwoDigitNumber(contents.offset::totalHoursAbs)
 
     /**
      * The amount of minutes that don't add to a whole hour in the UTC offset, in the range [0; 59].
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.offset
      */
     public var offsetMinutesOfHour: Int? by TwoDigitNumber(contents.offset::minutesOfHour)
 
     /**
      * The amount of seconds that don't add to a whole minute in the UTC offset, in the range [0; 59].
      * @throws IllegalArgumentException during assignment if the value is outside the `0..99` range.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.offset
      */
     public var offsetSecondsOfMinute: Int? by TwoDigitNumber(contents.offset::secondsOfMinute)
 
-    /** The timezone identifier, for example, "Europe/Berlin". */
+    /**
+     * The timezone identifier, for example, "Europe/Berlin".
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.timeZoneId
+     */
     public var timeZoneId: String? by contents::timeZoneId
 
     /**
@@ -377,6 +394,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      * * [offsetSecondsOfMinute] (default value is 0)
      *
      * @throws IllegalArgumentException if any of the fields has an out-of-range value.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.toUtcOffset
      */
     public fun toUtcOffset(): UtcOffset = contents.offset.toUtcOffset()
 
@@ -391,6 +409,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      * Also, [dayOfWeek] is checked for consistency with the other fields.
      *
      * @throws IllegalArgumentException if any of the fields is missing or invalid.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.toLocalDate
      */
     public fun toLocalDate(): LocalDate = contents.date.toLocalDate()
 
@@ -405,6 +424,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      *
      * @throws IllegalArgumentException if hours or minutes are not present, if any of the fields are invalid, or
      * [hourOfAmPm] and [amPm] are inconsistent with [hour].
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.toLocalTime
      */
     public fun toLocalTime(): LocalTime = contents.time.toLocalTime()
 
@@ -427,6 +447,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      *
      * @see toLocalDate
      * @see toLocalTime
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.toLocalDateTime
      */
     public fun toLocalDateTime(): LocalDateTime = toLocalDate().atTime(toLocalTime())
 
@@ -440,6 +461,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
      *
      * @throws IllegalArgumentException if any of the required fields are not present, out-of-range, or inconsistent
      * with one another.
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.toInstantUsingOffset
      */
     public fun toInstantUsingOffset(): Instant {
         val offset = toUtcOffset()
@@ -482,6 +504,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
  * @throws IllegalStateException if some values needed for the format are not present or can not be formatted:
  * for example, trying to format [DateTimeFormatBuilder.WithDate.monthName] using a [DateTimeComponents.monthNumber]
  * value of 20.
+ * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.formatting
  */
 public fun DateTimeFormat<DateTimeComponents>.format(block: DateTimeComponents.() -> Unit): String =
     format(DateTimeComponents().apply { block() })
@@ -494,6 +517,7 @@ public fun DateTimeFormat<DateTimeComponents>.format(block: DateTimeComponents.(
  * matches.
  *
  * @throws IllegalArgumentException if the text does not match the format.
+ * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.parsing
  */
 public fun DateTimeComponents.Companion.parse(
     input: CharSequence,

core/common/src/format/DateTimeFormatBuilder.kt

@@ -34,6 +34,8 @@ public sealed interface DateTimeFormatBuilder {
          * this padding can be disabled or changed to space padding by passing [padding].
          * For years outside this range, it's formatted as a decimal number with a leading sign, so the year 12345
          * is formatted as "+12345".
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.year
          */
         public fun year(padding: Padding = Padding.ZERO)
 
@@ -51,50 +53,47 @@ public sealed interface DateTimeFormatBuilder {
          * When given a two-digit year, it returns a year in the valid range, so "93" becomes 1993,
          * and when given a full year number with a leading sign, it parses the full year number,
          * so "+1850" becomes 1850.
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.yearTwoDigits
          */
         public fun yearTwoDigits(baseYear: Int)
 
         /**
          * A month-of-year number, from 1 to 12.
          *
          * By default, it's padded with zeros to two digits. This can be changed by passing [padding].
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.monthNumber
          */
         public fun monthNumber(padding: Padding = Padding.ZERO)
 
         /**
          * A month name (for example, "January").
          *
-         * Example:
-         * ```
-         * monthName(MonthNames.ENGLISH_FULL)
-         * ```
+         * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.monthName
          */
         public fun monthName(names: MonthNames)
 
         /**
          * A day-of-month number, from 1 to 31.
          *
          * By default, it's padded with zeros to two digits. This can be changed by passing [padding].
+         *
+         * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.dayOfMonth
          */
         public fun dayOfMonth(padding: Padding = Padding.ZERO)
 
         /**
          * A day-of-week name (for example, "Thursday").
          *
-         * Example:
-         * ```
-         * dayOfWeek(DayOfWeekNames.ENGLISH_FULL)
-         * ```
+         * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.dayOfWeek
          */
         public fun dayOfWeek(names: DayOfWeekNames)
 
         /**
          * An existing [DateTimeFormat] for the date part.
          *
-         * Example:
-         * ```
-         * date(LocalDate.Formats.ISO)
-         * ```
+         * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.date
          */
         public fun date(format: DateTimeFormat<LocalDate>)
     }