kotlinx-datetime/kotlinx.datetime/parseOrNull

parseOrNull

actual fun LocalDate.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalDate>): LocalDate?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalDate value, or null if the string does not match the format or does not represent a valid LocalDate.

If format is not specified, LocalDate.Formats.ISO is used. 2023-01-02 is an example of a string in this format.

See LocalDate.Formats and LocalDate.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing LocalDate values using predefined and custom formats or failing
check(LocalDate.parseOrNull("2024-04-16") == LocalDate(2024, Month.APRIL, 16))
val customFormat = LocalDate.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED); char(' '); day(); chars(", "); year()
}
check(LocalDate.parseOrNull("Apr 16, 2024", customFormat) == LocalDate(2024, Month.APRIL, 16))
check(LocalDate.parseOrNull("no date here", customFormat) == null)
check(LocalDate.parseOrNull("Apr 99, 2024", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun LocalDateTime.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalDateTime>): LocalDateTime?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalDateTime value, or null if the string does not match the format or does not represent a valid LocalDateTime.

If format is not specified, LocalDateTime.Formats.ISO is used. 2023-01-02T23:40:57.120 is an example of a string in this format.

See LocalDateTime.Formats and LocalDateTime.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing LocalDateTime values using predefined and custom formats or failing
check(LocalDateTime.parseOrNull("2024-02-15T08:30:15.123456789") ==
        LocalDate(2024, 2, 15).atTime(8, 30, 15, 123_456_789))
val customFormat = LocalDateTime.Format {
    date(LocalDate.Formats.ISO)
    char(' ')
    hour(); char(':'); minute(); char(':'); second()
    char(','); secondFraction(fixedLength = 3)
}
check(LocalDateTime.parseOrNull("2024-02-15 08:30:15,123", customFormat) ==
        LocalDate(2024, 2, 15).atTime(8, 30, 15, 123_000_000))
check(LocalDateTime.parseOrNull("2024-02-15 08:30:15", customFormat) == null)
check(LocalDateTime.parseOrNull("2024-02-15 99:99:99,999", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun LocalTime.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalTime>): LocalTime?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalTime value, or null if the string does not match the format or does not represent a valid LocalTime.

If format is not specified, LocalTime.Formats.ISO is used. 23:40:57.120 is an example of a string in this format.

See LocalTime.Formats and LocalTime.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing a LocalTime from a string using predefined and custom formats
check(LocalTime.parseOrNull("08:30:15.123456789") == LocalTime(8, 30, 15, 123_456_789))
val customFormat = LocalTime.Format {
    hour(); char(':'); minute(); char(':'); second()
    alternativeParsing({ char(',') }) { char('.') } // parse either a dot or a comma
    secondFraction(fixedLength = 3)
}
check(LocalTime.parseOrNull("08:30:15,123", customFormat) == LocalTime(8, 30, 15, 123_000_000))
check(LocalTime.parseOrNull("ten past twelve", customFormat) == null)
check(LocalTime.parseOrNull("99:99:99,123", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun UtcOffset.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<UtcOffset>): UtcOffset?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed UtcOffset value, or null if the string does not match the format or does not represent a valid UtcOffset.

If format is not specified, UtcOffset.Formats.ISO is used. +01:30 is an example of a string in this format.

See UtcOffset.Formats and UtcOffset.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing a UtcOffset from a string using predefined and custom formats or failing
check(UtcOffset.parseOrNull("+01:30")?.totalSeconds == 5400)
check(UtcOffset.parseOrNull("+0130", UtcOffset.Formats.FOUR_DIGITS)?.totalSeconds == 5400)
val customFormat = UtcOffset.Format { offsetHours(Padding.NONE); offsetMinutesOfHour() }
check(UtcOffset.parseOrNull("+130", customFormat)?.totalSeconds == 5400)
check(UtcOffset.parseOrNull("Europe/Berlin", customFormat) == null)
check(UtcOffset.parseOrNull("+9999", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun YearMonth.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<YearMonth>): YearMonth?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed YearMonth value, or null if the string does not match the format or does not represent a valid YearMonth.

If format is not specified, YearMonth.Formats.ISO is used. 2023-01 is an example of a string in this format.

See YearMonth.Formats and YearMonth.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing YearMonth values or failing
check(YearMonth.parseOrNull("2024-01") == YearMonth(2024, 1))
check(YearMonth.parseOrNull("2024-13") == null) 
   //sampleEnd
}
Content copied to clipboard
fun Instant.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<DateTimeComponents> = DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET): Instant?(source)

A shortcut for calling DateTimeFormat.parseOrNull, followed by DateTimeComponents.toInstantUsingOffset, returning null if any of the two operations fail.

Parses a string that represents an instant, including date and time components and a mandatory time zone offset and returns the parsed Instant value.

The string is considered to represent time on the UTC-SLS time scale instead of UTC. In practice, this means that, even if there is a leap second on the given day, it will not affect how the time is parsed, even if it's in the last 1000 seconds of the day. Instead, even if there is a negative leap second on the given day, 23:59:59 is still considered a valid time. 23:59:60 is invalid on UTC-SLS, so parsing it will fail.

If the format is not specified, DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET is used. 2023-01-02T23:40:57.120Z is an example of a string in this format.

See also

for formatting using the default format.

for formatting using a custom format.

for a variant that throws an exception on failure.

Throws

if the text cannot be parsed or the boundaries of Instant are exceeded.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.random.*
import kotlin.test.*
import kotlin.time.Duration.Companion.hours
import kotlin.time.Clock
import kotlin.time.Instant
import kotlin.time.isDistantFuture
import kotlin.time.isDistantPast

fun main() { 
   //sampleStart 
   // Parsing an Instant from a string using predefined and custom formats
check(Instant.parseOrNull("1970-01-01T00:00:00Z") == Instant.fromEpochSeconds(0))
check(Instant.parseOrNull("Thu, 01 Jan 1970 03:30:00 +0330", DateTimeComponents.Formats.RFC_1123) == Instant.fromEpochSeconds(0))
check(Instant.parseOrNull("The moment of Charlie Chaplin's birth") == null) 
   //sampleEnd
}
Content copied to clipboard
expect fun LocalDate.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalDate> = getIsoDateFormat()): LocalDate?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalDate value, or null if the string does not match the format or does not represent a valid LocalDate.

If format is not specified, LocalDate.Formats.ISO is used. 2023-01-02 is an example of a string in this format.

See LocalDate.Formats and LocalDate.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing LocalDate values using predefined and custom formats or failing
check(LocalDate.parseOrNull("2024-04-16") == LocalDate(2024, Month.APRIL, 16))
val customFormat = LocalDate.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED); char(' '); day(); chars(", "); year()
}
check(LocalDate.parseOrNull("Apr 16, 2024", customFormat) == LocalDate(2024, Month.APRIL, 16))
check(LocalDate.parseOrNull("no date here", customFormat) == null)
check(LocalDate.parseOrNull("Apr 99, 2024", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
expect fun LocalDateTime.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalDateTime> = getIsoDateTimeFormat()): LocalDateTime?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalDateTime value, or null if the string does not match the format or does not represent a valid LocalDateTime.

If format is not specified, LocalDateTime.Formats.ISO is used. 2023-01-02T23:40:57.120 is an example of a string in this format.

See LocalDateTime.Formats and LocalDateTime.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing LocalDateTime values using predefined and custom formats or failing
check(LocalDateTime.parseOrNull("2024-02-15T08:30:15.123456789") ==
        LocalDate(2024, 2, 15).atTime(8, 30, 15, 123_456_789))
val customFormat = LocalDateTime.Format {
    date(LocalDate.Formats.ISO)
    char(' ')
    hour(); char(':'); minute(); char(':'); second()
    char(','); secondFraction(fixedLength = 3)
}
check(LocalDateTime.parseOrNull("2024-02-15 08:30:15,123", customFormat) ==
        LocalDate(2024, 2, 15).atTime(8, 30, 15, 123_000_000))
check(LocalDateTime.parseOrNull("2024-02-15 08:30:15", customFormat) == null)
check(LocalDateTime.parseOrNull("2024-02-15 99:99:99,999", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
expect fun LocalTime.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalTime> = getIsoTimeFormat()): LocalTime?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalTime value, or null if the string does not match the format or does not represent a valid LocalTime.

If format is not specified, LocalTime.Formats.ISO is used. 23:40:57.120 is an example of a string in this format.

See LocalTime.Formats and LocalTime.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing a LocalTime from a string using predefined and custom formats
check(LocalTime.parseOrNull("08:30:15.123456789") == LocalTime(8, 30, 15, 123_456_789))
val customFormat = LocalTime.Format {
    hour(); char(':'); minute(); char(':'); second()
    alternativeParsing({ char(',') }) { char('.') } // parse either a dot or a comma
    secondFraction(fixedLength = 3)
}
check(LocalTime.parseOrNull("08:30:15,123", customFormat) == LocalTime(8, 30, 15, 123_000_000))
check(LocalTime.parseOrNull("ten past twelve", customFormat) == null)
check(LocalTime.parseOrNull("99:99:99,123", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
expect fun UtcOffset.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<UtcOffset> = getIsoUtcOffsetFormat()): UtcOffset?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed UtcOffset value, or null if the string does not match the format or does not represent a valid UtcOffset.

If format is not specified, UtcOffset.Formats.ISO is used. +01:30 is an example of a string in this format.

See UtcOffset.Formats and UtcOffset.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing a UtcOffset from a string using predefined and custom formats or failing
check(UtcOffset.parseOrNull("+01:30")?.totalSeconds == 5400)
check(UtcOffset.parseOrNull("+0130", UtcOffset.Formats.FOUR_DIGITS)?.totalSeconds == 5400)
val customFormat = UtcOffset.Format { offsetHours(Padding.NONE); offsetMinutesOfHour() }
check(UtcOffset.parseOrNull("+130", customFormat)?.totalSeconds == 5400)
check(UtcOffset.parseOrNull("Europe/Berlin", customFormat) == null)
check(UtcOffset.parseOrNull("+9999", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
expect fun YearMonth.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<YearMonth> = YearMonth.Formats.ISO): YearMonth?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed YearMonth value, or null if the string does not match the format or does not represent a valid YearMonth.

If format is not specified, YearMonth.Formats.ISO is used. 2023-01 is an example of a string in this format.

See YearMonth.Formats and YearMonth.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing YearMonth values or failing
check(YearMonth.parseOrNull("2024-01") == YearMonth(2024, 1))
check(YearMonth.parseOrNull("2024-13") == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun LocalDate.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalDate>): LocalDate?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalDate value, or null if the string does not match the format or does not represent a valid LocalDate.

If format is not specified, LocalDate.Formats.ISO is used. 2023-01-02 is an example of a string in this format.

See LocalDate.Formats and LocalDate.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing LocalDate values using predefined and custom formats or failing
check(LocalDate.parseOrNull("2024-04-16") == LocalDate(2024, Month.APRIL, 16))
val customFormat = LocalDate.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED); char(' '); day(); chars(", "); year()
}
check(LocalDate.parseOrNull("Apr 16, 2024", customFormat) == LocalDate(2024, Month.APRIL, 16))
check(LocalDate.parseOrNull("no date here", customFormat) == null)
check(LocalDate.parseOrNull("Apr 99, 2024", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun LocalDateTime.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalDateTime>): LocalDateTime?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalDateTime value, or null if the string does not match the format or does not represent a valid LocalDateTime.

If format is not specified, LocalDateTime.Formats.ISO is used. 2023-01-02T23:40:57.120 is an example of a string in this format.

See LocalDateTime.Formats and LocalDateTime.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing LocalDateTime values using predefined and custom formats or failing
check(LocalDateTime.parseOrNull("2024-02-15T08:30:15.123456789") ==
        LocalDate(2024, 2, 15).atTime(8, 30, 15, 123_456_789))
val customFormat = LocalDateTime.Format {
    date(LocalDate.Formats.ISO)
    char(' ')
    hour(); char(':'); minute(); char(':'); second()
    char(','); secondFraction(fixedLength = 3)
}
check(LocalDateTime.parseOrNull("2024-02-15 08:30:15,123", customFormat) ==
        LocalDate(2024, 2, 15).atTime(8, 30, 15, 123_000_000))
check(LocalDateTime.parseOrNull("2024-02-15 08:30:15", customFormat) == null)
check(LocalDateTime.parseOrNull("2024-02-15 99:99:99,999", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun LocalTime.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<LocalTime>): LocalTime?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed LocalTime value, or null if the string does not match the format or does not represent a valid LocalTime.

If format is not specified, LocalTime.Formats.ISO is used. 23:40:57.120 is an example of a string in this format.

See LocalTime.Formats and LocalTime.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing a LocalTime from a string using predefined and custom formats
check(LocalTime.parseOrNull("08:30:15.123456789") == LocalTime(8, 30, 15, 123_456_789))
val customFormat = LocalTime.Format {
    hour(); char(':'); minute(); char(':'); second()
    alternativeParsing({ char(',') }) { char('.') } // parse either a dot or a comma
    secondFraction(fixedLength = 3)
}
check(LocalTime.parseOrNull("08:30:15,123", customFormat) == LocalTime(8, 30, 15, 123_000_000))
check(LocalTime.parseOrNull("ten past twelve", customFormat) == null)
check(LocalTime.parseOrNull("99:99:99,123", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun UtcOffset.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<UtcOffset>): UtcOffset?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed UtcOffset value, or null if the string does not match the format or does not represent a valid UtcOffset.

If format is not specified, UtcOffset.Formats.ISO is used. +01:30 is an example of a string in this format.

See UtcOffset.Formats and UtcOffset.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing a UtcOffset from a string using predefined and custom formats or failing
check(UtcOffset.parseOrNull("+01:30")?.totalSeconds == 5400)
check(UtcOffset.parseOrNull("+0130", UtcOffset.Formats.FOUR_DIGITS)?.totalSeconds == 5400)
val customFormat = UtcOffset.Format { offsetHours(Padding.NONE); offsetMinutesOfHour() }
check(UtcOffset.parseOrNull("+130", customFormat)?.totalSeconds == 5400)
check(UtcOffset.parseOrNull("Europe/Berlin", customFormat) == null)
check(UtcOffset.parseOrNull("+9999", customFormat) == null) 
   //sampleEnd
}
Content copied to clipboard
actual fun YearMonth.Companion.parseOrNull(input: CharSequence, format: DateTimeFormat<YearMonth>): YearMonth?(source)

A shortcut for calling DateTimeFormat.parseOrNull.

Parses a string that represents a date and returns the parsed YearMonth value, or null if the string does not match the format or does not represent a valid YearMonth.

If format is not specified, YearMonth.Formats.ISO is used. 2023-01 is an example of a string in this format.

See YearMonth.Formats and YearMonth.Format for predefined and custom formats.

See also

for formatting using the default format.

for formatting using a custom format.

for a version of this function that throws an exception on faulty input.

Samples

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

fun main() { 
   //sampleStart 
   // Parsing YearMonth values or failing
check(YearMonth.parseOrNull("2024-01") == YearMonth(2024, 1))
check(YearMonth.parseOrNull("2024-13") == null) 
   //sampleEnd
}
Content copied to clipboard