From commits-return-28610-archive-asf-public=cust-asf.ponee.io@tinkerpop.apache.org Thu Apr 26 17:02:41 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 6F4C2180679 for ; Thu, 26 Apr 2018 17:02:40 +0200 (CEST) Received: (qmail 78190 invoked by uid 500); 26 Apr 2018 15:02:39 -0000 Mailing-List: contact commits-help@tinkerpop.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@tinkerpop.apache.org Delivered-To: mailing list commits@tinkerpop.apache.org Received: (qmail 78174 invoked by uid 99); 26 Apr 2018 15:02:39 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 26 Apr 2018 15:02:39 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 798BDF32B1; Thu, 26 Apr 2018 15:02:39 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: spmallette@apache.org To: commits@tinkerpop.apache.org Date: Thu, 26 Apr 2018 15:02:40 -0000 Message-Id: In-Reply-To: References: X-Mailer: ASF-Git Admin Mailer Subject: [2/2] tinkerpop git commit: Improved javadoc on Gremlin enums CTR Improved javadoc on Gremlin enums CTR Project: http://git-wip-us.apache.org/repos/asf/tinkerpop/repo Commit: http://git-wip-us.apache.org/repos/asf/tinkerpop/commit/a4c5a213 Tree: http://git-wip-us.apache.org/repos/asf/tinkerpop/tree/a4c5a213 Diff: http://git-wip-us.apache.org/repos/asf/tinkerpop/diff/a4c5a213 Branch: refs/heads/tp32 Commit: a4c5a2132f8f0c7824ceddc8adefe06274767071 Parents: 5954525 Author: Stephen Mallette Authored: Thu Apr 26 09:39:52 2018 -0400 Committer: Stephen Mallette Committed: Thu Apr 26 09:39:52 2018 -0400 ---------------------------------------------------------------------- .../gremlin/process/traversal/Compare.java | 12 ++++ .../gremlin/process/traversal/Contains.java | 4 ++ .../gremlin/process/traversal/Operator.java | 73 ++++++++++++++++++- .../tinkerpop/gremlin/process/traversal/P.java | 76 ++++++++++++++++++++ .../gremlin/process/traversal/Pop.java | 14 +++- .../gremlin/process/traversal/Scope.java | 19 +++-- 6 files changed, 188 insertions(+), 10 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a4c5a213/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Compare.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Compare.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Compare.java index 97b52b8..7d0d071 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Compare.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Compare.java @@ -36,6 +36,8 @@ public enum Compare implements BiPredicate { * {@link BigDecimal} so that it can be evaluated via {@link BigDecimal#compareTo}. Otherwise they are evaluated * via {@link Object#equals(Object)}. Testing against {@link Number#doubleValue()} enables the compare * operations to be a bit more forgiving with respect to comparing different number types. + * + * @since 3.0.0-incubating */ eq { @Override @@ -61,6 +63,8 @@ public enum Compare implements BiPredicate { * {@link BigDecimal} so that it can be evaluated via {@link BigDecimal#equals}. Otherwise they are evaluated * via {@link Object#equals(Object)}. Testing against {@link Number#doubleValue()} enables the compare * operations to be a bit more forgiving with respect to comparing different number types. + * + * @since 3.0.0-incubating */ neq { @Override @@ -83,6 +87,8 @@ public enum Compare implements BiPredicate { * {@link BigDecimal} so that it can be evaluated via {@link BigDecimal#compareTo}. Otherwise they are evaluated * via {@link Comparable#compareTo(Object)}. Testing against {@link BigDecimal#compareTo} enables the compare * operations to be a bit more forgiving with respect to comparing different number types. + * + * @since 3.0.0-incubating */ gt { @Override @@ -108,6 +114,8 @@ public enum Compare implements BiPredicate { * {@link BigDecimal} so that it can be evaluated via {@link BigDecimal#compareTo}. Otherwise they are evaluated * via {@link Comparable#compareTo(Object)}. Testing against {@link BigDecimal#compareTo} enables the compare * operations to be a bit more forgiving with respect to comparing different number types. + * + * @since 3.0.0-incubating */ gte { @Override @@ -130,6 +138,8 @@ public enum Compare implements BiPredicate { * {@link BigDecimal} so that it can be evaluated via {@link BigDecimal#compareTo}. Otherwise they are evaluated * via {@link Comparable#compareTo(Object)}. Testing against {@link BigDecimal#compareTo} enables the compare * operations to be a bit more forgiving with respect to comparing different number types. + * + * @since 3.0.0-incubating */ lt { @Override @@ -155,6 +165,8 @@ public enum Compare implements BiPredicate { * {@link BigDecimal} so that it can be evaluated via {@link BigDecimal#compareTo}. Otherwise they are evaluated * via {@link Comparable#compareTo(Object)}. Testing against {@link BigDecimal#compareTo} enables the compare * operations to be a bit more forgiving with respect to comparing different number types. + * + * @since 3.0.0-incubating */ lte { @Override http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a4c5a213/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Contains.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Contains.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Contains.java index 2da0436..da46d0b 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Contains.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Contains.java @@ -38,6 +38,8 @@ public enum Contains implements BiPredicate { /** * The first object is within the {@link Collection} provided in the second object. + * + * @since 3.0.0-incubating */ within { @Override @@ -48,6 +50,8 @@ public enum Contains implements BiPredicate { /** * The first object is not within the {@link Collection} provided in the second object. + * + * @since 3.0.0-incubating */ without { @Override http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a4c5a213/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Operator.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Operator.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Operator.java index a52f34b..f9e0b5c 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Operator.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Operator.java @@ -23,65 +23,132 @@ import java.util.Map; import java.util.function.BinaryOperator; /** + * A set of {@link BinaryOperator} instances that handle common operations for traversal steps. + * * @author Marko A. Rodriguez (http://markorodriguez.com) */ public enum Operator implements BinaryOperator { + /** + * An addition function. + * + * @since 3.0.0-incubating + */ sum { public Object apply(final Object a, Object b) { return NumberHelper.add((Number) a, (Number) b); } }, + + /** + * A subtraction function. + * + * @since 3.0.0-incubating + */ minus { public Object apply(final Object a, final Object b) { return NumberHelper.sub((Number) a, (Number) b); } }, + + /** + * A multiplication function. + * + * @since 3.0.0-incubating + */ mult { public Object apply(final Object a, final Object b) { return NumberHelper.mul((Number) a, (Number) b); } }, + + /** + * A division function. + * + * @since 3.0.0-incubating + */ div { public Object apply(final Object a, final Object b) { return NumberHelper.div((Number) a, (Number) b); } }, + + /** + * Selects the smaller of the values. + * + * @since 3.0.0-incubating + */ min { public Object apply(final Object a, final Object b) { return NumberHelper.min((Number) a, (Number) b); } }, + + /** + * Selects the larger of the values. + * + * @since 3.0.0-incubating + */ max { public Object apply(final Object a, final Object b) { return NumberHelper.max((Number) a, (Number) b); } }, + + /** + * The new incoming value (i.e. the second value to the function) is returned unchanged result in the assignment + * of that value to the object of the {@code Operator}. + * + * @since 3.1.0-incubating + */ assign { public Object apply(final Object a, final Object b) { return b; } }, + + /** + * Applies "and" to boolean values. + * + * @since 3.2.0-incubating + */ and { public Object apply(final Object a, final Object b) { return ((boolean) a) && ((boolean) b); } }, + + /** + * Applies "or" to boolean values. + * + * @since 3.2.0-incubating + */ or { public Object apply(final Object a, final Object b) { return ((boolean) a) || ((boolean) b); } }, + + /** + * Takes all objects in the second {@code Collection} and adds them to the first. + * + * @since 3.2.0-incubating + */ addAll { public Object apply(final Object a, final Object b) { if (a instanceof Map) - ((Map) a).putAll((Map) b); + ((Map) a).putAll((Map) b); else - ((Collection) a).addAll((Collection) b); + ((Collection) a).addAll((Collection) b); return a; } }, - ////// + + /** + * Sums and adds long values. + * + * @since 3.2.0-incubating + */ sumLong { public Object apply(final Object a, final Object b) { return (long) a + (long) b; http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a4c5a213/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/P.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/P.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/P.java index 3b2d0c2..8454f33 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/P.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/P.java @@ -28,6 +28,7 @@ import java.util.function.BiPredicate; import java.util.function.Predicate; /** + * Predefined {@code Predicate} values that can be used with * @author Marko A. Rodriguez (http://markorodriguez.com) * @author Stephen Mallette (http://stephen.genoprime.com) */ @@ -121,62 +122,137 @@ public class P implements Predicate, Serializable, Cloneable { //////////////// statics + /** + * Determines if values are equal. + * + * @since 3.0.0-incubating + */ public static P eq(final V value) { return new P(Compare.eq, value); } + /** + * Determines if values are not equal. + * + * @since 3.0.0-incubating + */ public static P neq(final V value) { return new P(Compare.neq, value); } + /** + * Determines if a value is less than another. + * + * @since 3.0.0-incubating + */ public static P lt(final V value) { return new P(Compare.lt, value); } + /** + * Determines if a value is less than or equal to another. + * + * @since 3.0.0-incubating + */ public static P lte(final V value) { return new P(Compare.lte, value); } + /** + * Determines if a value is greater than another. + * + * @since 3.0.0-incubating + */ public static P gt(final V value) { return new P(Compare.gt, value); } + /** + * Determines if a value is greater than or equal to another. + * + * @since 3.0.0-incubating + */ public static P gte(final V value) { return new P(Compare.gte, value); } + /** + * Determines if a value is within (exclusive) the range of the two specified values. + * + * @since 3.0.0-incubating + */ public static P inside(final V first, final V second) { return new AndP(Arrays.asList(new P(Compare.gt, first), new P(Compare.lt, second))); } + /** + * Determines if a value is not within (exclusive) of the range of the two specified values. + * + * @since 3.0.0-incubating + */ public static P outside(final V first, final V second) { return new OrP(Arrays.asList(new P(Compare.lt, first), new P(Compare.gt, second))); } + /** + * Determines if a value is within (inclusive) of the range of the two specified values. + * + * @since 3.0.0-incubating + */ public static P between(final V first, final V second) { return new AndP(Arrays.asList(new P(Compare.gte, first), new P(Compare.lt, second))); } + /** + * Determines if a value is within the specified list of values. + * + * @since 3.0.0-incubating + */ public static P within(final V... values) { return P.within(Arrays.asList(values)); } + /** + * Determines if a value is within the specified list of values. + * + * @since 3.0.0-incubating + */ public static P within(final Collection value) { return new P(Contains.within, value); } + /** + * Determines if a value is not within the specified list of values. + * + * @since 3.0.0-incubating + */ public static P without(final V... values) { return P.without(Arrays.asList(values)); } + /** + * Deermines if a value is not within the specified list of values. + * + * @since 3.0.0-incubating + */ public static P without(final Collection value) { return new P(Contains.without, value); } + /** + * Construct an instance of {@code P} from a {@code BiPredicate}. + * + * @since 3.0.0-incubating + */ public static P test(final BiPredicate biPredicate, final Object value) { return new P(biPredicate, value); } + /** + * The opposite of the specified {@code P}. + * + * @since 3.0.0-incubating + */ public static P not(final P predicate) { return predicate.negate(); } http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a4c5a213/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Pop.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Pop.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Pop.java index c9eab94..b2fe2b9 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Pop.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Pop.java @@ -19,20 +19,28 @@ package org.apache.tinkerpop.gremlin.process.traversal; /** + * Methods for extracting an item from a collection. + * * @author Marko A. Rodriguez (http://markorodriguez.com) */ public enum Pop { /** - * The first item in an ordered collection (i.e. collection[0]) + * The first item in an ordered collection (i.e. {@code collection[0]}). + * + * @since 3.0.0-incubating */ first, /** - * The last item in an ordered collection (i.e. collection[collection.size()-1]) + * The last item in an ordered collection (i.e. {@code collection[collection.size()-1]}). + * + * @since 3.0.0-incubating */ last, /** - * Get all the items and return them as a list + * Get all the items and return them as a list. + * + * @since 3.0.0-incubating */ all } http://git-wip-us.apache.org/repos/asf/tinkerpop/blob/a4c5a213/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Scope.java ---------------------------------------------------------------------- diff --git a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Scope.java b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Scope.java index 11979de..c454922 100644 --- a/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Scope.java +++ b/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/Scope.java @@ -19,15 +19,26 @@ package org.apache.tinkerpop.gremlin.process.traversal; /** - * Many {@link Step} instance can have a variable scope. - * {@link Scope#global}: the step operates on the entire traversal. - * {@link Scope#local}: the step operates on the current object in the step. + * Many {@link Step} instance can have a variable scope which alter the manner in which the step will behave in + * relation to how the traversers are processed. * * @author Marko A. Rodriguez (http://markorodriguez.com) */ public enum Scope { - global, local; + /** + * Informs the step to operate on the entire traversal. + * + * @since 3.0.0-incubating + */ + global, + + /** + * Informs the step to operate on the current object in the step. + * + * @since 3.0.0-incubating + */ + local; public Scope opposite() { return global.equals(this) ? local : global;