org.incava.ijdk.lang.Pair Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of ijdk Show documentation
Incava Java Development Kit
There is a newer version: 3.9.0
package org.incava.ijdk.lang;

/**
 * A two-element tuple, for classes that are comparable. Consider using KeyValue instead, which is
 * more flexible in variable types.
 *
 * @see KeyValue
 */
public class Pair, SecondType extends Comparable> 
    implements Comparable> {

    /**
     * Class method that allows inference of the parameterized type. The parameters must implement
     * Comparable.
     *
     *      *     // compare:
     *     Pair<String, Integer> pair = new Pair<String, Integer>("Homer", 34);
     *     Pair<String, Integer> pair = Pair.create("Homer", 34);
     * 
     *
     * @param  the type of the first value; must be Comparable
     * @param first the first value in the pair
     * @param  the type of the second value; must be Comparable
     * @param second the second value in the pair
     * @return the created pair
     */
    public static , Y extends Comparable>
        Pair of(X first, Y second) {
        return new Pair(first, second);
    }

    private final FirstType first;    
    private final SecondType second;
    
    /**
     * @param first the first value in the pair
     * @param second the second value in the pair
     */
    public Pair(FirstType first, SecondType second) {
        this.first  = first;
        this.second = second;
    }

    /**
     * Returns the first element.
     *
     * @return the first elememt
     */
    public FirstType getFirst() {
        return first;
    }

    /**
     * Returns the second element.
     *
     * @return the second elememt
     */
    public SecondType getSecond() {
        return second;
    }

    /**
     * Returns the first element, with a shorter method name than getFirst.
     *
     * @return the first elememt
     */
    public FirstType first() {
        return first;
    }

    /**
     * Returns the second element, with a shorter method name than getSecond~.
     *
     * @return the second elememt
     */
    public SecondType second() {
        return second;
    }

    /**
     * Compares this pair to the object, which should be of type Pair, or otherwise
     * false is returned.
     *
     * @param obj the object to compare to; can be null
     * @return whether the object equals this pair
     */
    public boolean equals(Object obj) {
        if (obj instanceof Pair) {
            Pair other = (Pair)obj;
            return getFirst().equals(other.getFirst()) && getSecond().equals(other.getSecond());
        }
        else {
            return false;
        }
    }

    /**
     * Compares this pair to the other.
     *
     * @param other the other object
     * @return the comparison value
     */
    public int compareTo(Pair other) {
        int cmp = getFirst().compareTo(other.getFirst());

        if (cmp == 0) {
            cmp = getSecond().compareTo(other.getSecond());
        }
        
        return cmp;
    }

    /**
     * Returns the pair as a string in the form "first, second".
     *
     * @return the pair in the form "first, second".
     */
    public String toString() {
        return String.valueOf(first) + ", " + String.valueOf(second);
    }

    /**
     * Returns a hash code for the pair.
     * 
     * @return the hash code
     */
    public int hashCode() {
        return (first == null ? 1 : first.hashCode()) * 31 + (second == null ? 1 : second.hashCode());
    }
}