Cole-Greer commented on code in PR #3683:
URL: https://github.com/apache/tinkerpop/pull/3683#discussion_r4106631578
##########
docs/src/reference/gremlin-variants.asciidoc:
##########
@@ -3183,21 +3183,50 @@ anchor:gremlin-net-limitations[]
[[gremlin-dotnet-limitations]]
=== Limitations
+Several Gremlin types have a wider domain than their closest C# counterparts,
so a value produced by the server
+that falls outside the C# range fails to deserialize when Gremlin.Net reads
the result.
+
* 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. An offset
+date-time whose offset or year lies outside the C# range fails to deserialize.
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`
+but 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` fails to deserialize. 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, so a value that exceeds the `decimal` range fails to
deserialize.
+* 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 not
reconstructed correctly on
+deserialization. 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 fails to
+deserialize. A `null` key does not arise from `group()` or `groupCount()` over
a missing property, because an
Review Comment:
> A `null` key does not arise from `group()` or `groupCount()` over a
missing property, because an element whose key-defining traversal produces
nothing is dropped from the result rather than counted under a `null` key. A
`null` key must be introduced explicitly, for example with
`by(coalesce(values('lang'), constant(null)))`.
In my opinion this is unnecessary flourish, people know what a null map key
is, I don't think we need to tell them what does and doesn't produce them.
--
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]
