001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.lang3.compare;
018
019import java.util.function.Predicate;
020
021import org.apache.commons.lang3.ObjectUtils;
022
023/**
024 * Utility library to provide helper methods for translating {@link Comparable#compareTo} result into a boolean.
025 *
026 * <p>Example: {@code boolean x = is(myComparable).lessThanOrEqualTo(otherComparable)}</p>
027 *
028 * <p>#ThreadSafe#</p>
029 *
030 * @since 3.10
031 */
032public class ComparableUtils {
033
034    /**
035     * Provides access to the available methods
036     *
037     * @param <A> the type of objects that this object may be compared against.
038     */
039    public static class ComparableCheckBuilder<A extends Comparable<A>> {
040
041        private final A a;
042
043        private ComparableCheckBuilder(final A a) {
044            this.a = a;
045        }
046
047        /**
048         * Checks if {@code [b <= a <= c]} or {@code [b >= a >= c]} where the {@code a} is object passed to {@link #is}.
049         *
050         * @param b the object to compare to the base object
051         * @param c the object to compare to the base object
052         * @return true if the base object is between b and c
053         */
054        public boolean between(final A b, final A c) {
055            return betweenOrdered(b, c) || betweenOrdered(c, b);
056        }
057
058        /**
059         * Checks if {@code (b < a < c)} or {@code (b > a > c)} where the {@code a} is object passed to {@link #is}.
060         *
061         * @param b the object to compare to the base object
062         * @param c the object to compare to the base object
063         * @return true if the base object is between b and c and not equal to those
064         */
065        public boolean betweenExclusive(final A b, final A c) {
066            return betweenOrderedExclusive(b, c) || betweenOrderedExclusive(c, b);
067        }
068
069        private boolean betweenOrdered(final A b, final A c) {
070            return greaterThanOrEqualTo(b) && lessThanOrEqualTo(c);
071        }
072
073        private boolean betweenOrderedExclusive(final A b, final A c) {
074            return greaterThan(b) && lessThan(c);
075        }
076
077        /**
078         * Checks if the object passed to {@link #is} is equal to {@code b}
079         *
080         * @param b the object to compare to the base object
081         * @return true if the value returned by {@link Comparable#compareTo} is equal to {@code 0}
082         */
083        public boolean equalTo(final A b) {
084            return a.compareTo(b) == 0;
085        }
086
087        /**
088         * Checks if the object passed to {@link #is} is greater than {@code b}
089         *
090         * @param b the object to compare to the base object
091         * @return true if the value returned by {@link Comparable#compareTo} is greater than {@code 0}
092         */
093        public boolean greaterThan(final A b) {
094            return a.compareTo(b) > 0;
095        }
096
097        /**
098         * Checks if the object passed to {@link #is} is greater than or equal to {@code b}
099         *
100         * @param b the object to compare to the base object
101         * @return true if the value returned by {@link Comparable#compareTo} is greater than or equal to {@code 0}
102         */
103        public boolean greaterThanOrEqualTo(final A b) {
104            return a.compareTo(b) >= 0;
105        }
106
107        /**
108         * Checks if the object passed to {@link #is} is less than {@code b}
109         *
110         * @param b the object to compare to the base object
111         * @return true if the value returned by {@link Comparable#compareTo} is less than {@code 0}
112         */
113        public boolean lessThan(final A b) {
114            return a.compareTo(b) < 0;
115        }
116
117        /**
118         * Checks if the object passed to {@link #is} is less than or equal to {@code b}
119         *
120         * @param b the object to compare to the base object
121         * @return true if the value returned by {@link Comparable#compareTo} is less than or equal to {@code 0}
122         */
123        public boolean lessThanOrEqualTo(final A b) {
124            return a.compareTo(b) <= 0;
125        }
126    }
127
128    /**
129     * Checks if {@code [b <= a <= c]} or {@code [b >= a >= c]} where the {@code a} is the tested object.
130     *
131     * @param b the object to compare to the tested object
132     * @param c the object to compare to the tested object
133     * @param <A> type of the test object
134     * @return a predicate for true if the tested object is between b and c
135     */
136    public static <A extends Comparable<A>> Predicate<A> between(final A b, final A c) {
137        return a -> is(a).between(b, c);
138    }
139
140    /**
141     * Checks if {@code (b < a < c)} or {@code (b > a > c)} where the {@code a} is the tested object.
142     *
143     * @param b the object to compare to the tested object
144     * @param c the object to compare to the tested object
145     * @param <A> type of the test object
146     * @return a predicate for true if the tested object is between b and c and not equal to those
147     */
148    public static <A extends Comparable<A>> Predicate<A> betweenExclusive(final A b, final A c) {
149        return a -> is(a).betweenExclusive(b, c);
150    }
151
152    /**
153     * Checks if the tested object is greater than or equal to {@code b}
154     *
155     * @param b the object to compare to the tested object
156     * @param <A> type of the test object
157     * @return a predicate for true if the value returned by {@link Comparable#compareTo}
158     * is greater than or equal to {@code 0}
159     */
160    public static <A extends Comparable<A>> Predicate<A> ge(final A b) {
161        return a -> is(a).greaterThanOrEqualTo(b);
162    }
163
164    /**
165     * Checks if the tested object is greater than {@code b}
166     *
167     * @param b the object to compare to the tested object
168     * @param <A> type of the test object
169     * @return a predicate for true if the value returned by {@link Comparable#compareTo} is greater than {@code 0}
170     */
171    public static <A extends Comparable<A>> Predicate<A> gt(final A b) {
172        return a -> is(a).greaterThan(b);
173    }
174
175    /**
176     * Provides access to the available methods
177     *
178     * @param a base object in the further comparison
179     * @param <A> type of the base object
180     * @return a builder object with further methods
181     */
182    public static <A extends Comparable<A>> ComparableCheckBuilder<A> is(final A a) {
183        return new ComparableCheckBuilder<>(a);
184    }
185
186    /**
187     * Checks if the tested object is less than or equal to {@code b}
188     *
189     * @param b the object to compare to the tested object
190     * @param <A> type of the test object
191     * @return a predicate for true if the value returned by {@link Comparable#compareTo}
192     * is less than or equal to {@code 0}
193     */
194    public static <A extends Comparable<A>> Predicate<A> le(final A b) {
195        return a -> is(a).lessThanOrEqualTo(b);
196    }
197
198    /**
199     * Checks if the tested object is less than {@code b}
200     *
201     * @param b the object to compare to the tested object
202     * @param <A> type of the test object
203     * @return a predicate for true if the value returned by {@link Comparable#compareTo} is less than {@code 0}
204     */
205    public static <A extends Comparable<A>> Predicate<A> lt(final A b) {
206        return a -> is(a).lessThan(b);
207    }
208
209    /**
210     * Returns the greater of two {@link Comparable} values, ignoring null.
211     * <p>
212     * For three or more values, use {@link ObjectUtils#max(Comparable...)}.
213     * </p>
214     *
215     * @param <A> Type of what we are comparing.
216     * @param comparable1 the first comparable, may be null.
217     * @param comparable2 the second comparable, may be null.
218     * @return the largest of {@code comparable1} and {@code comparable2}.
219     * @see ObjectUtils#max(Comparable...)
220     * @since 3.13.0
221     */
222    public static <A extends Comparable<A>> A max(final A comparable1, final A comparable2) {
223        return ObjectUtils.compare(comparable1, comparable2, false) > 0 ? comparable1 : comparable2;
224    }
225
226    /**
227     * Returns the lesser of two {@link Comparable} values, ignoring null.
228     * <p>
229     * For three or more values, use {@link ObjectUtils#min(Comparable...)}.
230     * </p>
231     *
232     * @param <A> Type of what we are comparing.
233     * @param comparable1 the first comparable, may be null.
234     * @param comparable2 the second comparable, may be null.
235     * @return the smallest of {@code comparable1} and {@code comparable2}.
236     * @see ObjectUtils#min(Comparable...)
237     * @since 3.13.0
238     */
239    public static <A extends Comparable<A>> A min(final A comparable1, final A comparable2) {
240        return ObjectUtils.compare(comparable1, comparable2, true) < 0 ? comparable1 : comparable2;
241    }
242
243    private ComparableUtils() {
244        // empty
245    }
246}