11438838d9fd9fe311986a1679deb604b5b51f4a

1 {-# LANGUAGE CPP, Trustworthy #-}

2 {-# LANGUAGE NoImplicitPrelude, MagicHash, StandaloneDeriving, BangPatterns,

3 KindSignatures, DataKinds, ConstraintKinds,

4 MultiParamTypeClasses, FunctionalDependencies #-}

5 {-# LANGUAGE AllowAmbiguousTypes #-}

6 -- ip :: IP x a => a is strictly speaking ambiguous, but IP is magic

7 {-# LANGUAGE UndecidableSuperClasses #-}

8 -- Because of the type-variable superclasses for tuples

10 {-# OPTIONS_GHC -Wno-unused-imports #-}

11 -- -Wno-unused-imports needed for the GHC.Tuple import below. Sigh.

13 {-# OPTIONS_GHC -Wno-unused-top-binds #-}

14 -- -Wno-unused-top-binds is there (I hope) to stop Haddock complaining

15 -- about the constraint tuples being defined but not used

17 {-# OPTIONS_HADDOCK not-home #-}

18 -----------------------------------------------------------------------------

19 -- |

20 -- Module : GHC.Classes

21 -- Copyright : (c) The University of Glasgow, 1992-2002

22 -- License : see libraries/base/LICENSE

23 --

24 -- Maintainer : cvs-ghc@haskell.org

25 -- Stability : internal

26 -- Portability : non-portable (GHC extensions)

27 --

28 -- Basic classes.

29 --

30 -----------------------------------------------------------------------------

33 -- * Implicit paramaters

34 IP(..),

36 -- * Equality and ordering

37 Eq(..),

38 Ord(..),

39 -- ** Monomorphic equality operators

40 -- | See GHC.Classes#matching_overloaded_methods_in_rules

45 -- ** Monomorphic comparison operators

49 -- * Functions over Bool

52 -- * Integer arithmetic

56 -- GHC.Magic is used in some derived instances

72 -- | The syntax @?x :: a@ is desugared into @IP "x" a@

73 -- IP is declared very early, so that libraries can take

74 -- advantage of the implicit-call-stack feature

76 ip :: a

78 {- $matching_overloaded_methods_in_rules

80 Matching on class methods (e.g. @(==)@) in rewrite rules tends to be a bit

81 fragile. For instance, consider this motivating example from the @bytestring@

82 library,

84 > break :: (Word8 -> Bool) -> ByteString -> (ByteString, ByteString)

85 > breakByte :: Word8 -> ByteString -> (ByteString, ByteString)

86 > {-# RULES "break -> breakByte" forall a. break (== x) = breakByte x #-}

92 rule has a chance to fire.

99 > (==) = eqWord8

100 > (/=) = neWord8

101 >

115 -}

117 -- | The 'Eq' class defines equality ('==') and inequality ('/=').

118 -- All the basic datatypes exported by the "Prelude" are instances of 'Eq',

119 -- and 'Eq' may be derived for any datatype whose constituents are also

120 -- instances of 'Eq'.

121 --

122 -- The Haskell Report defines no laws for 'Eq'. However, '==' is customarily

123 -- expected to implement an equivalence relationship where two values comparing

124 -- equal are indistinguishable by "public" functions, with a "public" function

125 -- being one not allowing to see implementation details. For example, for a

126 -- type representing non-normalised natural numbers modulo 100, a "public"

127 -- function doesn't make the difference between 1 and 201. It is expected to

128 -- have the following properties:

129 --

130 -- [__Reflexivity__]: @x == x@ = 'True'

131 -- [__Symmetry__]: @x == y@ = @y == x@

132 -- [__Transitivity__]: if @x == y && y == z@ = 'True', then @x == z@ = 'True'

133 -- [__Substitutivity__]: if @x == y@ = 'True' and @f@ is a "public" function

134 -- whose return type is an instance of 'Eq', then @f x == f y@ = 'True'

135 -- [__Negation__]: @x /= y@ = @not (x == y)@

136 --

137 -- Minimal complete definition: either '==' or '/='.

138 --

142 {-# INLINE (/=) #-}

143 {-# INLINE (==) #-}

146 {-# MINIMAL (==) | (/=) #-}

158 Eq h)

183 {-# SPECIALISE instance Eq [[Char]] #-}

184 {-# SPECIALISE instance Eq [Char] #-}

185 {-# SPECIALISE instance Eq [Int] #-}

190 deriving instance Eq Module

195 where

203 (==) = eqWord

204 (/=) = neWord

206 -- See GHC.Classes#matching_overloaded_methods_in_rules

207 {-# INLINE [1] eqWord #-}

208 {-# INLINE [1] neWord #-}

213 -- See GHC.Classes#matching_overloaded_methods_in_rules

215 (==) = eqChar

216 (/=) = neChar

218 -- See GHC.Classes#matching_overloaded_methods_in_rules

219 {-# INLINE [1] eqChar #-}

220 {-# INLINE [1] neChar #-}

225 -- | Note that due to the presence of @NaN@, `Float`'s 'Eq' instance does not

226 -- satisfy reflexivity.

227 --

228 -- >>> 0/0 == (0/0 :: Float)

229 -- False

230 --

231 -- Also note that `Float`'s 'Eq' instance does not satisfy substitutivity:

232 --

233 -- >>> 0 == (-0 :: Float)

234 -- True

235 -- >>> recip 0 == recip (-0 :: Float)

236 -- False

238 (==) = eqFloat

240 -- See GHC.Classes#matching_overloaded_methods_in_rules

241 {-# INLINE [1] eqFloat #-}

245 -- | Note that due to the presence of @NaN@, `Double`'s 'Eq' instance does not

246 -- satisfy reflexivity.

247 --

248 -- >>> 0/0 == (0/0 :: Double)

249 -- False

250 --

251 -- Also note that `Double`'s 'Eq' instance does not satisfy substitutivity:

252 --

253 -- >>> 0 == (-0 :: Double)

254 -- True

255 -- >>> recip 0 == recip (-0 :: Double)

256 -- False

258 (==) = eqDouble

260 -- See GHC.Classes#matching_overloaded_methods_in_rules

261 {-# INLINE [1] eqDouble #-}

266 (==) = eqInt

267 (/=) = neInt

269 -- See GHC.Classes#matching_overloaded_methods_in_rules

270 {-# INLINE [1] eqInt #-}

271 {-# INLINE [1] neInt #-}

298 #endif

301 -- | The 'Ord' class is used for totally ordered datatypes.

302 --

303 -- Instances of 'Ord' can be derived for any user-defined datatype whose

304 -- constituent types are in 'Ord'. The declared order of the constructors in

305 -- the data declaration determines the ordering in derived 'Ord' instances. The

306 -- 'Ordering' datatype allows a single comparison to determine the precise

307 -- ordering of two objects.

308 --

309 -- The Haskell Report defines no laws for 'Ord'. However, '<=' is customarily

310 -- expected to implement a non-strict partial order and have the following

311 -- properties:

312 --

313 -- [__Transitivity__]: if @x <= y && y <= z@ = 'True', then @x <= z@ = 'True'

314 -- [__Reflexivity__]: @x <= x@ = 'True'

315 -- [__Antisymmetry__]: if @x <= y && y <= x@ = 'True', then @x == y@ = 'True'

316 --

317 -- Note that the following operator interactions are expected to hold:

318 --

319 -- 1. @x >= y@ = @y <= x@

320 -- 2. @x < y@ = @x <= y && x /= y@

321 -- 3. @x > y@ = @y < x@

322 -- 4. @x < y@ = @compare x y == LT@

323 -- 5. @x > y@ = @compare x y == GT@

324 -- 6. @x == y@ = @compare x y == EQ@

325 -- 7. @min x y == if x <= y then x else y@ = 'True'

326 -- 8. @max x y == if x >= y then x else y@ = 'True'

327 --

328 -- Minimal complete definition: either 'compare' or '<='.

329 -- Using 'compare' can be more efficient for complex types.

330 --

337 -- NB: must be '<=' not '<' to validate the

338 -- above claim about the minimal things that

339 -- can be defined for an instance of Ord:

341 else GT

348 -- These two default methods use '<=' rather than 'compare'

349 -- because the latter is often more expensive

352 {-# MINIMAL compare | (<=) #-}

364 Ord h)

389 {-# SPECIALISE instance Ord [[Char]] #-}

390 {-# SPECIALISE instance Ord [Char] #-}

391 {-# SPECIALISE instance Ord [Int] #-}

397 other -> other

402 -- We don't use deriving for Ord Char, because for Ord the derived

403 -- instance defines only compare, which takes two primops. Then

404 -- '>' uses compare, and therefore takes two primops instead of one.

411 -- | Note that due to the presence of @NaN@, `Float`'s 'Ord' instance does not

412 -- satisfy reflexivity.

413 --

414 -- >>> 0/0 <= (0/0 :: Float)

415 -- False

416 --

417 -- Also note that, due to the same, `Ord`'s operator interactions are not

418 -- respected by `Float`'s instance:

419 --

420 -- >>> (0/0 :: Float) > 1

421 -- False

422 -- >>> compare (0/0 :: Float) 1

423 -- GT

428 else GT

435 -- | Note that due to the presence of @NaN@, `Double`'s 'Ord' instance does not

436 -- satisfy reflexivity.

437 --

438 -- >>> 0/0 <= (0/0 :: Double)

439 -- False

440 --

441 -- Also note that, due to the same, `Ord`'s operator interactions are not

442 -- respected by `Double`'s instance:

443 --

444 -- >>> (0/0 :: Double) > 1

445 -- False

446 -- >>> compare (0/0 :: Double) 1

447 -- GT

452 else GT

461 (<) = ltInt

462 (<=) = leInt

463 (>=) = geInt

464 (>) = gtInt

466 -- See GHC.Classes#matching_overloaded_methods_in_rules

467 {-# INLINE [1] gtInt #-}

468 {-# INLINE [1] geInt #-}

469 {-# INLINE [1] ltInt #-}

470 {-# INLINE [1] leInt #-}

488 (<) = ltWord

489 (<=) = leWord

490 (>=) = geWord

491 (>) = gtWord

493 -- See GHC.Classes#matching_overloaded_methods_in_rules

494 {-# INLINE [1] gtWord #-}

495 {-# INLINE [1] geWord #-}

496 {-# INLINE [1] ltWord #-}

497 {-# INLINE [1] leWord #-}

513 -- OK, so they're technically not part of a class...:

515 -- Boolean functions

517 -- | Boolean \"and\"

522 -- | Boolean \"or\"

527 -- | Boolean \"not\"

533 ------------------------------------------------------------------------

534 -- These don't really belong here, but we don't have a better place to

535 -- put them

537 -- These functions have built-in rules.

538 {-# NOINLINE [0] divInt# #-}

539 {-# NOINLINE [0] modInt# #-}

542 -- Be careful NOT to overflow if we do any additional arithmetic

543 -- on the arguments... the following previous version of this

544 -- code has problems with overflow:

545 -- | (x# ># 0#) && (y# <# 0#) = ((x# -# y#) -# 1#) `quotInt#` y#

546 -- | (x# <# 0#) && (y# ># 0#) = ((x# -# y#) +# 1#) `quotInt#` y#

557 where

561 {- *************************************************************

562 * *

563 * Constraint tuples *

564 * *

565 ************************************************************* -}

592 c17)

594 c17)

649 c31)

652 c31)

734 c45)

738 c45)

847 c59)

852 c59)