Skip to content

Commit 5631cff

Browse files
committed
Rename DateTimeComponents functions
1 parent 68cf4db commit 5631cff

File tree

10 files changed

+59
-46
lines changed

10 files changed

+59
-46
lines changed

core/common/src/Instant.kt

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -516,18 +516,18 @@ public fun Instant.minus(other: Instant, unit: DateTimeUnit.TimeBased): Long =
516516
*/
517517
public fun Instant.format(format: DateTimeFormat<DateTimeComponents>, offset: UtcOffset = UtcOffset.ZERO): String {
518518
val instant = this
519-
return format.format { populateFrom(instant, offset) }
519+
return format.format { setDateTimeOffset(instant, offset) }
520520
}
521521

522522
/**
523523
* Parses an [Instant] value using the given [format].
524524
* Equivalent to calling [DateTimeFormat.parse] on [format] with [input] and obtaining the resulting [Instant] using
525-
* [DateTimeComponents.toInstantUsingUtcOffset].
525+
* [DateTimeComponents.toInstantUsingOffset].
526526
*
527527
* @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
528528
*/
529529
public fun Instant.Companion.parse(input: CharSequence, format: DateTimeFormat<DateTimeComponents>): Instant =
530-
format.parse(input).toInstantUsingUtcOffset()
530+
format.parse(input).toInstantUsingOffset()
531531

532532
internal const val DISTANT_PAST_SECONDS = -3217862419201
533533
internal const val DISTANT_FUTURE_SECONDS = 3093527980800

core/common/src/UtcOffset.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ public expect class UtcOffset {
5757
* // `GMT` on zero, `+4:30:15`, using a custom format:
5858
* UtcOffset.Format {
5959
* optional("GMT") {
60-
* appendOffsetTotalHours(Padding.NONE)
60+
* appendOffsetHours(Padding.NONE)
6161
* char(':')
6262
* appendOffsetMinutesOfHour()
6363
* optional {

core/common/src/format/DateTimeComponents.kt

Lines changed: 32 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ import kotlin.reflect.*
2525
* val input = "2020-03-16T23:59:59.999999999+03:00"
2626
* val bag = DateTimeComponents.Format.ISO_INSTANT.parse(input)
2727
* val localDateTime = bag.toLocalDateTime() // LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999)
28-
* val instant = bag.toInstantUsingUtcOffset() // Instant.parse("2020-03-16T20:59:59.999999999Z")
28+
* val instant = bag.toInstantUsingOffset() // Instant.parse("2020-03-16T20:59:59.999999999Z")
2929
* val offset = bag.toUtcOffset() // UtcOffset(hours = 3)
3030
* ```
3131
*
@@ -55,8 +55,8 @@ import kotlin.reflect.*
5555
* ```
5656
* // Mon, 16 Mar 2020 23:59:59 +0300
5757
* DateTimeComponents.Format.RFC_1123.format {
58-
* populateFrom(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
59-
* populateFrom(UtcOffset(hours = 3))
58+
* setDateTimeOffset(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
59+
* setDateTimeOffset(UtcOffset(hours = 3))
6060
* }
6161
* ```
6262
*
@@ -171,15 +171,15 @@ public class DateTimeComponents internal constructor(internal val contents: Date
171171
*
172172
* If any of the fields are already set, they will be overwritten.
173173
*/
174-
public fun populateFrom(localTime: LocalTime) { contents.time.populateFrom(localTime) }
174+
public fun setTime(localTime: LocalTime) { contents.time.populateFrom(localTime) }
175175

176176
/**
177177
* Writes the contents of the specified [localDate] to this [DateTimeComponents].
178178
* The [localDate] is written to the [year], [monthNumber] and [dayOfMonth] fields.
179179
*
180180
* If any of the fields are already set, they will be overwritten.
181181
*/
182-
public fun populateFrom(localDate: LocalDate) { contents.date.populateFrom(localDate) }
182+
public fun setDate(localDate: LocalDate) { contents.date.populateFrom(localDate) }
183183

184184
/**
185185
* Writes the contents of the specified [localDateTime] to this [DateTimeComponents].
@@ -188,40 +188,53 @@ public class DateTimeComponents internal constructor(internal val contents: Date
188188
*
189189
* If any of the fields are already set, they will be overwritten.
190190
*/
191-
public fun populateFrom(localDateTime: LocalDateTime) {
191+
public fun setDateTime(localDateTime: LocalDateTime) {
192192
contents.date.populateFrom(localDateTime.date)
193193
contents.time.populateFrom(localDateTime.time)
194194
}
195195

196196
/**
197197
* Writes the contents of the specified [utcOffset] to this [DateTimeComponents].
198-
* The [utcOffset] is written to the [offsetTotalHours], [offsetMinutesOfHour] and [offsetSecondsOfMinute] fields.
198+
* The [utcOffset] is written to the [offsetHours], [offsetMinutesOfHour] and [offsetSecondsOfMinute] fields.
199199
*
200200
* If any of the fields are already set, they will be overwritten.
201201
*/
202-
public fun populateFrom(utcOffset: UtcOffset) { contents.offset.populateFrom(utcOffset) }
202+
public fun setOffset(utcOffset: UtcOffset) { contents.offset.populateFrom(utcOffset) }
203203

204204
/**
205205
* Writes the contents of the specified [instant] to this [DateTimeComponents].
206206
*
207207
* This method is almost always equivalent to the following code:
208208
* ```
209-
* populateFrom(instant.toLocalDateTime(offset))
210-
* populateFrom(offset)
209+
* setDateTime(instant.toLocalDateTime(offset))
210+
* setOffset(utcOffset)
211211
* ```
212212
* However, this also works for instants that are too large to be represented as a [LocalDateTime].
213213
*
214214
* If any of the fields are already set, they will be overwritten.
215215
*/
216-
public fun populateFrom(instant: Instant, offset: UtcOffset) {
216+
public fun setDateTimeOffset(instant: Instant, utcOffset: UtcOffset) {
217217
val smallerInstant = Instant.fromEpochSeconds(
218218
instant.epochSeconds % SECONDS_PER_10000_YEARS, instant.nanosecondsOfSecond
219219
)
220-
populateFrom(smallerInstant.toLocalDateTime(offset))
221-
populateFrom(offset)
220+
setDateTime(smallerInstant.toLocalDateTime(utcOffset))
221+
setOffset(utcOffset)
222222
year = year!! + ((instant.epochSeconds / SECONDS_PER_10000_YEARS) * 10000).toInt()
223223
}
224224

225+
/**
226+
* Writes the contents of the specified [localDateTime] and [utcOffset] to this [DateTimeComponents].
227+
*
228+
* A shortcut for calling [setDateTime] and [setOffset] separately.
229+
*
230+
* If [localDateTime] is obtained from an [Instant] using [LocalDateTime.toInstant], it is recommended to use
231+
* [setDateTimeOffset] that accepts an [Instant] directly.
232+
*/
233+
public fun setDateTimeOffset(localDateTime: LocalDateTime, utcOffset: UtcOffset) {
234+
setDateTime(localDateTime)
235+
setOffset(utcOffset)
236+
}
237+
225238
/** Returns the year component of the date. */
226239
public var year: Int? by contents.date::year
227240

@@ -276,7 +289,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
276289
public var offsetIsNegative: Boolean? by contents.offset::isNegative
277290

278291
/** The total amount of full hours in the UTC offset, in the range [0; 18]. */
279-
public var offsetTotalHours: Int? by TwoDigitNumber(contents.offset::totalHoursAbs)
292+
public var offsetHours: Int? by TwoDigitNumber(contents.offset::totalHoursAbs)
280293

281294
/** The amount of minutes that don't add to a whole hour in the UTC offset, in the range [0; 59]. */
282295
public var offsetMinutesOfHour: Int? by TwoDigitNumber(contents.offset::minutesOfHour)
@@ -291,7 +304,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
291304
* Builds a [UtcOffset] from the fields in this [DateTimeComponents].
292305
*
293306
* This method uses the following fields:
294-
* * [offsetTotalHours] (default value is 0)
307+
* * [offsetHours] (default value is 0)
295308
* * [offsetMinutesOfHour] (default value is 0)
296309
* * [offsetSecondsOfMinute] (default value is 0)
297310
*
@@ -358,7 +371,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
358371
*
359372
* @throws IllegalArgumentException if any of the required fields are not present.
360373
*/
361-
public fun toInstantUsingUtcOffset(): Instant {
374+
public fun toInstantUsingOffset(): Instant {
362375
val offset = toUtcOffset()
363376
val time = toLocalTime()
364377
val truncatedDate = contents.date.copy()
@@ -391,8 +404,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
391404
* ```
392405
* // Mon, 16 Mar 2020 23:59:59 +0300
393406
* DateTimeComponents.Format.RFC_1123.format {
394-
* populateFrom(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
395-
* populateFrom(UtcOffset(hours = 3))
407+
* setDateTime(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
408+
* setOffset(UtcOffset(hours = 3))
396409
* }
397410
* ```
398411
*/
@@ -478,7 +491,7 @@ internal class DateTimeComponentsFormat(override val actualFormat: StringFormat<
478491
override fun appendSecondFraction(minLength: Int?, maxLength: Int?) =
479492
actualBuilder.add(BasicFormatStructure(FractionalSecondDirective(minLength, maxLength)))
480493

481-
override fun appendOffsetTotalHours(padding: Padding) =
494+
override fun appendOffsetHours(padding: Padding) =
482495
actualBuilder.add(
483496
SignedFormatStructure(
484497
BasicFormatStructure(UtcOffsetWholeHoursDirective(padding)),

core/common/src/format/DateTimeFormatBuilder.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ public sealed interface DateTimeFormatBuilder {
186186
*
187187
* This field has the default value of 0. If you want to omit it, use [optional].
188188
*/
189-
public fun appendOffsetTotalHours(padding: Padding = Padding.ZERO)
189+
public fun appendOffsetHours(padding: Padding = Padding.ZERO)
190190

191191
/**
192192
* Appends the minute-of-hour of the UTC offset.

core/common/src/format/UtcOffsetFormat.kt

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ internal class UtcOffsetFormat(override val actualFormat: StringFormat<UtcOffset
3131
AbstractDateTimeFormatBuilder<UtcOffsetFieldContainer, Builder>, DateTimeFormatBuilder.WithUtcOffset {
3232

3333
override fun createEmpty(): Builder = Builder(AppendableFormatStructure())
34-
override fun appendOffsetTotalHours(padding: Padding) =
34+
override fun appendOffsetHours(padding: Padding) =
3535
actualBuilder.add(SignedFormatStructure(
3636
BasicFormatStructure(UtcOffsetWholeHoursDirective(padding)),
3737
withPlusSign = true
@@ -72,7 +72,7 @@ internal fun DateTimeFormatBuilder.WithUtcOffset.appendIsoOffset(
7272
) {
7373
require(outputMinute >= outputSecond) { "Seconds cannot be included without minutes" }
7474
fun DateTimeFormatBuilder.WithUtcOffset.appendIsoOffsetWithoutZOnZero() {
75-
appendOffsetTotalHours()
75+
appendOffsetHours()
7676
when (outputMinute) {
7777
WhenToOutput.NEVER -> {}
7878
WhenToOutput.IF_NONZERO -> {
@@ -214,7 +214,7 @@ internal class UtcOffsetWholeHoursDirective(private val padding: Padding) :
214214
) {
215215

216216
override val builderRepresentation: String get() =
217-
"${DateTimeFormatBuilder.WithUtcOffset::appendOffsetTotalHours.name}(${padding.toKotlinCode()})"
217+
"${DateTimeFormatBuilder.WithUtcOffset::appendOffsetHours.name}(${padding.toKotlinCode()})"
218218

219219
override fun equals(other: Any?): Boolean = other is UtcOffsetWholeHoursDirective && padding == other.padding
220220
override fun hashCode(): Int = padding.hashCode()
@@ -256,7 +256,7 @@ internal val ISO_OFFSET by lazy {
256256
UtcOffsetFormat.build {
257257
alternativeParsing({ chars("z") }) {
258258
optional("Z") {
259-
appendOffsetTotalHours()
259+
appendOffsetHours()
260260
char(':')
261261
appendOffsetMinutesOfHour()
262262
optional {
@@ -272,7 +272,7 @@ internal val ISO_OFFSET_BASIC by lazy {
272272
UtcOffsetFormat.build {
273273
alternativeParsing({ chars("z") }) {
274274
optional("Z") {
275-
appendOffsetTotalHours()
275+
appendOffsetHours()
276276
optional {
277277
appendOffsetMinutesOfHour()
278278
optional {
@@ -286,7 +286,7 @@ internal val ISO_OFFSET_BASIC by lazy {
286286
@SharedImmutable
287287
internal val FOUR_DIGIT_OFFSET by lazy {
288288
UtcOffsetFormat.build {
289-
appendOffsetTotalHours()
289+
appendOffsetHours()
290290
appendOffsetMinutesOfHour()
291291
}
292292
}

core/common/test/format/DateTimeComponentsFormatTest.kt

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,8 @@ class DateTimeComponentsFormatTest {
2222
year = 2008
2323
monthNumber = 6
2424
dayOfMonth = 40
25-
populateFrom(LocalTime(11, 5, 30))
26-
populateFrom(UtcOffset.ZERO)
25+
setTime(LocalTime(11, 5, 30))
26+
setOffset(UtcOffset.ZERO)
2727
},
2828
format.parse("Tue, 40 Jun 2008 11:05:30 GMT"))
2929
assertFailsWith<DateTimeFormatException> { format.parse("Bue, 3 Jun 2008 11:05:30 GMT") }
@@ -54,7 +54,7 @@ class DateTimeComponentsFormatTest {
5454
val dateTime = LocalDateTime(2008, 6, 3, 11, 5, 30, 123_456_789)
5555
val offset = UtcOffset(hours = 1)
5656
val formatted = "2008-06-03T11:05:30.123456789+01:00[Europe/Berlin]"
57-
assertEquals(formatted, format.format { populateFrom(dateTime); populateFrom(offset); timeZoneId = berlin })
57+
assertEquals(formatted, format.format { setDateTime(dateTime); setOffset(offset); timeZoneId = berlin })
5858
val bag = format.parse("2008-06-03T11:05:30.123456789+01:00[Europe/Berlin]")
5959
assertEquals(dateTime, bag.toLocalDateTime())
6060
assertEquals(offset, bag.toUtcOffset())
@@ -79,9 +79,9 @@ class DateTimeComponentsFormatTest {
7979
offset: UtcOffset? = null,
8080
zone: TimeZone? = null
8181
) = DateTimeComponents().apply {
82-
date?.let { populateFrom(it) }
83-
time?.let { populateFrom(it) }
84-
offset?.let { populateFrom(it) }
82+
date?.let { setDate(it) }
83+
time?.let { setTime(it) }
84+
offset?.let { setOffset(it) }
8585
timeZoneId = zone?.id
8686
}
8787

@@ -102,8 +102,8 @@ class DateTimeComponentsFormatTest {
102102
@Test
103103
fun testDocFormatting() {
104104
val str = DateTimeComponents.Formats.RFC_1123.format {
105-
populateFrom(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
106-
populateFrom(UtcOffset(hours = 3))
105+
setDateTime(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999))
106+
setOffset(UtcOffset(hours = 3))
107107
}
108108
assertEquals("Mon, 16 Mar 2020 23:59:59 +0300", str)
109109
}
@@ -130,7 +130,7 @@ class DateTimeComponentsFormatTest {
130130
val input = "2020-03-16T23:59:59.999999999+03:00"
131131
val bag = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET.parse(input)
132132
val localDateTime = bag.toLocalDateTime()
133-
val instant = bag.toInstantUsingUtcOffset()
133+
val instant = bag.toInstantUsingOffset()
134134
val offset = bag.toUtcOffset()
135135
assertEquals(LocalDateTime(2020, 3, 16, 23, 59, 59, 999_999_999), localDateTime)
136136
assertEquals(Instant.parse("2020-03-16T20:59:59.999999999Z"), instant)

core/common/test/format/DateTimeComponentsTest.kt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ import kotlin.test.*
1212
class DateTimeComponentsTest {
1313
@Test
1414
fun testAssigningIllegalValues() {
15-
val dateTimeComponents = DateTimeComponents().apply { populateFrom(instant, timeZone.offsetAt(instant)) }
15+
val dateTimeComponents = DateTimeComponents().apply { setDateTimeOffset(instant, timeZone.offsetAt(instant)) }
1616
for (field in twoDigitFields) {
1717
for (invalidValue in listOf(-1, 100, Int.MIN_VALUE, Int.MAX_VALUE, 1000, 253)) {
1818
assertFailsWith<IllegalArgumentException> { field.set(dateTimeComponents, invalidValue) }
@@ -31,7 +31,7 @@ class DateTimeComponentsTest {
3131

3232
@Test
3333
fun testAssigningLegalValues() {
34-
val dateTimeComponents = DateTimeComponents().apply { populateFrom(instant, timeZone.offsetAt(instant)) }
34+
val dateTimeComponents = DateTimeComponents().apply { setDateTimeOffset(instant, timeZone.offsetAt(instant)) }
3535
for (field in twoDigitFields) {
3636
for (validValue in listOf(null, 0, 5, 10, 43, 99)) {
3737
field.set(dateTimeComponents, validValue)
@@ -46,11 +46,11 @@ class DateTimeComponentsTest {
4646
DateTimeComponents::hour,
4747
DateTimeComponents::minute,
4848
DateTimeComponents::second,
49-
DateTimeComponents::offsetTotalHours,
49+
DateTimeComponents::offsetHours,
5050
DateTimeComponents::offsetMinutesOfHour,
5151
DateTimeComponents::offsetSecondsOfMinute,
5252
)
5353
val instant = Clock.System.now()
5454
val timeZone = TimeZone.currentSystemDefault()
55-
val currentTimeDateTimeComponents = DateTimeComponents().apply { populateFrom(instant, timeZone.offsetAt(instant)) }
55+
val currentTimeDateTimeComponents = DateTimeComponents().apply { setDateTimeOffset(instant, timeZone.offsetAt(instant)) }
5656
}

core/common/test/format/UtcOffsetFormatTest.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -166,7 +166,7 @@ class UtcOffsetFormatTest {
166166
fun testDoc() {
167167
val format = UtcOffset.Format {
168168
optional("GMT") {
169-
appendOffsetTotalHours(Padding.NONE)
169+
appendOffsetHours(Padding.NONE)
170170
char(':')
171171
appendOffsetMinutesOfHour()
172172
optional {

core/native/src/Instant.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,7 +140,7 @@ public actual class Instant internal constructor(public actual val epochSeconds:
140140
fromEpochSeconds(epochSeconds, nanosecondAdjustment.toLong())
141141

142142
public actual fun parse(isoString: String): Instant = try {
143-
DateTimeComponents.parse(isoString, DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET).toInstantUsingUtcOffset()
143+
DateTimeComponents.parse(isoString, DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET).toInstantUsingOffset()
144144
} catch (e: IllegalArgumentException) {
145145
throw DateTimeFormatException("Failed to parse an instant from '$isoString'", e)
146146
}

core/native/src/UtcOffset.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ public actual fun UtcOffset(hours: Int? = null, minutes: Int? = null, seconds: I
120120
private val lenientFormat = UtcOffsetFormat.build {
121121
alternativeParsing(
122122
{
123-
appendOffsetTotalHours(Padding.NONE)
123+
appendOffsetHours(Padding.NONE)
124124
},
125125
{
126126
appendIsoOffset(

0 commit comments

Comments
 (0)