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.math4.legacy.core;
018
019/**
020 * Generic pair.
021 * <br>
022 * Although the instances of this class are immutable, it is impossible
023 * to ensure that the references passed to the constructor will not be
024 * modified by the caller.
025 *
026 * @param <K> Key type.
027 * @param <V> Value type.
028 *
029 * @since 3.0
030 */
031public class Pair<K, V> {
032    /** Key. */
033    private final K key;
034    /** Value. */
035    private final V value;
036
037    /**
038     * Create an entry representing a mapping from the specified key to the
039     * specified value.
040     *
041     * @param k Key (first element of the pair).
042     * @param v Value (second element of the pair).
043     */
044    public Pair(K k, V v) {
045        key = k;
046        value = v;
047    }
048
049    /**
050     * Create an entry representing the same mapping as the specified entry.
051     *
052     * @param entry Entry to copy.
053     */
054    public Pair(Pair<? extends K, ? extends V> entry) {
055        this(entry.getKey(), entry.getValue());
056    }
057
058    /**
059     * Get the key.
060     *
061     * @return the key (first element of the pair).
062     */
063    public K getKey() {
064        return getFirst();
065    }
066
067    /**
068     * Get the value.
069     *
070     * @return the value (second element of the pair).
071     */
072    public V getValue() {
073        return getSecond();
074    }
075
076    /**
077     * Get the first element of the pair.
078     *
079     * @return the first element of the pair.
080     * @since 3.1
081     */
082    public K getFirst() {
083        return key;
084    }
085
086    /**
087     * Get the second element of the pair.
088     *
089     * @return the second element of the pair.
090     * @since 3.1
091     */
092    public V getSecond() {
093        return value;
094    }
095
096    /**
097     * Compare the specified object with this entry for equality.
098     *
099     * @param o Object.
100     * @return {@code true} if the given object is also a map entry and
101     * the two entries represent the same mapping.
102     */
103    @Override
104    public boolean equals(Object o) {
105        if (this == o) {
106            return true;
107        }
108        if (!(o instanceof Pair)) {
109            return false;
110        } else {
111            Pair<?, ?> oP = (Pair<?, ?>) o;
112            return (key == null ?
113                    oP.key == null :
114                    key.equals(oP.key)) &&
115                (value == null ?
116                 oP.value == null :
117                 value.equals(oP.value));
118        }
119    }
120
121    /**
122     * Compute a hash code.
123     *
124     * @return the hash code value.
125     */
126    @Override
127    public int hashCode() {
128        int result = key == null ? 0 : key.hashCode();
129
130        final int h = value == null ? 0 : value.hashCode();
131        result = 37 * result + h ^ (h >>> 16);
132
133        return result;
134    }
135
136    /** {@inheritDoc} */
137    @Override
138    public String toString() {
139        return "[" + getKey() + ", " + getValue() + "]";
140    }
141
142    /**
143     * Convenience factory method that calls the
144     * {@link #Pair(Object, Object) constructor}.
145     *
146     * @param <K> the key type
147     * @param <V> the value type
148     * @param k First element of the pair.
149     * @param v Second element of the pair.
150     * @return a new {@code Pair} containing {@code k} and {@code v}.
151     * @since 3.3
152     */
153    public static <K, V> Pair<K, V> create(K k, V v) {
154        return new Pair<>(k, v);
155    }
156}