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;
021
022import org.apache.commons.lang3.ObjectUtils;
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<L, R>(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    @SuppressWarnings( "deprecation" ) // ObjectUtils.equals(Object, Object) has been deprecated in 3.2
128    @Override
129    public boolean equals(final Object obj) {
130        if (obj == this) {
131            return true;
132        }
133        if (obj instanceof Map.Entry<?, ?>) {
134            final Map.Entry<?, ?> other = (Map.Entry<?, ?>) obj;
135            return ObjectUtils.equals(getKey(), other.getKey())
136                    && ObjectUtils.equals(getValue(), other.getValue());
137        }
138        return false;
139    }
140
141    /**
142     * <p>Returns a suitable hash code.
143     * The hash code follows the definition in {@code Map.Entry}.</p>
144     * 
145     * @return the hash code
146     */
147    @Override
148    public int hashCode() {
149        // see Map.Entry API specification
150        return (getKey() == null ? 0 : getKey().hashCode()) ^
151                (getValue() == null ? 0 : getValue().hashCode());
152    }
153
154    /**
155     * <p>Returns a String representation of this pair using the format {@code ($left,$right)}.</p>
156     * 
157     * @return a string describing this object, not null
158     */
159    @Override
160    public String toString() {
161        return new StringBuilder().append('(').append(getLeft()).append(',').append(getRight()).append(')').toString();
162    }
163
164    /**
165     * <p>Formats the receiver using the given format.</p>
166     * 
167     * <p>This uses {@link java.util.Formattable} to perform the formatting. Two variables may
168     * be used to embed the left and right elements. Use {@code %1$s} for the left
169     * element (key) and {@code %2$s} for the right element (value).
170     * The default format used by {@code toString()} is {@code (%1$s,%2$s)}.</p>
171     * 
172     * @param format  the format string, optionally containing {@code %1$s} and {@code %2$s}, not null
173     * @return the formatted string, not null
174     */
175    public String toString(final String format) {
176        return String.format(format, getLeft(), getRight());
177    }
178
179}