Skip to content
Topaz6.0 · Before release
Download

Search documentation

Specification 6.0 · Not released · Tested product 5.21.3

Use arrow keys to choose a result. Press Enter to open.

Type an API name, diagnostic number, rule, or project topic.

    Library · std.regex

    Regex.split

    Returns the input portions between selected matches and retains empty portions.

    split(text: string) -> Array<string>
    Module
    std.regex
    Receiver
    Regex
    Minimum arity
    1
    Maximum arity
    1

    Declaration and parameters

    Link

    Availability

    Included by default: Pending

    Import std.regex in language mode 5.21.

    The current compiler selects std/regex.tpz for this language mode. Availability in other released editions and inclusion in each installed distribution are Pending.

    Source evidence

    Receiver

    Regex

    Parameter constraints

    Additional contracts are Pending.

    Regex.split returns the input portions between the matches selected by findAll. Delimiters disappear and capture groups are not inserted. Empty portions at either end and between adjacent delimiters are retained. No match produces an array containing the original input.

    Regex.replaceAll replaces the same nonoverlapping matches while copying all text between them unchanged. No match returns the original text. The operation does not search inserted replacement text.

    Replacement references use a dollar sign followed by a braced capture number or name. Capture zero denotes the complete match. An unknown or nonparticipating capture expands to an empty string. Two dollar signs produce one literal dollar.

    A replacement selector is a nonnegative decimal capture number or an ASCII capture name. Dollar text that is neither a double dollar nor a well-formed braced selector is literal. Unbraced dollar names and numbers do not form references. Expansion is performed once and captured dollar text is not expanded again.

    An empty pattern splits at every scalar boundary and inserts replacement text at those same boundaries. The adjacent-empty-match rule from findAll also applies when a nonempty match is followed by an empty candidate.

    The receiver is evaluated once before text and replacement arguments, which are evaluated once from left to right. Splitting and replacement leave the original string and Regex unchanged. They have no external effects and do not call a user callback.

    Related rule: Split and replace using the shared match sequence

    Result

    Additional contracts are Pending.

    The declared result type is Array<string>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Returns the input portions between selected matches and retains empty portions.

    Resolved contracts

    Link

    Related entries

    Link

    std.regex

    Split and replace using the shared match sequence

    Link
    Ruletopaz.stdlib.contract.regex-transform.rule

    Split and replace using the shared match sequence

    Regex.split returns the input portions between the matches selected by findAll. Delimiters disappear and capture groups are not inserted. Empty portions at either end and between adjacent delimiters are retained. No match produces an array containing the original input.

    Regex.replaceAll replaces the same nonoverlapping matches while copying all text between them unchanged. No match returns the original text. The operation does not search inserted replacement text.

    Replacement references use a dollar sign followed by a braced capture number or name. Capture zero denotes the complete match. An unknown or nonparticipating capture expands to an empty string. Two dollar signs produce one literal dollar.

    A replacement selector is a nonnegative decimal capture number or an ASCII capture name. Dollar text that is neither a double dollar nor a well-formed braced selector is literal. Unbraced dollar names and numbers do not form references. Expansion is performed once and captured dollar text is not expanded again.

    An empty pattern splits at every scalar boundary and inserts replacement text at those same boundaries. The adjacent-empty-match rule from findAll also applies when a nonempty match is followed by an empty candidate.

    The receiver is evaluated once before text and replacement arguments, which are evaluated once from left to right. Splitting and replacement leave the original string and Regex unchanged. They have no external effects and do not call a user callback.

    Why

    Using one match sequence prevents a search from disagreeing with a later replacement. Braced capture references have one spelling and an explicit end, so a capture name cannot absorb following replacement text.

    Examples Retain empty split fields without inserting capturesExpand braced capture references and a literal dollarPreserve text that is not a braced referenceSplit and replace at each empty-pattern boundaryShare the adjacent-empty-match rule across transformationsEvaluate receiver and replacement inputs once in source order

    Source evidence

    Retain empty split fields without inserting captures

    Link

    run · running · Verification: not-run

    main.tpzRetain empty split fields without inserting capturesOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. match (Regex.compile("(,)")) {
    5. case Ok(pattern) => {
    6. for field in (pattern.split(",a,,b,")) {
    7. io.writeLine("[{field}]")
    8. }
    9. for field in (pattern.split("plain")) {
    10. io.writeLine("[{field}]")
    11. }
    12. }
    13. case Err(_) => io.writeLine("compile failed")
    14. }
    Expected outputexit 0
    []
[a]
[]
[b]
[]
[plain]
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. []
    2. [a]
    3. []
    4. [b]
    5. []
    6. [plain]

    This exact example has not been executed.

    Source evidence

    Expand braced capture references and a literal dollar

    Link

    run · running · Verification: not-run

    main.tpzExpand braced capture references and a literal dollarOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. match (Regex.compile("(?<word>[a-z]+)([0-9]+)?")) {
    5. case Ok(pattern) => {
    6. let replacement = "$\{word\}/$\{0\}/$\{2\}/$\{missing\}/$$"
    7. io.writeLine(pattern.replaceAll("a1 b", replacement))
    8. io.writeLine(pattern.replaceAll("123", replacement))
    9. }
    10. case Err(_) => io.writeLine("compile failed")
    11. }
    Expected outputexit 0
    a/a1/1//$ b/b///$
123
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. a/a1/1//$ b/b///$
    2. 123

    This exact example has not been executed.

    Source evidence

    Preserve text that is not a braced reference

    Link

    run · running · Verification: not-run

    main.tpzPreserve text that is not a braced referenceOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. match (Regex.compile("a")) {
    5. case Ok(pattern) => io.writeLine(pattern.replaceAll("a", "$word $1 $ $\{\} $\{bad-name\}"))
    6. case Err(_) => io.writeLine("compile failed")
    7. }
    Expected outputexit 0
    $word $1 $ ${} ${bad-name}
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. $word $1 $ ${} ${bad-name}

    This exact example has not been executed.

    Source evidence

    Split and replace at each empty-pattern boundary

    Link

    run · running · Verification: not-run

    main.tpzSplit and replace at each empty-pattern boundaryOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. match (Regex.compile("")) {
    5. case Ok(pattern) => {
    6. for field in (pattern.split("ab")) {
    7. io.writeLine("[{field}]")
    8. }
    9. io.writeLine(pattern.replaceAll("ab", "-"))
    10. }
    11. case Err(_) => io.writeLine("compile failed")
    12. }
    Expected outputexit 0
    []
[a]
[b]
[]
-a-b-
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. []
    2. [a]
    3. [b]
    4. []
    5. -a-b-

    This exact example has not been executed.

    Source evidence

    Share the adjacent-empty-match rule across transformations

    Link

    run · running · Verification: not-run

    main.tpzShare the adjacent-empty-match rule across transformationsOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. match (Regex.compile("a*")) {
    5. case Ok(pattern) => {
    6. for field in (pattern.split("ab")) {
    7. io.writeLine("[{field}]")
    8. }
    9. io.writeLine(pattern.replaceAll("ab", "-"))
    10. }
    11. case Err(_) => io.writeLine("compile failed")
    12. }
    Expected outputexit 0
    []
[b]
[]
-b-
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. []
    2. [b]
    3. []
    4. -b-

    This exact example has not been executed.

    Source evidence

    Evaluate receiver and replacement inputs once in source order

    Link

    run · running · Verification: not-run

    main.tpzEvaluate receiver and replacement inputs once in source orderOpen in Playground
    1. import std.regex { Regex }
    2. import std.test
    3. import std.io
    5. function makePattern() -> Regex {
    6. io.writeLine("receiver")
    7. return test.assertOk(Regex.compile("a"))
    8. }
    9. function inputText() -> string {
    10. io.writeLine("text")
    11. return "a"
    12. }
    13. function replacementText() -> string {
    14. io.writeLine("replacement")
    15. return "b"
    16. }
    17. io.writeLine(makePattern().replaceAll(inputText(), replacementText()))
    Expected outputexit 0
    receiver
text
replacement
b
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. receiver
    2. text
    3. replacement
    4. b

    This exact example has not been executed.

    Source evidence

    Menu

    Download