4. Numeric Types — int, float, long, complex

There are four distinct numeric types: plain integers, long integers, floating point numbers, and complex numbers. In addition, Booleans are a subtype of plain integers. Plain integers (also just called integers) are implemented using long in C, which gives them at least 32 bits of precision (sys.maxint is always set to the maximum plain integer value for the current platform, the minimum value is -sys.maxint - 1). Long integers have unlimited precision. Floating point numbers are usually implemented using double in C; information about the precision and internal representation of floating point numbers for the machine on which your program is running is available in sys.float_info. Complex numbers have a real and imaginary part, which are each a floating point number. To extract these parts from a complex number z, use z.real and z.imag. (The standard library includes additional numeric types, fractions that hold rationals, and decimal that hold floating-point numbers with user-definable precision.)

Numbers are created by numeric literals or as the result of built-in functions and operators. Unadorned integer literals (including binary, hex, and octal numbers) yield plain integers unless the value they denote is too large to be represented as a plain integer, in which case they yield a long integer. Integer literals with an 'L' or 'l' suffix yield long integers ('L' is preferred because 1l looks too much like eleven!). Numeric literals containing a decimal point or an exponent sign yield floating point numbers. Appending 'j' or 'J' to a numeric literal yields a complex number with a zero real part. A complex numeric literal is the sum of a real and an imaginary part.

Python fully supports mixed arithmetic: when a binary arithmetic operator has operands of different numeric types, the operand with the “narrower” type is widened to that of the other, where plain integer is narrower than long integer is narrower than floating point is narrower than complex. Comparisons between numbers of mixed type use the same rule. [2]_ The constructors int(), long(), float(), and complex() can be used to produce numbers of a specific type.

All built-in numeric types support the following operations. See power and later sections for the operators’ priorities.

Operation Result Notes
x + y sum of x and y  
x - y difference of x and y  
x * y product of x and y  
x / y quotient of x and y (1)
x // y (floored) quotient of x and y (4)(5)
x % y remainder of x / y (4)
-x x negated  
+x x unchanged  
abs(x) absolute value or magnitude of x (3)
int(x) x converted to integer (2)
long(x) x converted to long integer (2)
float(x) x converted to floating point (6)
complex(re,im) a complex number with real part re, imaginary part im. im defaults to zero.  
c.conjugate() conjugate of the complex number c. (Identity on real numbers)  
divmod(x, y) the pair (x // y, x % y) (3)(4)
pow(x, y) x to the power y (3)(7)
x ** y x to the power y (7)

Notes:

  1. For (plain or long) integer division, the result is an integer. The result is always rounded towards minus infinity: 1/2 is 0, (-1)/2 is -1, 1/(-2) is -1, and (-1)/(-2) is 0. Note that the result is a long integer if either operand is a long integer, regardless of the numeric value.

  2. Conversion from floats using int() or long() truncates toward zero like the related function, math.trunc(). Use the function math.floor() to round downward and math.ceil() to round upward.

  3. See 02 Built-in Functions for a full description.

  4. Deprecated since version 2.3: The floor division operator, the modulo operator, and the divmod() function are no longer defined for complex numbers. Instead, convert to a floating point number using the abs() function if appropriate.

  5. Also referred to as integer division. The resultant value is a whole integer, though the result’s type is not necessarily int.

  6. float also accepts the strings “nan” and “inf” with an optional prefix “+” or “-” for Not a Number (NaN) and positive or negative infinity.

    New in version 2.6.

  7. Python defines pow(0, 0) and 0 ** 0 to be 1, as is common for programming languages.

All numbers.Real types (int, long, and float) also include the following operations:

Operation Result
math.trunc(x) x truncated to Integral
round(x[, n]) x rounded to n digits, rounding ties away from zero. If n is omitted, it defaults to 0.
math.floor(x) the greatest integer as a float <= x
math.ceil(x) the least integer as a float >= x

4.1. Bitwise Operations on Integer Types

Bitwise operations only make sense for integers. Negative numbers are treated as their 2’s complement value (this assumes a sufficiently large number of bits that no overflow occurs during the operation).

The priorities of the binary bitwise operations are all lower than the numeric operations and higher than the comparisons; the unary operation ~ has the same priority as the other unary numeric operations (+ and -).

This table lists the bitwise operations sorted in ascending priority:

Operation Result Notes
x | y bitwise or of x and y  
x ^ y bitwise exclusive or of x and y  
x & y bitwise and of x and y  
x << n x shifted left by n bits (1)(2)
x >> n x shifted right by n bits (1)(3)
~x the bits of x inverted  

Notes:

  1. Negative shift counts are illegal and cause a ValueError to be raised.
  2. A left shift by n bits is equivalent to multiplication by pow(2, n). A long integer is returned if the result exceeds the range of plain integers.
  3. A right shift by n bits is equivalent to division by pow(2, n).

4.2. Additional Methods on Integer Types

The integer types implement the numbers.Integral abstract base class. In addition, they provide one more method:

int.bit_length()
long.bit_length()

Return the number of bits necessary to represent an integer in binary, excluding the sign and leading zeros:

>>> n = -37
>>> bin(n)
'-0b100101'
>>> n.bit_length()
6

More precisely, if x is nonzero, then x.bit_length() is the unique positive integer k such that 2**(k-1) <= abs(x) < 2**k. Equivalently, when abs(x) is small enough to have a correctly rounded logarithm, then k = 1 + int(log(abs(x), 2)). If x is zero, then x.bit_length() returns 0.

Equivalent to:

def bit_length(self):
    s = bin(self)       # binary representation:  bin(-37) --> '-0b100101'
    s = s.lstrip('-0b') # remove leading zeros and minus sign
    return len(s)       # len('100101') --> 6

New in version 2.7.

4.3. Additional Methods on Float

The float type implements the numbers.Real abstract base class. float also has the following additional methods.

float.as_integer_ratio()

Return a pair of integers whose ratio is exactly equal to the original float and with a positive denominator. Raises OverflowError on infinities and a ValueError on NaNs.

New in version 2.6.

float.is_integer()

Return True if the float instance is finite with integral value, and False otherwise:

>>> (-2.0).is_integer()
True
>>> (3.2).is_integer()
False

New in version 2.6.

Two methods support conversion to and from hexadecimal strings. Since Python’s floats are stored internally as binary numbers, converting a float to or from a decimal string usually involves a small rounding error. In contrast, hexadecimal strings allow exact representation and specification of floating-point numbers. This can be useful when debugging, and in numerical work.

float.hex()

Return a representation of a floating-point number as a hexadecimal string. For finite floating-point numbers, this representation will always include a leading 0x and a trailing p and exponent.

New in version 2.6.

float.fromhex(s)

Class method to return the float represented by a hexadecimal string s. The string s may have leading and trailing whitespace.

New in version 2.6.

Note that float.hex() is an instance method, while float.fromhex() is a class method.

A hexadecimal string takes the form:

[sign] ['0x'] integer ['.' fraction] ['p' exponent]

where the optional sign may by either + or -, integer and fraction are strings of hexadecimal digits, and exponent is a decimal integer with an optional leading sign. Case is not significant, and there must be at least one hexadecimal digit in either the integer or the fraction. This syntax is similar to the syntax specified in section 6.4.4.2 of the C99 standard, and also to the syntax used in Java 1.5 onwards. In particular, the output of float.hex() is usable as a hexadecimal floating-point literal in C or Java code, and hexadecimal strings produced by C’s %a format character or Java’s Double.toHexString are accepted by float.fromhex().

Note that the exponent is written in decimal rather than hexadecimal, and that it gives the power of 2 by which to multiply the coefficient. For example, the hexadecimal string 0x3.a7p10 represents the floating-point number (3 + 10./16 + 7./16**2) * 2.0**10, or 3740.0:

>>> float.fromhex('0x3.a7p10')
3740.0

Applying the reverse conversion to 3740.0 gives a different hexadecimal string representing the same number:

>>> float.hex(3740.0)
'0x1.d380000000000p+11'