What is the use of `regexp:Groups` and how to access it in ballerina regexp?

I need to know it what are the use cases of regexp:Groups object?

When we need to extract specific parts of the matched string we need capturing groups. By enclosing a portion of the regex pattern in parentheses, it forms a capturing group. The Groups type defined as below, in the ballerina regexp package helps to extract these specific parts.

public type Groups readonly & [Span, Span?...];

Groups is an intersection between readonly and a list of Span objects. The 0-th member of the list represents the matching substring for the full regular expression pattern. The i-th index member when i>1 will result in the sub string which matches the i-th capturing group.

Let's say you need to match a string to date pattern like,DD-MM-YYYY. And you need to extract date, month and year values. In this kind of a scenario you can use capturing groups to extract these specific values. Below ballerina code will help you to understand it further.

import ballerina/io;
import ballerina/lang.regexp;

public function main() {
    string date = "13-11-2023";
    regexp:Groups? result = re `(\d{2})-(\d{2})-(\d{4})`.findGroups(date);
    if result is regexp:Groups {
        io:println(result[0].substring()); // 13-11-2023

        regexp:Span? day = result[1];
        if day !is () {
            io:println(day.substring()); // 13
        }
        
        regexp:Span? month = result[2];
        if month !is () {
            io:println(month.substring()); // 11
        }

        regexp:Span? year = result[3];
        if year !is () {
            io:println(year.substring()); // 2023
        }
    }
}