#numeric #conversion #data #lossless #num #numbers #value

as_num

Checked conversions between Rust's numeric types

10 releases

0.3.1 Oct 6, 2023
0.2.5 Dec 31, 2018
0.2.4 Jul 21, 2018
0.2.3 Aug 5, 2017
0.1.2 Jan 21, 2017

#760 in Rust patterns

Download history 211/week @ 2024-07-25 52/week @ 2024-08-01 57/week @ 2024-08-08 53/week @ 2024-08-15 61/week @ 2024-08-22 108/week @ 2024-08-29 80/week @ 2024-09-05 92/week @ 2024-09-12 131/week @ 2024-09-19 147/week @ 2024-09-26 128/week @ 2024-10-03 128/week @ 2024-10-10 136/week @ 2024-10-17 133/week @ 2024-10-24 166/week @ 2024-10-31 85/week @ 2024-11-07

533 downloads per month
Used in 5 crates (via kompact)

MIT/Apache

17KB
304 lines

This module implements a very opinionated approach to converting numbers.

Imagine you have a function return_u32, and you would like to pass its return value into some other function take_i8:

fn return_u32() -> u32 {
    257
}
fn take_i8(i: i8) {
}

Then, the compiler (correctly) complains as soon as you write take_i8(return_u32()). I came into those situations frequently, so I simply changed it to take_i8(return_u32() as i8). However, when doing so, I implicitly assumed that the semantic meaning of the number does not change, i.e. I assume that i8 is capable of representing the exact same value that return_u32 gives me (which is not the case in the example shown).

This module enables you to write the following:

use as_num::TAsNum; // TAsNum is the trait enabling the conversions
take_i8(return_u32().as_num())

as_num converts its argument into the destination type, thereby checking whether the conversion can be done without loss of data.

It tries to follow a similar approach to the one that is chosen with e.g. "normal addition" and checked_add: It offers one method as_num that does the conversion (at last going down to Rust's as), and debug_asserts that the conversion is lossless. In addition to as_num, it offers a method checked_as_num, returning an Option.

This module implements conversion for any combination of the following types: i8, i16, i32, i64, isize, u8, u16, u32, u64, usize, f32, f64.

The function as_num debug_asserts that the destination value is convertible back to the exact same source value.

That, in particular, means that converting floating-point to integral numbers can only be done with as_num if the source is already been rounded to some integral number.

No runtime deps