code- Module
- Strings →
- Receiver
- string
- Minimum arity
- 1
- Maximum arity
- 1
Declaration and parameters
Availability
Included by default · yes
These types are provided by the language. No module import is required.
The declarations below describe the standard operations on built-in values.
Receiver
string
Parameter constraints
string. returns Option<int>. Index i counts Unicode scalars in the order of scalars(). It never counts UTF-8 bytes.
An index from zero to one less than the scalar count returns Some with the Unicode value of that scalar. A negative index or an index at or past the scalar count returns None(). The call does not fault for an index outside the text.
string. returns the number of bytes in the UTF-8 encoding of the stored scalars. Empty text returns 0. The count does not normalize text.
string. returns Array<string>. It scans the text from the start and divides it at each occurrence of sep that does not overlap an earlier occurrence.
The pieces keep source order. Adjacent separators and separators at either end produce empty pieces. Text without sep returns one piece that holds the whole text. Empty text returns one empty piece. Joining the pieces with sep reproduces the text.
An empty separator faults at run time with TPZ5001 at the call. Divide text into Unicode scalars with scalars() or into grapheme clusters with graphemes().
Result
The declared result type is Option<int>.
Effects
Failures
Result and effects
Index i counts Unicode scalars in the order of scalars(). An index outside the text returns None() and does not fault.
Related entries
Read code points, byte counts and separated pieces
Read code points, byte counts and separated pieces
string. returns Option<int>. Index i counts Unicode scalars in the order of scalars(). It never counts UTF-8 bytes.
An index from zero to one less than the scalar count returns Some with the Unicode value of that scalar. A negative index or an index at or past the scalar count returns None(). The call does not fault for an index outside the text.
string. returns the number of bytes in the UTF-8 encoding of the stored scalars. Empty text returns 0. The count does not normalize text.
string. returns Array<string>. It scans the text from the start and divides it at each occurrence of sep that does not overlap an earlier occurrence.
The pieces keep source order. Adjacent separators and separators at either end produce empty pieces. Text without sep returns one piece that holds the whole text. Empty text returns one empty piece. Joining the pieces with sep reproduces the text.
An empty separator faults at run time with TPZ5001 at the call. Divide text into Unicode scalars with scalars() or into grapheme clusters with graphemes().
Why
Text algorithms name their unit. code uses the scalar unit of scalars() and reports absence as a value, so a classifier can read the first scalar of any text without a separate length test. byte gives the UTF-8 size that wire formats and byte limits use. split divides text at literal separator text, while Regex. divides it at a pattern. An empty separator marks no position, so the call faults and the program chooses a text unit explicitly.
Read scalar values by scalar index
import std.iofunction show(value: Option<int>) -> string {match (value) {case Some(point) => "{point}"case None() => "none"}}let text = "a가😀"for index in ([-1, 0, 1, 2, 3]) {io.writeLine("{index}: {show(text.codePointAt(index))}")}
-1: none
0: 97
1: 44032
2: 128512
3: none
Expected result
Expected result
Execution completes. Exit code 0.
-1: none0: 971: 440322: 1285123: none
Compare scalar counts with UTF-8 byte counts
import std.iofor text in (["", "a", "가", "😀", "a가😀"]) {io.writeLine("{text.scalars().length} {text.byteLength()}")}
0 0
1 1
1 3
1 4
3 8
Expected result
Expected result
Execution completes. Exit code 0.
0 01 11 31 43 8
Keep empty pieces between separators
import std.iofunction show(pieces: Array<string>) -> string {"{pieces.length} [{pieces.join("|")}]"}io.writeLine(show("a,b,,c,".split(",")))io.writeLine(show("a::b".split("::")))io.writeLine(show("aaa".split("aa")))io.writeLine(show("plain".split(",")))io.writeLine(show("".split(",")))let text = ",x,"io.writeLine("{text.split(",").join(",") == text}")
5 [a|b||c|]
2 [a|b]
2 [|a]
1 [plain]
1 []
true
Expected result
Expected result
Execution completes. Exit code 0.
5 [a|b||c|]2 [a|b]2 [|a]1 [plain]1 []true
Fault on an empty separator
import std.iolet separator = ""let _ = "abc".split(separator)io.writeLine("after")
No stdout.Expected result
Expected result
Rejection during run. Nonzero exit.
stdlib-string-split-empty-separator at
main.tpz:4:9