From 25d92bbf6bb92113ed782e03f5cd0ca2d2b863eb Mon Sep 17 00:00:00 2001 From: James Rodewig <40268737+jrodewig@users.noreply.github.com> Date: Wed, 16 Jun 2021 14:41:41 -0400 Subject: [PATCH] [DOCS] SQL: Document `null` handing for string functions (#74201) (#74208) --- docs/reference/sql/functions/string.asciidoc | 70 ++++++++++---------- 1 file changed, 36 insertions(+), 34 deletions(-) diff --git a/docs/reference/sql/functions/string.asciidoc b/docs/reference/sql/functions/string.asciidoc index 3189d4d03e8d8..b577475c292a8 100644 --- a/docs/reference/sql/functions/string.asciidoc +++ b/docs/reference/sql/functions/string.asciidoc @@ -16,7 +16,7 @@ ASCII(string_exp) <1> *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: integer @@ -37,7 +37,7 @@ BIT_LENGTH(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: integer @@ -58,7 +58,7 @@ CHAR(code) <1> -------------------------------------------------- *Input*: -<1> integer expression +<1> integer expression. If `null` or negative, the function returns `null`. *Output*: string @@ -79,7 +79,7 @@ CHAR_LENGTH(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: integer @@ -107,7 +107,7 @@ CONCAT( *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`. `null` input strings are treated as empty strings. [source, sql] -------------------------------------------------- @@ -128,10 +128,10 @@ INSERT( -------------------------------------------------- *Input*: -<1> string expression -<2> integer expression -<3> integer expression -<4> string expression +<1> string expression. If `null`, the function returns `null`. +<2> integer expression. If `null`, the function returns `null`. +<3> integer expression. If `null`, the function returns `null`. +<4> string expression. If `null`, the function returns `null`. *Output*: string @@ -152,7 +152,7 @@ LCASE(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: string @@ -175,8 +175,9 @@ LEFT( -------------------------------------------------- *Input*: -<1> string expression -<2> integer expression +<1> string expression. If `null`, the function returns `null`. +<2> integer expression. If `null`, the function returns `null`. If `0` or +negative, the function returns an empty string. *Output*: string @@ -197,7 +198,7 @@ LENGTH(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: integer @@ -228,7 +229,7 @@ LOCATE( *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. 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. [source, sql] -------------------------------------------------- @@ -250,7 +251,7 @@ LTRIM(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: string @@ -271,7 +272,7 @@ OCTET_LENGTH(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: integer @@ -294,8 +295,8 @@ POSITION( -------------------------------------------------- *Input*: -<1> string expression -<2> string expression +<1> string expression. If `null`, the function returns `null`. +<2> string expression. If `null`, the function returns `null`. *Output*: integer @@ -318,8 +319,8 @@ REPEAT( -------------------------------------------------- *Input*: -<1> string expression -<2> integer expression +<1> string expression. If `null`, the function returns `null`. +<2> integer expression. If `0`, negative, or `null`, the function returns `null`. *Output*: string @@ -343,9 +344,9 @@ REPLACE( -------------------------------------------------- *Input*: -<1> string expression -<2> string expression -<3> string expression +<1> string expression. If `null`, the function returns `null`. +<2> string expression. If `null`, the function returns `null`. +<3> string expression. If `null`, the function returns `null`. *Output*: string @@ -368,8 +369,9 @@ RIGHT( -------------------------------------------------- *Input*: -<1> string expression -<2> integer expression +<1> string expression. If `null`, the function returns `null`. +<2> integer expression. If `null`, the function returns `null`. If `0` or +negative, the function returns an empty string. *Output*: string @@ -390,7 +392,7 @@ RTRIM(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: string @@ -411,7 +413,7 @@ SPACE(count) <1> -------------------------------------------------- *Input*: -<1> integer expression +<1> integer expression. If `null` or negative, the function returns `null`. *Output*: string @@ -434,8 +436,8 @@ STARTS_WITH( -------------------------------------------------- *Input*: -<1> string expression -<2> string expression +<1> string expression. If `null`, the function returns `null`. +<2> string expression. If `null`, the function returns `null`. *Output*: boolean value @@ -465,9 +467,9 @@ SUBSTRING( -------------------------------------------------- *Input*: -<1> string expression -<2> integer expression -<3> integer expression +<1> string expression. If `null`, the function returns `null`. +<2> integer expression. If `null`, the function returns `null`. +<3> integer expression. If `null`, the function returns `null`. *Output*: string @@ -487,7 +489,7 @@ TRIM(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: string @@ -508,7 +510,7 @@ UCASE(string_exp) <1> -------------------------------------------------- *Input*: -<1> string expression +<1> string expression. If `null`, the function returns `null`. *Output*: string