String0.27.1

Overview
Properties
Methods

external class String extends Any

A sequence of Unicode characters (code points).

Known subtypes:
Known usages:
All versions:

The following operators are supported for strings:

str[3]      // subscript
str1 + str2 // concatenation

Properties

link
length: Int

The number of characters in this string.

Also known as:

size, count
Note: The runtime complexity of this operation is O(n).

Facts:
```
"".length == 0
"abc".length == 3
```
link
lastIndex: Int

The index of the last character in this string (same as length - 1).
Returns -1 for an empty string.

Note: The runtime complexity of this operation is O(n).

Facts:
```
"".lastIndex == -1
"abc".lastIndex == 2
```
link
isEmpty: Boolean

Tells whether this string is empty.
Facts:
```
"".isEmpty
!("   ".isEmpty)
!("abc".isEmpty)
```
link
isBlank: Boolean

Tells if all characters in this string have Unicode property "White_Space".
Facts:
```
"".isBlank
"   ".isBlank
"\t\n\r".isBlank
!("abc".isBlank)
```
link

isRegex: Boolean

Tells if this string is a valid regular expression according to Regex.
link

md5: String

The MD5 hash of this string's UTF-8 byte sequence as hexadecimal string.

MD5 is cryptographically broken and should not be used for secure applications.
link

sha1: String

The SHA-1 hash of this string's UTF-8 byte sequence.

SHA-1 is cryptographically broken and should not be used for secure applications.
link

sha256: String

The SHA-256 cryptographic hash of this string's UTF-8 byte sequence as hexadecimal string.
link

sha256Int: Int

The first 64 bits of the SHA-256 cryptographic hash of this string's UTF-8 byte sequence.
link

base64: String

The Base64 encoding of this string's UTF-8 byte sequence.
link
base64Decoded: String

The inverse of base64.
Facts:
```
"abc".base64.base64Decoded == "abc"
```
link
chars: List<Char>(this.length == length)

The Unicode characters in this string.
Facts:
```
"abc".chars == List("a", "b", "c")
```
link
codePoints: List<Int(isBetween(0, 0x10FFFF))>(this.length == length)

The Unicode code points in this string.
Facts:
```
"abc".codePoints == List(0x61, 0x62, 0x63)
```

Methods(show inherited)

link

function

Any.getClass(): Class (pkl.base)

Returns the class of this.
link

function

Any.toString(): String (pkl.base)

Returns a string representation of this.

This method is used to convert the values of string interpolation expressions to strings.
link

function

Any.ifNonNull<Result>(transform: (NonNull) -> Result): Result? (pkl.base)

Returns this |> transform if this is non-null, and null otherwise.

This method is the complement of the ?? operator and the equivalent of an Option type's map and flatMap methods.

link

function

getOrNull(index: Int): Char?

Returns the character at index, or null if index is out of range.

Facts:

"abcde".getOrNull(-1) == null
"abcde".getOrNull(0) == "a"
"abcde".getOrNull(2) == "c"
"abcde".getOrNull(4) == "e"
"abcde".getOrNull(5) == null

link

function
substring(start: Int, exclusiveEnd: Int): String

Returns the substring from start until exclusiveEnd.
Throws if start is outside range 0..length or exclusiveEnd is outside range start..length.

Facts:
```
"abcde".substring(0, 0) == ""
"abcde".substring(0, 1) == "a"
"abcde".substring(1, 4) == "bcd"
"abcde".substring(4, 5) == "e"
"abcde".substring(5, 5) == ""
```

link

function

substringOrNull(start: Int, exclusiveEnd: Int): String?

Returns the substring from start until exclusiveEnd.

Returns null if start is outside range 0..length or exclusiveEnd is outside range start..length.

Facts:

"abcde".substringOrNull(0, 0) == ""
"abcde".substringOrNull(0, 1) == "a"
"abcde".substringOrNull(1, 4) == "bcd"
"abcde".substringOrNull(4, 5) == "e"
"abcde".substringOrNull(5, 5) == ""

"abcde".substringOrNull(-1, 3) == null
"abcde".substringOrNull(0, 6) == null
"abcde".substringOrNull(3, 2) == null

link

function
repeat(count: UInt): String

Concatenates count copies of this string.
Facts:
```
"abc".repeat(0) == ""
"abc".repeat(1) == "abc"
"abc".repeat(3) == "abcabcabc"
```
link

function

contains(pattern: String|Regex): Boolean

Tells whether this string contains pattern.
link

function

matches(regex: Regex): Boolean

Tells whether this string matches regex in its entirety.

Also known as:

test
link

function

startsWith(pattern: String|Regex): Boolean

Tells whether this string starts with pattern.
link

function

endsWith(pattern: String|Regex): Boolean

Tells whether this string ends with pattern.
link

function

indexOf(pattern: String|Regex): Int

Returns the zero-based index of the first occurrence of pattern in this string.

Throws if pattern does not occur in this string.
link

function

indexOfOrNull(pattern: String|Regex): Int?

Returns the zero-based index of the first occurrence of pattern in this string, or null if pattern does not occur in this string.
link

function

lastIndexOf(pattern: String|Regex): Int

Returns the zero-based index of the last occurrence of pattern in this string.

Throws if pattern does not occur in this string.
link

function

lastIndexOfOrNull(pattern: String|Regex): Int?

Returns the zero-based index of the last occurrence of pattern in this string, or null if pattern does not occur in this string.
link

function

take(n: Int): String

Returns the first n characters of this string.

Also known as:

limit

Returns this if n is greater than or equal to length.
link

function

takeWhile(predicate: (String) -> Boolean): String

Returns the longest prefix of this string that satisfies predicate.
link

function

takeLast(n: Int): String

Returns the last n characters of this string.

Returns this if n is greater than or equal to length.
link

function

takeLastWhile(predicate: (String) -> Boolean): String

Returns the longest suffix of this string that satisfies predicate.
link

function

drop(n: Int): String

Removes the first n characters of this string.

Also known as:

skip

Returns the empty string if n is greater than or equal to length.
link

function

dropWhile(predicate: (String) -> Boolean): String

Removes the longest prefix of this string that satisfies predicate.

Also known as:

skipWhile
link

function

dropLast(n: Int): String

Removes the last n characters of this string.

Also known as:

skipLast

Returns the empty string if n is greater than or equal to length.
link

function

dropLastWhile(predicate: (String) -> Boolean): String

Removes the longest suffix of this string that satisfies predicate.

Also known as:

skipLastWhile
link

function

replaceFirst(pattern: String|Regex, replacement: String): String

Replaces the first occurrence of pattern in this string with replacement.

Returns this string unchanged if pattern does not occur in this string.
link

function

replaceLast(pattern: String|Regex, replacement: String): String

Replaces the last occurrence of pattern in this string with replacement.

Returns this string unchanged if pattern does not occur in this string.
link

function

replaceAll(pattern: String|Regex, replacement: String): String

Replaces all occurrences of pattern in this string with replacement.

Returns this string unchanged if pattern does not occur in this string.
link

function

replaceFirstMapped(pattern: String|Regex, mapper: (RegexMatch) -> String): String

Replaces the first occurrence of pattern in this string with the return value of mapper.

Returns this string unchanged if pattern does not occur in this string.
link

function

replaceLastMapped(pattern: String|Regex, mapper: (RegexMatch) -> String): String

Replaces the last occurrence of pattern in this string with the return value of mapper.

Returns this string unchanged if pattern does not occur in this string.
link

function

replaceAllMapped(pattern: String|Regex, mapper: (RegexMatch) -> String): String

Replaces all occurrences of pattern in this string with the return value of mapper.

Returns this string unchanged if pattern does not occur in this string.
link

function

replaceRange(start: Int, exclusiveEnd: Int, replacement: String): String

Replaces the characters between start and exclusiveEnd with replacement.

Inserts replacement at index start if start == exclusiveEnd.
link

function

toUpperCase(): String

Performs a locale-independent character-by-character conversion of this string to uppercase.
link

function

toLowerCase(): String

Performs a locale-independent character-by-character conversion of this string to lowercase.
link

function

reverse(): String

Reverses the order of characters in this string.
link

function

trim(): String

Removes any leading and trailing characters with Unicode property "White_Space" from this string.

Also known as:

strip
link

function

trimStart(): String

Removes any leading characters with Unicode property "White_Space" from this string.

Also known as:

stripLeft, stripStart, stripLeading, trimLeft, trimLeading
link

function

trimEnd(): String

Removes any trailing characters with Unicode property "White_Space" from this string.

Also known as:

stripRight, stripEnd, stripTrailing, trimRight, trimTrailin
link

function

padStart(width: Int, char: Char): unknown

Increases the length of this string to width by adding leading chars.

Also known as:

padLeft

Returns this string unchanged if its length is already equal to or greater than width.
link

function

padEnd(width: Int, char: Char): unknown

Increases the length of this string to width by adding trailing chars.

Also known as:

padRight

Returns this string unchanged if its length is already equal to or greater than width.
link

function

split(pattern: String|Regex): List<String>

Splits this string around matches of pattern.
link

function
splitLimit(pattern: String|Regex, limit: Int(this > 0)): List<String>

Splits this string matches of pattern, up to limit substrings.
Returns a List with at most limit elements. If the limit has been reached, the last entry will contain the un-split remainder of this string.

Facts:
```
"a.b.c".splitLimit(".", 2) == List("a", "b.c")
"a.b.c".splitLimit(".", 1) == List("a.b.c")
"a.b.c".splitLimit(".", 50) == List("a", "b", "c")
"a.b:c".splitLimit(Regex("[.:]"), 3) == List("a", "b", "c")
```
link

function
capitalize(): String

Converts the first character of this string to title case.
Facts:
```
"pigeon".capitalize() == "Pigeon"
"pigeon bird".capitalize() == "Pigeon bird"
"".capitalize() == ""
```
link

function
decapitalize(): String

Converts the first character of this string to lower case.
Facts:
```
"Pigeon".decapitalize() == "pigeon"
"Pigeon Bird".decapitalize() == "pigeon Bird"
"".decapitalize() == ""
```
link

function

toInt(): Int

Parses this string as a signed decimal (base 10) integer.

Throws if this string cannot be parsed as a signed decimal integer, or if the integer is too large to fit into Int.
link

function

toIntOrNull(): Int?

Parses this string as a signed decimal (base 10) integer.

Returns null if this string cannot be parsed as a signed decimal integer, or if the integer is too large to fit into Int.
link

function

toFloat(): Float

Parses this string as a floating point number.

Throws if this string cannot be parsed as a floating point number.
link

function

toFloatOrNull(): Float?

Parses this string as a floating point number.

Returns null if this string cannot be parsed as a floating point number.
link

function

toBoolean(): Boolean

Parses "true" to true and "false" to false (case-insensitive).

Throws if this string is neither "true" nor "false" (case-insensitive).
link

function

toBooleanOrNull(): Boolean?

Parses "true" to true and "false" to false (case-insensitive).

Returns null if this string is neither "true" nor "false" (case-insensitive).