Skip to content

Commit cfc7c91

Browse files
committed
Update the docs
1 parent 050bd26 commit cfc7c91

File tree

4 files changed

+27
-2
lines changed

4 files changed

+27
-2
lines changed

core/common/src/LocalDate.kt

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,9 @@ public expect class LocalDate : Comparable<LocalDate> {
8484
* - [month] `1..12`
8585
* - [day] `1..31`, the upper bound can be less, depending on the month
8686
*
87+
* Use `LocalDate(year, month, day) to throw an exception
88+
* instead of returning `null` when the parameters are invalid.
89+
*
8790
* @sample kotlinx.datetime.test.samples.LocalDateSamples.createOrNullMonthNumber
8891
*/
8992
public fun createOrNull(year: Int, month: Int, day: Int): LocalDate?
@@ -98,6 +101,9 @@ public expect class LocalDate : Comparable<LocalDate> {
98101
* - [month] all values of the [Month] enum
99102
* - [day] `1..31`, the upper bound can be less, depending on the month
100103
*
104+
* Use `LocalDate(year, month, day) to throw an exception
105+
* instead of returning `null` when the parameters are invalid.
106+
*
101107
* @sample kotlinx.datetime.test.samples.LocalDateSamples.createOrNull
102108
*/
103109
public fun createOrNull(year: Int, month: Month, day: Int): LocalDate?
@@ -209,6 +215,8 @@ public expect class LocalDate : Comparable<LocalDate> {
209215
*
210216
* @throws IllegalArgumentException if any parameter is out of range or if [day] is invalid for the
211217
* given [month] and [year].
218+
* @see createOrNull for a version that returns `null` instead of throwing an exception
219+
* when the parameters are invalid.
212220
* @sample kotlinx.datetime.test.samples.LocalDateSamples.constructorFunctionMonthNumber
213221
*/
214222
public constructor(year: Int, month: Int, day: Int)
@@ -224,6 +232,8 @@ public expect class LocalDate : Comparable<LocalDate> {
224232
*
225233
* @throws IllegalArgumentException if any parameter is out of range or if [day] is invalid for the
226234
* given [month] and [year].
235+
* @see createOrNull for a version that returns `null` instead of throwing an exception
236+
* when the parameters are invalid.
227237
* @sample kotlinx.datetime.test.samples.LocalDateSamples.constructorFunction
228238
*/
229239
public constructor(year: Int, month: Month, day: Int)

core/common/src/LocalDateTime.kt

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,9 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
130130
* - [second] `0..59`
131131
* - [nanosecond] `0..999_999_999`
132132
*
133+
* Use `LocalDateTime(year, month, day, hour, minute, second, nanosecond)`
134+
* to throw an exception instead of returning `null` when the parameters are invalid.
135+
*
133136
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.createOrNull
134137
*/
135138
public fun createOrNull(
@@ -156,6 +159,9 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
156159
* - [second] `0..59`
157160
* - [nanosecond] `0..999_999_999`
158161
*
162+
* Use `LocalDateTime(year, month, day, hour, minute, second, nanosecond)`
163+
* to throw an exception instead of returning `null` when the parameters are invalid.
164+
*
159165
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.createOrNullWithMonth
160166
*/
161167
public fun createOrNull(
@@ -268,6 +274,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
268274
*
269275
* @throws IllegalArgumentException if any parameter is out of range
270276
* or if [day] is invalid for the given [monthNumber] and [year].
277+
* @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
271278
*
272279
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunctionWithMonthNumber
273280
*/
@@ -296,6 +303,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
296303
*
297304
* @throws IllegalArgumentException if any parameter is out of range,
298305
* or if [day] is invalid for the given [month] and [year].
306+
* @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
299307
*
300308
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunction
301309
*/
@@ -312,6 +320,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
312320
/**
313321
* Constructs a [LocalDateTime] instance by combining the given [date] and [time] parts.
314322
*
323+
* @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
315324
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.fromDateAndTime
316325
*/
317326
public constructor(date: LocalDate, time: LocalTime)

core/common/src/LocalTime.kt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,9 @@ public expect class LocalTime : Comparable<LocalTime> {
9494
* - [second] `0..59`
9595
* - [nanosecond] `0..999_999_999`
9696
*
97+
* Use `LocalTime(hour, minute, second, nanosecond)`
98+
* to throw an exception instead of returning `null` when the parameters are invalid.
99+
*
97100
* @sample kotlinx.datetime.test.samples.LocalTimeSamples.createOrNull
98101
*/
99102
public fun createOrNull(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalTime?
@@ -244,6 +247,7 @@ public expect class LocalTime : Comparable<LocalTime> {
244247
* - [nanosecond] `0..999_999_999`
245248
*
246249
* @throws IllegalArgumentException if any parameter is out of range.
250+
* @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
247251
* @sample kotlinx.datetime.test.samples.LocalTimeSamples.constructorFunction
248252
*/
249253
public constructor(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)

core/common/src/UtcOffset.kt

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,9 @@ public expect class UtcOffset {
9191
* However, the non-null component of the highest order can exceed these bounds,
9292
* for example, `UtcOffset.createOrNull(minutes = 241)` and `UtcOffset.createOrNull(seconds = -3600)` are both valid.
9393
*
94-
* @return the [UtcOffset] with the specified components, or `null` if the components are invalid
95-
* or the resulting `UtcOffset` value is outside of range `±18:00`.
94+
* Use `UtcOffset(hours, minutes, seconds)` to throw an exception instead of returning `null`
95+
* when the parameters are invalid.
96+
*
9697
* @sample kotlinx.datetime.test.samples.UtcOffsetSamples.createOrNull
9798
*/
9899
public fun createOrNull(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset?
@@ -230,6 +231,7 @@ public fun UtcOffset.format(format: DateTimeFormat<UtcOffset>): String = format.
230231
* @throws IllegalArgumentException if a component exceeds its bounds when a higher order component is specified.
231232
* @throws IllegalArgumentException if components have different signs.
232233
* @throws IllegalArgumentException if the resulting `UtcOffset` value is outside of range `±18:00`.
234+
* @see UtcOffset.createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
233235
* @sample kotlinx.datetime.test.samples.UtcOffsetSamples.constructorFunction
234236
*/
235237
public expect fun UtcOffset(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset

0 commit comments

Comments
 (0)