Merge pull request #5664 from rdulmina/master

Update on conflict clause `BBE` with more real-world sample

examples/advanced-conflict-handling/advanced_conflict_handling.bal

@@ -0,0 +1,40 @@
+import ballerina/io;
+
+type Student record {|
+    string name;
+    int score;
+|};
+
+public function main() {
+    Student[] students = [
+        {name: "John", score: 100},
+        {name: "Jane", score: 150},
+        {name: "John", score: 200}
+    ];
+
+    // Create a map of the student `name` and the `score` where we replace the value of the duplicate key if the new `score` is even.
+    // The old `score` `100` of `John` will be replaced by the new `score` 200` since `replaceIfSafe()`returns `nil` for even scores.
+    map<int>|error studentScores = map from var {name, score} in students
+                                   select [name, score]
+                                   on conflict replaceIfSafe(score);
+    io:println(studentScores);
+
+    students = [
+        {name: "John", score: 100},
+        {name: "Jane", score: 150},
+        {name: "John", score: 211}
+    ];
+
+    // The result of this will be an error since the key `John` is duplicated and the `replaceIfSafe()`returns an error for odd `score` `211`.
+    map<int>|error studentScores2 = map from var {name, score} in students
+                                    select [name, score]
+                                    on conflict replaceIfSafe(score);
+    io:println(studentScores2);
+}
+
+function replaceIfSafe(int score) returns error? {
+    if score % 2 != 0 {
+        return error("Key Conflict", message = "Duplicate key has an odd score");
+    }
+}
+

examples/advanced-conflict-handling/advanced_conflict_handling.md

@@ -0,0 +1,20 @@
+# Advanced conflict handling
+
+We can implement a custom conflict-handling policy to determine whether to replace a value or throw an error in the event of conflicting keys when constructing a map or table.
+
+::: code advanced_conflict_handling.bal :::
+
+::: out advanced_conflict_handling :::
+
+## Related links
+- [On conflict clause](/learn/by-example/on-conflict-clause)
+- [Query expressions](/learn/by-example/query-expressions)
+- [Sort iterable objects using query](/learn/by-example/sort-iterable-objects)
+- [Let clause in query expression](/learn/by-example/let-clause)
+- [Limit clause in query expression](/learn/by-example/limit-clause)
+- [Joining iterable objects using query](/learn/by-example/joining-iterable-objects)
+- [Querying tables](/learn/by-example/querying-tables)
+- [Create maps with query expression](/learn/by-example/create-maps-with-query)
+- [Create tables with query expression](/learn/by-example/create-tables-with-query)
+- [Create streams with query expression](/learn/by-example/create-streams-with-query)
+- [Nested query expressions](/learn/by-example/nested-query-expressions)

examples/advanced-conflict-handling/advanced_conflict_handling.metatags

@@ -0,0 +1,2 @@
+description: This BBE demonstrates writing custom conflict handling logic when constructing a map or a table.
+keywords: ballerina, ballerina by example, bbe, duplicate, key, map, table, query, on conflict, error

examples/advanced-conflict-handling/advanced_conflict_handling.out

@@ -0,0 +1,3 @@
+$ bal run advanced_conflict_handling.bal
+{"John":200,"Jane":150}
+error("Key Conflict",message="Duplicate key has an odd score")

examples/index.json

@@ -905,6 +905,13 @@
         "verifyOutput": true,
         "isLearnByExample": true
       },
+      {
+        "name": "Advanced conflict handling",
+        "url": "advanced-conflict-handling",
+        "verifyBuild": true,
+        "verifyOutput": true,
+        "isLearnByExample": true
+      },
       {
         "name": "Iterate over XML with a query",
         "url": "iterating-over-xml-with-query",

examples/on-conflict-clause/on_conflict_clause.md

@@ -2,13 +2,14 @@
 
 When constructing a map or a table with a key sequence using a query expression, there can be conflicting keys. The `on conflict` clause can be specified after the `select` clause to handle these cases.
 
-The syntax to write an `on conflict` clause is `on conflict expression`. The type of the expression should be `error?`. If the result of evaluating the expression is an error, then, the error will be the result. Otherwise, the old value is replaced by the new value.
+The `on conflict` clause uses the syntax `on conflict <expression>`, where the expression must be of type `error?`. If a conflicting key is found, and the expression evaluates to an error, that error becomes the result of the query expression. If it evaluates to `null` or the `on conflict` clause is absent, the old value is replaced by the new value.
 
 ::: code on_conflict_clause.bal :::
 
 ::: out on_conflict_clause.out :::
 
 ## Related links
+- [Advanced conflict handling](/learn/by-example/advanced-conflict-handling)
 - [Query expressions](/learn/by-example/query-expressions)
 - [Sort iterable objects using query](/learn/by-example/sort-iterable-objects)
 - [Let clause in query expression](/learn/by-example/let-clause)