    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.tuple;
    018
    019import java.io.Serializable;
    020import java.util.Map;
    021import java.util.Objects;
    022
    023import org.apache.commons.lang3.builder.CompareToBuilder;
    024
    025/**
    026 * <p>A pair consisting of two elements.</p>
    027 *
    028 * <p>This class is an abstract implementation defining the basic API.
    029 * It refers to the elements as 'left' and 'right'. It also implements the
    030 * {@code Map.Entry} interface where the key is 'left' and the value is 'right'.</p>
    031 *
    032 * <p>Subclass implementations may be mutable or immutable.
    033 * However, there is no restriction on the type of the stored objects that may be stored.
    034 * If mutable objects are stored in the pair, then the pair itself effectively becomes mutable.</p>
    035 *
    036 * @param <L> the left element type
    037 * @param <R> the right element type
    038 *
    039 * @since 3.0
    040 */
    041public abstract class Pair<L, R> implements Map.Entry<L, R>, Comparable<Pair<L, R>>, Serializable {
    042
    043    /** Serialization version */
    044    private static final long serialVersionUID = 4954918890077093841L;
    045
    046    /**
    047     * <p>Obtains an immutable pair of two objects inferring the generic types.</p>
    048     *
    049     * <p>This factory allows the pair to be created using inference to
    050     * obtain the generic types.</p>
    051     *
    052     * @param <L> the left element type
    053     * @param <R> the right element type
    054     * @param left  the left element, may be null
    055     * @param right  the right element, may be null
    056     * @return a pair formed from the two parameters, not null
    057     */
    058    public static <L, R> Pair<L, R> of(final L left, final R right) {
    059        return new ImmutablePair<>(left, right);
    060    }
    061
    062    //-----------------------------------------------------------------------
    063    /**
    064     * <p>Gets the left element from this pair.</p>
    065     *
    066     * <p>When treated as a key-value pair, this is the key.</p>
    067     *
    068     * @return the left element, may be null
    069     */
    070    public abstract L getLeft();
    071
    072    /**
    073     * <p>Gets the right element from this pair.</p>
    074     *
    075     * <p>When treated as a key-value pair, this is the value.</p>
    076     *
    077     * @return the right element, may be null
    078     */
    079    public abstract R getRight();
    080
    081    /**
    082     * <p>Gets the key from this pair.</p>
    083     *
    084     * <p>This method implements the {@code Map.Entry} interface returning the
    085     * left element as the key.</p>
    086     *
    087     * @return the left element as the key, may be null
    088     */
    089    @Override
    090    public final L getKey() {
    091        return getLeft();
    092    }
    093
    094    /**
    095     * <p>Gets the value from this pair.</p>
    096     *
    097     * <p>This method implements the {@code Map.Entry} interface returning the
    098     * right element as the value.</p>
    099     *
    100     * @return the right element as the value, may be null
    101     */
    102    @Override
    103    public R getValue() {
    104        return getRight();
    105    }
    106
    107    //-----------------------------------------------------------------------
    108    /**
    109     * <p>Compares the pair based on the left element followed by the right element.
    110     * The types must be {@code Comparable}.</p>
    111     *
    112     * @param other  the other pair, not null
    113     * @return negative if this is less, zero if equal, positive if greater
    114     */
    115    @Override
    116    public int compareTo(final Pair<L, R> other) {
    117      return new CompareToBuilder().append(getLeft(), other.getLeft())
    118              .append(getRight(), other.getRight()).toComparison();
    119    }
    120
    121    /**
    122     * <p>Compares this pair to another based on the two elements.</p>
    123     *
    124     * @param obj  the object to compare to, null returns false
    125     * @return true if the elements of the pair are equal
    126     */
    127    @Override
    128    public boolean equals(final Object obj) {
    129        if (obj == this) {
    130            return true;
    131        }
    132        if (obj instanceof Map.Entry<?, ?>) {
    133            final Map.Entry<?, ?> other = (Map.Entry<?, ?>) obj;
    134            return Objects.equals(getKey(), other.getKey())
    135                    && Objects.equals(getValue(), other.getValue());
    136        }
    137        return false;
    138    }
    139
    140    /**
    141     * <p>Returns a suitable hash code.
    142     * The hash code follows the definition in {@code Map.Entry}.</p>
    143     *
    144     * @return the hash code
    145     */
    146    @Override
    147    public int hashCode() {
    148        // see Map.Entry API specification
    149        return (getKey() == null ? 0 : getKey().hashCode()) ^
    150                (getValue() == null ? 0 : getValue().hashCode());
    151    }
    152
    153    /**
    154     * <p>Returns a String representation of this pair using the format {@code ($left,$right)}.</p>
    155     *
    156     * @return a string describing this object, not null
    157     */
    158    @Override
    159    public String toString() {
    160        return "(" + getLeft() + ',' + getRight() + ')';
    161    }
    162
    163    /**
    164     * <p>Formats the receiver using the given format.</p>
    165     *
    166     * <p>This uses {@link java.util.Formattable} to perform the formatting. Two variables may
    167     * be used to embed the left and right elements. Use {@code %1$s} for the left
    168     * element (key) and {@code %2$s} for the right element (value).
    169     * The default format used by {@code toString()} is {@code (%1$s,%2$s)}.</p>
    170     *
    171     * @param format  the format string, optionally containing {@code %1$s} and {@code %2$s}, not null
    172     * @return the formatted string, not null
    173     */
    174    public String toString(final String format) {
    175        return String.format(format, getLeft(), getRight());
    176    }
    177
    178}