UtcOffset

@Serializable(with = UtcOffsetSerializer::class)
actual class UtcOffset(source)
@Serializable(with = UtcOffsetSerializer::class)
expect class UtcOffset(source)

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
}
@Serializable(with = UtcOffsetSerializer::class)
actual class UtcOffset(zoneOffset: ZoneOffset)(source)
@Serializable(with = UtcOffsetSerializer::class)
actual class UtcOffset(source)

Constructors

Link copied to clipboard
constructor(zoneOffset: ZoneOffset)

Types

Link copied to clipboard
actual object Companion
expect object Companion
actual object Companion
actual object Companion
Link copied to clipboard
actual object Formats
expect object Formats

A collection of predefined formats for parsing and formatting UtcOffset values.

actual object Formats
actual object Formats

Properties

Link copied to clipboard
actual val totalSeconds: Int
expect val totalSeconds: Int

The number of seconds from UTC.

actual val totalSeconds: Int
actual val totalSeconds: Int

Functions

Link copied to clipboard

Returns the fixed-offset time zone with the given UTC offset.

Link copied to clipboard
actual open operator override fun equals(other: Any?): Boolean
expect open operator override fun equals(other: Any?): Boolean

Returns true if other is a UtcOffset with the same totalSeconds.

actual open operator override fun equals(other: Any?): Boolean
actual open operator override fun equals(other: Any?): Boolean
Link copied to clipboard

Formats this value using the given format. Equivalent to calling DateTimeFormat.format on format with this.

hashCode
Link copied to clipboard
open override fun hashCode(): Int
open override fun hashCode(): Int
open override fun hashCode(): Int
Link copied to clipboard
Link copied to clipboard
actual open override fun toString(): String
expect open override fun toString(): String

Converts this UTC offset to the extended ISO 8601 string representation, for example, +02:30 or Z.

actual open override fun toString(): String
actual open override fun toString(): String