feat(feel): Clarify edge cases in FEEL expressions (#4222)

* feat(feel): Clarify built-in function usage

Extend the description of the functions `date()`, `number()`, and `substring()` to clarify the behavior for certain edge cases.

* feat(feel): Clarify unary-tests behavior

Extend the description when a unary-tests expression is fulfilled. Make it explicit what an expression with the special variable `?` must evaluate to true.

* docs: Improve wording

Co-authored-by: Nicola Puppa <[email protected]>

* docs: Improve wording

Co-authored-by: Mark Sellings <[email protected]>

* docs: Improve wording

---------

Co-authored-by: Nicola Puppa <[email protected]>
Co-authored-by: Mark Sellings <[email protected]>

docs/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md

@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel

docs/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md

@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)

docs/components/modeler/feel/language-guide/feel-temporal-expressions.md

@@ -40,9 +40,11 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
+
 ### Addition
 
-Adds a value to another value. The operator is defined for the followings types.
+Adds a value to another value. The operator is defined for the following types.
 
 If a value has a different type, the result is `null`.
 

docs/components/modeler/feel/language-guide/feel-unary-tests.md

@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -129,13 +129,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"

versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md

@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel

versioned_docs/version-8.2/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md

@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)

versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-temporal-expressions.md

@@ -40,6 +40,8 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
+
 ### Addition
 
 <table>

versioned_docs/version-8.2/components/modeler/feel/language-guide/feel-unary-tests.md

@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -128,13 +128,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/docs/components/modeler/feel/language-guide/feel-functions#invocation).
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"

versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md

@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel

versioned_docs/version-8.3/components/modeler/feel/builtin-functions/feel-built-in-functions-string.md

@@ -23,11 +23,15 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3)
 // "obar"
+
+substring("foobar", -2)
+// "ar"
 ```
 
 ## substring(string, start position, length)
 
-Returns a substring of the given value starting at `start position`.
+Returns a substring of the given value, starting at `start position` with the given `length`. If `length` is greater than
+the remaining characters of the value, it returns all characters from `start position` until the end.
 
 **Function signature**
 
@@ -42,6 +46,12 @@ The `start position` starts at the index `1`. The last position is `-1`.
 ```feel
 substring("foobar", 3, 3)
 // "oba"
+
+substring("foobar", -3, 2)
+// "ba"
+
+substring("foobar", 3, 10)
+// "obar"
 ```
 
 ## string length(string)

versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-temporal-expressions.md

@@ -40,6 +40,8 @@ duration("P3M")
 @"P3M"
 ```
 
+The value is `null` if a date or date-time literal doesn't represent a valid calendar date. For example, `@"2024-06-31"` is invalid because June has only 30 days.
+
 ### Addition
 
 Adds a value to another value. The operator is defined for the followings types.

versioned_docs/version-8.3/components/modeler/feel/language-guide/feel-unary-tests.md

@@ -9,10 +9,10 @@ entries of a decision table (i.e. the conditions of a rule).
 
 A unary-tests expression returns `true` if one of the following conditions is fulfilled:
 
-- The expression evaluates to `true` when the input value is applied to it.
-- The expression evaluates to a list, and the input value is equal to at least one of the values in
-  that list.
+- The expression evaluates to `true` when the input value is applied to the unary operators.
+- The expression evaluates to `true` when the input value is assigned to the special variable `?`.
 - The expression evaluates to a value, and the input value is equal to that value.
+- The expression evaluates to a list, and the input value is equal to at least one of the values.
 - The expression is equal to `-` (a dash).
 
 ### Comparison
@@ -129,13 +129,14 @@ not(2, 3)
 
 ### Expressions
 
-Evaluates an expression that returns a boolean value. For example, [invoking a function](/docs/components/modeler/feel/language-guide/feel-functions#invocation).
+When a unary operator is not enough to express the condition, any expression that returns a boolean value can be used,
+such as [invoking a function](/components/modeler/feel/language-guide/feel-functions.md#invocation).
 
-The input value can be accessed in the expression by using the symbol `?` (a question mark).
+In the expression, the input value can be accessed by the special variable `?`.
 
 ```feel
 contains(?, "good")
-// check if the input value (string) contains "good"
+// checks if the input value (string) contains "good"
 
 ends with(?, "@camunda.com")
 // checks if the input value (string) ends with "@camunda.com"

versioned_docs/version-8.4/components/modeler/feel/builtin-functions/feel-built-in-functions-conversion.md

@@ -32,6 +32,8 @@ string(date("2012-12-25"))
 
 Parses the given string to a number.
 
+Returns `null` if the string is not a number.
+
 **Function signature**
 
 ```feel
@@ -72,6 +74,9 @@ context([{"key":"a", "value":1}, {"key":"b", "value":2}])
 
 Returns a date from the given value.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31"` is invalid because June has
+only 30 days.
+
 **Function signature**
 
 ```feel
@@ -100,6 +105,9 @@ date(date and time("2012-12-25T11:00:00"))
 
 Returns a date from the given components.
 
+Returns `null` if the components don't represent a valid calendar date. For example, `2024,6,31` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel
@@ -179,6 +187,9 @@ time(14, 30, 0, duration("PT1H"))
 
 Parses the given string into a date and time.
 
+Returns `null` if the string is not a valid calendar date. For example, `"2024-06-31T10:00:00"` is invalid because
+June has only 30 days.
+
 **Function signature**
 
 ```feel