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
The following commit(s) were added to refs/heads/master by this push:
new f6382038fc Clarify difference() step semantics in the provider
documentation
f6382038fc is described below
commit f6382038fc641664930d9ccc701574b6f260f44f
Author: Stephen Mallette <[email protected]>
AuthorDate: Fri Sep 11 14:41:50 2026 +0000
Clarify difference() step semantics in the provider documentation
Expand the Considerations for the difference() step in
gremlin-semantics.asciidoc
with language-agnostic behavioral detail. The result is a SET whose
iteration
order is unspecified and does not preserve the incoming list order, and A-B
is
directional rather than order-preserving. Membership compares members by
both
value and type, so numerically equal values of different types are
distinct, and
a null is a legal list element while a null or non-iterable whole traverser
or
argument raises an error. It also notes that a traversal supplied as the
argument
produces the comparison list as a single result.
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/dev/provider/gremlin-semantics.asciidoc | 19 ++++++++++++++++---
1 file changed, 16 insertions(+), 3 deletions(-)
diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc
b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 791a935313..0c1e80a487 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -1640,9 +1640,22 @@ None
*Considerations:*
-Set difference (`A-B`) is an ordered operation. The incoming traverser is
treated as `A` and the provided argument is
-treated as `B`. A set is returned after the difference operation is applied so
there won't be duplicates. This step only
-applies to list types which means that non-iterable types (including null)
will cause exceptions to be thrown.
+Set difference (`A-B`) is a directional operation. The incoming traverser is
treated as `A` and the provided argument
+as `B`, so `A-B` and `B-A` generally yield different results. This
directionality is the only sense in which the
+operation is ordered. The result is a `SET`, so it contains no duplicates, and
its iteration order is unspecified. In
+particular the result does not preserve the order of the incoming list, so a
traversal that depends on a particular
+member order orders the result explicitly.
+
+Membership of the result is decided by comparing each member of `A` against
the members of `B` by value and by type.
+Numerically equal values of different numeric types, such as an `INT` and a
`LONG` of the same magnitude, are treated
+as distinct members, so a value from `A` is removed only when `B` contains a
member of the same type and value. A
+`NULL` is a legal member of either list and is compared in the same way, so a
`NULL` in `A` is removed only when `B`
+also contains a `NULL`.
+
+This step only applies to lists. An error is raised when the incoming
traverser or the argument is itself `NULL` or is
+not iterable, while a `NULL` that appears as an element of an otherwise
iterable list is permitted and behaves as
+described above. When the argument is supplied as a `Traversal`, that
traversal produces the comparison list as a
+single result rather than as a stream of separate results.
*Exceptions:*
