[GHC] #15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: (none) Type: feature | Status: new request | Priority: normal | Milestone: 8.6.1 Component: Core | Version: 8.4.2 Libraries | Keywords: | Operating System: Unknown/Multiple Architecture: | Type of failure: None/Unknown Unknown/Multiple | Test Case: | Blocked By: Blocking: | Related Tickets: Differential Rev(s): | Wiki Page: -------------------------------------+------------------------------------- As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined. Here's a first draft of what I have in mind for `Float`'s `Eq` and `Ord` instances: {{{ -- | Note that in the presence of @NaN@, this instance does not satisfy -- reflexivity: -- -- >>> nan = 0/0 :: Float -- >>> nan == nan -- False -- -- Also note that this instance does not encode structural equality: -- -- >>> 0 == (-0 :: Float) -- True -- >>> recip 0 == recip (-0 :: Float) -- False instance Eq Float where (==) = eqFloat }}} {{{ -- | Due to the peculiarities of @NaN@, this instance does not satisfy totality: -- -- >>> nan = 0/0 :: Float -- >>> nan <= nan -- False -- -- Another special case with @NaN@ is: -- -- @ -- 'compare' x y -- | 'isNaN' x || 'isNaN' y = 'GT' -- @ -- -- However -- -- @ -- nan > _ = False -- _ > nan = False -- @ -- -- In consequence we also have: -- -- @ -- 'max' x y | 'isNaN' x || 'isNaN' y = x -- 'min' x y | 'isNaN' x || 'isNaN' y = y -- @ -- -- Ignoring @NaN@, @Infinity@ and @-Infinity@ are the respective greatest -- and least elements of 'Float'. instance Ord Float where (F# x) `compare` (F# y) = if isTrue# (x `ltFloat#` y) then LT else if isTrue# (x `eqFloat#` y) then EQ else GT (F# x) < (F# y) = isTrue# (x `ltFloat#` y) (F# x) <= (F# y) = isTrue# (x `leFloat#` y) (F# x) >= (F# y) = isTrue# (x `geFloat#` y) (F# x) > (F# y) = isTrue# (x `gtFloat#` y) }}} -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Comment (by dfeuer): That's perfectly documentation that Haddock will, sadly, chew up and turn into something almost completely unreadable. Ryan Scott thinks it's good to write documentation like that to drive Haddock development, but I'm not sure. As for what the customary laws ''are'', here's a rough draft: == `Eq` `Eq` is expected to be an equivalence relation, and values that compare "equal" should be indistinguishable (except perhaps when using an "private" interface). Reflexivity:: `x == x = True` Symmetry:: `x == y = y == x` Transitivity:: If `x == y && y == z = True`, then `x == z = True` Substitutivity:: If `x == y = True` and `f` is a "public" function, then `f x == f y = True` Negation:: `x /= y = not (x == y)` == `Ord` === Basics Transitivity:: If `x <= y && y <= z = True`, then `x <= z = True` Reflexivity:: relative to `==`: = True` Antisymmetry:: If `x <= y && y <= x = True`, then `x == y = True` === Operator interactions 1. `x >= y = y <= x` 2. `x < y = x <= y && x /= y` 3. `x > y = y < x` 4. `x < y = compare x y == LT` 5. `x > y = compare x y == GT` 6. `x == y = compare x y == EQ` The `max` and `min` rules look a bit funny. Note that `max x y` needn't be ''identical'' to either `x` or `y`; it just needs to ''look'' the same. 7. `min x y == if x <= y then x else y = True` 8. `max x y == if x >= y then x else y = True` -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:1 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by dfeuer): * cc: dfeuer (added) -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:2 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by bgamari): * keywords: => newcomer -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:3 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: new Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Wiki Page: | -------------------------------------+------------------------------------- Changes (by Azel): * owner: (none) => Azel -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:4 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: patch Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Changes (by Azel): * status: new => patch * differential: => Phab:D4736 -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:5 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: patch Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by dfeuer): Expanding a bit in another direction, I think it probably makes sense to note that `Num` instances are typically expected to form rings. In fact, the `signum` and `abs` functions suggest even more structure, although I don't personally know what sort of structure that ''is''. I'd be very hesitant to document any expectations beyond the ring laws, because there are a number of exotic `Num` instances in the wild. The best-behaved law-breaker here is `Natural`, which does not have a sensible `negate` or `(-)`; it's a perfectly good semiring (more specifically, a ''rig''), but we don't have a class corresponding to that. As usual, `Float` and `Double` are truly flagrant law-breakers. It might also be worth mentioning that types that are well-behaved instances of both `Num` and `Ord` are ''not'' necessarily ordered rings. In particular, `Int`, `Word`, `Int8`, `Word8`, etc., are not ordered rings. As far as I know, the only `Num`+`Ord` instances in `base` that implement ordered rings are `Integer` and `Rational`. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:6 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: patch Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by Azel): Continuing on that vein, what laws do you think should be expected for `Fractional`, `Floating`, `RealFloat` and `RealFrac`? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:7 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: patch Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by Azel): Thinking about it, I think `Fractional` instances are expected to form division rings, `Floating` instances are expected to form exponential fields and `signum` and `abs` could imply that `Num` instances are expected to be division rings as well but if so division ought to be there. `RealFloat` is for machine-level floating-point types so there shouldn't be anything to add rules-wise. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:8 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: patch Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by Azel): Continuing on that vein, I think `Integral` instances are expected to form Euclidean rings (or is it Euclidean fields?). However, I have no idea for `RealFrac` instances…subsets of ℚ? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:9 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Changes (by Azel): * status: patch => merge -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:10 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances
(e.g. Float) should be documented
-------------------------------------+-------------------------------------
Reporter: sjakobi | Owner: Azel
Type: feature request | Status: merge
Priority: normal | Milestone: 8.6.1
Component: Core Libraries | Version: 8.4.2
Resolution: | Keywords: newcomer
Operating System: Unknown/Multiple | Architecture:
| Unknown/Multiple
Type of failure: None/Unknown | Test Case:
Blocked By: | Blocking:
Related Tickets: | Differential Rev(s): Phab:D4736
Wiki Page: |
-------------------------------------+-------------------------------------
Comment (by Ben Gamari
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by bgamari): I suspect there is more work to be done here. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:12 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Description changed by sjakobi: Old description:
As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined.
Here's a first draft of what I have in mind for `Float`'s `Eq` and `Ord` instances:
{{{ -- | Note that in the presence of @NaN@, this instance does not satisfy -- reflexivity: -- -- >>> nan = 0/0 :: Float -- >>> nan == nan -- False -- -- Also note that this instance does not encode structural equality: -- -- >>> 0 == (-0 :: Float) -- True -- >>> recip 0 == recip (-0 :: Float) -- False instance Eq Float where (==) = eqFloat }}}
{{{ -- | Due to the peculiarities of @NaN@, this instance does not satisfy totality: -- -- >>> nan = 0/0 :: Float -- >>> nan <= nan -- False -- -- Another special case with @NaN@ is: -- -- @ -- 'compare' x y -- | 'isNaN' x || 'isNaN' y = 'GT' -- @ -- -- However -- -- @ -- nan > _ = False -- _ > nan = False -- @ -- -- In consequence we also have: -- -- @ -- 'max' x y | 'isNaN' x || 'isNaN' y = x -- 'min' x y | 'isNaN' x || 'isNaN' y = y -- @ -- -- Ignoring @NaN@, @Infinity@ and @-Infinity@ are the respective greatest -- and least elements of 'Float'. instance Ord Float where (F# x) `compare` (F# y) = if isTrue# (x `ltFloat#` y) then LT else if isTrue# (x `eqFloat#` y) then EQ else GT
(F# x) < (F# y) = isTrue# (x `ltFloat#` y) (F# x) <= (F# y) = isTrue# (x `leFloat#` y) (F# x) >= (F# y) = isTrue# (x `geFloat#` y) (F# x) > (F# y) = isTrue# (x `gtFloat#` y) }}}
New description: As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined. === Documented so far: (in 793902e6891c30150fd3ac1e0e471269a4766780) ==== Classes * `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord` ==== Non-abiding instances * `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num` === TODO: * `RealFrac` -- -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:13 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Description changed by sjakobi: Old description:
As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined.
=== Documented so far:
(in 793902e6891c30150fd3ac1e0e471269a4766780)
==== Classes
* `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord`
==== Non-abiding instances
* `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num`
=== TODO:
* `RealFrac`
New description: As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined. === Documented so far: (in 793902e6891c30150fd3ac1e0e471269a4766780) ==== Classes * `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord` ==== Non-abiding instances * `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num` === TODO (This is not an exhaustive list, please add more) * `RealFrac` -- -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:14 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Old description:
As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined.
=== Documented so far:
(in 793902e6891c30150fd3ac1e0e471269a4766780)
==== Classes
* `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord`
==== Non-abiding instances
* `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num`
=== TODO
(This is not an exhaustive list, please add more)
* `RealFrac`
New description: As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined. === Documented so far: (in 793902e6891c30150fd3ac1e0e471269a4766780) ==== Classes * `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord` ==== Non-abiding instances * `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num` === TODO (This is not an exhaustive list, please add more) * `RealFrac` * the Arrow classes * `Word` & co -- Comment (by Azel): What structure would `RealFrac` represent though? And do all instances of `Monad`, `Functor` and `Applicative` in base respect the relevant laws? -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:15 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Old description:
As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined.
=== Documented so far:
(in 793902e6891c30150fd3ac1e0e471269a4766780)
==== Classes
* `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord`
==== Non-abiding instances
* `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num`
=== TODO
(This is not an exhaustive list, please add more)
* `RealFrac` * the Arrow classes * `Word` & co
New description: As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined. === Documented so far: (in 793902e6891c30150fd3ac1e0e471269a4766780) ==== Classes * `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord` ==== Non-abiding instances * `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num` === TODO (This is not an exhaustive list, please add more) * the Arrow classes * Document non-abiding instances for the types from `Data.Word` and `Data.Int`. -- Comment (by sjakobi):
What structure would RealFrac represent though?
And do all instances of Monad, Functor and Applicative in base respect
Not sure if there's any fitting structure, but I guess you could say that `RealFrac`'s are already documented on the methods. I'm removing it from the TODO list. the relevant laws? I think this is question for a different ticket. I'd like to keep this ticket about classes whose laws haven't been documented so far.
* the Arrow classes
What about them? Their laws seem to be well documented. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:16 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by Azel): I guess that's a fair point about `Monad` & co. And about the Arrow classes, they are but only by reference to an external paper. I guess that just means we need to make sure the links to the papers stay live. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:17 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by sjakobi): Replying to [comment:17 Azel]:
I guess that's a fair point about `Monad` & co. And about the Arrow classes, they are but only by reference to external papers. I guess that just means we need to make sure the links to the papers stay live.
Are we looking at the same docs? The haddocks for `Arrow`, `ArrowPlus`, `ArrowChoice` all have their laws spelled out right there. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:18 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: merge Priority: normal | Milestone: 8.6.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Old description:
As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined.
=== Documented so far:
(in 793902e6891c30150fd3ac1e0e471269a4766780)
==== Classes
* `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord`
==== Non-abiding instances
* `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num`
=== TODO
(This is not an exhaustive list, please add more)
* the Arrow classes * Document non-abiding instances for the types from `Data.Word` and `Data.Int`.
New description: As beginning Haskellers regularly ask about these laws and instances I think it would be good to have them documented where they are defined. === Documented so far: (in 793902e6891c30150fd3ac1e0e471269a4766780) ==== Classes * `Eq` * `Floating` * `Fractional` * `Integral` * `Num` * `Ord` ==== Non-abiding instances * `CDouble` (shares `Double`'s deficiencies) * `CFloat` (shares `Float`'s deficiencies) * `Complex a` (inherits deficiencies) * `Double`: `Eq`, `Ord`, `Fractional`, `Num` * `Float`: `Eq`, `Ord`, `Fractional`, `Num` * `Ratio a` (inherits deficiencies) * `Natural`: `Num` === TODO (This is not an exhaustive list, please add more) * Document non-abiding instances for the types from `Data.Word` and `Data.Int`. -- Comment (by Azel): Ah yes my bad: I was looking at the wrong version of base's documentation. I'll remove it from the TODO list. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:19 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: (none) Type: feature request | Status: new Priority: normal | Milestone: 8.8.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Changes (by monoidal): * status: merge => new * owner: Azel => (none) Comment: Commit 793902e is in ghc-8.6 branch, so I understand there's nothing to merge. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:21 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: new Priority: normal | Milestone: 8.8.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Changes (by monoidal): * owner: (none) => Azel -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:22 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
#15078: base: Customary type class laws (e.g. for Eq) and non-abiding instances (e.g. Float) should be documented -------------------------------------+------------------------------------- Reporter: sjakobi | Owner: Azel Type: feature request | Status: new Priority: normal | Milestone: 8.8.1 Component: Core Libraries | Version: 8.4.2 Resolution: | Keywords: newcomer Operating System: Unknown/Multiple | Architecture: | Unknown/Multiple Type of failure: None/Unknown | Test Case: Blocked By: | Blocking: Related Tickets: | Differential Rev(s): Phab:D4736 Wiki Page: | -------------------------------------+------------------------------------- Comment (by jpath): For `Num` I would expect `fromIntegral` to be a ring homomorphism. φ is a ring homomorphism if: 1. φ(x + y) = φ(x) + φ(y) 2. φ(x · y) = φ(x) · φ(y) 3. φ(1) = 1 We get φ(0) = 0, because φ(0) = φ(1 - 1) = φ(1) - φ(1) = 0, but we do need the “`fromIntegral 0` is addivite identity” law, to state the ring laws in the first place. In the case of dom φ = ℤ, we can also drop the second law, as φ is already uniquely defined by laws 1 and 3. So I would like to add `fromIntegral (a + b) = fromIntegral a + fromIntegral b` and maybe `fromIntegral (a * b) = fromIntegral a * fromIntegral b` even though it is redundant. Similarly I would like `fromRational` to be a ring homomorphism, again law 2 would be redundant, but we may still want it anyway. Note that these laws do not require any additional structure, as ℤ is the initial object in the category of rings and ℚ the initial object in the category of fields, so for every ring R a unique ring homomorphism φ: ℤ → R exists and for every field F a unique field homomorphism ℚ → F exists. The laws just ask that `fromIntegral` and `fromRational` are indeed these homomorphisms. Also `a / b = a * recip b`. -- Ticket URL: http://ghc.haskell.org/trac/ghc/ticket/15078#comment:23 GHC http://www.haskell.org/ghc/ The Glasgow Haskell Compiler
participants (1)
-
GHC