Merge branch '3.8-dev'

Author: Cole-Greer

CHANGELOG.asciidoc

@@ -94,6 +94,7 @@ image::https://raw.githubusercontent.com/apache/tinkerpop/master/docs/static/ima
 
 This release also includes changes from <<release-3-7-XXX, 3.7.XXX>>.
 
+* Modified mathematical operators to prevent overflows in steps such as `sum()` and 'sack()' to prefer promotion to the next highest number type.
 * Added `DateTime` ontop of the existing 'datetime' grammar.
 * Added UUID() + UUID(value) to grammar
 * Modified `TraversalStrategy` construction in Javascript where configurations are now supplied as a `Map` of options.

docs/src/dev/provider/gremlin-semantics.asciidoc

@@ -85,7 +85,7 @@ TinkerPop performs type promotion a.k.a type casting for Numbers. Numbers are By
 Double, BigInteger, and BigDecimal. In general, numbers are compared using semantic equivalence, without regard for
 their specific type, e.g. `1 == 1.0`.
 
-Numeric types are promoted as follows:
+For comparisons numeric types are promoted as follows:
 
 * First determine whether to use floating point or not. If any numbers in the comparison are floating point then we
 convert all of them to floating point.
@@ -104,6 +104,16 @@ convert all of them to floating point.
 BigDecimal and BigInteger may not be supported depending on the language and Storage, therefore the behavior of type
 casting for these two types can vary depending on a Graph provider.
 
+For numeric type mathematical operations (div/mul/add/sub), types are promoted as follows:
+
+On math operations (when used in steps such as sum/sack) the highest common number class between
+the two inputs is used. Any number being floating point forces a floating point result.
+If an overflow occurs (either integer or floating-point), the method promotes the precision
+by increasing the bit width, until a suitable type is found. If no suitable type exists
+(e.g., for very large integers beyond 64-bit), an Arithmetic Exception is thrown.
+For floating-point numbers, if double overflows, the result is Double.POSITIVE_INFINITY
+or Double.NEGATIVE_INFINITY instead of an exception.
+
 [[gremlin-semantics-concepts]]
 == Comparability, Equality, Orderability, and Equivalence
 

docs/src/upgrade/release-3.8.x.asciidoc

@@ -30,6 +30,47 @@ complete list of all the modifications that are part of this release.
 
 === Upgrading for Users
 
+==== Auto promotion of number types
+
+Previously, operations like sum or sack that involved mathematical calculations did not automatically promote the result
+to a larger numeric type (e.g., from int to long) when needed. As a result, values could wrap around within their current
+type, leading to unexpected behavior. This issue has now been resolved by enabling automatic type promotion for results.
+
+Now, any mathematical operations such as Add, Sub, Mul, and Div will now automatically promote to the next numeric type
+if an overflow is detected. For integers, the promotion sequence is: byte → short → int → long → overflow exception. For
+floating-point numbers, the sequence is: float → double → infinity.
+
+The following example showcases the change in overflow behavior between 3.7.3 and 3.8.0
+
+[source,groovy]
+----
+// 3.7.3
+gremlin> g.inject([Byte.MAX_VALUE, (byte) 1], [Short.MAX_VALUE, (short) 1], [Integer.MAX_VALUE,1], [Long.MAX_VALUE, 1l]).sum(local)
+==>-128 // byte
+==>-32768 // short
+==>-2147483648 // int
+==>-9223372036854775808 // long
+
+gremlin> g.inject([Float.MAX_VALUE, Float.MAX_VALUE], [Double.MAX_VALUE, Double.MAX_VALUE]).sum(local)
+==>Infinity // float
+==>Infinity // double
+
+// 3.8.0
+gremlin> g.inject([Byte.MAX_VALUE, (byte) 1], [Short.MAX_VALUE, (short) 1], [Integer.MAX_VALUE,1]).sum(local)
+==>128 // short
+==>32768 // int
+==>2147483648 // long
+
+gremlin> g.inject([Long.MAX_VALUE, 1l]).sum(local)
+// throws java.lang.ArithmeticException: long overflow
+
+gremlin> g.inject([Float.MAX_VALUE, Float.MAX_VALUE], [Double.MAX_VALUE, Double.MAX_VALUE]).sum(local)
+==>6.805646932770577E38 // double
+==>Infinity // double
+----
+
+See link:https://issues.apache.org/jira/browse/TINKERPOP-3115[TINKERPOP-3115] for more details.
+
 ==== The Switch from Date to OffsetDateTime
 The default implementation for date type in Gremlin is now changed from the `java.util.Date` to the more encompassing `java.time.OffsetDateTime`. This means the reference implementation for all date manipulation steps, `asDate()`, `dateAdd()`, and `dateDiff()`, as well as helper methods `datetime()`, will return `OffsetDateTime`, whose string representation will be in ISO 8601 format.
 
@@ -254,11 +295,6 @@ The GLVs will only support GraphBinary V4 and GraphSON support has been removed.
 that was available in most GLVs has been removed. GraphBinary is a more compact format and has support for the same
 types. This should lead to increased performance for users upgrading from any version of GraphSON to GraphBinary.
 
-==== Improved handling of integer overflows
-
-Integer overflows caused by addition and multiplication operations will throw an exception instead of being silently
-skipped with incorrect result.
-
 ==== Gremlin Lang Float Literals Default to Double
 
 The `GremlinLangScriptEngine` has been modified to treat float literals without explicit type suffixes (like 'm', 'f',
@@ -334,6 +370,26 @@ link:https://tinkerpop.apache.org/docs/3.8.0/dev/provider/#gherkin-tests-suite[P
 
 See: link:https://issues.apache.org/jira/browse/TINKERPOP-3136[TINKERPOP-3136]
 
+==== Auto promotion of number types
+
+Previously, operations like sum or sack that involved mathematical calculations did not automatically promote the result
+to a larger numeric type (e.g., from int to long) when needed. As a result, values could wrap around within their current
+type, leading to unexpected behavior. This issue has now been resolved by enabling automatic type promotion for results.
+
+Now, any mathematical operations such as Add, Sub, Mul, and Div will now automatically promote to the next numeric type
+if an overflow is detected. For integers, the promotion sequence is: byte → short → int → long → overflow exception. For
+floating-point numbers, the sequence is: float → double → infinity.
+
+As a example the following query...
+
+"""
+g.withSack(32767s).inject(1s).sack(sum).sack()
+"""
+
+Before would return a short overflow exception or wrap to -1 depending on language, but now returns 32769i.
+
+See link:https://issues.apache.org/jira/browse/TINKERPOP-3115[TINKERPOP-3115] for more details.
+
 ==== The Switch from Date to OffsetDateTime
 
 The default implementation for date type in Gremlin is now changed from the deprecated `java.util.Date` to the more encompassing `java.time.OffsetDateTime`. This means the reference implementation for all date manipulation steps, `asDate()`, `dateAdd()`, and `dateDiff()`, as well as helper methods `datetime()`, will return `OffsetDateTime`, whose string representation will be in ISO 8601 format.