Repository files navigation

Compile-time assertions for Rust, brought to you byNikolai Vazquez.

This library lets you ensure correct assumptions about constants, types, andmore. See thedocs andFAQ for more info!

This crate is availableon crates.io and can be used byadding the following to your project'sCargo.toml:

[dependencies]static_assertions ="1.1.0"

and this to your crate root (main.rs orlib.rs):

#[macro_use]externcrate static_assertions;

This crate exposes the following macros:

• assert_cfg!
• assert_eq_align!
• assert_eq_size!
• assert_eq_size_ptr!
• assert_eq_size_val!
• assert_fields!
• assert_impl_all!
• assert_impl_any!
• assert_impl_one!
• assert_not_impl_all!
• assert_not_impl_any!
• assert_obj_safe!
• assert_trait_sub_all!
• assert_trait_super_all!
• assert_type_eq_all!
• assert_type_ne_all!
• const_assert!
• const_assert_eq!
• const_assert_ne!

• Q: When would I want to use this?

  A: This library is useful for when wanting to ensure properties ofconstants, types, and traits.

  Basic examples:

  • With the release of 1.39,str::len can be called in aconstcontext. Usingconst_assert!, one can check that a string generated fromelsewhere is of a given size:

    constDATA:&str =include_str!("path/to/string.txt");const_assert!(DATA.len() <512);

  • Have a type that absolutely must implement certain traits? Withassert_impl_all!, one can ensure this:

    structFoo{value:// ...}assert_impl_all!(Foo:Send,Sync);

• Q: How can I contribute?

  A: A couple of ways! You can:

  • Attempt coming up with some form of static analysis that you'd like to seeimplemented. Create anew issue and describe how you'd imagine yourassertion to work, with example code to demonstrate.

  • Implement your own static assertion and create apull request.

  • Give feedback. What are some pain points? Where is it unpleasant?

  • Write docs. If you're familiar with how this library works, sharing yourknowledge with the rest its users would be great!

• Q: Will this affect my compiled binary?

  A: Nope! There is zero runtime cost to using this because all checks areat compile-time, and so no code is emitted to run.

• Q: Will this affect my compile times?

  A: Likely not by anything perceivable. If this is a concern, this librarycan be put indev-dependencies:

  [dev-dependencies]static_assertions ="1.1.0"

  and then assertions can be conditionally run behind#[cfg(test)]:

  #[cfg(test)]const_assert_eq!(MEANING_OF_LIFE,42);

  However, the assertions will only be checked when runningcargo test. Thissomewhat defeats the purpose of catching false static conditions up-front witha compilation failure.

• Q: What isconst _?

  A: It's a way of creating an unnamed constant. This is used so that macroscan be called from a global scope without requiring a scope-unique label. Thislibrary makes use of the side effects of evaluating theconst expression.See the feature'stracking issueandissue #1for more info.

SeeCHANGELOG.mdfor a complete list of what has changed from one version to another.

This project is released under either:

• MIT License

• Apache License (Version 2.0)

at your choosing.