@@ -66,21 +66,55 @@ sin nullability (toList -> as) a = case nullability of
6666 (Opaleye.ListExpr (toPrimExpr <$> xs))
6767
6868
69+-- | Compare two expressions for equality.
70+--
71+-- This corresponds to the SQL @IS NOT DISTINCT FROM@ operator, and will equate
72+-- @null@ values as @true@. This differs from @=@ which would return @null@.
73+-- This operator matches Haskell's '==' operator. For an operator identical to
74+-- SQL @=@, see '==?'.
6975(==.) :: Sql DBEq a => Expr a -> Expr a -> Expr Bool
7076(==.) = seq nullabilization
7177infix 4 ==.
7278
7379
80+-- | Test if two expressions are different (not equal).
81+--
82+-- This corresponds to the SQL @IS DISTINCT FROM@ operator, and will return
83+-- @false@ when comparing two @null@ values. This differs from ordinary @=@
84+-- which would return @null@. This operator is closer to Haskell's '=='
85+-- operator. For an operator identical to SQL @=@, see '/=?'.
7486(/=.) :: Sql DBEq a => Expr a -> Expr a -> Expr Bool
7587(/=.) = sne nullabilization
7688infix 4 /=.
7789
7890
91+-- | Test if two expressions are equal. This operator is usually the best
92+-- choice when forming join conditions, as PostgreSQL has a much harder time
93+-- optimizing a join that has multiple 'True' conditions.
94+--
95+-- This corresponds to the SQL @=@ operator, though it will always return a
96+-- 'Bool'.
97+--
98+-- >>> select c $ pure $ lit Nothing ==? lit True
99+-- False
100+--
101+-- >>> select c $ pure $ lit Nothing ==? lit Nothing
102+-- False
79103(==?) :: DBEq a => Expr (Maybe a) -> Expr (Maybe a) -> Expr Bool
80104a ==? b = coalesce $ unsafeLiftOpNullable eq a b
81105infix 4 ==?
82106
83107
108+-- | Test if two expressions are different.
109+--
110+-- This corresponds to the SQL @<>@ operator, though it will always return a
111+-- 'Bool'.
112+--
113+-- >>> select c $ pure $ lit Nothing /=? lit True
114+-- True
115+--
116+-- >>> select c $ pure $ lit Nothing /=? lit Nothing
117+-- False
84118(/=?) :: DBEq a => Expr (Maybe a) -> Expr (Maybe a) -> Expr Bool
85119a /=? b = coalesce $ unsafeLiftOpNullable ne a b
86120infix 4 /=?