Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
View this page
Toggle table of contents sidebar

# Native integer operations

Mypyc supports these integer types:

- `int` (arbitrary-precision integer)

- `i64` (64-bit signed integer)

- `i32` (32-bit signed integer)

- `i16` (16-bit signed integer)

- `u8` (8-bit unsigned integer)

`i64`, `i32`, `i16` and `u8` are native integer types and are available in the `mypy_extensions` module. `int` corresponds to the Python `int` type, but uses a more efficient runtime representation (tagged pointer). Native integer types are value types.

All integer types have optimized primitive operations, but the native integer types are more efficient than `int`, since they don’t require range or bounds checks.

Operations on integers that are listed here have fast, optimized implementations. Other integer operations use generic implementations that are generally slower. Some operations involving integers and other types, such as list indexing, are documented elsewhere.

## Construction

`int` type:

- Integer literal

- `int(x: float)`

- `int(x: i64)`

- `int(x: i32)`

- `int(x: i16)`

- `int(x: u8)`

- `int(x: str)`

- `int(x: str, base: int)`

- `int(x: int)` (no-op)

`i64` type:

- `i64(x: int)`

- `i64(x: float)`

- `i64(x: i64)` (no-op)

- `i64(x: i32)`

- `i64(x: i16)`

- `i64(x: u8)`

- `i64(x: str)`

- `i64(x: str, base: int)`

`i32` type:

- `i32(x: int)`

- `i32(x: float)`

- `i32(x: i64)` (truncate)

- `i32(x: i32)` (no-op)

- `i32(x: i16)`

- `i32(x: u8)`

- `i32(x: str)`

- `i32(x: str, base: int)`

`i16` type:

- `i16(x: int)`

- `i16(x: float)`

- `i16(x: i64)` (truncate)

- `i16(x: i32)` (truncate)

- `i16(x: i16)` (no-op)

- `i16(x: u8)`

- `i16(x: str)`

- `i16(x: str, base: int)`

Conversions from `int` to a native integer type raise `OverflowError` if the value is too large or small. Conversions from a wider native integer type to a narrower one truncate the value and never fail. More generally, operations between native integer types don’t check for overflow.

## Implicit conversions

`int` values can be implicitly converted to a native integer type, for convenience. This means that these are equivalent:

    from mypy_extensions import i64

    def implicit() -> None:
        # Implicit conversion of 0 (int) to i64
        x: i64 = 0

    def explicit() -> None:
        # Explicit conversion of 0 (int) to i64
        x = i64(0)

Similarly, a native integer value can be implicitly converted to an arbitrary-precision integer. These two functions are equivalent:

    def implicit(x: i64) -> int:
        # Implicit conversion from i64 to int
        return x

    def explicit(x: i64) -> int:
        # Explicit conversion from i64 to int
        return int(x)

## Operators

- Arithmetic (`+`, `-`, `*`, `//`, `/`, `%`)

- Bitwise operations (`&`, `|`, `^`, `<<`, `>>`, `~`)

- Comparisons (`==`, `!=`, `<`, etc.)

- Augmented assignment (`x += y`, etc.)

If one of the above native integer operations overflows or underflows with signed operands, the behavior is undefined. Signed native integer types should only be used if all possible values are small enough for the type. For this reason, the arbitrary-precision `int` type is recommended for signed values unless the performance of integer operations is critical.

Operations on unsigned integers (`u8`) wrap around on overflow.

It’s a compile-time error to mix different native integer types in a binary operation such as addition. An explicit conversion is required:

    from mypy_extensions import i64, i32

    def add(x: i64, y: i32) -> None:
        a = x + y  # Error (i64 + i32)
        b = x + i64(y)  # OK

You can freely mix a native integer value and an arbitrary-precision `int` value in an operation. The native integer type is “sticky” and the `int` operand is coerced to the native integer type:

    def example(x: i64, y: int) -> None:
        a = x * y
        # Type of "a" is "i64"
        ...
        b = 1 - x
        # Similarly, type of "b" is "i64"

## Statements

For loop over a range is compiled efficiently, if the `range(...)` object is constructed in the for statement (after `in`):

- `for x in range(end)`

- `for x in range(start, end)`

- `for x in range(start, end, step)`

If one of the arguments to `range` in a for loop is a native integer type, the type of the loop variable is inferred to have this native integer type, instead of `int`:

    for x in range(i64(n)):
        # Type of "x" is "i64"
        ...