Fix: Enrich instructions for string functions FORMAT() and FROM_BASE6…

…4() (#15487) (#16085) * Enrich instructions for string functions FORMAT() and FROM_BASE64() * Add a detailed description * Update the lint CI * Apply suggestions from code review * Apply reviewer recommendations Co-authored-by: xixirangrang <[email protected]> * Apply suggestions from code review Co-authored-by: xixirangrang <[email protected]> * Update functions-and-operators/string-functions.md * Update functions-and-operators/string-functions.md * Update functions-and-operators/string-functions.md * Apply suggestions from code review Co-authored-by: Grace Cai <[email protected]> * Update functions-and-operators/string-functions.md Co-authored-by: Grace Cai <[email protected]> * Update functions-and-operators/string-functions.md * Update functions-and-operators/string-functions.md --------- Co-authored-by: xixirangrang <[email protected]> Co-authored-by: Grace Cai <[email protected]>
pingcap · Jan 31, 2024 · ce69aca · ce69aca
1 parent 420f7f7
commit ce69aca
Showing 1 changed file with 91 additions and 2 deletions.
diff --git a/functions-and-operators/string-functions.md b/functions-and-operators/string-functions.md
@@ -440,11 +440,100 @@ Return the index position of the first argument within the second argument.
 
 ### [`FORMAT()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_format)
 
-Return a number formatted to specified number of decimal places.
+The `FORMAT(X,D[,locale])` function is used to format the number `X` to a format similar to `"#,###,###. ##"`, rounded to `D` decimal places, and return the result as a string.
+
+Arguments:
+
+- `X`: the number to be formatted. It can be a direct numeric value, a numeric string, or a number in scientific notation.
+- `D`: the number of decimal places for the returned value. The function rounds the number `X` to `D` decimal places. If `D` is greater than the actual number of decimal places in `X`, the result is padded with zeros to the corresponding length.
+ `[locale]`: specifies a locale setting to be used for grouping between decimal points, thousands separators, and separators for resultant numbers. A valid locale value is the same as the valid value of the [`lc_time_names`](https://dev.mysql.com/doc/refman/8.3/en/server-system-variables.html#sysvar_lc_time_names) system variable. If not specified or the region setting is `NULL`, the `'en_US'` region setting is used by default. This argument is optional.
+
+Behaviors:
+
+- If the first argument is a string and contains only numbers, the function returns a result based on that numeric value. For example, `FORMAT('12.34', 1)` and `FORMAT(12.34, 1)` return the same result.
+- If the first argument is a number represented in scientific notation (using `E/e`), the function returns the result based on that number. For example, `FORMAT('1E2', 3)` returns `100.000`.
+- If the first argument is a string starting with non-numeric characters, the function returns zero and a warning `(Code 1292)`. For example, `FORMAT('q12.36', 5)` returns `0.00000`, but also includes a warning `Warning (Code 1292): Truncated incorrect DOUBLE value: 'q12.36'`.
+- If the first argument is a string mixing numbers and non-numbers, the function returns a result based on the consecutive numeric part at the beginning of the argument, and also includes a warning `(Code 1292)`. For example, `FORMAT('12.36q56.78', 1)` returns the same numeric result as `FORMAT('12.36', 1)`, but includes a warning `Warning (Code 1292): Truncated incorrect DOUBLE value: '12.36q56.78'`.
+- If the second argument is zero or a negative number, the function truncates the decimal part and returns an integer.
+- If any of the arguments is `NULL`, the function returns `NULL`.
+
+Examples:
+
+The following examples show how to format the number 12.36 to different decimal places:
+
+```sql
+mysql> SELECT FORMAT(12.36, 1);
++------------------+
+| FORMAT(12.36, 1) |
++------------------+
+| 12.4             |
++------------------+
+```
+
+```sql
+mysql> SELECT FORMAT(12.36, 5);
++------------------+
+| FORMAT(12.36, 5) |
++------------------+
+| 12.36000         |
++------------------+
+```
+
+```sql
+mysql> SELECT FORMAT(12.36, 2);
++------------------+
+| FORMAT(12.36, 2) |
++------------------+
+| 12.36            |
++------------------+
+```
 
 ### [`FROM_BASE64()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_from-base64)
 
-Decode to a base-64 string and return result.
+The `FROM_BASE64()` function is used to decode a [Base64](https://datatracker.ietf.org/doc/html/rfc4648) encoded string and return the decoded result in its hexadecimal form.
+
+- This function accepts a single argument, that is, the Base64 encoded string to be decoded.
+- If the argument is `NULL` or not a valid Base64 encoded string, the `FROM_BASE64()` function returns `NULL`.
+
+Examples:
+
+The following example shows how to decode the Base64 encoded string `'SGVsbG8gVGlEQg=='`. This string is the result of encoding `'Hello TiDB'`, using the [`TO_BASE64()`](#to_base64) function.
+
+```sql
+mysql> SELECT TO_BASE64('Hello TiDB');
++-------------------------+
+| TO_BASE64('Hello TiDB') |
++-------------------------+
+| SGVsbG8gVGlEQg==        |
++-------------------------+
+
+mysql> SELECT FROM_BASE64('SGVsbG8gVGlEQg==');
++------------------------------------------------------------------+
+| FROM_BASE64('SGVsbG8gVGlEQg==')                                  |
++------------------------------------------------------------------+
+| 0x48656C6C6F2054694442                                           |
++------------------------------------------------------------------+
+```
+
+```sql
+mysql> SELECT CONVERT(FROM_BASE64('SGVsbG8gVGlEQg==') USING utf8mb4);
++--------------------------------------------------------+
+| CONVERT(FROM_BASE64('SGVsbG8gVGlEQg==') USING utf8mb4) |
++--------------------------------------------------------+
+| Hello TiDB                                             |
++--------------------------------------------------------+
+```
+
+The following example shows how to decode the Base64 encoded number `MTIzNDU2`. This string is the result of encoding `123456`, which can be done using the [`TO_BASE64()`](#to_base64) function.
+
+```sql
+mysql> SELECT FROM_BASE64('MTIzNDU2');
++--------------------------------------------------+
+| FROM_BASE64('MTIzNDU2')                          |
++--------------------------------------------------+
+| 0x313233343536                                   |
++--------------------------------------------------+
+```
 
 ### [`HEX()`](https://dev.mysql.com/doc/refman/8.0/en/string-functions.html#function_hex)