The most general class for number types, more precisely for rings, i.e. numbers that can be added and subtracted and multiplied in the usual sense, but not necessarily divided.
This class contains both integral types (Int
, Integer
, Word32
etc.) and fractional types (Double
, Rational
, also complex numbers etc.). In case of finite types, the semantics are generally understood as modular arithmetic, i.e. with over- and underflow^{†}.
Note that the rules for the numerical classes are much less strictly obeyed than the monad or monoid laws, or those for equality comparison. In particular, floating-point numbers generally obey laws only in a approximate sense.
fromInteger :: Num a => Integer -> a
. convert an integer to the general number type (wrapping around the range, if necessary). Haskell number literals can be understood as a monomorphic Integer
literal with the general conversion around it, so you can use the literal 5
in both an Int
context and a Complex Double
setting.
(+) :: Num a => a -> a -> a
. Standard addition, generally understood as associative and commutative, i.e.,
a + (b + c) ≡ (a + b) + c
a + b ≡ b + a
(-) :: Num a => a -> a -> a
. Subtraction, which is the inverse of addition:
(a - b) + b ≡ (a + b) - b ≡ a
(*) :: Num a => a -> a -> a
. Multiplication, an associative operation that's distributive over addition:
a * (b * c) ≡ (a * b) * c
a * (b + c) ≡ a * b + a * c
for the most common instances, multiplication is also commutative, but this is definitely not a requirement.
negate :: Num a => a -> a
. The full name of the unary negation operator. -1
is syntactic sugar for negate 1
.
-a ≡ negate a ≡ 0 - a
abs :: Num a => a -> a
. The absolute-value function always gives a non-negative result of the same magnitude
abs (-a) ≡ abs a
abs (abs a) ≡ abs a
abs a ≡ 0
should only happen if a ≡ 0
.
For real types it's clear what non-negative means: you always have abs a >= 0
. Complex etc. types don't have a well-defined ordering, however the result of abs
should always lie in the real subset^{‡} (i.e. give a number that could also be written as a single number literal without negation).
signum :: Num a => a -> a
. The sign function, according to the name, yields only -1
or 1
, depending on the sign of the argument. Actually, that's only true for nonzero real numbers; in general signum
is better understood as the normalising function:
abs (signum a) ≡ 1 -- unless a≡0
signum a * abs a ≡ a -- This is required to be true for all Num instances
Note that section 6.4.4 of the Haskell 2010 Report explicitly requires this last equality to hold for any valid Num
instance.
Some libraries, notably linear and hmatrix, have a much laxer understanding of what the Num
class is for: they treat it just as a way to overload the arithmetic operators. While this is pretty straightforward for +
and -
, it already becomes troublesome with *
and more so with the other methods. For instance, should *
mean matrix multiplication or element-wise multiplication?
It is arguably a bad idea to define such non-number instances; please consider dedicated classes such as VectorSpace
.
^{†} _{In particular, the “negatives” of unsigned types are wrapped around to large positive, e.g. (-4 :: Word32) == 4294967292.}
^{‡} _{This is widely not fulfilled: vector types do not have a real subset. The controversial Num-instances for such types generally define abs and signum element-wise, which mathematically speaking doesn't really make sense.}