[
https://issues.apache.org/jira/browse/TINKERPOP-3166?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=18009832#comment-18009832
]
ASF GitHub Bot commented on TINKERPOP-3166:
-------------------------------------------
andreachild commented on code in PR #3153:
URL: https://github.com/apache/tinkerpop/pull/3153#discussion_r2230153721
##########
docs/src/upgrade/release-3.8.x.asciidoc:
##########
@@ -30,6 +30,69 @@ complete list of all the modifications that are part of this
release.
=== Upgrading for Users
+==== Number Conversion Step
+
+We have been iterative introducing new language features into Gremlin, with
the last major set of string, list and date manipulation
+steps introduced in the 3.7 line. In 3.8.0, we are now introducing a number
conversion step, `asNumber()`, to bridge
+a gap in casting functionalities.
+
+The new `asNumber()` serves as an umbrella step that parses strings and casts
numbers into desired types. For the convenience of remote traversals in GLVs,
these number types are denoted by a set of number tokens (`N`).
+
+This new step will allow users to normalize their data by converting string
numbers and mixed numeric types to consistent format, making it easier to
perform downstream mathematical operations. As an example:
+
+[source,text]
+----
+// sum() step can only take numbers
+gremlin> g.inject(1.0, 2l, 3, "4", "0x5").sum()
+class java.lang.String cannot be cast to class java.lang.Number
+
+// use asNumber() to avoid casting exceptions
+gremlin> g.inject(1.0, 2l, 3, "4", "0x5").asNumber().sum()
+==>15.0
+
+// given sum() step returned a double, one can use asNumber() to further cast
the result into desired type
+gremlin> g.inject(1.0, 2l, 3, "4", "0x5").asNumber().sum().asNumber(N.nint)
+==>15
+----
+
+Semantically, the `asNumber()` step will convert the incoming traverser to the
nearest parsable type if no argument is provided, or to the desired numerical
type, based on the number token (`N`) provided.
+
+Numerical input will pass through unless a type is specified by the number
token. `ArithmeticException` will be thrown for any overflow during narrowing
of types:
Review Comment:
```suggestion
Numerical input will pass through unless a type is specified by the number
token. `ArithmeticException` will be thrown for any overflow as a result of
narrowing of types:
```
> Add number conversion step asNumber()
> -------------------------------------
>
> Key: TINKERPOP-3166
> URL: https://issues.apache.org/jira/browse/TINKERPOP-3166
> Project: TinkerPop
> Issue Type: Improvement
> Components: language
> Affects Versions: 3.8.0
> Reporter: Yang Xia
> Priority: Major
>
> Given the addition of the {{asString()}} and {{asDate()}} steps in the 3.7
> line, it should also be helpful to add an {{asNumber()}} step that does
> numerical casting/conversions.
> The current idea is for the {{asNumber()}} step to convert the incoming
> traverser to the nearest parsable type (e.g. int or double) if no argument is
> provided, or to the desired numerical type, based on a number token
> ({{{}N{}}}) provided. Like the {{asDate()}} step, it will not be scoped (for
> now, scopes can be added in the future).
> Some conjured examples:
> {code:java}
> gremlin> g.inject(5).asNumber()
> ==> 5 // parses to int
> gremlin> g.inject(5.123f).asNumber()
> ==> 5.123
> gremlin> g.inject(5.43).asNumber(N.int)
> ==> 5 {code}
> More details can be found in the [proposal
> doc|https://github.com/apache/tinkerpop/blob/master/docs/src/dev/future/proposal-asnumber-step-6.asciidoc].
>
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
