Merge pull request #10814 from pijuskri/dat/contains-empty

Clarify handling of empty arguments in xpath function contains

Author: MarkvanMents

content/en/docs/refguide/modeling/xpath/xpath-constraints/xpath-constraint-functions/_index.md

@@ -23,3 +23,7 @@ The following pages describe the functions that can be executed within constrain
 * [contains](/refguide/xpath-contains/)
 * [starts-with](/refguide/xpath-starts-with/)
 * [ends-with](/refguide/xpath-ends-with/)
+
+{{% alert color="info" %}}
+In all these functions, the attribute in the example is just the name of the attribute, for example `Name`. This is for clarity. However, the attribute can also contain the path to the attribute, for example `Sales.Order_Customer/Sales.Customer/Name`.
+{{% /alert %}}

content/en/docs/refguide/modeling/xpath/xpath-constraints/xpath-constraint-functions/xpath-contains.md

@@ -13,6 +13,28 @@ The `contains()` function tests whether a string attribute contains a specific s
 String comparisons in XPath constraints are generally case-insensitive, but this can depend on the collation setting for some databases. See [Case-Sensitive Database Behavior](/refguide/case-sensitive-database-behavior/) for more information.
 {{% /alert %}}
 
+## Syntax
+
+The syntax is as follows:
+
+```
+contains ( attribute, string_expression )
+```
+
+### attribute
+
+`attribute` specifies the attribute to test. It must be of the **String** type.
+
+### expression
+
+`string_expression` specifies the value to test for being contained in the attribute. It can be a string literal or a string parameter.
+
+{{% alert color="info" %}}
+If the `attribute` is an empty value or `NULL`, the function will always return `false`, independent of the value of `string_expression`.
+
+If the `string_expression` is empty, it is treated as an empty string. The function is then equivalent to ```attribute != empty```.
+{{% /alert %}}
+
 ## Example
 
 This query returns all the customers from which the name contains the string `an`:

content/en/docs/refguide/modeling/xpath/xpath-constraints/xpath-constraint-functions/xpath-ends-with.md

@@ -13,17 +13,39 @@ The `ends-with()` function checks whether a string attribute ends with a specifi
 String comparisons in XPath constraints are generally case-insensitive, but this can depend on the collation setting for some databases. See [Case-Sensitive Database Behavior](/refguide/case-sensitive-database-behavior/) for more information.
 {{% /alert %}}
 
+## Syntax
+
+The syntax is as follows:
+
+```
+ends-with ( attribute, string_expression )
+```
+
+### attribute
+
+`attribute` specifies the attribute to test. It must be of the **String** type.
+
+### expression
+
+`string_expression` specifies the value to test for being at the end of the attribute. It must be a string literal or a string parameter.
+
+{{% alert color="info" %}}
+If the `attribute` is an empty value or `NULL`, the function will always return `false`, independent of the value of `string_expression`.
+
+If the `string_expression` is empty, it is treated as an empty string. The function is then equivalent to ```attribute != empty```.
+{{% /alert %}}
+
 ## Example
 
 This query returns all customers whose name ends with the sub-string `sen`:
 
 {{< tabpane >}}
-  {{% tab header="Environments:" disabled=true /%}}
-  {{< tab header="Studio Pro" lang="StudioPro" >}}
-    [ends-with(Name, 'sen')]
+    {{% tab header="Environments:" disabled=true /%}}
+    {{< tab header="Studio Pro" lang="StudioPro" >}}
+        [ends-with(Name, 'sen')]
     {{% /tab %}}
-  {{< tab header="Java" lang="JavaQuery" >}}
-     //Sales.Customer[ends-with(Name, 'sen')]
+    {{< tab header="Java" lang="JavaQuery" >}}
+        //Sales.Customer[ends-with(Name, 'sen')]
     {{% /tab %}}
 {{< /tabpane >}}
 

content/en/docs/refguide/modeling/xpath/xpath-constraints/xpath-constraint-functions/xpath-starts-with.md

@@ -13,17 +13,39 @@ The `starts-with()` function tests whether a string attribute starts with a spec
 String comparisons in XPath constraints are generally case-insensitive, but this can depend on the collation setting for some databases. See [Case-Sensitive Database Behavior](/refguide/case-sensitive-database-behavior/) for more information.
 {{% /alert %}}
 
+## Syntax
+
+The syntax is as follows:
+
+```
+starts-with ( attribute, string_expression )
+```
+
+### attribute
+
+`attribute` specifies the attribute to test. It must be of the **String** type.
+
+### expression
+
+`string_expression` specifies the value to test for being at the start of the attribute. It should be a string literal or a string parameter.
+
+{{% alert color="info" %}}
+If the `attribute` is an empty value or `NULL`, the function will always return `false`, independent of the value of `string_expression`.
+
+If the `string_expression` is empty, it is treated as an empty string. The function is then equivalent to ```attribute != empty```.
+{{% /alert %}}
+
 ## Example
 
 This query returns all the customers from which the name starts with the string "Jans":
 
 {{< tabpane >}}
-  {{% tab header="Environments:" disabled=true /%}}
-  {{< tab header="Studio Pro" lang="StudioPro" >}}
-    [starts-with(Name, 'Jans')]
+    {{% tab header="Environments:" disabled=true /%}}
+    {{< tab header="Studio Pro" lang="StudioPro" >}}
+        [starts-with(Name, 'Jans')]
     {{% /tab %}}
-  {{< tab header="Java" lang="JavaQuery" >}}
-     //Sales.Customer[starts-with(Name, 'Jans')]
+    {{< tab header="Java" lang="JavaQuery" >}}
+        //Sales.Customer[starts-with(Name, 'Jans')]
     {{% /tab %}}
 {{< /tabpane >}}