[
https://issues.apache.org/jira/browse/TINKERPOP-2978?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17778759#comment-17778759
]
ASF GitHub Bot commented on TINKERPOP-2978:
-------------------------------------------
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.
> Add List Manipulation Steps to Gremlin
> --------------------------------------
>
> Key: TINKERPOP-2978
> URL: https://issues.apache.org/jira/browse/TINKERPOP-2978
> Project: TinkerPop
> Issue Type: Improvement
> Components: language
> Reporter: Cole Greer
> Priority: Major
>
> Today Gremlin requires that users fall back to closures to handle many common
> list manipulation options that users want to do on data in the graph. This
> is a problem for many users as many of the providers prevent the use of
> closures due to the security risks so for these users there is no way to
> manipulate lists directly.
> A full list of proposed functions and semantics is detailed here:
> https://github.com/apache/tinkerpop/blob/3.7.0/docs/src/dev/future/proposal-3-remove-closures.asciidoc
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
