From 1dd1ad9d37cde223048e60e007d04b77d41f94e5 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Sat, 5 Aug 2017 20:52:20 +0200 Subject: [PATCH 1/7] Add Eq docs --- docs/src/main/tut/typeclasses/eq.md | 51 +++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/src/main/tut/typeclasses/eq.md diff --git a/docs/src/main/tut/typeclasses/eq.md b/docs/src/main/tut/typeclasses/eq.md new file mode 100644 index 0000000000..7973e76c9a --- /dev/null +++ b/docs/src/main/tut/typeclasses/eq.md @@ -0,0 +1,51 @@ +--- +layout: docs +title: "Eq" +section: "typeclasses" +source: "kernel/src/main/scala/cats/kernel/Eq.scala" +scaladoc: "#cats.kernel.Eq" +--- + +# Eq + +Show is an alternative to the standard Java `equals` method. +It is defined by the single method `eqv`: + +```scala +def eqv(x: A, y: A): Boolean +``` + +In Scala it's possible to compare any two values using `==` (which desugars to Java `equals`). +This is because `equals` type signature uses `Any` (Java's `Object`) to compare two values. +This means that we can compare two completely unrelated types without getting a compiler error. +The Scala compiler may warn us in some cases, but not all, which can lead to some weird bugs. +For example this code will raise a warning at compile time: + + +```tut:book:fail +42 == "Hello" +``` + +While this code will compile without a hitch: + +```tut:book +"Hello" == 42 +``` + +Ideally, Scala shouldn't let us compare two types that can never be equal. + +As you can probably see in the type signature of `eqv`, it is impossible to compare two values of different types, +eliminating these types of bugs altogether. + +The `Eq` syntax package also offers some handy symbolic operators: + +```tut:book +import cats.implicits._ + +1 === 1 + +"Hello" =!= "World" +``` + +Implementing `Eq` instances yourself for every data type might seem like huge drawback compared to only slight gains of typesafety. +Fortunately for us, there is a small library called [kittens](https://github.com/milessabin/kittens), which can derive a lot of type class instances for our data types including `Eq`. From 44f7eca2721088f912802764054fbadccc30b2a0 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Tue, 8 Aug 2017 17:02:06 +0200 Subject: [PATCH 2/7] Add Eq.fromUniverseEquals example --- docs/src/main/tut/typeclasses/eq.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/docs/src/main/tut/typeclasses/eq.md b/docs/src/main/tut/typeclasses/eq.md index 7973e76c9a..44e9a621df 100644 --- a/docs/src/main/tut/typeclasses/eq.md +++ b/docs/src/main/tut/typeclasses/eq.md @@ -48,4 +48,23 @@ import cats.implicits._ ``` Implementing `Eq` instances yourself for every data type might seem like huge drawback compared to only slight gains of typesafety. -Fortunately for us, there is a small library called [kittens](https://github.com/milessabin/kittens), which can derive a lot of type class instances for our data types including `Eq`. +Fortunately for us, we have two great options. One option is to use inbuilt helper functions. +Another option is to use a small library called [kittens](https://github.com/milessabin/kittens), which can derive a lot of type class instances for our data types including `Eq`. + +The first option using `Eq.fromUniversalEquals` only defers to `==` and works like this: + +```tut:book +import cats.kernel.Eq +import cats.implicits._ + + +case class Foo(a: Int, b: String) + + +implicit val eqFoo: Eq[Foo] = Eq.fromUniversalEquals + + +Foo(10, "") === Foo(10, "") +``` + +For an example using Kittens check out the [kittens repo](https://github.com/milessabin/kittens). From bfa382e44d86b0f3f5e120662fa9cf3f34d41815 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Wed, 9 Aug 2017 17:30:46 +0200 Subject: [PATCH 3/7] Add eqProduct explanation --- docs/src/main/tut/typeclasses/eq.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/src/main/tut/typeclasses/eq.md b/docs/src/main/tut/typeclasses/eq.md index 44e9a621df..3217721746 100644 --- a/docs/src/main/tut/typeclasses/eq.md +++ b/docs/src/main/tut/typeclasses/eq.md @@ -67,4 +67,16 @@ implicit val eqFoo: Eq[Foo] = Eq.fromUniversalEquals Foo(10, "") === Foo(10, "") ``` +You can even go one step further and make use of the fact, that every case class will extend `scala.Product`, by creating an `Eq` instance for it. +This means, you'll get an instance for all your case classes, but you'll have to define them for regular classes and objects yourself. +```tut:book + +case class Bar(a: Double, b: Int) + +implicit def eqProduct[A <: Product]: Eq[A] = Eq.fromUniversalEquals + +Bar(2, 0) === Bar(2, 0) +``` + + For an example using Kittens check out the [kittens repo](https://github.com/milessabin/kittens). From 96e1483718ceef19f932899a68691f8e5697b791 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Wed, 9 Aug 2017 18:21:25 +0200 Subject: [PATCH 4/7] Rephrase eqProduct section --- docs/src/main/tut/typeclasses/eq.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/src/main/tut/typeclasses/eq.md b/docs/src/main/tut/typeclasses/eq.md index 3217721746..10bcb47b69 100644 --- a/docs/src/main/tut/typeclasses/eq.md +++ b/docs/src/main/tut/typeclasses/eq.md @@ -67,8 +67,7 @@ implicit val eqFoo: Eq[Foo] = Eq.fromUniversalEquals Foo(10, "") === Foo(10, "") ``` -You can even go one step further and make use of the fact, that every case class will extend `scala.Product`, by creating an `Eq` instance for it. -This means, you'll get an instance for all your case classes, but you'll have to define them for regular classes and objects yourself. +You can even go one step further by making this implicitly available for all `scala.Product`s (which include case classes). ```tut:book case class Bar(a: Double, b: Int) From 65d8a7fd0a0175244f12cbf757d417333b3d6c19 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Wed, 9 Aug 2017 18:23:43 +0200 Subject: [PATCH 5/7] Mixup --- docs/src/main/tut/typeclasses/eq.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/main/tut/typeclasses/eq.md b/docs/src/main/tut/typeclasses/eq.md index 10bcb47b69..e873d424fb 100644 --- a/docs/src/main/tut/typeclasses/eq.md +++ b/docs/src/main/tut/typeclasses/eq.md @@ -8,7 +8,7 @@ scaladoc: "#cats.kernel.Eq" # Eq -Show is an alternative to the standard Java `equals` method. +Eq is an alternative to the standard Java `equals` method. It is defined by the single method `eqv`: ```scala From 937aa3b81cf10a05c5ecb2b3b884aeb52019cd21 Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Fri, 25 Aug 2017 22:00:00 +0200 Subject: [PATCH 6/7] Add menu entry --- docs/src/main/resources/microsite/data/menu.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/src/main/resources/microsite/data/menu.yml b/docs/src/main/resources/microsite/data/menu.yml index 081dfffe2a..b3531b2478 100644 --- a/docs/src/main/resources/microsite/data/menu.yml +++ b/docs/src/main/resources/microsite/data/menu.yml @@ -76,6 +76,10 @@ options: url: typeclasses/invariantmonoidal.html menu_section: variance + - title: Eq + url: typeclasses/eq.html + menu_type: typeclasses + - title: Foldable url: typeclasses/foldable.html menu_type: typeclasses From bfb63e0680d567ee30067d5827a3bf35cf1d07cf Mon Sep 17 00:00:00 2001 From: Luka Jacobowitz Date: Wed, 20 Sep 2017 22:19:35 +0200 Subject: [PATCH 7/7] Remove section about Eq for Product --- docs/src/main/tut/typeclasses/eq.md | 10 ---------- 1 file changed, 10 deletions(-) diff --git a/docs/src/main/tut/typeclasses/eq.md b/docs/src/main/tut/typeclasses/eq.md index e873d424fb..0a3537148a 100644 --- a/docs/src/main/tut/typeclasses/eq.md +++ b/docs/src/main/tut/typeclasses/eq.md @@ -67,15 +67,5 @@ implicit val eqFoo: Eq[Foo] = Eq.fromUniversalEquals Foo(10, "") === Foo(10, "") ``` -You can even go one step further by making this implicitly available for all `scala.Product`s (which include case classes). -```tut:book - -case class Bar(a: Double, b: Int) - -implicit def eqProduct[A <: Product]: Eq[A] = Eq.fromUniversalEquals - -Bar(2, 0) === Bar(2, 0) -``` - For an example using Kittens check out the [kittens repo](https://github.com/milessabin/kittens).