GHC.Natural

base-4.12.0.0: Basic libraries

Copyright | (C) 2014 Herbert Valerio Riedel (C) 2011 Edward Kmett
License | see libraries/base/LICENSE
Maintainer | libraries@haskell.org
Stability | internal
Portability | non-portable (GHC Extensions)
Safe Haskell | None
Language | Haskell2010

GHC.Natural

Contents

- The `Natural` number type
- Arithmetic
- Bits
- Conversions
- Modular arithmetic

Description

The arbitrary-precision `Natural` number type.

Note: This is an internal GHC module with an API subject to change. It's recommended use the Numeric.Natural module to import the `Natural` type.

Since: base-4.8.0.0

Synopsis

- data Natural
  - = NatS# GmpLimb#
  - | NatJ# !BigNat
- mkNatural :: [Word] -> Natural
- isValidNatural :: Natural -> Bool
- plusNatural :: Natural -> Natural -> Natural
- minusNatural :: Natural -> Natural -> Natural
- minusNaturalMaybe :: Natural -> Natural -> Maybe Natural
- timesNatural :: Natural -> Natural -> Natural
- negateNatural :: Natural -> Natural
- signumNatural :: Natural -> Natural
- quotRemNatural :: Natural -> Natural -> (Natural, Natural)
- quotNatural :: Natural -> Natural -> Natural
- remNatural :: Natural -> Natural -> Natural
- gcdNatural :: Natural -> Natural -> Natural
- lcmNatural :: Natural -> Natural -> Natural
- andNatural :: Natural -> Natural -> Natural
- orNatural :: Natural -> Natural -> Natural
- xorNatural :: Natural -> Natural -> Natural
- bitNatural :: Int# -> Natural
- testBitNatural :: Natural -> Int -> Bool
- popCountNatural :: Natural -> Int
- shiftLNatural :: Natural -> Int -> Natural
- shiftRNatural :: Natural -> Int -> Natural
- naturalToInteger :: Natural -> Integer
- naturalToWord :: Natural -> Word
- naturalToInt :: Natural -> Int
- naturalFromInteger :: Integer -> Natural
- wordToNatural :: Word -> Natural
- intToNatural :: Int -> Natural
- naturalToWordMaybe :: Natural -> Maybe Word
- wordToNatural# :: Word# -> Natural
- wordToNaturalBase :: Word# -> Natural
- powModNatural :: Natural -> Natural -> Natural -> Natural

# The `Natural` number type

Warning: The internal implementation of `Natural` (i.e. which constructors are available) depends on the `Integer` backend used!

data Natural #

Type representing arbitrary-precision non-negative integers.

    >>> 2^100 :: Natural
    1267650600228229401496703205376

Operations whose result would be negative ``throw` (`Underflow` :: `ArithException`)`,

    >>> -1 :: Natural
    *** Exception: arithmetic underflow

Since: base-4.8.0.0

Constructors

NatS# GmpLimb# | in `[0, maxBound::Word]`
NatJ# !BigNat | in `]maxBound::Word, +inf[` Invariant: `NatJ#` is used iff value doesn't fit in `NatS#` constructor. NB: Order of constructors *must* coincide with `Ord` relation

Instances

Enum Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Enum Methods succ :: Natural -> Natural # pred :: Natural -> Natural # toEnum :: Int -> Natural # fromEnum :: Natural -> Int # enumFrom :: Natural -> [Natural] # enumFromThen :: Natural -> Natural -> [Natural] # enumFromTo :: Natural -> Natural -> [Natural] # enumFromThenTo :: Natural -> Natural -> Natural -> [Natural] #
Eq Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Natural Methods (==) :: Natural -> Natural -> Bool Source # (/=) :: Natural -> Natural -> Bool Source #
Integral Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Real Methods quot :: Natural -> Natural -> Natural # rem :: Natural -> Natural -> Natural # div :: Natural -> Natural -> Natural # mod :: Natural -> Natural -> Natural # quotRem :: Natural -> Natural -> (Natural, Natural) # divMod :: Natural -> Natural -> (Natural, Natural) # toInteger :: Natural -> Integer #
Data Natural # | Since: base-4.8.0.0
Instance details Defined in Data.Data Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Natural -> c Natural # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Natural # toConstr :: Natural -> Constr # dataTypeOf :: Natural -> DataType # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Natural) # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Natural) # gmapT :: (forall b. Data b => b -> b) -> Natural -> Natural # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Natural -> r # gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Natural -> r # gmapQ :: (forall d. Data d => d -> u) -> Natural -> [u] # gmapQi :: Int -> (forall d. Data d => d -> u) -> Natural -> u # gmapM :: Monad m => (forall d. Data d => d -> m d) -> Natural -> m Natural # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Natural -> m Natural # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Natural -> m Natural #
Num Natural # | Note that `Natural`'s `Num` instance isn't a ring: no element but 0 has an additive inverse. It is a semiring though. Since: base-4.8.0.0
Instance details Defined in GHC.Num Methods (+) :: Natural -> Natural -> Natural # (-) :: Natural -> Natural -> Natural # (*) :: Natural -> Natural -> Natural # negate :: Natural -> Natural # abs :: Natural -> Natural # signum :: Natural -> Natural # fromInteger :: Integer -> Natural #
Ord Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Natural Methods compare :: Natural -> Natural -> Ordering Source # (<) :: Natural -> Natural -> Bool Source # (<=) :: Natural -> Natural -> Bool Source # (>) :: Natural -> Natural -> Bool Source # (>=) :: Natural -> Natural -> Bool Source # max :: Natural -> Natural -> Natural Source # min :: Natural -> Natural -> Natural Source #
Read Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Read Methods readsPrec :: Int -> ReadS Natural # readList :: ReadS [Natural] # readPrec :: ReadPrec Natural # readListPrec :: ReadPrec [Natural] #
Real Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Real Methods toRational :: Natural -> Rational #
Show Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Show Methods showsPrec :: Int -> Natural -> ShowS # show :: Natural -> String # showList :: [Natural] -> ShowS #
Ix Natural # | Since: base-4.8.0.0
Instance details Defined in GHC.Arr Methods range :: (Natural, Natural) -> [Natural] # index :: (Natural, Natural) -> Natural -> Int # unsafeIndex :: (Natural, Natural) -> Natural -> Int inRange :: (Natural, Natural) -> Natural -> Bool # rangeSize :: (Natural, Natural) -> Int # unsafeRangeSize :: (Natural, Natural) -> Int
Bits Natural # | Since: base-4.8.0
Instance details Defined in Data.Bits Methods (.&.) :: Natural -> Natural -> Natural # (.|.) :: Natural -> Natural -> Natural # xor :: Natural -> Natural -> Natural # complement :: Natural -> Natural # shift :: Natural -> Int -> Natural # rotate :: Natural -> Int -> Natural # zeroBits :: Natural # bit :: Int -> Natural # setBit :: Natural -> Int -> Natural # clearBit :: Natural -> Int -> Natural # complementBit :: Natural -> Int -> Natural # testBit :: Natural -> Int -> Bool # bitSizeMaybe :: Natural -> Maybe Int # bitSize :: Natural -> Int # isSigned :: Natural -> Bool # shiftL :: Natural -> Int -> Natural # unsafeShiftL :: Natural -> Int -> Natural # shiftR :: Natural -> Int -> Natural # unsafeShiftR :: Natural -> Int -> Natural # rotateL :: Natural -> Int -> Natural # rotateR :: Natural -> Int -> Natural # popCount :: Natural -> Int #
PrintfArg Natural # | Since: base-4.8.0.0
Instance details Defined in Text.Printf Methods formatArg :: Natural -> FieldFormatter # parseFormat :: Natural -> ModifierParser #

mkNatural #

Arguments

:: [Word] | value expressed in 32 bit chunks, least significant first
-> Natural |

Construct `Natural` value from list of `Word`s.

This function is used by GHC for constructing `Natural` literals.

isValidNatural :: Natural -> Bool #

Test whether all internal invariants are satisfied by `Natural` value

This operation is mostly useful for test-suites and/or code which constructs `Integer` values directly.

Since: base-4.8.0.0

# Arithmetic

plusNatural :: Natural -> Natural -> Natural #

`Natural` Addition

minusNatural :: Natural -> Natural -> Natural #

`Natural` subtraction. May ``throw` `Underflow``.

minusNaturalMaybe :: Natural -> Natural -> Maybe Natural #

`Natural` subtraction. Returns `Nothing`s for non-positive results.

Since: base-4.8.0.0

timesNatural :: Natural -> Natural -> Natural #

`Natural` multiplication

negateNatural :: Natural -> Natural #

signumNatural :: Natural -> Natural #

quotRemNatural :: Natural -> Natural -> (Natural, Natural) #

quotNatural :: Natural -> Natural -> Natural #

remNatural :: Natural -> Natural -> Natural #

gcdNatural :: Natural -> Natural -> Natural #

Compute greatest common divisor.

lcmNatural :: Natural -> Natural -> Natural #

compute least common multiplier.

# Bits

andNatural :: Natural -> Natural -> Natural #

orNatural :: Natural -> Natural -> Natural #

xorNatural :: Natural -> Natural -> Natural #

bitNatural :: Int# -> Natural #

testBitNatural :: Natural -> Int -> Bool #

popCountNatural :: Natural -> Int #

shiftLNatural :: Natural -> Int -> Natural #

shiftRNatural :: Natural -> Int -> Natural #

# Conversions

naturalToInteger :: Natural -> Integer #

@since 4.X.0.0

naturalToWord :: Natural -> Word #

naturalToInt :: Natural -> Int #

naturalFromInteger :: Integer -> Natural #

Since: base-4.10.0.0

wordToNatural :: Word -> Natural #

Construct `Natural` from `Word` value.

Since: base-4.8.0.0

intToNatural :: Int -> Natural #

Convert `Int` to `Natural`. Throws `Underflow` when passed a negative `Int`.

naturalToWordMaybe :: Natural -> Maybe Word #

Try downcasting `Natural` to `Word` value. Returns `Nothing` if value doesn't fit in `Word`.

Since: base-4.8.0.0

wordToNatural# :: Word# -> Natural #

Convert a Word# into a Natural

Built-in rule ensures that applications of this function to literal Word# are lifted into Natural literals.

wordToNaturalBase :: Word# -> Natural #

Convert a Word# into a Natural

In base we can't use wordToNatural# as built-in rules transform some of them into Natural literals. Use this function instead.

# Modular arithmetic

powModNatural :: Natural -> Natural -> Natural -> Natural #

"``powModNatural` b e m`" computes base `b` raised to exponent `e` modulo `m`.

Since: base-4.8.0.0