Skip to content

Commit 25d92bb

Browse files
jrodewigjrodewig
authored
[DOCS] SQL: Document null handing for string functions (#74201) (#74208)
1 parent e8c94ed commit 25d92bb

File tree

1 file changed

+36
-34
lines changed

1 file changed

+36
-34
lines changed

‎docs/reference/sql/functions/string.asciidoc‎

Lines changed: 36 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ ASCII(string_exp) <1>
1616

1717
*Input*:
1818

19-
<1> string expression
19+
<1> string expression. If `null`, the function returns `null`.
2020

2121
*Output*: integer
2222

@@ -37,7 +37,7 @@ BIT_LENGTH(string_exp) <1>
3737
--------------------------------------------------
3838
*Input*:
3939

40-
<1> string expression
40+
<1> string expression. If `null`, the function returns `null`.
4141

4242
*Output*: integer
4343

@@ -58,7 +58,7 @@ CHAR(code) <1>
5858
--------------------------------------------------
5959
*Input*:
6060

61-
<1> integer expression
61+
<1> integer expression. If `null` or negative, the function returns `null`.
6262

6363
*Output*: string
6464

@@ -79,7 +79,7 @@ CHAR_LENGTH(string_exp) <1>
7979
--------------------------------------------------
8080
*Input*:
8181

82-
<1> string expression
82+
<1> string expression. If `null`, the function returns `null`.
8383

8484
*Output*: integer
8585

@@ -107,7 +107,7 @@ CONCAT(
107107

108108
*Output*: string
109109

110-
*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. `NULL` input strings are treated as empty strings.
110+
*Description*: Returns a character string that is the result of concatenating `string_exp1` to `string_exp2`. `null` input strings are treated as empty strings.
111111

112112
[source, sql]
113113
--------------------------------------------------
@@ -128,10 +128,10 @@ INSERT(
128128
--------------------------------------------------
129129
*Input*:
130130

131-
<1> string expression
132-
<2> integer expression
133-
<3> integer expression
134-
<4> string expression
131+
<1> string expression. If `null`, the function returns `null`.
132+
<2> integer expression. If `null`, the function returns `null`.
133+
<3> integer expression. If `null`, the function returns `null`.
134+
<4> string expression. If `null`, the function returns `null`.
135135

136136
*Output*: string
137137

@@ -152,7 +152,7 @@ LCASE(string_exp) <1>
152152
--------------------------------------------------
153153
*Input*:
154154

155-
<1> string expression
155+
<1> string expression. If `null`, the function returns `null`.
156156

157157
*Output*: string
158158

@@ -175,8 +175,9 @@ LEFT(
175175
--------------------------------------------------
176176
*Input*:
177177

178-
<1> string expression
179-
<2> integer expression
178+
<1> string expression. If `null`, the function returns `null`.
179+
<2> integer expression. If `null`, the function returns `null`. If `0` or
180+
negative, the function returns an empty string.
180181

181182
*Output*: string
182183

@@ -197,7 +198,7 @@ LENGTH(string_exp) <1>
197198
--------------------------------------------------
198199
*Input*:
199200

200-
<1> string expression
201+
<1> string expression. If `null`, the function returns `null`.
201202

202203
*Output*: integer
203204

@@ -228,7 +229,7 @@ LOCATE(
228229

229230
*Output*: integer
230231

231-
*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.
232+
*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.
232233

233234
[source, sql]
234235
--------------------------------------------------
@@ -250,7 +251,7 @@ LTRIM(string_exp) <1>
250251
--------------------------------------------------
251252
*Input*:
252253

253-
<1> string expression
254+
<1> string expression. If `null`, the function returns `null`.
254255

255256
*Output*: string
256257

@@ -271,7 +272,7 @@ OCTET_LENGTH(string_exp) <1>
271272
--------------------------------------------------
272273
*Input*:
273274

274-
<1> string expression
275+
<1> string expression. If `null`, the function returns `null`.
275276

276277
*Output*: integer
277278

@@ -294,8 +295,8 @@ POSITION(
294295
--------------------------------------------------
295296
*Input*:
296297

297-
<1> string expression
298-
<2> string expression
298+
<1> string expression. If `null`, the function returns `null`.
299+
<2> string expression. If `null`, the function returns `null`.
299300

300301
*Output*: integer
301302

@@ -318,8 +319,8 @@ REPEAT(
318319
--------------------------------------------------
319320
*Input*:
320321

321-
<1> string expression
322-
<2> integer expression
322+
<1> string expression. If `null`, the function returns `null`.
323+
<2> integer expression. If `0`, negative, or `null`, the function returns `null`.
323324

324325
*Output*: string
325326

@@ -343,9 +344,9 @@ REPLACE(
343344
--------------------------------------------------
344345
*Input*:
345346

346-
<1> string expression
347-
<2> string expression
348-
<3> string expression
347+
<1> string expression. If `null`, the function returns `null`.
348+
<2> string expression. If `null`, the function returns `null`.
349+
<3> string expression. If `null`, the function returns `null`.
349350

350351
*Output*: string
351352

@@ -368,8 +369,9 @@ RIGHT(
368369
--------------------------------------------------
369370
*Input*:
370371

371-
<1> string expression
372-
<2> integer expression
372+
<1> string expression. If `null`, the function returns `null`.
373+
<2> integer expression. If `null`, the function returns `null`. If `0` or
374+
negative, the function returns an empty string.
373375

374376
*Output*: string
375377

@@ -390,7 +392,7 @@ RTRIM(string_exp) <1>
390392
--------------------------------------------------
391393
*Input*:
392394

393-
<1> string expression
395+
<1> string expression. If `null`, the function returns `null`.
394396

395397
*Output*: string
396398

@@ -411,7 +413,7 @@ SPACE(count) <1>
411413
--------------------------------------------------
412414
*Input*:
413415

414-
<1> integer expression
416+
<1> integer expression. If `null` or negative, the function returns `null`.
415417

416418
*Output*: string
417419

@@ -434,8 +436,8 @@ STARTS_WITH(
434436
--------------------------------------------------
435437
*Input*:
436438

437-
<1> string expression
438-
<2> string expression
439+
<1> string expression. If `null`, the function returns `null`.
440+
<2> string expression. If `null`, the function returns `null`.
439441

440442
*Output*: boolean value
441443

@@ -465,9 +467,9 @@ SUBSTRING(
465467
--------------------------------------------------
466468
*Input*:
467469

468-
<1> string expression
469-
<2> integer expression
470-
<3> integer expression
470+
<1> string expression. If `null`, the function returns `null`.
471+
<2> integer expression. If `null`, the function returns `null`.
472+
<3> integer expression. If `null`, the function returns `null`.
471473

472474
*Output*: string
473475

@@ -487,7 +489,7 @@ TRIM(string_exp) <1>
487489
--------------------------------------------------
488490
*Input*:
489491

490-
<1> string expression
492+
<1> string expression. If `null`, the function returns `null`.
491493

492494
*Output*: string
493495

@@ -508,7 +510,7 @@ UCASE(string_exp) <1>
508510
--------------------------------------------------
509511
*Input*:
510512

511-
<1> string expression
513+
<1> string expression. If `null`, the function returns `null`.
512514

513515
*Output*: string
514516

0 commit comments

Comments
 (0)