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 Lang 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 from 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 new StringBuilder().append('(').append(getLeft()).append(',').append(getRight()).append(')').toString();
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}