org.matheclipse.generic.interfaces.Pair Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of ext.bundle.math.symja_jas Show documentation
The newest version!
/*
 * Copyright (c) 2006 Frederic Daoud, Javelot Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */
/*
 * Pair.java
 */
package org.matheclipse.generic.interfaces;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;

/**
 * Used to create a tuple of two objects. Tuples can be used anywhere there is a
 * need to group objects together, and Pairs are used by the
 * {@link Tuples#zip(Collection, Collection)} method.
 * 
 * @param A
 *          the type of the first object.
 * @param B
 *          the type of the second object.
 * 
 * @author Copyright © 2006 Frederic Daoud
 */
public class Pair, B extends Comparable> implements Comparable>,
		Serializable {
	// Version UID for serialization, generated by the serialver command.
	private static final long serialVersionUID = 1322589550168140645L;

	// The two objects contained by this pair.
	private A m_first;

	private B m_second;

	/**
	 * Default constructor.
	 */
	public Pair() {
	}

	/**
	 * Creates a tuple containing the two given objects.
	 * 
	 * @param p_first
	 *          the first object of the pair. A null value is
	 *          accepted.
	 * @param p_second
	 *          the second object of the pair. A null value is
	 *          accepted.
	 */
	public Pair(A p_first, B p_second) {
		m_first = p_first;
		m_second = p_second;
	}

	/**
	 * Returns the first object of the tuple.
	 * 
	 * @return the first object of the tuple, which may be null.
	 */
	public A getFirst() {
		return m_first;
	}

	/**
	 * Sets the first object of the tuple.
	 * 
	 * @param p_first
	 *          the first object of the tuple.
	 */
	public void setFirst(A p_first) {
		m_first = p_first;
	}

	/**
	 * Returns the second object of the tuple.
	 * 
	 * @return the second object of the tuple, which may be null.
	 */
	public B getSecond() {
		return m_second;
	}

	/**
	 * Sets the second object of the tuple.
	 * 
	 * @param p_second
	 *          the second object of the tuple.
	 */
	public void setSecond(B p_second) {
		m_second = p_second;
	}

	/**
	 * Returns the hash code associated with this object.
	 * 
	 * 
	 * Thanks to Paul Field for suggesting the improvement on this hash function.
	 * 
	 * 
	 * @return the hash code associated with this object, which is calculated by
	 *         adding together the hash codes of the objects contained in the
	 *         tuple, multiplying by 31 each time. A
	 *         null value is considered to have* a hash code of
	 *         0. Thus, if this pair contains two null
	 *         values, this method returns 0.
	 */
	public int hashCode() {
		int hc = 0;
		if (m_first != null) {
			hc += m_first.hashCode();
		}
		if (m_second != null) {
			hc *= 31;
			hc += m_second.hashCode();
		}
		return hc;
	}

	/**
	 * Determines if the given object is equal to this object, by comparing the
	 * two objects of each tuple using their respective
	 * equals(Object) methods. Corresponding null values
	 * are also considered equal.
	 * 
	 * @param obj
	 *          the object against which to compare this tuple.
	 * @return true if the pairs contain the same values;
	 *         false otherwise.
	 */
	@SuppressWarnings("unchecked")
	public boolean equals(Object obj) {
		if (this == obj) {
			return true;
		}
		if (obj instanceof Pair) {
			Pair other = (Pair) obj;
			return m_first.equals(other.getFirst()) && m_second.equals(other.getSecond());
		}
		return false;
	}

	/**
	 * Sort tuples according to the objects that they contain. If the contained in
	 * the tuples do not implement the {@link java.lang.Comparable} interface,
	 * they are left unsorted.
	 */
	public int compareTo(Pair p_pair) {
		try {
			int result = m_first.compareTo(p_pair.getFirst());
			if (result == 0) {
				result = m_second.compareTo(p_pair.getSecond());
			}
			return result;
		} catch (ClassCastException exc) {
			return 0;
		}
	}

	/**
	 * Returns a list of the String representations of the objects of the tuple.
	 * Subclasses override this method to specify additional objects. The
	 * {@link #toString()} method uses this to construct the String representation
	 * of the tuple.
	 * 
	 * @return a list of the String representations of the objects of the tuple.
	 */
	protected List getStrings() {
		List result = new ArrayList();

		result.add(String.valueOf(m_first));
		result.add(String.valueOf(m_second));

		return result;
	}

	/**
	 * Returns a String representation of the Pair.
	 * 
	 * @return a String representation of the Pair of the form
	 *         "(String, String)".
	 */
	public String toString() {
		return "(" + m_first.toString() + ", " + m_second.toString() + ")";
	}
}