Numbers

Package names on this page are preview naming and may change before launch.

Integer types

• Signed types will use two's complement, the same representation on every target.
• Each width and sign will be its own type. An i32 will never be turned into an i64, or a u8 into a u16, without an explicit conversion.
• bool will not be a number, and a number will never be a condition.

Literals

• Integer literals will be decimal: 0, 42, 1_000_000. A single _ may separate digits.
• A literal will take the type its place expects: in let port: u16 = 8080; the literal will be a u16. When nothing says otherwise, it will be an i64.
• A literal will have to fit the type it takes. let small: u8 = 300; will be refused when you check your code, not when it runs.
• A minus sign will be an operator. The smallest signed value will still be writable directly: -128 as an i8.

Arithmetic

The same rules will apply in every build, with no difference between a debug build and a release build.

Both sides of an operator will have to have the same type. Stopping the program will be a panic: Errors and checked arithmetic describes what a panic does, and Results and errors how to report a failure your code expects instead.

Comparison and bits

• ==, !=, <, <=, > and >= will compare two integers of the same type and give a bool. Signed types will compare as signed values, unsigned types as unsigned ones. Comparisons will not chain: write a < b && b < c.
• &, |, ^ and ~ will work on the exact bits of one integer type.
• The shift count of << and >> will be an unsigned integer of the same width as the value, and will have to be less than that width: a larger count will stop the program. << will stop the program when the result does not fit; >> will round a signed value down and fill an unsigned one with zeros.

Wrapping and saturating operations

When you want a result other than a stop, you will ask for it by name, at the place where you need it. The meaning of + will never change.

The preview library has no wrapping or saturating division.

Checked conversions

Converting between integer types will always be explicit. The standard library will have one conversion for each of the eight target types. Each will take an integer of any type and return Result<T, CastError>, where T is the target type:

• Result::Ok(value) will hold the same number in the new type;
• Result::Err(CastError::OutOfRange) will mean the number does not fit, for example 300 into a u8 or -1 into a u64.

No conversion will silently cut off bits or change a sign.

An example

Checked arithmetic will stop the program on an overflow. When a large value is something your program expects, test for it first and return an error instead:

fn add_stock(on_hand: u16, delivered: u16) -> Result<u16, CapacityError> {
    if delivered > 65_535 - on_hand {
        return Result::Err(CapacityError::Full);
    }
    return Result::Ok(on_hand + delivered);
}

Not in the preview

These are not part of the preview syntax. Their rules will be described here when the syntax is final:

• Floating-point and fixed-point numbers, and the machine-sized integers usize and isize.
• Hexadecimal, binary and exponent literals.

Numerical arrays, complex numbers and linear algebra will come from optional official packages, such as math/array and math/linalg. Scientific computing describes the scientific packages.