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

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

#729 in Rust patterns

Download history 64/week @ 2024-06-10 58/week @ 2024-06-17 55/week @ 2024-06-24 80/week @ 2024-07-01 44/week @ 2024-07-08 65/week @ 2024-07-15 227/week @ 2024-07-22 61/week @ 2024-07-29 48/week @ 2024-08-05 53/week @ 2024-08-12 59/week @ 2024-08-19 100/week @ 2024-08-26 84/week @ 2024-09-02 69/week @ 2024-09-09 105/week @ 2024-09-16 165/week @ 2024-09-23

428 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