Cole-Greer commented on code in PR #2302: URL: https://github.com/apache/tinkerpop/pull/2302#discussion_r1367395931
########## docs/src/dev/provider/gremlin-semantics.asciidoc: ########## @@ -725,6 +725,42 @@ link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/o link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/service/ServiceRegistry.java[ServiceRegistry], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#call-step[reference] +[[combine-step]] +=== combine() + +*Description:* Appends one list to the other and returns the result to the Traversal Stream. + +*Syntax:* `combine(Object)` + +[width="100%",options="header"] +|========================================================= +|Start Step |Mid Step |Modulated |Domain |Range +|N |Y |N |`array`/`Iterable` |`List` +|========================================================= + +*Arguments:* + +* `Object` - A list of items (as an Iterable or an array) a traversal that will produce a list of items. Review Comment: ```suggestion * `Object` - A list of items (as an Iterable or an array), or a traversal that will produce a list of items. ``` ########## docs/src/dev/provider/gremlin-semantics.asciidoc: ########## @@ -725,6 +725,42 @@ link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/o link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/structure/service/ServiceRegistry.java[ServiceRegistry], link:https://tinkerpop.apache.org/docs/x.y.z/reference/#call-step[reference] +[[combine-step]] +=== combine() + +*Description:* Appends one list to the other and returns the result to the Traversal Stream. + +*Syntax:* `combine(Object)` + +[width="100%",options="header"] +|========================================================= +|Start Step |Mid Step |Modulated |Domain |Range +|N |Y |N |`array`/`Iterable` |`List` +|========================================================= + +*Arguments:* + +* `Object` - A list of items (as an Iterable or an array) a traversal that will produce a list of items. + +*Modulation:* + +None + +*Considerations:* + +A list is returned after the combine operation is applied so duplicates are allowed. `Merge` can be used instead if +duplicates aren't wanted. This step only applies to list types which means that non-iterable types (including null) +will cause exceptions to be thrown. + +*Exceptions* + +* If the incoming traverser isn't a list (array or Iterable) then an `IllegalArgumentException` will be thrown. +* If the argument doesn't resolve to a list (array or Iterable) 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/filter/CombineStep.java[source], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#combine-step[reference], +link:https://tinkerpop.apache.org/docs/x.y.z/reference/#merge-step[reference], Review Comment: Is the link to the merge reference docs intended here? If so can we change the hyperlink name to something else such as: ```suggestion link:https://tinkerpop.apache.org/docs/x.y.z/reference/#merge-step[merge() reference] ``` ########## docs/src/reference/the-traversal.asciidoc: ########## @@ -1140,6 +1140,24 @@ g.V().coin(1.0) link:++https://tinkerpop.apache.org/javadocs/x.y.z/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html#coin-double-++[`coin(double)`] +[[combine-step]] +=== Combine Step + +The `combine()`-step (*map*) combines the elements of the incoming list traverser and the provided list argument into +one list. This is also known as appending or concatenating. This step only expects list data (array or Iterable) and +will throw an `IllegalArgumentException` if any other type is encountered (including null). This differs from the +`merge` step in that it allows duplicates to exist. + +[gremlin-groovy,modern] +---- +g.V().values("name").fold().combine(["james","jen","marko","vadas"]) Review Comment: Could you add one example for each step which uses a child traversal as the argument? It would be good to showcase that capability as well. -- 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]
