This is an automated email from the ASF dual-hosted git repository.
xiazcy pushed a commit to branch 3.8-dev
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
The following commit(s) were added to refs/heads/3.8-dev by this push:
new 3c04c9bb01 CTR fix asNumber() related docs
3c04c9bb01 is described below
commit 3c04c9bb0160191b6b8ed2cea7688d653da1d7b0
Author: Yang Xia <[email protected]>
AuthorDate: Mon Jul 20 12:59:35 2026 -0700
CTR fix asNumber() related docs
---
docs/src/dev/provider/gremlin-semantics.asciidoc | 8 +++---
docs/src/reference/the-traversal.asciidoc | 33 +++++-------------------
docs/src/upgrade/release-3.8.0.asciidoc | 9 ++++---
3 files changed, 17 insertions(+), 33 deletions(-)
diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc
b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 4bd94b29f2..1fc85258a4 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -809,27 +809,27 @@
link:https://tinkerpop.apache.org/docs/x.y.z/reference/#asDate-step[reference]
[[asNumber-step]]
=== asNumber()
-*Description:* converts 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.
+*Description:* converts the incoming traverser to the nearest parsable type if
no argument is provided, or to the desired numerical type, based on the type
token (`GType`) provided.
*Syntax:* `asNumber()` | `asNumber(GType typeToken)`
[width="100%",options="header"]
|=========================================================
|Start Step |Mid Step |Modulated |Domain |Range
-|N |Y |N |`Number`/`String` |`Number`
+|N |Y |N |`Number`/`String`/`Date` |`Number`
|=========================================================
*Arguments:*
* `typeToken` - The enum `GType` to denote the desired type to parse/cast to.
-If no type token is provided, the incoming number remains unchanged.
+If no type token is provided, the incoming number remains unchanged. A `Date`
input is converted to milliseconds since epoch. A `null` input passes through
as `null`.
*Exceptions*
* If any overflow occurs during narrowing of types, then an
`ArithmeticException` will be thrown.
* If the incoming string cannot be parsed into a valid number format, then a
`NumberFormatException` will be thrown.
-* If the incoming traverser is a non-String/Number (including `null`) value
then an `IllegalArgumentException` will be thrown.
+* If the incoming traverser is a non-String/Number/Date value then an
`IllegalArgumentException` will be thrown.
* If the supplied type token is not a number type, then an
`IllegalArgumentException` will be thrown.
See:
link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/AsNumberStep.java[source],
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index efaf2d424f..6ce8da2c9e 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -851,13 +851,14 @@ or to the desired numerical type, based on the type token
(`GType`) provided. If
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.
-String inputs are parsed into numeric values. By default, the value will be
parsed as an integer if it represents a
-whole number, or as a double if it contains a decimal point. A
`NumberFormatException` will be thrown if the string
-cannot be parsed into a valid number format.
+String inputs are parsed into numeric values, choosing the smallest type that
can represent the value without loss of
+precision. A whole number is parsed as an `Integer`, widening to `Long` or
`BigInteger` if it is too large to fit.
+A number with a decimal point is parsed as a `Float`, widening to `Double` or
`BigDecimal` when higher precision is
+required. A `NumberFormatException` will be thrown if the string cannot be
parsed into a valid number format.
Date inputs are converted to milliseconds since epoch (January 1, 1970,
00:00:00 GMT).
-All other input types will result in `IllegalArgumentException`.
+A `null` input passes through as `null`. All other input types will result in
`IllegalArgumentException`.
[gremlin-groovy,modern]
----
@@ -872,30 +873,10 @@ g.inject("2023-08-02T00:00:00Z").asDate().asNumber() <4>
<3> A double is converted into an int.
<4> A date is converted into milliseconds since epoch.
-[NOTE, caption=Java]
-====
-The enums values `byte`, `short`, `int`, `long`, `float`, `double` are
reserved word in Java, and therefore must be
-referred to in Gremlin with an underscore appended as a suffix: `byte_`,
`short_`, `int_`, `long_`, `float_`, `double_`.
-====
-
-[NOTE, caption=Groovy & Gremlin Console]
-====
-The enums values `byte`, `short`, `int`, `long`, `float`, `double` are
reserved word in Groovy, therefore as the Gremlin
-Console is Groovy-based, they must be referred to in Gremlin with an
underscore appended as a suffix: `byte_`,
-`short_`, `int_`, `long_`, `float_`, `double_`.
-====
-
-[NOTE, caption=JavaScript]
-====
-The enums values `byte`, `short`, `int`, `long`, `float`, `double` are
reserved word in Javascript, and therefore must
-be referred to in Gremlin with an underscore appended as a suffix: `byte_`,
`short_`, `int_`, `long_`, `float_`,
-`double_`.
-====
-
*Additional References*
-link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asNumber()++[`asNumber()`]
-link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asNumber(org.apache.tinkerpop.gremlin.process.traversal.N)++[`asNumber(N)`]
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asNumber()++[`asNumber()`],
+link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#asNumber(org.apache.tinkerpop.gremlin.process.traversal.GType)++[`asNumber(GType)`]
[[barrier-step]]
=== Barrier Step
diff --git a/docs/src/upgrade/release-3.8.0.asciidoc
b/docs/src/upgrade/release-3.8.0.asciidoc
index 6204d39df3..778b0045ef 100644
--- a/docs/src/upgrade/release-3.8.0.asciidoc
+++ b/docs/src/upgrade/release-3.8.0.asciidoc
@@ -615,7 +615,8 @@ See:
link:https://issues.apache.org/jira/browse/TINKERPOP-3083[TINKERPOP-3083]
===== asString() No Longer Allow Nulls
The `asString()` step will no longer allow `null` input. An
`IllegalArgumentException` will be thrown for consistency
-with all other parsing steps (i.e. `asDate()`, `asBool()`, `asNumber()`).
+with the `asDate()` and `asBool()` parsing steps. Note that `asNumber()`
differs here and passes `null` through as
+`null` rather than throwing.
See:
link:https://lists.apache.org/thread/q76pgrvhprosb4lty63bnsnbw2ljyl7m[DISCUSS]
thread
@@ -1436,8 +1437,10 @@ gremlin> g.inject(128).asNumber(GType.BYTE)
==> ArithmeticException
----
-String input will be parsed. By default, the smalled unit of number to be
parsed into is `int` if no type token is
-provided. `NumberFormatException` will be thrown for any unparsable strings:
+String input will be parsed into the smallest type that can hold the value
without losing precision when no type token
+is provided: a whole number defaults to `int` (widening to `long` or
`BigInteger`), and a number with a decimal point
+defaults to `float` (widening to `double` or `BigDecimal`).
`NumberFormatException` will be thrown for any unparsable
+strings:
[source,text]
----
