andreachild commented on code in PR #3153: URL: https://github.com/apache/tinkerpop/pull/3153#discussion_r2230182273
########## 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: + +[source,text] +---- +gremlin> g.inject(5.0).asNumber(N.nint) +==> 5 // casts double to int +gremlin> g.inject(12).asNumber(N.byte) +==> 12 +gremlin> g.inject(128).asNumber(N.byte) Review Comment: ```suggestion gremlin> g.inject(128).asNumber(N.nbyte) ``` -- 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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
