Hash typeclass

core/src/main/scala/cats/instances/all.scala

@@ -25,3 +25,4 @@ trait AllInstances
   with    TupleInstances
   with    UUIDInstances
   with    SymbolInstances
+  with    HashInstances

core/src/main/scala/cats/instances/hash.scala

@@ -0,0 +1,18 @@
+package cats
+package instances
+
+import cats.functor._
+
+/**
+ * @author Tongfei Chen
+ */
+trait HashInstances {
+  implicit val catsFunctorContravariantForHash: Contravariant[Hash] =
+    new Contravariant[Hash] {
+      /** Derive an `Hash` for `B` given an `Hash[A]` and a function `B => A`.
+       *
+       * Note: resulting instances are law-abiding only when the functions used are injective (represent a one-to-one mapping)
+       */
+      def contramap[A, B](fa: Hash[A])(f: B => A): Hash[B] = Hash.by(f)(fa)
+    }
+}

core/src/main/scala/cats/package.scala

@@ -78,13 +78,15 @@ package object cats {
   type Eq[A] = cats.kernel.Eq[A]
   type PartialOrder[A] = cats.kernel.PartialOrder[A]
   type Order[A] = cats.kernel.Order[A]
+  type Hash[A] = cats.kernel.Hash[A]
   type Semigroup[A] = cats.kernel.Semigroup[A]
   type Monoid[A] = cats.kernel.Monoid[A]
   type Group[A] = cats.kernel.Group[A]
 
   val Eq = cats.kernel.Eq
   val PartialOrder = cats.kernel.PartialOrder
   val Order = cats.kernel.Order
+  val Hash = cats.kernel.Hash
   val Semigroup = cats.kernel.Semigroup
   val Monoid = cats.kernel.Monoid
   val Group = cats.kernel.Group

kernel-laws/src/main/scala/cats/kernel/laws/HashLaws.scala

@@ -0,0 +1,38 @@
+package cats.kernel
+package laws
+
+import org.typelevel.discipline.Laws
+import org.scalacheck._
+import org.scalacheck.Prop._
+
+object HashLaws {
+  def apply[A : Eq : Arbitrary : Cogen]: HashLaws[A] =
+    new HashLaws[A] {
+      def Equ = implicitly[Eq[A]]
+      def Arb = implicitly[Arbitrary[A]]
+      def Cog = implicitly[Cogen[A]]
+    }
+}
+
+/**
+ * @author Tongfei Chen
+ */
+trait HashLaws[A] extends Laws {
+
+  implicit def Equ: Eq[A]
+  implicit def Arb: Arbitrary[A]
+  implicit def Cog: Cogen[A]
+
+  def hash(implicit A: Hash[A]): HashProperties = new HashProperties(
+    name = "hash",
+    parent = None,
+    Rules.serializable(Equ),
+    "compatibility-hash" -> forAll { (x: A, y: A) =>
+      !(A.eqv(x, y)) ?|| (A.hash(x) == A.hash(y))
+    }
+  )
+
+  class HashProperties(name: String, parent: Option[RuleSet], props: (String, Prop)*)
+  extends DefaultRuleSet(name, parent, props: _*)
+
+}

kernel-laws/src/test/scala/cats/kernel/laws/LawTests.scala

@@ -27,6 +27,7 @@ class LawTests extends FunSuite with Discipline {
   implicit override val generatorDrivenConfig: PropertyCheckConfiguration =
     PropertyCheckConfiguration(minSuccessful = PropMinSuccessful, sizeRange = PropMaxSize)
 
+  implicit def hashLaws[A: Cogen: Eq: Arbitrary]: HashLaws[A] = HashLaws[A]
   implicit def orderLaws[A: Cogen: Eq: Arbitrary]: OrderLaws[A] = OrderLaws[A]
   implicit def groupLaws[A: Cogen: Eq: Arbitrary]: GroupLaws[A] = GroupLaws[A]
 
@@ -61,6 +62,24 @@ class LawTests extends FunSuite with Discipline {
     laws[OrderLaws, Map[String, HasEq[Int]]].check(_.eqv)
   }
 
+  laws[HashLaws, Unit].check(_.hash)
+  laws[HashLaws, Boolean].check(_.hash)
+  laws[HashLaws, String].check(_.hash)
+  laws[HashLaws, Symbol].check(_.hash)
+  laws[HashLaws, Byte].check(_.hash)
+  laws[HashLaws, Short].check(_.hash)
+  laws[HashLaws, Char].check(_.hash)
+  laws[HashLaws, Int].check(_.hash)
+  laws[HashLaws, Long].check(_.hash)
+  laws[HashLaws, BitSet].check(_.hash)
+  laws[HashLaws, BigInt].check(_.hash)
+  laws[HashLaws, UUID].check(_.hash)
+  laws[HashLaws, List[Int]].check(_.hash)
+  laws[HashLaws, Option[String]].check(_.hash)
+  laws[HashLaws, List[String]].check(_.hash)
+  laws[HashLaws, Vector[Int]].check(_.hash)
+  laws[HashLaws, Stream[Int]].check(_.hash)
+
   laws[OrderLaws, List[HasEq[Int]]].check(_.eqv)
   laws[OrderLaws, Option[HasEq[Int]]].check(_.eqv)
   laws[OrderLaws, Vector[HasEq[Int]]].check(_.eqv)

kernel/src/main/scala/cats/kernel/Hash.scala

@@ -0,0 +1,52 @@
+package cats.kernel
+
+import scala.{specialized => sp}
+import scala.util.hashing.Hashing
+
+/**
+ * A type class used to represent a hashing scheme for objects of a given type.
+ * For any two instances `x` and `y` that are considered equivalent under the
+ * equivalence relation defined by this object, `hash(x)` should equal `hash(y)`.
+ * @author Tongfei Chen
+ */
+trait Hash[@sp A] extends Any with Eq[A] with Serializable { self =>
+
+  /**
+   * Returns the hash code of the given object under this hashing scheme.
+   */
+  def hash(x: A): Int
+
+  // `Hash#on` deliberately not implement to avoid `Hash`/`Order` diamond inheritance problem.
+  // Please use `Hash.by` for the same functionality.
+}
+
+abstract class HashFunctions[H[T] <: Hash[T]] extends EqFunctions[H] {
+
+  def hash[@sp A](x: A)(implicit ev: H[A]): Int = ev hash x
+
+}
+
+
+object Hash extends HashFunctions[Hash] {
+
+  /** Fetch a `Hash` instance given the specific type. */
+  @inline final def apply[A](implicit ev: Hash[A]): Hash[A] = ev
+
+  def by[@sp A, @sp B](f: A => B)(implicit ev: Hash[B]): Hash[A] =
+    new Hash[A] {
+      def hash(x: A) = ev.hash(f(x))
+      def eqv(x: A, y: A) = ev.eqv(f(x), f(y))
+    }
+
+  implicit def catsKernelHashingForHash[A](implicit ev: Hash[A]): Hashing[A] =
+    new Hashing[A] {
+      def hash(x: A): Int = ev.hash(x)
+    }
+
+  def fromUniversalHashCode[A]: Hash[A] =
+    new Hash[A] {
+      def hash(x: A) = x.##
+      def eqv(x: A, y: A) = x == y
+    }
+
+}

kernel/src/main/scala/cats/kernel/instances/bigDecimal.scala

@@ -4,8 +4,8 @@ package instances
 package object bigDecimal extends BigDecimalInstances // scalastyle:ignore package.object.name
 
 trait BigDecimalInstances {
-  implicit val catsKernelStdOrderForBigDecimal: Order[BigDecimal] =
-    new BigDecimalOrder
+  implicit val catsKernelStdEqForBigDecimal: Order[BigDecimal] with Hash[BigDecimal] =
+    new BigDecimalEq
   implicit val catsKernelStdGroupForBigDecimal: CommutativeGroup[BigDecimal] =
     new BigDecimalGroup
 }
@@ -17,7 +17,9 @@ class BigDecimalGroup extends CommutativeGroup[BigDecimal] {
   override def remove(x: BigDecimal, y: BigDecimal): BigDecimal = x - y
 }
 
-class BigDecimalOrder extends Order[BigDecimal] {
+class BigDecimalEq extends Order[BigDecimal] with Hash[BigDecimal] {
+
+  def hash(x: BigDecimal): Int = x.hashCode()
 
   def compare(x: BigDecimal, y: BigDecimal): Int = x compare y
 

kernel/src/main/scala/cats/kernel/instances/bigInt.scala

@@ -4,8 +4,8 @@ package instances
 package object bigInt extends BigIntInstances // scalastyle:ignore package.object.name
 
 trait BigIntInstances {
-  implicit val catsKernelStdOrderForBigInt: Order[BigInt] =
-    new BigIntOrder
+  implicit val catsKernelStdEqForBigInt: Order[BigInt] with Hash[BigInt] =
+    new BigIntEq
   implicit val catsKernelStdGroupForBigInt: CommutativeGroup[BigInt] =
     new BigIntGroup
 }
@@ -17,8 +17,9 @@ class BigIntGroup extends CommutativeGroup[BigInt] {
   override def remove(x: BigInt, y: BigInt): BigInt = x - y
 }
 
-class BigIntOrder extends Order[BigInt] {
+class BigIntEq extends Order[BigInt] with Hash[BigInt] {
 
+  def hash(x: BigInt): Int = x.hashCode()
   def compare(x: BigInt, y: BigInt): Int = x compare y
 
   override def eqv(x: BigInt, y: BigInt): Boolean = x == y

kernel/src/main/scala/cats/kernel/instances/bitSet.scala

@@ -6,14 +6,16 @@ import scala.collection.immutable.BitSet
 package object bitSet extends BitSetInstances
 
 trait BitSetInstances {
-  implicit val catsKernelStdPartialOrderForBitSet: PartialOrder[BitSet] =
-    new BitSetPartialOrder
+  implicit val catsKernelStdEqForBitSet: PartialOrder[BitSet] with Hash[BitSet] =
+    new BitSetPartialEq
 
   implicit val catsKernelStdSemilatticeForBitSet: BoundedSemilattice[BitSet] =
     new BitSetSemilattice
 }
 
-class BitSetPartialOrder extends PartialOrder[BitSet] {
+class BitSetPartialEq extends PartialOrder[BitSet] with Hash[BitSet] {
+  def hash(x: BitSet): Int = x.hashCode()
+
   def partialCompare(x: BitSet, y: BitSet): Double =
     if (x eq y) 0.0
     else if (x.size < y.size) if (x.subsetOf(y)) -1.0 else Double.NaN

kernel/src/main/scala/cats/kernel/instances/boolean.scala

@@ -4,11 +4,13 @@ package instances
 package object boolean extends BooleanInstances
 
 trait BooleanInstances {
-  implicit val catsKernelStdOrderForBoolean: Order[Boolean] =
-    new BooleanOrder
+  implicit val catsKernelStdEqForBoolean: Order[Boolean] with Hash[Boolean] =
+    new BooleanEq
 }
 
-class BooleanOrder extends Order[Boolean] {
+class BooleanEq extends Order[Boolean] with Hash[Boolean] {
+
+  def hash(x: Boolean): Int = x.##
   def compare(x: Boolean, y: Boolean): Int =
     if (x == y) 0 else if (x) 1 else -1
 

kernel/src/main/scala/cats/kernel/instances/byte.scala

@@ -4,7 +4,7 @@ package instances
 package object byte extends ByteInstances
 
 trait ByteInstances {
-  implicit val catsKernelStdOrderForByte: Order[Byte] = new ByteOrder
+  implicit val catsKernelStdEqForByte: Order[Byte] with Hash[Byte] = new ByteEq
   implicit val catsKernelStdGroupForByte: CommutativeGroup[Byte] = new ByteGroup
 }
 
@@ -15,7 +15,9 @@ class ByteGroup extends CommutativeGroup[Byte] {
   override def remove(x: Byte, y: Byte): Byte = (x - y).toByte
 }
 
-class ByteOrder extends Order[Byte] {
+class ByteEq extends Order[Byte] with Hash[Byte] {
+
+  def hash(x: Byte): Int = x.##
 
   def compare(x: Byte, y: Byte): Int =
     if (x < y) -1 else if (x > y) 1 else 0

kernel/src/main/scala/cats/kernel/instances/char.scala

@@ -4,10 +4,11 @@ package instances
 package object char extends CharInstances
 
 trait CharInstances {
-  implicit val catsKernelStdOrderForChar = new CharOrder
+  implicit val catsKernelStdEqForChar: Order[Char] with Hash[Char] = new CharEq
 }
 
-class CharOrder extends Order[Char] {
+class CharEq extends Order[Char] with Hash[Char] {
+  def hash(x: Char): Int = x.##
   def compare(x: Char, y: Char): Int =
     if (x < y) -1 else if (x > y) 1 else 0
   override def eqv(x:Char, y:Char): Boolean = x == y

kernel/src/main/scala/cats/kernel/instances/double.scala

@@ -1,12 +1,10 @@
 package cats.kernel
 package instances
 
-import java.lang.Math
-
 package object double extends DoubleInstances
 
 trait DoubleInstances {
-  implicit val catsKernelStdOrderForDouble: Order[Double] = new DoubleOrder
+  implicit val catsKernelStdEqForDouble: Order[Double] with Hash[Double] = new DoubleEq
   implicit val catsKernelStdGroupForDouble: CommutativeGroup[Double] = new DoubleGroup
 }
 
@@ -17,8 +15,9 @@ class DoubleGroup extends CommutativeGroup[Double] {
   override def remove(x: Double, y: Double): Double = x - y
 }
 
-class DoubleOrder extends Order[Double] {
+class DoubleEq extends Order[Double] with Hash[Double] {
 
+  def hash(x: Double): Int = x.##
   def compare(x: Double, y: Double): Int =
     java.lang.Double.compare(x, y)
 

kernel/src/main/scala/cats/kernel/instances/either.scala

@@ -63,21 +63,35 @@ trait EitherInstances0 extends EitherInstances1 {
           }
         }
     }
-}
 
-trait EitherInstances1 {
-  implicit def catsStdEqForEither[A, B](implicit A: Eq[A], B: Eq[B]): Eq[Either[A, B]] =
-    new Eq[Either[A, B]] {
-      def eqv(x: Either[A, B], y: Either[A, B]): Boolean =
+  implicit def catsStdHashForEither[A, B](implicit A: Hash[A], B: Hash[B]): Hash[Either[A, B]] =
+    new EitherEq[A, B](A, B) with Hash[Either[A, B]] {
+      def hash(x: Either[A, B]): Int = {
         x match {
-          case Left(xx) => y match {
-            case Left(yy) => A.eqv(xx, yy)
-            case Right(_) => false
-          }
-          case Right(xx) => y match {
-            case Left(_) => false
-            case Right(yy) => B.eqv(xx, yy)
-          }
+          case Left(xx) => Left(A.hash(xx)).##
+          case Right(xx) => Right(B.hash(xx)).##
         }
+      }
     }
 }
+
+trait EitherInstances1 {
+
+  // isolated class for inheritance
+  private[cats] class EitherEq[A, B](A: Eq[A], B: Eq[B]) extends Eq[Either[A, B]] {
+    def eqv(x: Either[A, B], y: Either[A, B]): Boolean =
+      x match {
+        case Left(xx) => y match {
+          case Left(yy) => A.eqv(xx, yy)
+          case Right(_) => false
+        }
+        case Right(xx) => y match {
+          case Left(_) => false
+          case Right(yy) => B.eqv(xx, yy)
+        }
+      }
+  }
+
+  implicit def catsStdEqForEither[A, B](implicit A: Eq[A], B: Eq[B]): Eq[Either[A, B]] = new EitherEq(A, B)
+
+}

kernel/src/main/scala/cats/kernel/instances/float.scala

@@ -4,7 +4,7 @@ package instances
 package object float extends FloatInstances
 
 trait FloatInstances {
-  implicit val catsKernelStdOrderForFloat: Order[Float] = new FloatOrder
+  implicit val catsKernelStdEqForFloat: Order[Float] with Hash[Float] = new FloatEq
   implicit val catsKernelStdGroupForFloat: CommutativeGroup[Float] = new FloatGroup
 }
 
@@ -26,7 +26,9 @@ class FloatGroup extends CommutativeGroup[Float] {
  * If you would prefer an absolutely lawful fractional value, you'll
  * need to investigate rational numbers or more exotic types.
  */
-class FloatOrder extends Order[Float] {
+class FloatEq extends Order[Float] with Hash[Float] {
+
+  def hash(x: Float): Int = x.##
 
   def compare(x: Float, y: Float): Int =
     java.lang.Float.compare(x, y)

kernel/src/main/scala/cats/kernel/instances/function.scala

@@ -19,6 +19,12 @@ trait FunctionInstances extends FunctionInstances0 {
 
 trait FunctionInstances0 extends FunctionInstances1 {
 
+  implicit def catsKernelHashForFunction0[A](implicit ev: Hash[A]): Hash[() => A] =
+    new Hash[() => A] {
+      def hash(x: () => A) = ev.hash(x())
+      def eqv(x: () => A, y: () => A) = ev.eqv(x(), y())
+    }
+
   implicit def catsKernelPartialOrderForFunction0[A](implicit ev: PartialOrder[A]): PartialOrder[() => A] =
     new PartialOrder[() => A] {
       def partialCompare(x: () => A, y: () => A): Double = ev.partialCompare(x(), y())