@@ -25,7 +25,7 @@ import kotlin.reflect.*
25
25
* val input = "2020-03-16T23:59:59.999999999+03:00"
26
26
* val bag = DateTimeComponents.Format.ISO_INSTANT.parse(input)
27
27
* 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")
29
29
* val offset = bag.toUtcOffset() // UtcOffset(hours = 3)
30
30
* ```
31
31
*
@@ -55,8 +55,8 @@ import kotlin.reflect.*
55
55
* ```
56
56
* // Mon, 16 Mar 2020 23:59:59 +0300
57
57
* 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))
60
60
* }
61
61
* ```
62
62
*
@@ -171,15 +171,15 @@ public class DateTimeComponents internal constructor(internal val contents: Date
171
171
*
172
172
* If any of the fields are already set, they will be overwritten.
173
173
*/
174
- public fun populateFrom (localTime : LocalTime ) { contents.time.populateFrom(localTime) }
174
+ public fun setTime (localTime : LocalTime ) { contents.time.populateFrom(localTime) }
175
175
176
176
/* *
177
177
* Writes the contents of the specified [localDate] to this [DateTimeComponents].
178
178
* The [localDate] is written to the [year], [monthNumber] and [dayOfMonth] fields.
179
179
*
180
180
* If any of the fields are already set, they will be overwritten.
181
181
*/
182
- public fun populateFrom (localDate : LocalDate ) { contents.date.populateFrom(localDate) }
182
+ public fun setDate (localDate : LocalDate ) { contents.date.populateFrom(localDate) }
183
183
184
184
/* *
185
185
* Writes the contents of the specified [localDateTime] to this [DateTimeComponents].
@@ -188,40 +188,53 @@ public class DateTimeComponents internal constructor(internal val contents: Date
188
188
*
189
189
* If any of the fields are already set, they will be overwritten.
190
190
*/
191
- public fun populateFrom (localDateTime : LocalDateTime ) {
191
+ public fun setDateTime (localDateTime : LocalDateTime ) {
192
192
contents.date.populateFrom(localDateTime.date)
193
193
contents.time.populateFrom(localDateTime.time)
194
194
}
195
195
196
196
/* *
197
197
* 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.
199
199
*
200
200
* If any of the fields are already set, they will be overwritten.
201
201
*/
202
- public fun populateFrom (utcOffset : UtcOffset ) { contents.offset.populateFrom(utcOffset) }
202
+ public fun setOffset (utcOffset : UtcOffset ) { contents.offset.populateFrom(utcOffset) }
203
203
204
204
/* *
205
205
* Writes the contents of the specified [instant] to this [DateTimeComponents].
206
206
*
207
207
* This method is almost always equivalent to the following code:
208
208
* ```
209
- * populateFrom (instant.toLocalDateTime(offset))
210
- * populateFrom(offset )
209
+ * setDateTime (instant.toLocalDateTime(offset))
210
+ * setOffset(utcOffset )
211
211
* ```
212
212
* However, this also works for instants that are too large to be represented as a [LocalDateTime].
213
213
*
214
214
* If any of the fields are already set, they will be overwritten.
215
215
*/
216
- public fun populateFrom (instant : Instant , offset : UtcOffset ) {
216
+ public fun setDateTimeOffset (instant : Instant , utcOffset : UtcOffset ) {
217
217
val smallerInstant = Instant .fromEpochSeconds(
218
218
instant.epochSeconds % SECONDS_PER_10000_YEARS , instant.nanosecondsOfSecond
219
219
)
220
- populateFrom (smallerInstant.toLocalDateTime(offset ))
221
- populateFrom(offset )
220
+ setDateTime (smallerInstant.toLocalDateTime(utcOffset ))
221
+ setOffset(utcOffset )
222
222
year = year!! + ((instant.epochSeconds / SECONDS_PER_10000_YEARS ) * 10000 ).toInt()
223
223
}
224
224
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
+
225
238
/* * Returns the year component of the date. */
226
239
public var year: Int? by contents.date::year
227
240
@@ -276,7 +289,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
276
289
public var offsetIsNegative: Boolean? by contents.offset::isNegative
277
290
278
291
/* * 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)
280
293
281
294
/* * The amount of minutes that don't add to a whole hour in the UTC offset, in the range [0; 59]. */
282
295
public var offsetMinutesOfHour: Int? by TwoDigitNumber (contents.offset::minutesOfHour)
@@ -291,7 +304,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
291
304
* Builds a [UtcOffset] from the fields in this [DateTimeComponents].
292
305
*
293
306
* This method uses the following fields:
294
- * * [offsetTotalHours ] (default value is 0)
307
+ * * [offsetHours ] (default value is 0)
295
308
* * [offsetMinutesOfHour] (default value is 0)
296
309
* * [offsetSecondsOfMinute] (default value is 0)
297
310
*
@@ -358,7 +371,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
358
371
*
359
372
* @throws IllegalArgumentException if any of the required fields are not present.
360
373
*/
361
- public fun toInstantUsingUtcOffset (): Instant {
374
+ public fun toInstantUsingOffset (): Instant {
362
375
val offset = toUtcOffset()
363
376
val time = toLocalTime()
364
377
val truncatedDate = contents.date.copy()
@@ -391,8 +404,8 @@ public class DateTimeComponents internal constructor(internal val contents: Date
391
404
* ```
392
405
* // Mon, 16 Mar 2020 23:59:59 +0300
393
406
* 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))
396
409
* }
397
410
* ```
398
411
*/
@@ -478,7 +491,7 @@ internal class DateTimeComponentsFormat(override val actualFormat: StringFormat<
478
491
override fun appendSecondFraction (minLength : Int? , maxLength : Int? ) =
479
492
actualBuilder.add(BasicFormatStructure (FractionalSecondDirective (minLength, maxLength)))
480
493
481
- override fun appendOffsetTotalHours (padding : Padding ) =
494
+ override fun appendOffsetHours (padding : Padding ) =
482
495
actualBuilder.add(
483
496
SignedFormatStructure (
484
497
BasicFormatStructure (UtcOffsetWholeHoursDirective (padding)),
0 commit comments