Add new Data.Bits.Bits(zeroBits) method

This adds a new method to `Bits` which completes the Bits API
with a direct way to introduce a value with all bits cleared.

See also original proposal at

  http://permalink.gmane.org/gmane.comp.lang.haskell.libraries/21157

diff --git a/libraries/base/Data/Bits.hs b/libraries/base/Data/Bits.hs
index c06caf9..e771624 100644 (file)
--- a/libraries/base/Data/Bits.hs
+++ b/libraries/base/Data/Bits.hs
@@ -25,6 +25,7 @@ module Data.Bits (
     complement,
     shift,
     rotate,
+    zeroBits,
     bit,
     setBit,
     clearBit,
@@ -131,7 +132,26 @@ class Eq a => Bits a where
                   | i>0  = (x `shift` i) .|. (x `shift` (i-bitSize x))
     -}
 
-    -- | @bit i@ is a value with the @i@th bit set and all other bits clear
+    -- | 'zeroBits' is the value with all bits unset.
+    --
+    -- The following laws ought to hold (for all valid bit indices @/n/@):
+    --
+    --   * @'clearBit' 'zeroBits' /n/ == 'zeroBits'@
+    --   * @'setBit'   'zeroBits' /n/ == 'bit' /n/@
+    --   * @'testBit'  'zeroBits' /n/ == False@
+    --   * @'popCount' 'zeroBits'   == 0@
+    --
+    -- This method uses @'clearBit' ('bit' 0) 0@ as its default
+    -- implementation (which ought to be equivalent to 'zeroBits' for
+    -- types which possess a 0th bit).
+    --
+    -- /Since: 4.7.0.0/
+    zeroBits :: a
+    zeroBits = clearBit (bit 0) 0
+
+    -- | @bit /i/@ is a value with the @/i/@th bit set and all other bits clear.
+    --
+    -- See also 'zeroBits'.
     bit               :: Int -> a
 
     -- | @x \`setBit\` i@ is the same as @x .|. bit i@

diff --git a/libraries/base/changelog.md b/libraries/base/changelog.md
index 88ceec5..7e33059 100644 (file)
--- a/libraries/base/changelog.md
+++ b/libraries/base/changelog.md
@@ -24,6 +24,9 @@
     with a `bitSizeMaybe` method to replace the now obsolete
     `bitsize` method.
 
+  * `Data.Bits.Bits` gained a new `zeroBits` method which completes the
+    `Bits` API with a direct way to introduce a value with all bits cleared.
+
   * There are now `Bits` and `FiniteBits` instances for `Bool`.
 
   * There are now `Eq`, `Ord`, `Show` and `Read` instances for `ZipList`.