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

    Match.groups

    An independent array of optional numbered captures beginning with the complete match at zero.

    Match.groups: Array<Option<string>>
    Module
    std.regex
    Receiver
    Match
    Minimum arity
    0
    Maximum arity
    0

    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

    Match

    Parameter constraints

    Additional contracts are Pending.

    Match.start and Match.end are read-only nonnegative UTF-8 byte offsets in the original input. They follow the inclusive start and exclusive end of byte intervals. Both are scalar boundaries and the end does not exceed the UTF-8 byte length of the input.

    Match.text is the matched substring. An empty match has equal start and end and an empty text value. The offsets are not string grapheme indexes. A match may select a combining mark inside a grapheme.

    Encoding the original input with encodeUtf8, slicing its bytes from start to end, and calling decodeUtf8 returns Ok containing Match.text. This relationship also holds for non-ASCII input.

    Match.groups returns an independent array indexed by capture number. Entry zero is Some containing the entire match. Capturing parentheses are numbered from one in opening-parenthesis order. Named groups participate in the same numbering and noncapturing groups do not.

    A nonparticipating capture has value None(). A participating empty capture has value Some containing an empty string. A repeated capture retains the last participating capture in the selected match.

    Match.named returns an independent map from capture names to captured strings. A nonparticipating named capture is absent. A participating empty named capture is present with an empty string. Names are inserted in ascending ASCII order.

    Reading a Match field evaluates its receiver once and does not modify the Match or input. Mutating a groups array or named map does not affect a later field read. Field access cannot fail for a Match value.

    Related rule: Read match boundaries and capture snapshots

    Result

    Additional contracts are Pending.

    The declared result type is Array<Option<string>>.

    Effects

    Pending

    Failures

    Pending

    Result and effects

    Link

    Select this field from a value of its named type without call parentheses.

    An independent array of optional numbered captures beginning with the complete match at zero.

    Resolved contracts

    Link

    Related entries

    Link

    std.regex

    Read match boundaries and capture snapshots

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

    Read match boundaries and capture snapshots

    Match.start and Match.end are read-only nonnegative UTF-8 byte offsets in the original input. They follow the inclusive start and exclusive end of byte intervals. Both are scalar boundaries and the end does not exceed the UTF-8 byte length of the input.

    Match.text is the matched substring. An empty match has equal start and end and an empty text value. The offsets are not string grapheme indexes. A match may select a combining mark inside a grapheme.

    Encoding the original input with encodeUtf8, slicing its bytes from start to end, and calling decodeUtf8 returns Ok containing Match.text. This relationship also holds for non-ASCII input.

    Match.groups returns an independent array indexed by capture number. Entry zero is Some containing the entire match. Capturing parentheses are numbered from one in opening-parenthesis order. Named groups participate in the same numbering and noncapturing groups do not.

    A nonparticipating capture has value None(). A participating empty capture has value Some containing an empty string. A repeated capture retains the last participating capture in the selected match.

    Match.named returns an independent map from capture names to captured strings. A nonparticipating named capture is absent. A participating empty named capture is present with an empty string. Names are inserted in ascending ASCII order.

    Reading a Match field evaluates its receiver once and does not modify the Match or input. Mutating a groups array or named map does not affect a later field read. Field access cannot fail for a Match value.

    Why

    Byte offsets identify every exact match even when a pattern selects part of a grapheme. The byte-slice relationship makes those offsets usable without confusing them with text indexing. Optional numbered captures and omitted named entries distinguish absence from a captured empty string.

    Examples Report UTF-8 byte offsets for non-ASCII matchesRecover a match through the byte slice identified by its offsetsKeep capture zero and distinguish missing and empty capturesOmit absent named captures and retain a captured empty string

    Source evidence

    Report UTF-8 byte offsets for non-ASCII matches

    Link

    run · running · Verification: not-run

    main.tpzReport UTF-8 byte offsets for non-ASCII matchesOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. function show(patternText: string, text: string) -> () {
    5. match (Regex.compile(patternText)) {
    6. case Ok(pattern) => {
    7. match (pattern.find(text)) {
    8. case Some(found) => io.writeLine("{found.start}:{found.end}:{found.text}")
    9. case None() => io.writeLine("no match")
    10. }
    11. }
    12. case Err(_) => io.writeLine("compile failed")
    13. }
    14. }
    15. show("한", "é한🙂")
    16. show("́", "éx")
    Expected outputexit 0
    2:5:한
1:3:́
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 2:5:한
    2. 1:3:́

    This exact example has not been executed.

    Source evidence

    Recover a match through the byte slice identified by its offsets

    Link

    run · running · Verification: not-run

    main.tpzRecover a match through the byte slice identified by its offsetsOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. let text = "한x"
    5. match (Regex.compile("한")) {
    6. case Ok(pattern) => {
    7. match (pattern.find(text)) {
    8. case Some(found) => {
    9. let bytes = text.encodeUtf8().slice(found.start, found.end)
    10. match (bytes.decodeUtf8()) {
    11. case Ok(decoded) => io.writeLine(decoded)
    12. case Err(_) => io.writeLine("invalid UTF-8 slice")
    13. }
    14. }
    15. case None() => io.writeLine("no match")
    16. }
    17. }
    18. case Err(_) => io.writeLine("compile failed")
    19. }
    Expected outputexit 0
    한
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 한

    This exact example has not been executed.

    Source evidence

    Keep capture zero and distinguish missing and empty captures

    Link

    run · running · Verification: not-run

    main.tpzKeep capture zero and distinguish missing and empty capturesOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. match (Regex.compile("(?<word>a)(b)?()")) {
    5. case Ok(pattern) => {
    6. match (pattern.find("a")) {
    7. case Some(found) => {
    8. io.writeLine("{found.groups.length}")
    9. for group in (found.groups) {
    10. match (group) {
    11. case Some(text) => io.writeLine("some={text}")
    12. case None() => io.writeLine("none")
    13. }
    14. }
    15. }
    16. case None() => io.writeLine("no match")
    17. }
    18. }
    19. case Err(_) => io.writeLine("compile failed")
    20. }
    Expected outputexit 0
    4
some=a
some=a
none
some=
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. 4
    2. some=a
    3. some=a
    4. none
    5. some=

    This exact example has not been executed.

    Source evidence

    Omit absent named captures and retain a captured empty string

    Link

    run · running · Verification: not-run

    main.tpzOmit absent named captures and retain a captured empty stringOpen in Playground
    1. import std.regex { Regex }
    2. import std.io
    4. match (Regex.compile("(?<z>a)?(?<a>b*)")) {
    5. case Ok(pattern) => {
    6. match (pattern.find("")) {
    7. case Some(found) => {
    8. let mut snapshot = found.named
    9. let hasOptional = snapshot.containsKey("z")
    10. io.writeLine("{hasOptional}")
    11. match (snapshot.get("a")) {
    12. case Some(text) => io.writeLine("some={text}")
    13. case None() => io.writeLine("none")
    14. }
    15. snapshot.insert("a", "changed")
    16. match (found.named.get("a")) {
    17. case Some(text) => io.writeLine("again={text}")
    18. case None() => io.writeLine("none")
    19. }
    20. }
    21. case None() => io.writeLine("no match")
    22. }
    23. }
    24. case Err(_) => io.writeLine("compile failed")
    25. }
    Expected outputexit 0
    false
some=
again=
    $ topaz run main.tpz · target product 5.21.3
    Expected result

    Expected result

    Execution completes. Exit code 0.

    No stderr.

    Expected stdout
    1. false
    2. some=
    3. again=

    This exact example has not been executed.

    Source evidence

    Menu

    Download