Skip to content

Commit a07cb8d

Browse files
dkhalanskyjbdkhalanskyjb
committed
Replace dayOfMonth with day and monthNumber with month
`monthNumber` is still called that in the formatting facilities to distinguish `monthNumber` from `monthName`, and also in `DateTimeComponents` because `monthNumber` can contain out-of-bounds data and is useful even aside from being a view of `Month`. Fixes #84 Blocked by an IDE bug: <https://youtrack.jetbrains.com/issue/KTIJ-29647/ReplaceWith-of-properties-just-erases-code>
1 parent bc8adee commit a07cb8d

28 files changed

+286
-152
lines changed

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ val datetimeInSystemZone: LocalDateTime = currentMoment.toLocalDateTime(TimeZone
108108
```
109109

110110
A `LocalDateTime` instance exposes familiar components of the Gregorian calendar:
111-
`year`, `month`, `dayOfMonth`, `hour`, and so on up to `nanosecond`.
111+
`year`, `month`, `day`, `hour`, and so on up to `nanosecond`.
112112
The property `dayOfWeek` shows what weekday that date is,
113113
and `dayOfYear` shows the day number since the beginning of a year.
114114

@@ -210,7 +210,7 @@ can define their own format or use some of the predefined ones:
210210
val dateFormat = LocalDate.Format {
211211
monthNumber(padding = Padding.SPACE)
212212
char('/')
213-
dayOfMonth()
213+
day()
214214
char(' ')
215215
year()
216216
}

‎core/common/src/LocalDate.kt

Lines changed: 44 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ package kotlinx.datetime
88
import kotlinx.datetime.format.*
99
import kotlinx.datetime.serializers.*
1010
import kotlinx.serialization.Serializable
11+
import kotlin.internal.*
1112

1213
/**
1314
* The date part of [LocalDateTime].
@@ -96,7 +97,7 @@ public expect class LocalDate : Comparable<LocalDate> {
9697
* Creates a new format for parsing and formatting [LocalDate] values.
9798
*
9899
* Only parsing and formatting of well-formed values is supported. If the input does not fit the boundaries
99-
* (for example, [dayOfMonth] is 31 for February), consider using [DateTimeComponents.Format] instead.
100+
* (for example, [day] is 31 for February), consider using [DateTimeComponents.Format] instead.
100101
*
101102
* There is a collection of predefined formats in [LocalDate.Formats].
102103
*
@@ -157,19 +158,19 @@ public expect class LocalDate : Comparable<LocalDate> {
157158
/**
158159
* Constructs a [LocalDate] instance from the given date components.
159160
*
160-
* The components [monthNumber] and [dayOfMonth] are 1-based.
161+
* The components [month] and [day] are 1-based.
161162
*
162163
* The supported ranges of components:
163164
* - [year] the range is platform-dependent, but at least is enough to represent dates of all instants between
164165
* [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE]
165-
* - [monthNumber] `1..12`
166-
* - [dayOfMonth] `1..31`, the upper bound can be less, depending on the month
166+
* - [month] `1..12`
167+
* - [day] `1..31`, the upper bound can be less, depending on the month
167168
*
168-
* @throws IllegalArgumentException if any parameter is out of range or if [dayOfMonth] is invalid for the
169+
* @throws IllegalArgumentException if any parameter is out of range or if [day] is invalid for the
169170
* given [monthNumber] and [year].
170171
* @sample kotlinx.datetime.test.samples.LocalDateSamples.constructorFunctionMonthNumber
171172
*/
172-
public constructor(year: Int, monthNumber: Int, dayOfMonth: Int)
173+
public constructor(year: Int, month: Int, day: Int)
173174

174175
/**
175176
* Constructs a [LocalDate] instance from the given date components.
@@ -178,13 +179,13 @@ public expect class LocalDate : Comparable<LocalDate> {
178179
* - [year] the range is platform-dependent, but at least is enough to represent dates of all instants between
179180
* [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE]
180181
* - [month] all values of the [Month] enum
181-
* - [dayOfMonth] `1..31`, the upper bound can be less, depending on the month
182+
* - [day] `1..31`, the upper bound can be less, depending on the month
182183
*
183-
* @throws IllegalArgumentException if any parameter is out of range or if [dayOfMonth] is invalid for the
184+
* @throws IllegalArgumentException if any parameter is out of range or if [day] is invalid for the
184185
* given [month] and [year].
185186
* @sample kotlinx.datetime.test.samples.LocalDateSamples.constructorFunction
186187
*/
187-
public constructor(year: Int, month: Month, dayOfMonth: Int)
188+
public constructor(year: Int, month: Month, day: Int)
188189

189190
/**
190191
* Returns the year component of the date.
@@ -193,11 +194,8 @@ public expect class LocalDate : Comparable<LocalDate> {
193194
*/
194195
public val year: Int
195196

196-
/**
197-
* Returns the number-of-the-month (1..12) component of the date.
198-
*
199-
* Shortcut for `month.number`.
200-
*/
197+
/** @suppress */
198+
@Deprecated("Use the 'month' property instead", ReplaceWith("this.month.number"), level = DeprecationLevel.WARNING)
201199
public val monthNumber: Int
202200

203201
/**
@@ -210,8 +208,12 @@ public expect class LocalDate : Comparable<LocalDate> {
210208
/**
211209
* Returns the day-of-month (`1..31`) component of the date.
212210
*
213-
* @sample kotlinx.datetime.test.samples.LocalDateSamples.dayOfMonth
211+
* @sample kotlinx.datetime.test.samples.LocalDateSamples.day
214212
*/
213+
public val day: Int
214+
215+
/** @suppress */
216+
@Deprecated("Use the 'day' property instead", ReplaceWith("this.day"), level = DeprecationLevel.WARNING)
215217
public val dayOfMonth: Int
216218

217219
/**
@@ -259,6 +261,32 @@ public expect class LocalDate : Comparable<LocalDate> {
259261
public override fun toString(): String
260262
}
261263

264+
/**
265+
* @suppress
266+
*/
267+
@Deprecated(
268+
"Use the constructor that accepts a 'month' and a 'day'",
269+
ReplaceWith("LocalDate(year = year, month = monthNumber, day = dayOfMonth)"),
270+
level = DeprecationLevel.WARNING
271+
)
272+
@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
273+
@LowPriorityInOverloadResolution
274+
public fun LocalDate(year: Int, monthNumber: Int, dayOfMonth: Int): LocalDate =
275+
LocalDate(year = year, month = monthNumber, day = dayOfMonth)
276+
277+
/**
278+
* @suppress
279+
*/
280+
@Deprecated(
281+
"Use the constructor that accepts a 'day'",
282+
ReplaceWith("LocalDate(year = year, month = month, day = dayOfMonth)"),
283+
level = DeprecationLevel.WARNING
284+
)
285+
@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
286+
@LowPriorityInOverloadResolution
287+
public fun LocalDate(year: Int, month: Month, dayOfMonth: Int): LocalDate =
288+
LocalDate(year = year, month = month, day = dayOfMonth)
289+
262290
/**
263291
* Formats this value using the given [format].
264292
* Equivalent to calling [DateTimeFormat.format] on [format] with `this`.
@@ -287,7 +315,7 @@ public fun String.toLocalDate(): LocalDate = LocalDate.parse(this)
287315
* @sample kotlinx.datetime.test.samples.LocalDateSamples.atTimeInline
288316
*/
289317
public fun LocalDate.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalDateTime =
290-
LocalDateTime(year, monthNumber, dayOfMonth, hour, minute, second, nanosecond)
318+
LocalDateTime(year, month.number, day, hour, minute, second, nanosecond)
291319

292320
/**
293321
* Combines this date's components with the specified [LocalTime] components into a [LocalDateTime] value.

‎core/common/src/LocalDateTime.kt

Lines changed: 64 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ import kotlinx.datetime.format.*
99
import kotlinx.datetime.serializers.LocalDateTimeIso8601Serializer
1010
import kotlinx.datetime.serializers.LocalDateTimeComponentSerializer
1111
import kotlinx.serialization.Serializable
12+
import kotlin.internal.*
1213

1314
/**
1415
* The representation of a specific civil date and time without a reference to a particular time zone.
@@ -137,15 +138,15 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
137138
*
138139
* // `08/30 18:43:13`, using a custom format:
139140
* LocalDateTime.Format {
140-
* monthNumber(); char('/'); dayOfMonth()
141+
* monthNumber(); char('/'); day()
141142
* char(' ')
142143
* hour(); char(':'); minute()
143144
* optional { char(':'); second() }
144145
* }
145146
* ```
146147
*
147148
* Only parsing and formatting of well-formed values is supported. If the input does not fit the boundaries
148-
* (for example, [dayOfMonth] is 31 for February), consider using [DateTimeComponents.Format] instead.
149+
* (for example, [day] is 31 for February), consider using [DateTimeComponents.Format] instead.
149150
*
150151
* There is a collection of predefined formats in [LocalDateTime.Formats].
151152
*
@@ -194,27 +195,27 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
194195
/**
195196
* Constructs a [LocalDateTime] instance from the given date and time components.
196197
*
197-
* The components [monthNumber] and [dayOfMonth] are 1-based.
198+
* The components [month] and [day] are 1-based.
198199
*
199200
* The supported ranges of components:
200201
* - [year] the range is platform-dependent, but at least is enough to represent dates of all instants between
201202
* [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE]
202-
* - [monthNumber] `1..12`
203-
* - [dayOfMonth] `1..31`, the upper bound can be less, depending on the month
203+
* - [month] `1..12`
204+
* - [day] `1..31`, the upper bound can be less, depending on the month
204205
* - [hour] `0..23`
205206
* - [minute] `0..59`
206207
* - [second] `0..59`
207208
* - [nanosecond] `0..999_999_999`
208209
*
209210
* @throws IllegalArgumentException if any parameter is out of range,
210-
* or if [dayOfMonth] is invalid for the given [monthNumber] and [year].
211+
* or if [day] is invalid for the given [month] and [year].
211212
*
212213
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunctionWithMonthNumber
213214
*/
214215
public constructor(
215216
year: Int,
216-
monthNumber: Int,
217-
dayOfMonth: Int,
217+
month: Int,
218+
day: Int,
218219
hour: Int,
219220
minute: Int,
220221
second: Int = 0,
@@ -228,21 +229,21 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
228229
* - [year] the range is platform-dependent, but at least is enough to represent dates of all instants between
229230
* [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE]
230231
* - [month] all values of the [Month] enum
231-
* - [dayOfMonth] `1..31`, the upper bound can be less, depending on the month
232+
* - [day] `1..31`, the upper bound can be less, depending on the month
232233
* - [hour] `0..23`
233234
* - [minute] `0..59`
234235
* - [second] `0..59`
235236
* - [nanosecond] `0..999_999_999`
236237
*
237238
* @throws IllegalArgumentException if any parameter is out of range,
238-
* or if [dayOfMonth] is invalid for the given [month] and [year].
239+
* or if [day] is invalid for the given [month] and [year].
239240
*
240241
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunction
241242
*/
242243
public constructor(
243244
year: Int,
244245
month: Month,
245-
dayOfMonth: Int,
246+
day: Int,
246247
hour: Int,
247248
minute: Int,
248249
second: Int = 0,
@@ -263,11 +264,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
263264
*/
264265
public val year: Int
265266

266-
/**
267-
* Returns the number-of-the-month (1..12) component of the [date].
268-
*
269-
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
270-
*/
267+
/** @suppress */
268+
@Deprecated("Use the 'month' property instead", ReplaceWith("month.number"), level = DeprecationLevel.WARNING)
271269
public val monthNumber: Int
272270

273271
/**
@@ -282,6 +280,10 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
282280
*
283281
* @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
284282
*/
283+
public val day: Int
284+
285+
/** @suppress */
286+
@Deprecated("Use the 'day' property instead", ReplaceWith("day"), level = DeprecationLevel.WARNING)
285287
public val dayOfMonth: Int
286288

287289
/**
@@ -383,6 +385,52 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
383385
public override fun toString(): String
384386
}
385387

388+
/**
389+
* @suppress
390+
*/
391+
@Deprecated(
392+
"Use the constructor that accepts a 'month' and a 'day'",
393+
ReplaceWith("LocalDateTime(year = year, month = monthNumber, day = dayOfMonth, hour = hour, minute = minute, second = second, nanosecond = nanosecond)"),
394+
level = DeprecationLevel.WARNING
395+
)
396+
@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
397+
@LowPriorityInOverloadResolution
398+
public fun LocalDateTime(
399+
year: Int,
400+
monthNumber: Int,
401+
dayOfMonth: Int,
402+
hour: Int,
403+
minute: Int,
404+
second: Int = 0,
405+
nanosecond: Int = 0,
406+
): LocalDateTime = LocalDateTime(
407+
year = year, month = monthNumber, day = dayOfMonth,
408+
hour = hour, minute = minute, second = second, nanosecond = nanosecond
409+
)
410+
411+
/**
412+
* @suppress
413+
*/
414+
@Deprecated(
415+
"Use the constructor that accepts a 'day'",
416+
ReplaceWith("LocalDateTime(year = year, month = month, day = dayOfMonth, hour = hour, minute = minute, second = second, nanosecond = nanosecond)"),
417+
level = DeprecationLevel.WARNING
418+
)
419+
@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
420+
@LowPriorityInOverloadResolution
421+
public fun LocalDateTime(
422+
year: Int,
423+
month: Month,
424+
dayOfMonth: Int,
425+
hour: Int,
426+
minute: Int,
427+
second: Int = 0,
428+
nanosecond: Int = 0,
429+
): LocalDateTime = LocalDateTime(
430+
year = year, month = month, day = dayOfMonth,
431+
hour = hour, minute = minute, second = second, nanosecond = nanosecond
432+
)
433+
386434
/**
387435
* Formats this value using the given [format].
388436
* Equivalent to calling [DateTimeFormat.format] on [format] with `this`.

‎core/common/src/LocalTime.kt

Lines changed: 31 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@ import kotlinx.datetime.format.*
1010
import kotlinx.datetime.serializers.LocalTimeIso8601Serializer
1111
import kotlinx.datetime.serializers.LocalTimeComponentSerializer
1212
import kotlinx.serialization.Serializable
13+
import kotlin.internal.*
1314

1415

1516
/**
@@ -364,8 +365,21 @@ public fun String.toLocalTime(): LocalTime = LocalTime.parse(this)
364365
*
365366
* @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDateComponentWiseMonthNumber
366367
*/
367-
public fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int = 0): LocalDateTime =
368-
LocalDateTime(year, monthNumber, dayOfMonth, hour, minute, second, nanosecond)
368+
public fun LocalTime.atDate(year: Int, month: Int, day: Int = 0): LocalDateTime =
369+
LocalDateTime(year, month, day, hour, minute, second, nanosecond)
370+
371+
/** @suppress */
372+
@Deprecated(
373+
"Use the overload that accepts a 'month' and a 'day' instead",
374+
ReplaceWith("this.atDate(year = year, month = monthNumber, day = dayOfMonth)"),
375+
DeprecationLevel.WARNING
376+
)
377+
@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
378+
@LowPriorityInOverloadResolution
379+
public fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int, fakeArgument: Unit = Unit): LocalDateTime =
380+
fakeArgument.let {
381+
LocalDateTime(year, monthNumber, dayOfMonth, hour, minute, second, nanosecond)
382+
}
369383

370384
/**
371385
* Combines this time's components with the specified date components into a [LocalDateTime] value.
@@ -375,8 +389,21 @@ public fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int = 0): L
375389
*
376390
* @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDateComponentWise
377391
*/
378-
public fun LocalTime.atDate(year: Int, month: Month, dayOfMonth: Int = 0): LocalDateTime =
379-
LocalDateTime(year, month, dayOfMonth, hour, minute, second, nanosecond)
392+
public fun LocalTime.atDate(year: Int, month: Month, day: Int = 0): LocalDateTime =
393+
LocalDateTime(year, month, day, hour, minute, second, nanosecond)
394+
395+
/** @suppress */
396+
@Deprecated(
397+
"Use the overload that accepts a 'month' and a 'day' instead",
398+
ReplaceWith("this.atDate(year = year, month = month, day = dayOfMonth)"),
399+
DeprecationLevel.WARNING
400+
)
401+
@Suppress("INVISIBLE_MEMBER", "INVISIBLE_REFERENCE")
402+
@LowPriorityInOverloadResolution
403+
public fun LocalTime.atDate(year: Int, month: Month, dayOfMonth: Int, fakeArgument: Unit = Unit): LocalDateTime =
404+
fakeArgument.let {
405+
LocalDateTime(year, month, dayOfMonth, hour, minute, second, nanosecond)
406+
}
380407

381408
/**
382409
* Combines this time's components with the specified [LocalDate] components into a [LocalDateTime] value.

0 commit comments

Comments
 (0)