Adapt functionality for use in Mango
- drop overflowing/wrapping - rename to Checked Math - be very restrictive in what syntax is accepted, never silently skip transforming subexpressions - update dependencies
This commit is contained in:
Christian Kamm
parent
ae2a60a27b
commit
dcd249a3a0
16
Cargo.toml
16
Cargo.toml
|
|
@ -1,11 +1,10 @@
|
|||
[package]
|
||||
name = "overflow"
|
||||
description = "Proc macros for changing the overflow behavior of math expressions"
|
||||
name = "checked_math"
|
||||
description = "Proc macros for changing the checking behavior of math expressions"
|
||||
version = "0.1.0"
|
||||
authors = ["Ryan Levick<ryan.levick@gmail.com>"]
|
||||
repository = "https://github.com/rylev/overflow"
|
||||
authors = ["Ryan Levick<ryan.levick@gmail.com>", "Christian Kamm <mail@ckamm.de>"]
|
||||
license = "MIT"
|
||||
edition = "2018"
|
||||
edition = "2021"
|
||||
autotests = false
|
||||
|
||||
[lib]
|
||||
|
|
@ -19,6 +18,7 @@ path = "tests/progress.rs"
|
|||
trybuild = "1.0"
|
||||
|
||||
[dependencies]
|
||||
syn = { version = "0.15.39", features = ["full", "extra-traits"] }
|
||||
quote = "0.6.12"
|
||||
proc-macro2 = "0.4.30"
|
||||
syn = { version = "1.0.86", features = ["full", "extra-traits"] }
|
||||
quote = "1.0.15"
|
||||
proc-macro2 = "1.0.36"
|
||||
proc-macro-error = "1.0.4"
|
||||
|
|
|
|||
46
README.md
46
README.md
|
|
@ -1,40 +1,56 @@
|
|||
# Overflow
|
||||
# Checked Math
|
||||
|
||||
A convenience macro for changing the overflow properties of math expressions without having to change those expressions (mostly).
|
||||
A convenience macro for changing the checking properties of math expressions without having to change those expressions (mostly).
|
||||
|
||||
## Some Background
|
||||
|
||||
By default Rust's math expressions (e.g., 2 * 9) panic on overflow in debug builds and overflow silently in release builds. While this is a fine default, you may want different behaivor. For instance, integer overflow may be expected behaivor. In that case you'll want to reach for the various overflow APIs available for Rust numbers (e.g., [`wrapping_mul`](https://doc.rust-lang.org/std/primitive.u32.html#method.wrapping_mul)). The issue with this however, is that you can no longer use normal math notation, instead needing to use cumbersome methods like `a.wrapping_add(b)` instead of `a + b`.
|
||||
By default Rust's math expressions (e.g., 2 * 9) panic on overflow in debug builds and overflow silently in release builds. While this is a fine default, you may want different behaivor. For instance, you may want to panic on overflow even in release builds. In that case you'll want to reach for the various APIs available for Rust numbers (e.g., [`checked_mul`](https://doc.rust-lang.org/std/primitive.u32.html#method.checked_mul)). The issue with this however, is that you can no longer use normal math notation, instead needing to use cumbersome methods like `a.checked_add(b).unwrap()` instead of `a + b`.
|
||||
|
||||
Overflow lets you keep using normal math notation but still change the way that overflows are handled.
|
||||
Checked Math lets you keep using normal math notation by performing the rewrite in a proc macro.
|
||||
|
||||
## Example
|
||||
|
||||
By default the following will fail in debug builds at runtime:
|
||||
By default the following may silently overflow in release builds at runtime:
|
||||
|
||||
```rust
|
||||
(2u8.pow(20) << 20) + 2 * 2;
|
||||
(x * y) + z
|
||||
```
|
||||
|
||||
In order to make this wrap in debug and release builds you would need to write it this way:
|
||||
In order to to panic on error instead, people often rewrite to:
|
||||
|
||||
```rust
|
||||
(2u8.wrapping_pow(20).wrapping_shl(20)).wrapping_add(2u8.wrapping_mul(2))
|
||||
x.checked_mul(y).unwrap().checked_add(z).unwrap()
|
||||
```
|
||||
|
||||
Or you could use Overflow and write the following:
|
||||
Or you could use Checked Math and write the following:
|
||||
|
||||
```rust
|
||||
overflow::wrapping! { (2u8.pow(20) << 20) + 2u8 * 2 }
|
||||
use checked_math::checked_math as cm;
|
||||
cm!((x * y) + z).unwrap()
|
||||
```
|
||||
|
||||
The above converts the normal meth expression syntax directly into the `wrapping` variant from above.
|
||||
The macro call converts the normal math expression into an expression returning `None` if any of the checked math steps return `None`, and `Some(_)` on success.
|
||||
|
||||
Projects may want to wrap the rewriting macro to automatically include their error
|
||||
reporting, for example:
|
||||
```rust
|
||||
#[macro_export]
|
||||
macro_rules! my_checked_math {
|
||||
($x: expr) => {
|
||||
checked_math::checked_math!($x).unwrap_or_else(|| panic!("math error"))
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Limitations
|
||||
|
||||
Overflow is currently limited in the following:
|
||||
Checked Math is currently limited in the following:
|
||||
|
||||
* The crate currently requires nightly because proc macros in expressions are not currently stable.
|
||||
* Because math operations can more easily propogate type inference information than method calls, you may have to add type information when using the macros that were not neceesary before.
|
||||
* Overflow behaivor is only affected at the top level (or within parenthesis) meaning that if you have math expressions inside of method invocations or inside of other macros, those expressions will not be converted.
|
||||
* Conversion of `pow` is extremely naive so if you call a `pow` method on some type, this will be converted to `wrapping_pow` even if that makes no sense for that type.
|
||||
* The syntax the macro accepts is intentionally limited to binary expressions, parentheses, argument-less calls and some extras. The background is that it would be confusing if inner expressions like in `checked_math!(foo(a + b))` or `checked_math!(if a + b { b + c } else { d })` were silently not transformed.
|
||||
* Conversion of `pow` is extremely naive so if you call a `pow` method on some type, this will be converted to `checked_pow` even if that makes no sense for that type.
|
||||
|
||||
## History
|
||||
|
||||
This is a modified version of `overflow` from https://github.com/rylev/overflow/ originally by Ryan Levick.
|
||||
See LICENSE.
|
||||
|
|
|
|||
39
src/lib.rs
39
src/lib.rs
|
|
@ -3,43 +3,24 @@ extern crate proc_macro;
|
|||
mod transform;
|
||||
|
||||
use proc_macro::TokenStream;
|
||||
use proc_macro_error::proc_macro_error;
|
||||
use syn::parse_macro_input;
|
||||
|
||||
/// Produces a semantically equivalent expression as the one provided
|
||||
/// except that each math call is substituted with the equivalent version
|
||||
/// of the `wrapping` API.
|
||||
///
|
||||
/// For instance, `+` is substituted with a call to `wrapping_add`
|
||||
#[proc_macro]
|
||||
pub fn wrapping(input: TokenStream) -> TokenStream {
|
||||
let input = parse_macro_input!(input as syn::Expr);
|
||||
let expanded = transform::wrapping::transform_expr(input);
|
||||
|
||||
TokenStream::from(expanded)
|
||||
}
|
||||
|
||||
/// Produces a semantically equivalent expression as the one provided
|
||||
/// except that each math call is substituted with the equivalent version
|
||||
/// of the `checked` API.
|
||||
///
|
||||
/// For instance, `+` is substituted with a call to `checked_add`
|
||||
/// Examples:
|
||||
/// - `checked_math!{ 1 }` will become `Some(1)`
|
||||
/// - `checked_math!{ a + b }` will become `a.checked_add(b)`
|
||||
///
|
||||
/// The macro is intened to be used for arithmetic expressions only and
|
||||
/// significantly restricts the available syntax.
|
||||
#[proc_macro]
|
||||
pub fn checked(input: TokenStream) -> TokenStream {
|
||||
#[proc_macro_error]
|
||||
pub fn checked_math(input: TokenStream) -> TokenStream {
|
||||
let input = parse_macro_input!(input as syn::Expr);
|
||||
let expanded = transform::checked::transform_expr(input, true);
|
||||
let expanded = transform::checked::transform_expr(input);
|
||||
|
||||
TokenStream::from(expanded)
|
||||
}
|
||||
|
||||
/// Produces a semantically equivalent expression as the one provided
|
||||
/// except that each math call is substituted with the equivalent version
|
||||
/// of the `overflowing` API.
|
||||
///
|
||||
/// For instance, `+` is substituted with a call to `overflowing_add`
|
||||
#[proc_macro]
|
||||
pub fn overflowing(input: TokenStream) -> TokenStream {
|
||||
let input = parse_macro_input!(input as syn::Expr);
|
||||
let expanded = transform::overflowing::transform_expr(input, true);
|
||||
|
||||
TokenStream::from(expanded)
|
||||
}
|
||||
|
|
@ -1,36 +1,58 @@
|
|||
use proc_macro_error::abort;
|
||||
use quote::quote;
|
||||
use syn::{spanned::Spanned, BinOp, Expr, ExprBinary, ExprUnary, Ident, UnOp};
|
||||
use syn::{spanned::Spanned, BinOp, Expr, ExprBinary, ExprUnary, Ident, Lit, UnOp};
|
||||
|
||||
pub fn transform_expr(mut expr: Expr, wrap_expression: bool) -> proc_macro2::TokenStream {
|
||||
pub fn transform_expr(mut expr: Expr) -> proc_macro2::TokenStream {
|
||||
match expr {
|
||||
Expr::Unary(unary) => transform_unary(unary),
|
||||
Expr::Binary(binary) => transform_binary(binary),
|
||||
Expr::MethodCall(ref mut mc) if mc.method == "pow" => {
|
||||
mc.method = syn::Ident::new("checked_pow", mc.method.span());
|
||||
quote! { #mc }
|
||||
Expr::MethodCall(ref mut mc) => {
|
||||
if mc.method == "pow" {
|
||||
mc.method = syn::Ident::new("checked_pow", mc.method.span());
|
||||
quote! { #mc }
|
||||
} else if mc.method == "abs" {
|
||||
mc.method = syn::Ident::new("checked_abs", mc.method.span());
|
||||
quote! { #mc }
|
||||
} else if mc.args.is_empty() {
|
||||
quote! { Some(#mc) }
|
||||
} else {
|
||||
abort!(mc, "method calls with arguments are not supported");
|
||||
}
|
||||
}
|
||||
Expr::MethodCall(ref mut mc) if mc.method == "abs" => {
|
||||
mc.method = syn::Ident::new("checked_abs", mc.method.span());
|
||||
quote! { #mc }
|
||||
Expr::Call(ref mut c) => {
|
||||
if c.args.is_empty() {
|
||||
quote! { Some(#c) }
|
||||
} else {
|
||||
abort!(c, "calls with arguments are not supported");
|
||||
}
|
||||
}
|
||||
Expr::Paren(p) => {
|
||||
let expr = transform_expr(*p.expr, false);
|
||||
let expr = transform_expr(*p.expr);
|
||||
quote! {
|
||||
(#expr)
|
||||
}
|
||||
}
|
||||
_ => {
|
||||
if wrap_expression {
|
||||
quote! { Some(#expr) }
|
||||
} else {
|
||||
quote! { #expr }
|
||||
Expr::Group(g) => {
|
||||
let expr = transform_expr(*g.expr);
|
||||
quote! {
|
||||
(#expr)
|
||||
}
|
||||
}
|
||||
Expr::Lit(lit) => match lit.lit {
|
||||
Lit::Int(_) | Lit::Float(_) => quote! { Some(#lit) },
|
||||
_ => abort!(lit, "unsupported literal"),
|
||||
},
|
||||
Expr::Path(_) | Expr::Field(_) => {
|
||||
quote! { Some(#expr) }
|
||||
}
|
||||
_ => {
|
||||
abort!(expr, "unsupported expr {:?}", expr);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn transform_unary(unary: ExprUnary) -> proc_macro2::TokenStream {
|
||||
let expr = transform_expr(*unary.expr, true);
|
||||
let expr = transform_expr(*unary.expr);
|
||||
let op = unary.op;
|
||||
match op {
|
||||
UnOp::Neg(_) => {
|
||||
|
|
@ -43,13 +65,14 @@ fn transform_unary(unary: ExprUnary) -> proc_macro2::TokenStream {
|
|||
}
|
||||
}
|
||||
}
|
||||
_ => quote! { #expr },
|
||||
UnOp::Deref(_) => quote! { #expr },
|
||||
UnOp::Not(_) => abort!(expr, "unsupported unary expr"),
|
||||
}
|
||||
}
|
||||
|
||||
fn transform_binary(binary: ExprBinary) -> proc_macro2::TokenStream {
|
||||
let left = transform_expr(*binary.left, true);
|
||||
let right = transform_expr(*binary.right, true);
|
||||
let left = transform_expr(*binary.left);
|
||||
let right = transform_expr(*binary.right);
|
||||
let op = binary.op;
|
||||
let method_name = match op {
|
||||
BinOp::Add(_) => Some("checked_add"),
|
||||
|
|
@ -59,7 +82,7 @@ fn transform_binary(binary: ExprBinary) -> proc_macro2::TokenStream {
|
|||
BinOp::Rem(_) => Some("checked_rem"),
|
||||
BinOp::Shl(_) => Some("checked_shl"),
|
||||
BinOp::Shr(_) => Some("checked_shr"),
|
||||
_ => None,
|
||||
_ => abort!(op, "unsupported binary expr"),
|
||||
};
|
||||
method_name
|
||||
.map(|method_name| {
|
||||
|
|
@ -82,4 +105,4 @@ fn transform_binary(binary: ExprBinary) -> proc_macro2::TokenStream {
|
|||
}
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,3 +1 @@
|
|||
pub mod wrapping;
|
||||
pub mod checked;
|
||||
pub mod overflowing;
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
use quote::quote;
|
||||
use syn::{spanned::Spanned, BinOp, Expr, ExprBinary, ExprUnary, Ident, UnOp};
|
||||
|
||||
pub fn transform_expr(mut expr: Expr, wrap_expression: bool) -> proc_macro2::TokenStream {
|
||||
match expr {
|
||||
Expr::Unary(unary) => transform_unary(unary),
|
||||
Expr::Binary(binary) => transform_binary(binary),
|
||||
Expr::MethodCall(ref mut mc) if mc.method == "pow" => {
|
||||
transform_method_call(mc, "overflowing_pow")
|
||||
}
|
||||
Expr::MethodCall(ref mut mc) if mc.method == "abs" => {
|
||||
transform_method_call(mc, "overflowing_abs")
|
||||
}
|
||||
Expr::Paren(p) => {
|
||||
let expr = transform_expr(*p.expr, false);
|
||||
quote! {
|
||||
(#expr)
|
||||
}
|
||||
}
|
||||
_ => {
|
||||
if wrap_expression {
|
||||
quote! { (#expr, false) }
|
||||
} else {
|
||||
quote! { #expr }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn transform_unary(unary: ExprUnary) -> proc_macro2::TokenStream {
|
||||
let expr = transform_expr(*unary.expr, true);
|
||||
let op = unary.op;
|
||||
match op {
|
||||
UnOp::Neg(_) => {
|
||||
quote! {
|
||||
{
|
||||
let (result, expr_did_overflow) = #expr;
|
||||
let (result, neg_did_overflow) = result.overflowing_neg();
|
||||
(result, expr_did_overflow || neg_did_overflow)
|
||||
}
|
||||
}
|
||||
}
|
||||
_ => quote! { #expr },
|
||||
}
|
||||
}
|
||||
|
||||
fn transform_binary(binary: ExprBinary) -> proc_macro2::TokenStream {
|
||||
let left = transform_expr(*binary.left, true);
|
||||
let right = transform_expr(*binary.right, true);
|
||||
let op = binary.op;
|
||||
let method_name = match op {
|
||||
BinOp::Add(_) => Some("overflowing_add"),
|
||||
BinOp::Sub(_) => Some("overflowing_sub"),
|
||||
BinOp::Mul(_) => Some("overflowing_mul"),
|
||||
BinOp::Div(_) => Some("overflowing_div"),
|
||||
BinOp::Rem(_) => Some("overflowing_rem"),
|
||||
BinOp::Shl(_) => Some("overflowing_shl"),
|
||||
BinOp::Shr(_) => Some("overflowing_shr"),
|
||||
_ => None,
|
||||
};
|
||||
method_name
|
||||
.map(|method_name| {
|
||||
let method_name = Ident::new(method_name, op.span());
|
||||
quote! {
|
||||
{
|
||||
let (left, left_overflowed) = #left;
|
||||
let (right, right_overflowed) = #right;
|
||||
let (result, overflowed) = left.#method_name(right);
|
||||
(result, overflowed || left_overflowed || right_overflowed)
|
||||
}
|
||||
}
|
||||
})
|
||||
.unwrap_or_else(|| {
|
||||
quote! {
|
||||
let (left, left_overflowed) = #left;
|
||||
let (right, right_overflowed) = #right;
|
||||
let result = left # op right;
|
||||
(result, left_overflowed || right_overflowed)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
fn transform_method_call(mc: &mut syn::ExprMethodCall, name: &str) -> proc_macro2::TokenStream {
|
||||
mc.method = syn::Ident::new(name, mc.method.span());
|
||||
quote! { #mc }
|
||||
}
|
||||
|
|
@ -1,64 +0,0 @@
|
|||
use quote::quote;
|
||||
use syn::{spanned::Spanned, BinOp, Expr, ExprBinary, ExprUnary, Ident, UnOp};
|
||||
|
||||
pub fn transform_expr(mut expr: Expr) -> proc_macro2::TokenStream {
|
||||
match expr {
|
||||
Expr::Unary(unary) => transform_unary(unary),
|
||||
Expr::Binary(binary) => transform_binary(binary),
|
||||
Expr::MethodCall(ref mut mc) if mc.method == "pow" => {
|
||||
mc.method = syn::Ident::new("wrapping_pow", mc.method.span());
|
||||
quote! { #mc }
|
||||
}
|
||||
Expr::MethodCall(ref mut mc) if mc.method == "abs" => {
|
||||
mc.method = syn::Ident::new("wrapping_abs", mc.method.span());
|
||||
quote! { #mc }
|
||||
}
|
||||
Expr::Paren(p) => {
|
||||
let expr = transform_expr(*p.expr);
|
||||
quote! {
|
||||
(#expr)
|
||||
}
|
||||
}
|
||||
_ => quote! { #expr },
|
||||
}
|
||||
}
|
||||
|
||||
fn transform_unary(unary: ExprUnary) -> proc_macro2::TokenStream {
|
||||
let expr = transform_expr(*unary.expr);
|
||||
let op = unary.op;
|
||||
match op {
|
||||
UnOp::Neg(_) => {
|
||||
quote! {
|
||||
#expr.wrapping_neg()
|
||||
}
|
||||
}
|
||||
_ => quote! { #expr },
|
||||
}
|
||||
}
|
||||
|
||||
fn transform_binary(binary: ExprBinary) -> proc_macro2::TokenStream {
|
||||
let left = transform_expr(*binary.left);
|
||||
let right = transform_expr(*binary.right);
|
||||
let op = binary.op;
|
||||
let method_name = match op {
|
||||
BinOp::Add(_) => Some("wrapping_add"),
|
||||
BinOp::Sub(_) => Some("wrapping_sub"),
|
||||
BinOp::Mul(_) => Some("wrapping_mul"),
|
||||
BinOp::Div(_) => Some("wrapping_div"),
|
||||
BinOp::Rem(_) => Some("wrapping_rem"),
|
||||
BinOp::Shl(_) => Some("wrapping_shl"),
|
||||
BinOp::Shr(_) => Some("wrapping_shr"),
|
||||
_ => None,
|
||||
};
|
||||
|
||||
method_name
|
||||
.map(|method_name| {
|
||||
let method_name = Ident::new(method_name, op.span());
|
||||
quote! {
|
||||
#left.#method_name(#right)
|
||||
}
|
||||
})
|
||||
.unwrap_or_else(|| {
|
||||
quote! { #left #op #right }
|
||||
})
|
||||
}
|
||||
|
|
@ -1,35 +1,38 @@
|
|||
#![feature(proc_macro_hygiene)]
|
||||
use overflow::{wrapping, checked, overflowing};
|
||||
use checked_math::checked_math;
|
||||
|
||||
fn f() -> u8 {
|
||||
3u8
|
||||
}
|
||||
|
||||
struct S {}
|
||||
impl S {
|
||||
fn m(&self) -> u8 {
|
||||
2u8
|
||||
}
|
||||
}
|
||||
|
||||
fn main() {
|
||||
let num = 2u8;
|
||||
let result = wrapping!{ ((num.pow(20) << 20) + 255) + 2u8 * 2u8 };
|
||||
assert!(result == 3);
|
||||
|
||||
let result = wrapping!{ -std::i8::MIN };
|
||||
assert!(result == -128);
|
||||
|
||||
let result = wrapping!{ 12u8 + 6u8 / 3};
|
||||
assert!(result == 14);
|
||||
|
||||
let result = checked!{ (num + (2u8 / 10)) * 5 };
|
||||
let result = checked_math!{ (num + (2u8 / 10)) * 5 };
|
||||
assert!(result == Some(10));
|
||||
|
||||
let result = checked!{ ((num.pow(20) << 20) + 255) + 2u8 * 2u8 };
|
||||
let result = checked_math!{ ((num.pow(20) << 20) + 255) + 2u8 * 2u8 };
|
||||
assert!(result == None);
|
||||
|
||||
let result = checked!{ -std::i8::MIN };
|
||||
let result = checked_math!{ -std::i8::MIN };
|
||||
assert!(result == None);
|
||||
|
||||
let result = checked!{ 12u8 + 6u8 / 3};
|
||||
let result = checked_math!{ 12u8 + 6u8 / 3 };
|
||||
assert!(result == Some(14));
|
||||
|
||||
let result = overflowing!{ ((num.pow(20) << 20) + 255) + 2u8 * 2u8 };
|
||||
assert!(result == (3, true));
|
||||
let result = checked_math!{ 12u8 + 6u8 / f() };
|
||||
assert!(result == Some(14));
|
||||
|
||||
let result = overflowing!{ -std::i8::MIN };
|
||||
assert!(result == (-128, true));
|
||||
let result = checked_math!{ 12u8 + 6u8 / num };
|
||||
assert!(result == Some(15));
|
||||
|
||||
let result = overflowing!{ (num + 10) + 6u8 / 3};
|
||||
assert!(result == (14, false));
|
||||
let s = S{};
|
||||
let result = checked_math!{ 12u8 + s.m() };
|
||||
assert!(result == Some(14));
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue