Skip to content
Tutorials Center
My learning

Topics

Lesson 5 of 38 ยท Getting Started

Value Types and Numbers

Understand the four number types of WebAssembly, signed versus unsigned integers, i64 and BigInt, float rounding, conversions, and the other value types.

WebAssembly has very few types, and that is a strength. Every value on the stack, every local variable and every function parameter is one of a handful of simple types. Compilers map richer types (strings, structs, booleans, characters) onto these, so knowing exactly how the numbers behave tells you how everything else behaves.

The core number types

Type Size Byte in binary JavaScript sees it as
i32 32-bit integer 0x7f number (signed)
i64 64-bit integer 0x7e BigInt (signed)
f32 32-bit float (IEEE 754) 0x7d number
f64 64-bit float (IEEE 754) 0x7c number

Besides these there are v128 (a 128-bit SIMD vector, see the performance chapter) and reference types such as funcref and externref, which hold a function or any JavaScript value. Booleans, pointers, char and unsigned types do not exist as types: a boolean is an i32 that is 0 or 1, and a pointer is an i32 index into memory.

Integers have no sign, instructions do

The integer types are just bit patterns. Whether a pattern means -1 or 4294967295 depends on the instruction you apply. Add, subtract, multiply and the bitwise operators are the same for both. Division, remainder, right shift, comparisons and conversions come in _s (signed) and _u (unsigned) forms.

Operation Signed Unsigned
Divide i32.div_s i32.div_u
Remainder i32.rem_s i32.rem_u
Less than i32.lt_s i32.lt_u
Shift right i32.shr_s (keeps sign) i32.shr_u (fills with zeros)

Arithmetic wraps: i32.add of 2147483647 and 1 is -2147483648 when read as signed, or 2147483648 when read as unsigned. The bits are identical. JavaScript always reads an i32 result as signed, so use >>> 0 to see it as unsigned.

Node.js Signed and unsigned integer instructions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The last three lines show the JavaScript glue. When you call an exported function, each argument is converted with the same rules as x | 0: strings and booleans become numbers, fractions are truncated, and values outside the 32-bit range wrap. Wasm itself never sees a fraction or a string.

i64 and BigInt

A 64-bit integer cannot be stored exactly in a JavaScript number (which only has 53 bits of integer precision), so the API uses BigInt for i64 parameters and results. Passing a plain number where a BigInt is expected throws a TypeError.

Floats

f32 and f64 follow IEEE 754 exactly, so results match C, Rust and Java. f64 is the same as a JavaScript number; f32 is rounded to 32 bits at the boundary, and Math.fround(x) shows the value you will get. Floats can hold NaN, Infinity and -0.

Converting a float to an integer has two flavors. i32.trunc_f64_s traps (throws a RuntimeError) when the value is NaN or out of range. The saturating version i32.trunc_sat_f64_s never traps: NaN becomes 0 and out-of-range values clamp to the minimum or maximum.

Node.js i64, f32, f64 and conversions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at addF32(0.1, 0.2): it prints 0.30000001192092896. That is the 32-bit float nearest to the real sum, shown as a 64-bit number. It is not a bug; use Math.fround when comparing.

Choosing types in practice

flowchart TD
    Q["What are you storing?"] --> A{"Whole number?"}
    A -- "yes, fits in 32 bits, or a pointer" --> I32["i32"]
    A -- "yes, huge or a timestamp" --> I64["i64 (BigInt in JS)"]
    A -- no --> B{"Need precision?"}
    B -- "general" --> F64["f64"]
    B -- "graphics, audio, memory-bound" --> F32["f32"]

Compilers make this choice for you, but it explains some surprises: a C long is 32-bit in Wasm, size_t is 32-bit unless you use the 64-bit memory proposal, and Rust u8, u16 and bool all live in i32 values on the stack.

If a result looks wrong by a sign or by 2^32, the cause is almost always signed versus unsigned. Print the value with >>> 0 and decide which interpretation the code intended.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. How does a JavaScript caller pass an i64 argument to an exported function?

    i64 values map to BigInt. A plain number throws a TypeError.
  2. 2. Where does the signed or unsigned meaning of an i32 come from?

    i32 is only a bit pattern. Instructions such as div_s, div_u, lt_s and lt_u decide how to interpret it.
  3. 3. What does i32.trunc_sat_f64_s return for NaN?

    The saturating conversion never traps: NaN becomes 0 and out-of-range values clamp to the integer limits.
  4. 4. What happens to add(2 ** 32 + 5, 1) on an i32 function called from JavaScript?

    Arguments are converted like x | 0, which wraps modulo 2^32.

Summary

  • The core types are i32, i64, f32 and f64; booleans and pointers are i32 values.
  • Integer signedness lives in the instructions (_s and _u), and arithmetic wraps.
  • i64 crosses to JavaScript as BigInt; the other three as number.
  • Float arguments to integer parameters are truncated and wrapped; trunc traps on bad input while trunc_sat clamps.
  • v128 and reference types (funcref, externref) exist too and are covered later.

Next: Module Structure and Sections