v0.4.0
Numbers · Lesson 16.8

Checked convert

Source
Convert between number types with ConvertChecked, which reports when the value did not survive, and clamp with ConvertSaturating.

Between integer types, as keeps the value or stops the program: 300 as a uint8, or −1, ends it with Panic: integer cast out of range, and written as constants the compiler refuses them outright. That is right where the value is known to fit — and a crash everywhere else. A count read from a file, a size passed in by a caller, a result of float arithmetic: none of these is known to fit, and the program would rather decide for itself what to do.

Core::ConvertChecked converts without ever stopping and tells you whether anything was lost.

Converting and checking

It follows the out-parameter shape of checked arithmetic. The converted value is written through a pointer — which also names the destination type — and the bool it returns is true when the value did not survive:

var small: uint8 = 0;
let fits = ConvertChecked(200, @small);
let tooLarge = ConvertChecked(300, @small);
let negative = ConvertChecked(-1, @small);

There is no type argument to write: the source type comes from the value, the destination type from the pointer. @small points at a uint8, so each call converts to uint8.

SourceDestinationLostWritten
200uint8false200
300uint8true44
-1uint8true255
42.0int32false42
42.7int32true42
NaNint32true0

As with checked arithmetic, the pointer is written either way: an integer keeps its low bits, as Truncate would, and a float is cut and clamped as a float as does it. Check the flag before you trust the value.

Every way a value can be lost

"Did not survive" covers every way a conversion can go wrong:

  • Too large for the destination: 300 into a uint8.
  • Negative into an unsigned type: −1 into a uint8.
  • A fraction cut off: 42.7 into an int32 becomes 42, and the 0.7 counts as lost. 42.0 has no fraction, so it converts cleanly.
  • NaN or an infinity, which no integer can represent.
var whole: int32 = 0;
let exact = ConvertChecked(42.0, @whole);
let fraction = ConvertChecked(42.7, @whole);
let nan = ConvertChecked(float64::NaN, @whole);

Two relatives that decide for you

Sometimes the right response to a value that does not fit is not to report it but to pick something. Two functions with the same shape do that, without returning a flag:

  • ConvertWrapping keeps whatever fits — the low bits of an integer, as Truncate does — with a name that says the loss is intended. It is the counterpart of wrapping arithmetic, and works in generic code too.
  • ConvertSaturating clamps to the nearest value the destination can hold.
ConvertSaturating(300, @small);
ConvertSaturating(-1, @small);

300 becomes 255, the largest uint8, and −1 becomes 0, the smallest.

flowchart LR
    v["A value that might<br/>not fit the destination"] --> q{"What should happen<br/>if it does not?"}
    q -- "it always fits" --> as["`as`"]
    q -- "tell me" --> c["`ConvertChecked`"]
    q -- "keep the low bits,<br/>on purpose" --> w["`ConvertWrapping`"]
    q -- "use the nearest<br/>value that fits" --> s["`ConvertSaturating`"]

Reporting it in a type

As with Area in checked arithmetic, the flag and the pointer are best kept inside a function whose return type tells the caller what can happen:

func ToByte(count: int32) -> uint8? {
    var result: uint8 = 0;
    let lost = ConvertChecked(count, @result);
    if lost {
        return none;
    }
    return result;
}

ToByte(99) is 99; ToByte(999) is none, and the caller cannot use a wrong byte without first deciding what none means.

The program

The whole lesson is one package in the Examples repository. Its comments explain every step.

Src/Main.rux
// Between integer types, `as` keeps the value or stops the program: 300 or -1 as a `uint8` ends it
// with `Panic: integer cast out of range`. That is right where the value is known to fit, and a
// crash everywhere else, where the program would rather decide for itself. `Core::ConvertChecked`
// converts without ever stopping and tells you whether anything was lost.
//
// It follows the out-parameter shape of the checked arithmetic: the converted value is written
// through a pointer, which also names the destination type, and the `bool` it returns is `true`
// when the value did not survive. "Did not survive" covers every way a conversion can go wrong:
// too large, negative into an unsigned type, a fraction cut off a float, and a NaN or infinity.
//
// Two relatives decide what to do with a value that does not fit, without reporting it.
// `ConvertWrapping` keeps whatever fits, the low bits of an integer, with a name that says the
// loss is intended, and `ConvertSaturating` clamps to the nearest value the destination can hold.
import Core::{ ConvertChecked, ConvertSaturating, float64 };
import Io::PrintLine;

// Turns a count into a byte, or `none` when it does not fit in one.
func ToByte(count: int32) -> uint8? {
    var result: uint8 = 0;
    let lost = ConvertChecked(count, @result);
    if lost {
        return none;
    }
    return result;
}

func Main() -> int {
    var small: uint8 = 0;

    // Each source value, converted to `uint8` and checked.
    let fits = ConvertChecked(200, @small);
    PrintLine("200  -> uint8  lost {:5}  value {}", fits, small);
    let tooLarge = ConvertChecked(300, @small);
    PrintLine("300  -> uint8  lost {:5}  value {}", tooLarge, small);
    let negative = ConvertChecked(-1, @small);
    PrintLine("-1   -> uint8  lost {:5}  value {}", negative, small);

    // From a float, the fraction counts as part of the value.
    var whole: int32 = 0;
    let exact = ConvertChecked(42.0, @whole);
    PrintLine("42.0 -> int32  lost {:5}  value {}", exact, whole);
    let fraction = ConvertChecked(42.7, @whole);
    PrintLine("42.7 -> int32  lost {:5}  value {}", fraction, whole);
    let nan = ConvertChecked(float64::NaN, @whole);
    PrintLine("NaN  -> int32  lost {}", nan);
    PrintLine("");

    // Saturating keeps the nearest value instead.
    ConvertSaturating(300, @small);
    PrintLine("300 saturated  {}", small);
    ConvertSaturating(-1, @small);
    PrintLine("-1 saturated   {}", small);
    PrintLine("");

    // A checking function turns the report into a type.
    PrintLine("ToByte(99)     {}", ToByte(99) ?? 0);
    match ToByte(999) {
        .Some(value) => PrintLine("ToByte(999)    {}", value),
        none => PrintLine("ToByte(999)    does not fit")
    }
    return 0;
}

Besides Io, its Rux.toml lists Core under [Dependencies].

Run it

cd Examples/Numbers/CheckedConvert
rux run
200  -> uint8  lost false  value 200
300  -> uint8  lost true   value 44
-1   -> uint8  lost true   value 255
42.0 -> int32  lost false  value 42
42.7 -> int32  lost true   value 42
NaN  -> int32  lost true

300 saturated  255
-1 saturated   0

ToByte(99)     99
ToByte(999)    does not fit

Common mistakes

Try it yourself

  1. Convert float64::Infinity to an int32 with ConvertChecked, and then with ConvertSaturating. What does each give?
  2. Store 300 in an int32 called count, and compare ConvertWrapping(count, @small) with count.Truncate<uint8>() and with count as uint8.
  3. Convert the integer 16777217 to a float32 with ConvertChecked. Is anything lost? Look up why in Float.
  4. Write func ToPercent(ratio: float64) -> uint8? that multiplies by 100 and returns none unless the result is a whole number from 0 to 100.

Learn more