base-4.7.0.0: Basic libraries

Data.Bits

Description

This module defines bitwise operations for signed and unsigned integers. Instances of the class `Bits` for the `Int` and `Integer` types are available from this module, and instances for explicitly sized integral types are available from the Data.Int and Data.Word modules.

Synopsis

# Documentation

class Eq a => Bits a where Source

The `Bits` class defines bitwise operations over integral types.

• Bits are numbered from 0 with bit 0 being the least significant bit.

Minimal complete definition: `.&.`, `.|.`, `xor`, `complement`, (`shift` or (`shiftL` and `shiftR`)), (`rotate` or (`rotateL` and `rotateR`)), `bitSize`, `isSigned`, `testBit`, `bit`, and `popCount`. The latter three can be implemented using `testBitDefault`, `bitDefault`, and `popCountDefault`, if `a` is also an instance of `Num`.

Minimal complete definition

Methods

(.&.) :: a -> a -> a infixl 7 Source

Bitwise "and"

(.|.) :: a -> a -> a infixl 5 Source

Bitwise "or"

xor :: a -> a -> a infixl 6 Source

Bitwise "xor"

complement :: a -> a Source

Reverse all the bits in the argument

shift :: a -> Int -> a infixl 8 Source

`shift x i` shifts `x` left by `i` bits if `i` is positive, or right by `-i` bits otherwise. Right shifts perform sign extension on signed number types; i.e. they fill the top bits with 1 if the `x` is negative and with 0 otherwise.

An instance can define either this unified `shift` or `shiftL` and `shiftR`, depending on which is more convenient for the type in question.

rotate :: a -> Int -> a infixl 8 Source

`rotate x i` rotates `x` left by `i` bits if `i` is positive, or right by `-i` bits otherwise.

For unbounded types like `Integer`, `rotate` is equivalent to `shift`.

An instance can define either this unified `rotate` or `rotateL` and `rotateR`, depending on which is more convenient for the type in question.

zeroBits :: a Source

`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

bit :: Int -> a Source

`bit i` is a value with the `i`th bit set and all other bits clear.

See also `zeroBits`.

setBit :: a -> Int -> a Source

`x `setBit` i` is the same as `x .|. bit i`

clearBit :: a -> Int -> a Source

`x `clearBit` i` is the same as `x .&. complement (bit i)`

complementBit :: a -> Int -> a Source

`x `complementBit` i` is the same as `x `xor` bit i`

testBit :: a -> Int -> Bool Source

Return `True` if the `n`th bit of the argument is 1

bitSizeMaybe :: a -> Maybe Int Source

Return the number of bits in the type of the argument. The actual value of the argument is ignored. Returns Nothing for types that do not have a fixed bitsize, like `Integer`.

Since: 4.7.0.0

bitSize :: a -> Int Source

Deprecated: Use `bitSizeMaybe` or `finiteBitSize` instead

Return the number of bits in the type of the argument. The actual value of the argument is ignored. The function `bitSize` is undefined for types that do not have a fixed bitsize, like `Integer`.

isSigned :: a -> Bool Source

Return `True` if the argument is a signed type. The actual value of the argument is ignored

shiftL :: a -> Int -> a infixl 8 Source

Shift the argument left by the specified number of bits (which must be non-negative).

An instance can define either this and `shiftR` or the unified `shift`, depending on which is more convenient for the type in question.

unsafeShiftL :: a -> Int -> a Source

Shift the argument left by the specified number of bits. The result is undefined for negative shift amounts and shift amounts greater or equal to the `bitSize`.

Defaults to `shiftL` unless defined explicitly by an instance.

Since: 4.5.0.0

shiftR :: a -> Int -> a infixl 8 Source

Shift the first argument right by the specified number of bits. The result is undefined for negative shift amounts and shift amounts greater or equal to the `bitSize`.

Right shifts perform sign extension on signed number types; i.e. they fill the top bits with 1 if the `x` is negative and with 0 otherwise.

An instance can define either this and `shiftL` or the unified `shift`, depending on which is more convenient for the type in question.

unsafeShiftR :: a -> Int -> a Source

Shift the first argument right by the specified number of bits, which must be non-negative an smaller than the number of bits in the type.

Right shifts perform sign extension on signed number types; i.e. they fill the top bits with 1 if the `x` is negative and with 0 otherwise.

Defaults to `shiftR` unless defined explicitly by an instance.

Since: 4.5.0.0

rotateL :: a -> Int -> a infixl 8 Source

Rotate the argument left by the specified number of bits (which must be non-negative).

An instance can define either this and `rotateR` or the unified `rotate`, depending on which is more convenient for the type in question.

rotateR :: a -> Int -> a infixl 8 Source

Rotate the argument right by the specified number of bits (which must be non-negative).

An instance can define either this and `rotateL` or the unified `rotate`, depending on which is more convenient for the type in question.

popCount :: a -> Int Source

Return the number of set bits in the argument. This number is known as the population count or the Hamming weight.

Since: 4.5.0.0

class Bits b => FiniteBits b where Source

The `FiniteBits` class denotes types with a finite, fixed number of bits.

Since: 4.7.0.0

Methods

finiteBitSize :: b -> Int Source

Return the number of bits in the type of the argument. The actual value of the argument is ignored. Moreover, `finiteBitSize` is total, in contrast to the deprecated `bitSize` function it replaces.

````finiteBitSize` = `bitSize`
`bitSizeMaybe` = `Just` . `finiteBitSize`
```

Since: 4.7.0.0

bitDefault :: (Bits a, Num a) => Int -> a Source

Default implementation for `bit`.

Note that: `bitDefault i = 1 shiftL i`

Since: 4.6.0.0

testBitDefault :: (Bits a, Num a) => a -> Int -> Bool Source

Default implementation for `testBit`.

Note that: `testBitDefault x i = (x .&. bit i) /= 0`

Since: 4.6.0.0

popCountDefault :: (Bits a, Num a) => a -> Int Source

Default implementation for `popCount`.

This implementation is intentionally naive. Instances are expected to provide an optimized implementation for their size.

Since: 4.6.0.0