usize

These examples describe the Development language contract. They are not a claim that every workflow is supported by the current public preview. Declaration excerpts belong inside a function unless a full module is shown.

Width and valid range

usize has the target pointer’s width P, rather than a fixed cross-target width. The range is 0 through 2^P-1. On the implemented Linux x86_64 target, P is 64 and the inclusive range is 0 through 18,446,744,073,709,551,615. Use fixed-width types for a wire/file format.

// Linux x86_64 target:
let Minimum: usize = 0_usize;
let Maximum: usize = 18446744073709551615_usize;

Operations and intended use

Use usize for collection lengths and indices. Ordinary arithmetic wraps at the pointer width; an unsigned size can still underflow. Prefer CheckedSub when subtracting a possibly larger length. Division/remainder by zero trap. Checked, wrapping, saturating and bitwise/shift operations follow the integer rules. An integer offset alone does not authorize raw pointer access.

let Start: usize = 4;
let Next: usize? = Start.CheckedAdd(2);
let Saturated: usize = Start +| 2;

Literals and conversions

Use _usize for an explicit pointer-sized literal. A fitting context-typed literal also works. Changing signedness or narrowing requires an explicit checked conversion. Do not assume a value that fits a 64-bit host fits every future target.

let Count: usize = 42;
let Explicit = 42_usize;
let Fixed: u32? = Count as? u32;

See all primitive types and literals and user-defined suffixes.