Merge pull request #376 from ballerina-platform/build

Add proposals

Author: kalaiyarasiganeshalingam

docs/proposals/extract_substring.md

@@ -0,0 +1,82 @@
+# Proposal: Introduce APIs to extract a substring/s from the given string
+
+_Owners_: @daneshk @kalaiyarasiganeshalingam  
+_Reviewers_: @daneshk  
+_Created_: 2022/03/11   
+_Updated_: 2022/03/11  
+_Issues_: [#2689](https://github.com/ballerina-platform/ballerina-standard-library/issues/2689) 
+
+## Summary
+The Ballerina Regex module doesn't have any API to extract a substring/s from the given string by using regex. So, this proposal introduces new APIs to extract a substring/s from the given string using regex.
+
+## Goals
+Provide a way to extract a substring/s using regex.
+
+## Motivation
+As mentioned in the summary, at the moment, users have no way to extract a substring/s from the given string. But this is an important feature in string manipulation. So, this allows users to extract a substring/s easily by using Ballerina.
+
+## Description
+
+```ballerina
+# Holds the matched substring and its position in the input string.
+#
+# + matched - Matched substring
+# + startIndex - The start index of the match
+# + endIndex - The last index of the match
+type PartMatch record {|
+string matched;
+int startIndex;
+int endIndex;
+|};
+```
+
+```ballerina
+# Holds information about matched regex groups
+public type Groups readonly & object {
+int count;
+// Capture groups are indexed from 1
+// Group 0 means whole regex
+// Panics if i < 0 or > count
+isolated function get(int i) returns PartMatch?;
+};
+```
+
+```ballerina
+# Holds the results of a match against a regular expression.
+# It contains the match boundaries, groups and group boundaries.
+#
+# + groups - Information about matched regex groups
+public type Match record {|
+// The match for the whole regex
+*PartMatch;
+Groups groups;
+|};
+```
+
+```ballerina
+# Returns the first substring in str that matches the regex.
+# ```ballerina
+# regex:Match? result = regex:search("Betty Botter bought some butter but she said the butter’s bitter.", 
+#                                    "\\b[bB].tt[a-z]*");
+# ```
+#
+# + str - The string to be matched
+# + regex - The regex value
+# + startIndex - The starting index for the search
+# + return - a `Match` record which holds the matched substring, or nil if there is no match
+public isolated function search(string str, string regex, int startIndex = 0) returns Match?;
+```
+
+```ballerina
+# Returns all substrings in str that match the regex.
+# ```ballerina
+# regex:Match[] result = regex:searchAll("Betty Botter bought some butter but she said the butter’s bitter.", 
+#                                       "\\b[bB].tt[a-z]*");
+# ```
+#
+# + str - The string to be matched
+# + regex - The regex value
+# + return - An array of `Match` records
+# Each member holds a matched substring
+public isolated function searchAll(string str, string regex) returns Match[];
+```

docs/proposals/update_replace_functions.md

@@ -0,0 +1,92 @@
+# Proposal: Improve the replacement functions
+
+_Owners_: @daneshk @kalaiyarasiganeshalingam  
+_Reviewers_: @daneshk  
+_Created_: 2022/03/11   
+_Updated_: 2022/03/11  
+_Issues_: [#2772](https://github.com/ballerina-platform/ballerina-standard-library/issues/2772) 
+
+## Summary
+The existing replacement functions don't support the following functionalities:
+- There is no way to replace the matches from the particular string index of the given string.
+- There isn't any mechanism to replace the matches with a dynamic value.
+
+So, this proposal improves the replacement functions to support the above functionalities.
+
+## Goals
+Provide a way to support the above functionalities.
+
+## Motivation
+This allows users to get the above functionalities when using replacement functions.
+
+## Description
+API improvements are:
+
+- Introduce a function to create the new substring to be used to replace the matches. 
+    ```ballerina
+    # A function to be invoked to create the new substring to be used to replace the matches.
+    type ReplacerFunction function(Match matched) returns string;
+    ```
+
+- Introduce a new type to get the replacement value.  
+    ```ballerina
+    # A function to be invoked to create the new substring or string value to be used to replace the matches.
+    public type Replacement ReplacerFunction|string;
+    ```
+
+- Change the type of replacement param from string to `Replacement` type.
+    ```ballerina
+    # Replaces each occurrence of the substrings, which match the provided
+    # regex from the given original string value with the
+    # provided replacement string.
+    # ```ballerina
+    # string result = regex:replaceAll("Ballerina is great", "\\s+", "_");
+    # ```
+    #
+    # + originalString - The original string to replace the occurrences of the
+    #                    substrings that match the provided regex
+    # + regex - The regex to match the substrings in the `originalString` , which is to be replaced
+    # + replacement - The replacement string or function to replace the substrings, which
+    #                 match the regex
+    # + return - The resultant string with the replaced substrings
+    public isolated function replaceAll(string originalString, string regex, Replacement replacement) returns string;
+    ```
+
+- Introduce a new function to replace the first substring from the given start index of the string.
+  This is an improved function from the `replaceFirst`.
+    ```ballerina
+    # Replaces the first substring that matches the given regex with
+    # the provided replacement string or function.
+    # ```ballerina
+    # string result = regex:replace("Ballerina is great", "\\s+", "_");
+    # ```
+    #
+    # + originalString - The original string to replace the first occurrence of the
+    #                    substring that matches the provided regex
+    # + regex - The regex to match the first substring in the `originalString` to
+    #           be replaced
+    # + replacement - The replacement string or function to replace the first substring, which
+    #                 matches the regex
+    # + startIndex - The starting index for the search
+    # + return - The resultant string with the replaced substring
+    public isolated function replace(string originalString, string regex, Replacement replacement, int startIndex = 0) 
+                             returns string;
+    ```
+  
+- Deprecate the existing `replaceFirst` function.
+    ```ballerina
+    # Replaces the first substring that matches the given regex with
+    # the provided replacement string.
+    # ```ballerina
+    # string result = regex:replaceFirst("Ballerina is great", "\\s+", "_");
+    # ```
+    #
+    # + originalString - The original string to replace the first occurrence of the
+    #                    substring that matches the provided regex
+    # + regex - The regex to match the first substring in the `originalString` to
+    #           be replaced
+    # + replacement - The replacement string to replace the first substring, which
+    #                 matches the regex
+    # + return - The resultant string with the replaced substring
+    public isolated function replaceFirst(string originalString, string regex, string replacement) returns string;
+    ```