replaceFirst

inline fun CharSequence.replaceFirst(regex: Regex, replacement: String): String(source)

Replaces the first occurrence of the given regular expression regex in this char sequence with the specified replacement expression.

This is a convenience function that is equivalent to regex.replaceFirst(this, replacement). For details about its behaviour and the substitution syntax of replacement expression, refer to Regex.replaceFirst.

Since Kotlin

1.0

Samples

import java.util.Locale
import kotlin.test.*

fun main() { 
   //sampleStart 
   val text = "The events are on 15-09-2024 and 16-10-2024."
// Regex to match dates in dd-mm-yyyy format
val dateRegex = "(?<day>\\d{2})-(?<month>\\d{2})-(?<year>\\d{4})".toRegex()
// Replacement expression that puts day, month and year values in the ISO 8601 recommended yyyy-mm-dd format
val replacement = "\${year}-\${month}-\${day}"

// Replacing the first occurrence of a date from dd-mm-yyyy to yyyy-mm-dd format
println(text.replaceFirst(dateRegex, replacement)) // The events are on 2024-09-15 and 16-10-2024.

// One can also reference the matched groups by index
println(text.replaceFirst(dateRegex, "$3-$2-$1")) // The events are on 2024-09-15 and 16-10-2024.

// Using a backslash to include the special character '$' as a literal in the result
println(text.replaceFirst(dateRegex, "$3-\\$2-$1")) // The events are on 2024-\$2-15 and 16-10-2024. 
   //sampleEnd
}

expect fun String.replaceFirst(oldChar: Char, newChar: Char, ignoreCase: Boolean = false): String(source)

Returns a new string with the first occurrence of oldChar replaced with newChar.

Since Kotlin

1.0

expect fun String.replaceFirst(oldValue: String, newValue: String, ignoreCase: Boolean = false): String(source)

Returns a new string obtained by replacing the first occurrence of the oldValue substring in this string with the specified newValue string.

Since Kotlin

1.0
actual fun String.replaceFirst(oldChar: Char, newChar: Char, ignoreCase: Boolean = false): String(source)
actual fun String.replaceFirst(oldValue: String, newValue: String, ignoreCase: Boolean = false): String(source)

Since Kotlin

1.1
actual fun String.replaceFirst(oldChar: Char, newChar: Char, ignoreCase: Boolean = false): String(source)

Returns a new string with the first occurrence of oldChar replaced with newChar.

Since Kotlin

1.0

actual fun String.replaceFirst(oldValue: String, newValue: String, ignoreCase: Boolean = false): String(source)

Returns a new string obtained by replacing the first occurrence of the oldValue substring in this string with the specified newValue string.

Since Kotlin

1.0
actual fun String.replaceFirst(oldChar: Char, newChar: Char, ignoreCase: Boolean = false): String(source)

Returns a new string with the first occurrence of oldChar replaced with newChar.

Since Kotlin

1.3

actual fun String.replaceFirst(oldValue: String, newValue: String, ignoreCase: Boolean = false): String(source)

Returns a new string obtained by replacing the first occurrence of the oldValue substring in this string with the specified newValue string.

Since Kotlin

1.3
actual fun String.replaceFirst(oldChar: Char, newChar: Char, ignoreCase: Boolean = false): String(source)

Returns a new string with the first occurrence of oldChar replaced with newChar.

Since Kotlin

1.8

actual fun String.replaceFirst(oldValue: String, newValue: String, ignoreCase: Boolean = false): String(source)

Returns a new string obtained by replacing the first occurrence of the oldValue substring in this string with the specified newValue string.

Since Kotlin

1.8
actual fun String.replaceFirst(oldChar: Char, newChar: Char, ignoreCase: Boolean = false): String(source)

Returns a new string with the first occurrence of oldChar replaced with newChar.

Since Kotlin

1.8

actual fun String.replaceFirst(oldValue: String, newValue: String, ignoreCase: Boolean = false): String(source)

Returns a new string obtained by replacing the first occurrence of the oldValue substring in this string with the specified newValue string.

Since Kotlin

1.8