Merge pull request #5815 from MaryamZi/add-rest-arg-bbe

Add a BBE for rest arguments

examples/default-values-for-function-parameters/default_values_for_function_parameters.md

@@ -9,3 +9,4 @@ Ballerina allows specifying default values for function parameters. You can use
 ## Related links
 - [Rest Parameters](/learn/by-example/rest-parameters/)
 - [Provide function arguments by name](/learn/by-example/provide-function-arguments-by-name/)
+- [Rest arguments](/learn/by-example/rest-arguments/)

examples/functions/functions.md

@@ -13,6 +13,7 @@ Function parameters are final variables and cannot be modified within the functi
 - [Rest Parameters](/learn/by-example/rest-parameters/)
 - [Default values for function parameters](/learn/by-example/default-values-for-function-parameters/)
 - [Provide function arguments by name](/learn/by-example/provide-function-arguments-by-name/)
+- [Rest arguments](/learn/by-example/rest-arguments/)
 - [Function pointers](/learn/by-example/function-pointers/)
 - [Function values](/learn/by-example/function-values/)
 - [Function types](/learn/by-example/function-types/)

examples/index.json

@@ -224,6 +224,13 @@
         "verifyOutput": true,
         "isLearnByExample": true
       },
+      {
+        "name": "Rest arguments",
+        "url": "rest-arguments",
+        "verifyBuild": true,
+        "verifyOutput": true,
+        "isLearnByExample": true
+      },
       {
         "name": "Function pointers",
         "url": "function-pointers",

examples/provide-function-arguments-by-name/provide_function_arguments_by_name.md

@@ -9,3 +9,4 @@ Ballerina allows you to call functions with named arguments, which do not have t
 ## Related links
 - [Functions](/learn/by-example/functions/)
 - [Included record parameters](/learn/by-example/included-record-parameters/)
+- [Rest arguments](/learn/by-example/rest-arguments/)

examples/rest-arguments/rest_arguments.bal

@@ -0,0 +1,70 @@
+import ballerina/http;
+import ballerina/io;
+
+// A function to print the sum of two or more integers.
+function sum(int first, int second, int... others) {
+    int sum = first + second;
+    foreach int othVal in others {
+        sum += othVal;
+    }
+    io:println(sum);
+}
+
+// A record with some HTTP client configuration values.
+type Configuration record {|
+    string url;
+    decimal timeout;
+    http:HttpVersion httpVersion;
+|};
+
+// A function that initializes an HTTP client using some configuration.
+function initializeHttpClient(string url, decimal timeout, http:HttpVersion httpVersion) {
+    // Intialize the client just for demonstration.
+    http:Client|error cl = new (url, {timeout, httpVersion});
+    if cl is error {
+        io:println("Failed to initialize an HTTP client", cl);
+        return;
+    }
+    io:println(
+        string `Initialized client with URL: ${url}, timeout: ${timeout}, HTTP version: ${httpVersion}`);
+}
+
+public function main() {
+    // Call the `sum` function using an array of length 4 as a rest argument.
+    int[4] ints1 = [1, 2, 3, 4];
+    sum(...ints1);
+
+    // Since the `sum` function has two required parameters, when providing only a list rest 
+    // argument, the length of the list should be guaranteed by the static type to be at
+    // least 2.
+    // Call the `sum` function using a tuple with at least two members.
+    [int, int, int...] ints2 = [5, 6];
+    sum(...ints2);
+
+    // A rest argument can be used along with positional arguments, 
+    // providing only some of the arguments.
+    // Call the `sum` function with a rest argument after two positional arguments.
+    sum(5, 6, ...ints1);
+
+    // Call the `sum` function with a rest argument after one positonal argument.
+    // Note how the rest argument provides arguments for both a required parameter
+    // and the rest parameter. Since only one positional argument is provided, the list
+    // type of the expression used in the rest argument should guarantee the presence of 
+    // at least one member in the list to provide an argument for the second required parameter.
+    [int, int...] ints3 = [5, 6, 7];
+    sum(4, ...ints3);
+
+    // Call the `initializeHttpClient` function using a record value in the rest argument
+    // providing values for all the parameters.
+    Configuration config1 = {httpVersion: http:HTTP_2_0, url: "http://localhost:8080", timeout: 60};
+    initializeHttpClient(...config1);
+
+    // Call the `initializeHttpClient` function using a positional argument and a rest argument with 
+    // a record value. The positional argument provides the argument for the first parameter (`url`) and the 
+    // rest argument provides values for the other two parameters. 
+    record {|
+        decimal timeout;
+        http:HttpVersion httpVersion;
+    |} config2 = {httpVersion: http:HTTP_1_1, timeout: 15};
+    initializeHttpClient("http://localhost:8080", ...config2);
+}

examples/rest-arguments/rest_arguments.md

@@ -0,0 +1,15 @@
+# Rest arguments
+
+Ballerina allows you to call functions with rest arguments, with an expression of a mapping or list type, spreading the members of the mapping or the list as individual arguments to the function.
+
+If the type of the expression used in the rest argument is a list type, the rest argument is equivalent to specifying each member of the list value as a positional argument. If it is a mapping type, the rest argument is equivalent to specifying each field of the mapping value as a named argument, where the name and the value of the named argument come from the name and the value of the field. In either case, the static type of the expression must ensure that the equivalent positional and/or named arguments would be valid and that arguments are provided for all the required parameters.
+
+::: code rest_arguments.bal :::
+
+::: out rest_arguments.out :::
+
+## Related links
+- [Functions](/learn/by-example/functions/)
+- [Provide function arguments by name](/learn/by-example/provide-function-arguments-by-name/)
+- [Included record parameters](/learn/by-example/included-record-parameters/)
+- [Aggregation](/learn/by-example/aggregation/)

examples/rest-arguments/rest_arguments.metatags

@@ -0,0 +1,2 @@
+description: This BBE demonstrates calling functions with rest arguments in Ballerina.
+keywords: ballerina, ballerina by example, bbe, rest arguments, functions, function definition, parameters

examples/rest-arguments/rest_arguments.out

@@ -0,0 +1,7 @@
+$ bal run rest_arguments.bal
+10
+11
+21
+22
+Initialized client with URL: http://localhost:8080, timeout: 60, HTTP version: 2.0
+Initialized client with URL: http://localhost:8080, timeout: 15, HTTP version: 1.1