[commit: packages/base] master: Add new Data.Bits.Bits(zeroBits) method (83bd2f5)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/base

On branch  : master
Link       : http://ghc.haskell.org/trac/ghc/changeset/83bd2f5fc7e4d748ee35911876c1d4239689db0f/base

>---------------------------------------------------------------

commit 83bd2f5fc7e4d748ee35911876c1d4239689db0f
Author: Herbert Valerio Riedel <hvr at gnu.org>
Date:   Fri Feb 28 09:39:41 2014 +0100

    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


>---------------------------------------------------------------

83bd2f5fc7e4d748ee35911876c1d4239689db0f
 Data/Bits.hs |   22 +++++++++++++++++++++-
 changelog.md |    3 +++
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/Data/Bits.hs b/Data/Bits.hs
index c06caf9..e771624 100644
--- a/Data/Bits.hs
+++ b/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 at 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/changelog.md b/changelog.md
index 88ceec5..7e33059 100644
--- a/changelog.md
+++ b/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`.