Browse Source

[DOCS] SQL: Move `null` handling to arg descriptions (#74255)

https://github.com/elastic/elasticsearch/pull/74201 documents `null` handling  to the arg descriptions of several string functions.

This PR moves pre-existing docs for `null` handling and similar edge case handling for string functions to arg descriptions for consistency.

Relates to #74193
James Rodewig 4 years ago
parent
commit
853f2436ee
1 changed files with 16 additions and 11 deletions
  1. 16 11
      docs/reference/sql/functions/string.asciidoc

+ 16 - 11
docs/reference/sql/functions/string.asciidoc

@@ -58,11 +58,12 @@ CHAR(code) <1>
 --------------------------------------------------
 *Input*:
 
-<1> integer expression. If `null` or negative, the function returns `null`.
+<1> integer expression between `0` and `255`. If `null`, negative, or greater
+than `255`, the function returns `null`.
 
 *Output*: string
 
-*Description*: Returns the character that has the ASCII code value specified by the numeric input. The value should be between 0 and 255; otherwise, the return value is data source–dependent.
+*Description*: Returns the character that has the ASCII code value specified by the numeric input.
 
 [source, sql]
 --------------------------------------------------
@@ -102,12 +103,12 @@ CONCAT(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> string expression
+<1> string expression. Treats `null` as an empty string.
+<2> string expression. Treats `null` as an empty string.
 
 *Output*: string
 
-*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. `null` input strings are treated as empty strings.
+*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`.
 
 [source, sql]
 --------------------------------------------------
@@ -223,13 +224,17 @@ LOCATE(
 --------------------------------------------------
 *Input*:
 
-<1> string expression
-<2> string expression
-<3> integer expression; optional
+<1> string expression.  If `null`, the function returns `null`.
+<2> string expression.  If `null`, the function returns `null`.
+<3> integer expression; optional. If `null`, `0`, `1`, negative, or not
+specified, the search starts at the first character position.
 
 *Output*: integer
 
-*Description*: Returns the starting position of the first occurrence of `pattern` within `source`. The optional `start` specifies the character position to start the search with. The first character position in `source` is indicated by the value 1. Not specifying `start` or specifying it as `null`, any negative value, 0 or 1, starts the search at the first character position. If `pattern` is not found within `source`, the value 0 is returned.
+*Description*: Returns the starting position of the first occurrence of
+`pattern` within `source`. The optional `start` specifies the character position
+to start the search with. If the `pattern` is not found within `source`, the
+function returns `0`.
 
 [source, sql]
 --------------------------------------------------
@@ -441,8 +446,8 @@ STARTS_WITH(
 
 *Output*: boolean value
 
-*Description*: Returns `true` if the source expression starts with the specified pattern, `false` otherwise. The matching is case sensitive.
-If either parameters is `null`, the function returns `null`.
+*Description*: Returns `true` if the source expression starts with the specified
+pattern, `false` otherwise. The matching is case sensitive.
 
 [source, sql]
 --------------------------------------------------