Utc Offset
An offset from UTC.
Examples of these values:
Z
, an offset of zero;+05
, plus five hours;-02
, minus two hours;+03:30
, plus three hours and thirty minutes;+01:23:45
, plus one hour, 23 minutes, and 45 seconds.
Pitfall: the offset is not a time zone. It does not contain any information about the time zone's rules, such as daylight-saving-time transitions. It is just a fixed offset from UTC, something that may be in effect in a given location today but will change tomorrow. Even if the offset is fixed currently, it may change in the future due to political decisions.
See TimeZone for a type that represents a time zone.
Platform specifics
On the JVM, there are UtcOffset.toJavaZoneOffset()
and java.time.ZoneOffset.toKotlinUtcOffset()
extension functions to convert between kotlinx.datetime
and java.time
objects used for the same purpose.
Construction, serialization, and deserialization
To construct a UtcOffset value, use the UtcOffset constructor function. totalSeconds returns the number of seconds from UTC. See sample 1.
There is also a ZERO constant for the offset of zero.
parse and toString methods can be used to obtain a UtcOffset from and convert it to a string in the ISO 8601 extended format (for example, +01:30
). See sample 2.
parse and UtcOffset.format both support custom formats created with Format or defined in Formats. See sample 3.
To serialize and deserialize UtcOffset values with kotlinx-serialization
, use the UtcOffsetSerializer.
Samples
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*
fun main() {
//sampleStart
// Constructing a UtcOffset using the constructor function
val offset = UtcOffset(hours = 3, minutes = 30)
check(offset.totalSeconds == 12600)
// UtcOffset.ZERO is a constant representing the zero offset
check(UtcOffset(seconds = 0) == UtcOffset.ZERO)
//sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*
fun main() {
//sampleStart
// Parsing a UtcOffset from a string
val offset = UtcOffset.parse("+01:30")
check(offset.totalSeconds == 90 * 60)
// Formatting a UtcOffset to a string
val formatted = offset.toString()
check(formatted == "+01:30")
//sampleEnd
}
import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*
fun main() {
//sampleStart
// Parsing a UtcOffset using a custom format
val customFormat = UtcOffset.Format {
optional("GMT") {
offsetHours(Padding.NONE); char(':'); offsetMinutesOfHour()
optional { char(':'); offsetSecondsOfMinute() }
}
}
val offset = customFormat.parse("+01:30:15")
// Formatting a UtcOffset using both a custom format and a predefined one
check(offset.format(customFormat) == "+1:30:15")
check(offset.format(UtcOffset.Formats.FOUR_DIGITS) == "+0130")
//sampleEnd
}
Functions
Returns the fixed-offset time zone with the given UTC offset.
Returns true
if other is a UtcOffset with the same totalSeconds.
Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this
.
Converts this kotlinx.datetime.UtcOffset value to a java.time.ZoneOffset value.