This is an automated email from the ASF dual-hosted git repository. spmallette pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/tinkerpop.git
commit f34d481f1560bb1ca2af7b80e32f9740a0aad1f2 Author: Stephen Mallette <[email protected]> AuthorDate: Fri Sep 25 16:56:52 2026 +0000 Clarify Gremlin.Net type limitations with the actual client-side outcome Sharpen the Gremlin.Net Limitations section so each type-range limitation states its true trigger and the concrete behavior a user hits when the server returns an out-of-range value. The DateTimeOffset entry notes that the +/-14:00 offset bound, not merely an extreme year, is the common trigger, and that the DateTimeOffset constructor rejects the value so Gremlin.Net raises an ArgumentOutOfRangeException while reading the result. The Duration and BigDecimal entries name the OverflowException raised when a value exceeds the TimeSpan range or the decimal precision of 28-29 digits. The null Map key entry states that such a result raises an IOException. The non-BMP character entry now states the real behavior: the four-byte Char is decoded into a surrogate pair of which only the leading surrogate is returned, so the character is silently corrupted without an error. Assisted-by: Kiro:claude-opus-4.8 --- docs/src/reference/gremlin-variants.asciidoc | 33 ++++++++++++++++++++-------- 1 file changed, 24 insertions(+), 9 deletions(-) diff --git a/docs/src/reference/gremlin-variants.asciidoc b/docs/src/reference/gremlin-variants.asciidoc index 714f0e7b7d..9193d6237e 100644 --- a/docs/src/reference/gremlin-variants.asciidoc +++ b/docs/src/reference/gremlin-variants.asciidoc @@ -3206,21 +3206,36 @@ anchor:gremlin-net-limitations[] [[gremlin-dotnet-limitations]] === Limitations +Several Gremlin types have a wider domain than their closest C# counterparts. When the server returns a value +that falls outside the C# range, the outcome depends on the type. In most cases Gremlin.Net raises an exception +as it deserializes the response, so the error surfaces on the client at the point the result is read. The one +exception is a character outside the Basic Multilingual Plane, which is reconstructed incorrectly without any +error. + * The `subgraph()`-step returns a detached `Graph` data container exposing `Vertices: IDictionary<object, Vertex>` and `Edges: IDictionary<object, Edge>`. The result is not a live `Graph` instance: mutating the collections has no effect on the source graph, and it cannot be passed to `traversal().with(...)`. To re-query subgraph elements against the original graph, extract their `Id` and use `g.V(id)` / `g.E(id)` on the original `GraphTraversalSource`. -* `DateTimeOffset` cannot represent the extreme values of Gremlin's `OffsetDateTime` maximum and minimum, -so offset date-time values at those boundaries will fail to deserialize. -* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so extreme duration values (such as -`Duration.FOREVER`) that exceed `TimeSpan.MaxValue` or `TimeSpan.MinValue` will fail to deserialize. +* C#'s `DateTimeOffset` accepts offsets only in the range `-14:00` to `+14:00` and years from 1 to 9999, while +Gremlin's `OffsetDateTime` permits offsets up to `+18:00`/`-18:00` and a much wider year range. When the offset +or year of the returned value lies outside the C# range, the `DateTimeOffset` constructor rejects it and +Gremlin.Net raises an `ArgumentOutOfRangeException` while reading the result. The offset bound is the more common +trigger, since a value such as `datetime('2018-03-22T00:35:44.741+18:00')` is a valid `OffsetDateTime` that +cannot be represented as a `DateTimeOffset`. +* Gremlin's `Duration` type has a much larger range than C#'s `TimeSpan`, so a duration whose magnitude exceeds +`TimeSpan.MaxValue` or `TimeSpan.MinValue` cannot be constructed and Gremlin.Net raises an `OverflowException` +while reading the result. This affects only extreme values such as `Duration.FOREVER`. Durations within the +`TimeSpan` range are unaffected. * Gremlin's `BigDecimal` supports up to 33 digits of precision while C#'s `decimal` type is limited to 28-29 -significant digits, so high-precision values may lose accuracy or fail to deserialize. -* C# `char` values do not support values outside the Basic Multilingual Plane, which are mainly 4-byte UTF-8 -characters. Those GraphBinary `Char` values are not supported. -* C# `Dictionary` does not allow `null` keys, so `Map` results with `null` keys (e.g. from `group()` or -`groupCount()` on a missing property) will fail during deserialization. +significant digits. When the returned value exceeds the `decimal` range, the conversion overflows and +Gremlin.Net raises an `OverflowException` while reading the result. +* C#'s `char` holds a single UTF-16 code unit and cannot represent a code point outside the Basic Multilingual +Plane, which GraphBinary encodes as a four-byte `Char`. Such a value is decoded into a surrogate pair, of which +only the leading surrogate is returned, so the character is silently corrupted rather than raising an error. +Characters within the Basic Multilingual Plane are unaffected. +* C#'s `Dictionary` does not allow `null` keys, so a `Map` result that contains a `null` key cannot be populated +and Gremlin.Net raises an `IOException` while reading the result. anchor:gremlin-dotnet-template[] anchor:dotnet-application-examples[]
