kotlinx-datetime/kotlinx.datetime/UtcOffset

UtcOffset

@Serializable(with = UtcOffsetSerializer::class)

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.

A non-throwing version of the constructor is the orNull function.

There is also a ZERO constant for the offset of zero.

parse, parseOrNull, 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, parseOrNull, and UtcOffset.format all support custom formats created with Format or defined in Formats. See sample 3.

To serialize and deserialize UtcOffset values with kotlinx-serialization, use the default serializer, or UtcOffsetIso8601Serializer for the ISO 8601 format explicitly.

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)

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.

See TimeZone for a type that represents a time zone.

Platform specifics

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.

A non-throwing version of the constructor is the orNull function.

There is also a ZERO constant for the offset of zero.

parse, parseOrNull, 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, parseOrNull, and UtcOffset.format all support custom formats created with Format or defined in Formats. See sample 3.

To serialize and deserialize UtcOffset values with kotlinx-serialization, use the default serializer, or UtcOffsetIso8601Serializer for the ISO 8601 format explicitly.

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) : Serializable(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.

See TimeZone for a type that represents a time zone.

Platform specifics

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.

A non-throwing version of the constructor is the orNull function.

There is also a ZERO constant for the offset of zero.

parse, parseOrNull, 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, parseOrNull, and UtcOffset.format all support custom formats created with Format or defined in Formats. See sample 3.

To serialize and deserialize UtcOffset values with kotlinx-serialization, use the default serializer, or UtcOffsetIso8601Serializer for the ISO 8601 format explicitly.

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
}