[2/3] incubator-tinkerpop git commit: TINKERPOP3-670: Add doc for tail step

[ok...@apache.org]

TINKERPOP3-670: Add doc for tail step


Project: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/commit/12f854b8
Tree: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/tree/12f854b8
Diff: http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/diff/12f854b8

Branch: refs/heads/master
Commit: 12f854b8fbb636ec1e44ba514465ce61220f60f4
Parents: 50b8945
Author: mhfrantz <mf...@redsealnetworks.com>
Authored: Fri May 15 16:49:33 2015 -0700
Committer: mhfrantz <mf...@redsealnetworks.com>
Committed: Fri May 15 17:28:35 2015 -0700

----------------------------------------------------------------------
 docs/src/the-traversal.asciidoc | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/12f854b8/docs/src/the-traversal.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/the-traversal.asciidoc b/docs/src/the-traversal.asciidoc
index ca01fc4..0519ce3 100644
--- a/docs/src/the-traversal.asciidoc
+++ b/docs/src/the-traversal.asciidoc
@@ -1262,6 +1262,38 @@ g.V().repeat(both()).times(3).values('age').sum()
 
 IMPORTANT: `sum(local)` determines the sum of the current, local object (not the objects in the traversal stream). This works for `Collection`-type objects. For any other object, a sum of `Double.NaN` is returned.
 
+[[tail-step]]
+Tail Step
+~~~~~~~~~
+
+The `tail()`-step is analogous to <<limit-step,`limit()`-step>>, except that it emits the last few objects instead of the first few.
+
+[gremlin-groovy,modern]
+----
+g.V().values('name').order().tail() <1>
+g.V().values('name').order().tail(1) <2>
+g.V().values('name').order().tail(3) <3>
+----
+
+<1> Last name (alphabetically).
+<2> Same as statement 1.
+<3> Last three names.
+
+The `tail()`-step can also be applied with `Scope.local`, in which case it operates on the incoming collection.
+
+[gremlin-groovy,modern]
+----
+g.V().as('a').out().as('a').out().as('a').select('a').by(tail(local)).values('name') <1>
+g.V().as('a').out().as('a').out().as('a').select('a').by(unfold().values('name').fold()).tail(local) <2>
+g.V().as('a').out().as('a').out().as('a').select('a').by(unfold().values('name').fold()).tail(local, 2) <3>
+g.V().valueMap().tail(local) <4>
+----
+
+<1> Only the most recent name from the "a" step (`List<Vertex>` becomes `Vertex`).
+<2> Same result as statement 1 (`List<String>` becomes `String`).
+<3> `List<String>` for each path containing the last two names from the 'a' step.
+<4> `Map<String, Object>` for each vertex, but containing only the last property value.
+
 [[timelimit-step]]
 TimeLimit Step
 ~~~~~~~~~~~~~~