kotlinx-datetime/kotlinx.datetime/UtcOffset/Companion/orNull

orNull

actual fun orNull(hours: Int?, minutes: Int?, seconds: Int?): UtcOffset?(source)

Constructs a UtcOffset from hours, minutes, and seconds components or returns null if a value is out of range or invalid.

All components must have the same sign. Otherwise, null will be returned.

The bounds are checked: it is invalid to pass something other than ±[0; 59] as the number of seconds or minutes; null will be returned if this rule is violated. For example, UtcOffset.orNull(hours = 3, minutes = 61) returns null.

However, the non-null component of the highest order can exceed these bounds, for example, UtcOffset.orNull(minutes = 241) and UtcOffset.orNull(seconds = -3600) are both valid.

Use UtcOffset(hours, minutes, seconds) to throw an exception instead of returning null when the parameters are invalid.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Using the orNull function to create UtcOffset values
val validOffset = UtcOffset.orNull(hours = 3, minutes = 30)
check(validOffset != null)
check(validOffset.totalSeconds == 12600)

// For valid inputs, orNull returns a non-null value
check(UtcOffset.orNull(seconds = -3600) == UtcOffset(hours = -1))

// For invalid inputs, orNull returns null
check(UtcOffset.orNull(hours = 1, minutes = 60) == null)
// Since `hours` is positive, `minutes` must also be positive
check(UtcOffset.orNull(hours = 1, minutes = -30) == null)
// The total offset must be within the range ±18:00
check(UtcOffset.orNull(hours = 19) == null) 
   //sampleEnd
}
Content copied to clipboard
expect fun orNull(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset?(source)

Constructs a UtcOffset from hours, minutes, and seconds components or returns null if a value is out of range or invalid.

All components must have the same sign. Otherwise, null will be returned.

The bounds are checked: it is invalid to pass something other than ±[0; 59] as the number of seconds or minutes; null will be returned if this rule is violated. For example, UtcOffset.orNull(hours = 3, minutes = 61) returns null.

However, the non-null component of the highest order can exceed these bounds, for example, UtcOffset.orNull(minutes = 241) and UtcOffset.orNull(seconds = -3600) are both valid.

Use UtcOffset(hours, minutes, seconds) to throw an exception instead of returning null when the parameters are invalid.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Using the orNull function to create UtcOffset values
val validOffset = UtcOffset.orNull(hours = 3, minutes = 30)
check(validOffset != null)
check(validOffset.totalSeconds == 12600)

// For valid inputs, orNull returns a non-null value
check(UtcOffset.orNull(seconds = -3600) == UtcOffset(hours = -1))

// For invalid inputs, orNull returns null
check(UtcOffset.orNull(hours = 1, minutes = 60) == null)
// Since `hours` is positive, `minutes` must also be positive
check(UtcOffset.orNull(hours = 1, minutes = -30) == null)
// The total offset must be within the range ±18:00
check(UtcOffset.orNull(hours = 19) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun orNull(hours: Int?, minutes: Int?, seconds: Int?): UtcOffset?(source)

Constructs a UtcOffset from hours, minutes, and seconds components or returns null if a value is out of range or invalid.

All components must have the same sign. Otherwise, null will be returned.

The bounds are checked: it is invalid to pass something other than ±[0; 59] as the number of seconds or minutes; null will be returned if this rule is violated. For example, UtcOffset.orNull(hours = 3, minutes = 61) returns null.

However, the non-null component of the highest order can exceed these bounds, for example, UtcOffset.orNull(minutes = 241) and UtcOffset.orNull(seconds = -3600) are both valid.

Use UtcOffset(hours, minutes, seconds) to throw an exception instead of returning null when the parameters are invalid.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*

fun main() { 
   //sampleStart 
   // Using the orNull function to create UtcOffset values
val validOffset = UtcOffset.orNull(hours = 3, minutes = 30)
check(validOffset != null)
check(validOffset.totalSeconds == 12600)

// For valid inputs, orNull returns a non-null value
check(UtcOffset.orNull(seconds = -3600) == UtcOffset(hours = -1))

// For invalid inputs, orNull returns null
check(UtcOffset.orNull(hours = 1, minutes = 60) == null)
// Since `hours` is positive, `minutes` must also be positive
check(UtcOffset.orNull(hours = 1, minutes = -30) == null)
// The total offset must be within the range ±18:00
check(UtcOffset.orNull(hours = 19) == null) 
   //sampleEnd
}
Content copied to clipboard