You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@spark.apache.org by GitBox <gi...@apache.org> on 2022/06/21 21:08:04 UTC
[GitHub] [spark] dtenedor opened a new pull request, #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
dtenedor opened a new pull request, #36950:
URL: https://github.com/apache/spark/pull/36950
### What changes were proposed in this pull request?
Update documentation for number format strings with the `{try_}to_number` functions.
### Why are the changes needed?
The existing documentation is incomplete.
### Does this PR introduce _any_ user-facing change?
No.
### How was this patch tested?
N/A
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1172102842
thanks, merging to master!
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1169022035
Thanks @cloud-fan for your review, made another pass.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1165971831
@cloud-fan thanks for your thoughtful review! Here are the latest renderings of the docs:
<img width="1195" alt="image" src="https://user-images.githubusercontent.com/99207096/175697957-eec112c0-a0a6-4752-a9ee-299bba5438c5.png">
<img width="1188" alt="image" src="https://user-images.githubusercontent.com/99207096/175697990-0d420823-feeb-4d77-b2db-c30dfd2a9832.png">
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1162377572
> @dtenedor Could you build the doc site locally and provide a screenshot in the section "How was this patch tested?" ?
@gengliangwang Sure, this is done. I can do this again for more iteration(s) on this PR as needed as well
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] gengliangwang commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
gengliangwang commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903082142
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,101 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
Review Comment:
Also we need to introduce the behaviors of handling errors
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1163311776
@cloud-fan thanks for taking a look at this! Here's the latest rendering:
<img width="1257" alt="image" src="https://user-images.githubusercontent.com/99207096/175079925-8337f790-302f-4b7c-9072-4f0cc99912d0.png">
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r906431818
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,132 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits in the input string. If the
+ 0/9 sequence starts with 0 and is before the decimal point, it can only match a digit sequence of
+ the same size. Otherwise, if the sequence starts with 9 or is after the decimal point, it can
+ match a digit sequence that has the same or smaller size.
Review Comment:
Sounds good, done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903955288
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,137 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ L | $ ]
Review Comment:
Good catch, no, we did not. Removed this part from the syntax.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r910872390
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
Review Comment:
```suggestion
When parsing, the input string does not need to include a decimal point.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] AmplabJenkins commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
AmplabJenkins commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1162692194
Can one of the admins verify this patch?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r906086065
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,132 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits in the input string. If the
+ 0/9 sequence starts with 0 and is before the decimal point, it can only match a digit sequence of
+ the same size. Otherwise, if the sequence starts with 9 or is after the decimal point, it can
+ match a digit sequence that has the same or smaller size.
Review Comment:
Since this doc is for both parsing and formatting, let's rephrase it a little bit:
```
A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller size.
If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the number of digits:
when parsing only a digit sequence of the same size can be matched, when formatting the
digit sequence will be left-padded with zeros in the result string to reach the same size.
Otherwise, the 0/9 sequence can match any digit sequence with the same or smaller size
when parsing, and pad the digit sequence with spaces in the result string when formatting.
Note that, the digit sequence will become a '#' sequence if the size is larger than the 0/9
sequence.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r910861183
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
Review Comment:
```suggestion
{ ' [ S | MI ] [ $ ]
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r910877387
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
+
+- **`$`**
+
+ Specifies the location of the `$` currency sign. This character may only be specified once.
+
+- **`S`**
+
+ Specifies the position of an optional '+' or '-' sign. This character may only be specified once.
+
+- **`MI`**
+
+ Specifies an optional `-` sign at the end, but no `+`.
Review Comment:
did you push any updates?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r911239445
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
Review Comment:
Done.
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
Review Comment:
Done.
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
Review Comment:
Done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] gengliangwang commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
gengliangwang commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903082142
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,101 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
Review Comment:
Also we need to introduce the behaviors of handling errors, which is the difference between the two functions.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] gengliangwang commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
gengliangwang commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903081571
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,101 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
Review Comment:
Shall we have the highlights for all the functions?
E.g.
```
to_number(string, format);
try_to_number(string, format);
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r906049426
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,132 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
Review Comment:
```suggestion
Functions such as `to_number` and `to_char` support converting between values of string and
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903246844
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,137 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ L | $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ L | $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A `0` to the left of the decimal point indicates that at least this many digits must be present.
Review Comment:
shall we use the doc in the functions?
```
A sequence of 0 or 9 in the format
string matches a sequence of digits in the input string. If the 0/9 sequence starts with
0 and is before the decimal point, it can only match a digit sequence of the same size.
Otherwise, if the sequence starts with 9 or is after the decimal point, it can match a
digit sequence that has the same or smaller size.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r911240780
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
+
+- **`$`**
+
+ Specifies the location of the `$` currency sign. This character may only be specified once.
+
+- **`S`**
+
+ Specifies the position of an optional '+' or '-' sign. This character may only be specified once.
+
+- **`MI`**
+
+ Specifies an optional `-` sign at the end, but no `+`.
Review Comment:
sorry about that -- I forgot to push. Updated now :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r908766310
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
+
+- **`$`**
+
+ Specifies the location of the `$` currency sign. This character may only be specified once.
+
+- **`S`**
+
+ Specifies the position of an optional '+' or '-' sign. This character may only be specified once.
+
+- **`MI`**
+
+ Specifies an optional `-` sign at the end, but no `+`.
Review Comment:
Good catch -- we ended up allowing `MI` at the beginning as well during conversations while building the feature. I updated these docs accordingly.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r907666826
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
+
+- **`$`**
+
+ Specifies the location of the `$` currency sign. This character may only be specified once.
+
+- **`S`**
+
+ Specifies the position of an optional '+' or '-' sign. This character may only be specified once.
+
+- **`MI`**
+
+ Specifies an optional `-` sign at the end, but no `+`.
Review Comment:
Seems our implementation allows `MI` at the beginning. Is it intentional and we should fix the doc, or it's a mistake?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1162368043
@srielau FYI, looks like we forgot to update the Apache Spark docs for the to_number/try_to_number format strings; this PR updates them.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903134910
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,101 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
Review Comment:
Sure, this sounds good. Added this to the docs.
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,101 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+```
+ { ' [ S ] [ L | $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ L | $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A `0` to the left of the decimal point indicates that at least this many digits must be present.
+
+ A leading `9` indicates that these digits are optional.
+
+ The input value must not be larger than the number of digits to the left of the decimal point
+ allowed by the format string.
+
+ Digits to the right of the decimal point in the format string indicate the most digits that the
+ input value may have to the right of the decimal point.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
+
+- **`$`**
+
+ Specifies the location of the `$` currency sign. This character may only be specified once.
+
+- **`S`**
+
+ Specifies the position of an optional '+' or '-' sign. This character may only be specified once.
+
+- **`MI`**
+
+ Specifies an optional `-` sign at the end, but no `+`.
+
+- **`PR`**
+
+ Maps negative input values to wrapping angle brackets (`<1>`) in the corresponding string.
+
+ Positive input values do not receive wrapping angle brackets.
+
+### Examples
+
+The following examples use the `try_to_number` SQL function which accepts an input string as the
Review Comment:
Added this to the examples section at the end.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] srielau commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
srielau commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1162375351
So far Spark docs have been out of scope for me....
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r906086541
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,132 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits in the input string. If the
+ 0/9 sequence starts with 0 and is before the decimal point, it can only match a digit sequence of
+ the same size. Otherwise, if the sequence starts with 9 or is after the decimal point, it can
+ match a digit sequence that has the same or smaller size.
Review Comment:
Let's rephrase other element docs as well. also cc @srielau
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r910874004
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,165 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
Review Comment:
```suggestion
There must be a `0` or `9` to the left and right of each grouping separator. When parsing,
the input string must match the grouping separator relevant for the size of the number.
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] gengliangwang commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
gengliangwang commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1162371252
@dtenedor Could you build the doc site locally and provide a screenshot in the section "How was this patch tested?" ?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903244589
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,137 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ L | $ ]
Review Comment:
do we end up supporting `L`?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r911756134
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,168 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `to_char` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ MI | S ] [ $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A sequence of 0 or 9 in the format string matches a sequence of digits with the same or smaller
+ size. If the 0/9 sequence starts with 0 and is before the decimal point, it requires matching the
+ number of digits: when parsing, it matches only a digit sequence of the same size; when
+ formatting, the result string adds left-padding with zeros to the digit sequence to reach the
+ same size. Otherwise, the 0/9 sequence matches any digit sequence with the same or smaller size
+ when parsing, and pads the digit sequence with spaces in the result string when formatting. Note
+ that the digit sequence will become a '#' sequence if the size is larger than the 0/9 sequence.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point. This character may only be specified once.
+
+ When parsing, the input string does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator. When parsing,
+ the input string must match the grouping separator relevant for the size of the number.
+
+- **`$`**
+
+ Specifies the location of the `$` currency sign. This character may only be specified once.
+
+- **`S`**
+
+ Specifies the position of an optional '+' or '-' sign. This character may only be specified once.
+
+- **`MI`**
+
+ Specifies the position of an optional '-' sign (no '+'). This character may only be specified once.
+
+ When formatting, it prints a space for positive values.
+
+- **`PR`**
+
+ Maps negative input values to wrapping angle brackets (`<1>`) in the corresponding string.
+
+ Positive input values do not receive wrapping angle brackets.
+
+### Function types and error handling
+
+* The `to_number` function accepts an input string and a format string argument. It requires that
+the input string matches the provided format and raises an error otherwise. The function then
+returns the corresponding Decimal value.
+* The `try_to_number` function accepts an input string and a format string argument. It works the
+same as the `to_number` function except that it returns NULL instead of raising an error if the
+input string does not match the given number format.
+* The `to_char` function accepts an input decimal and a format string argument. It requires that
+the input decimal matches the provided format and raises an error otherwise. The function then
+returns the corresponding string value.
+* All functions will fail if the given format string is invalid.
+
+### Examples
+
+The following examples use the `to_number`, `try_to_number`, `to_char`, and `try_to_char` SQL
+functions.
+
+Note that the format string used in most of these examples expects:
+* an optional sign at the beginning,
+* followed by a dollar sign,
+* followed by a number between 3 and 6 digits long,
+* thousands separators,
+* up to two digits beyond the decimal point.
+
+#### The `to_number` function
+
+```sql
+-- The negative number with currency symbol maps to characters in the format string.
+> SELECT to_number('-$12,345.67', 'S$999,099.99');
+ -12345.67
+
+-- The '$' sign is not optional.
+> SELECT to_number('5', '$9');
+ Error: the input string does not match the given number format
+
+-- The plus sign is optional, and so are fractional digits.
+> SELECT to_number('$345', 'S$999,099.99');
+ 345.00
+
+-- The format requires at least three digits.
+> SELECT to_number('$45', 'S$999,099.99');
+ Error: the input string does not match the given number format
+
+-- The format requires at least three digits.
+> SELECT to_number('$045', 'S$999,099.99');
+ 45.00
+
+-- MI indicates an optional minus sign at the beginning or end of the input string.
+> SELECT to_number('1234-', '999999MI');
+ -1234
+
+-- PR indicates optional wrapping angel brakets.
+> SELECT to_number('9', '999PR')
+ 9
+```
+
+#### The `try_to_number` function:
+
+```sql
+-- The '$' sign is not optional.
+> SELECT try_to_number('5', '$9');
+ NULL
+
+-- The format requires at least three digits.
+> SELECT try_to_number('$45', 'S$999,099.99');
+ NULL
+```
+
+#### The `to_char` function:
+
+```sql
+> SELECT to_char(decimal(454), '999');
+ "454"
+
+-- '99' can format digit sequence with a smaller size.
+> SELECT to_char(decimal(1), '99.9');
+ "1.0"
Review Comment:
```suggestion
" 1.0"
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan closed pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
cloud-fan closed pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
URL: https://github.com/apache/spark/pull/36950
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] gengliangwang commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
gengliangwang commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903082475
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,101 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+```
+ { ' [ S ] [ L | $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ L | $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A `0` to the left of the decimal point indicates that at least this many digits must be present.
+
+ A leading `9` indicates that these digits are optional.
+
+ The input value must not be larger than the number of digits to the left of the decimal point
+ allowed by the format string.
+
+ Digits to the right of the decimal point in the format string indicate the most digits that the
+ input value may have to the right of the decimal point.
+
+- **`.`** or **`D`**
+
+ Specifies the position of the decimal point.
+
+ The input value does not need to include a decimal point.
+
+- **`,`** or **`G`**
+
+ Specifies the position of the `,` grouping (thousands) separator.
+
+ There must be a `0` or `9` to the left and right of each grouping separator.
+
+- **`$`**
+
+ Specifies the location of the `$` currency sign. This character may only be specified once.
+
+- **`S`**
+
+ Specifies the position of an optional '+' or '-' sign. This character may only be specified once.
+
+- **`MI`**
+
+ Specifies an optional `-` sign at the end, but no `+`.
+
+- **`PR`**
+
+ Maps negative input values to wrapping angle brackets (`<1>`) in the corresponding string.
+
+ Positive input values do not receive wrapping angle brackets.
+
+### Examples
+
+The following examples use the `try_to_number` SQL function which accepts an input string as the
Review Comment:
It would be great if we can have examples for to_number as well
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1162443809
@gengliangwang Updates from the latest round of review:
<img width="1255" alt="image" src="https://user-images.githubusercontent.com/99207096/174910423-9d3c6009-9a6d-453f-99ff-4cff317471ee.png">
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r903958488
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,137 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
+Decimal type. Such functions accept format strings indicating how to map between these types.
+
+### Syntax
+
+Number format strings support the following syntax:
+
+```
+ { ' [ S ] [ L | $ ]
+ [ 0 | 9 | G | , ] [...]
+ [ . | D ]
+ [ 0 | 9 ] [...]
+ [ L | $ ] [ PR | MI | S ] ' }
+```
+
+### Elements
+
+Each number format string can contain the following elements (case insensitive):
+
+- **`0`** or **`9`**
+
+ Specifies an expected digit between `0` and `9`.
+
+ A `0` to the left of the decimal point indicates that at least this many digits must be present.
Review Comment:
Sure, sounds good. Updated this to the docs here.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on a diff in pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on code in PR #36950:
URL: https://github.com/apache/spark/pull/36950#discussion_r906426882
##########
docs/sql-ref-number-pattern.md:
##########
@@ -19,4 +19,132 @@ license: |
limitations under the License.
---
-TODO: Add the content of Number Patterns for Formatting and Parsing
+### Description
+
+Functions such as `to_number` and `try_to_number` support converting between values of string and
Review Comment:
Done.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1171448405
Thanks @cloud-fan for putting up with me forgetting to push the last round of changes .__. Updated again.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] dtenedor commented on pull request #36950: [SPARK-38796][SQL] Update documentation for number format strings with the {try_}to_number functions
Posted by GitBox <gi...@apache.org>.
dtenedor commented on PR #36950:
URL: https://github.com/apache/spark/pull/36950#issuecomment-1167544715
friendly ping when you have a moment @cloud-fan :)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org