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

This library lets you ensure correct assumptions about constants, types, and more. See the [docs] and FAQ for more info!

Installation

This crate is available on crates.io and can be used by adding the following to your project's Cargo.toml:

[dependencies]
static_assertions = "1.1.0"

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

#[macro_use]
extern crate static_assertions;

Usage

This crate exposes the following macros:

• [assert_cfg!]
• [asserteqalign!]
• [asserteqsize!]
• [asserteqsize_ptr!]
• [asserteqsize_val!]
• [assert_fields!]
• [assertimplall!]
• [assertimplany!]
• [assertimplone!]
• [assertnotimpl_all!]
• [assertnotimpl_any!]
• [assertobjsafe!]
• [asserttraitsub_all!]
• [asserttraitsuper_all!]
• [asserttypeeq_all!]
• [asserttypene_all!]
• [const_assert!]
• [constasserteq!]
• [constassertne!]

FAQ

• Q: When would I want to use this?

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

Basic examples:

- With the release of 1.39, str::len can be called in a const context. Using [const_assert!], one can check that a string generated from elsewhere is of a given size:

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

- Have a type that absolutely must implement certain traits? With [assertimplall!], one can ensure this:

struct Foo {
        value: // ...
    }
assertimplall!(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 see implemented. Create a [new issue] and describe how you'd imagine your assertion to work, with example code to demonstrate.

- Implement your own static assertion and create a [pull request].

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

- Write docs. If you're familiar with how this library works, sharing your knowledge 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 are at 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 library can be put in dev-dependencies:

[dev-dependencies]
  static_assertions = "1.1.0"

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

#[cfg(test)]
  constasserteq!(MEANINGOFLIFE, 42);

However, the assertions will only be checked when running cargo test. This somewhat defeats the purpose of catching false static conditions up-front with a compilation failure.

• Q: What is const _?

A: It's a way of creating an unnamed constant. This is used so that macros can be called from a global scope without requiring a scope-unique label. This library makes use of the side effects of evaluating the const expression. See the feature's tracking issue and issue #1 for more info.

Changes

See CHANGELOG.md for a complete list of what has changed from one version to another.

License

This project is released under either:

• MIT License

• Apache License (Version 2.0)

at your choosing.

[new issue]: https://github.com/nvzqz/static-assertions-rs/issues/new [pull request]: https://github.com/nvzqz/static-assertions-rs/pulls [docs]: https://docs.rs/static_assertions

[assertcfg!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertcfg.html [asserteqalign!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserteqalign.html [asserteqsize!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserteqsize.html [asserteqsizeptr!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserteqsizeptr.html [asserteqsizeval!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserteqsizeval.html [assertfields!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertfields.html [assertimplall!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertimplall.html [assertimplany!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertimplany.html [assertimplone!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertimplone.html [assertnotimplall!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertnotimplall.html [assertnotimplany!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertnotimplany.html [assertobjsafe!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.assertobjsafe.html [asserttraitsuball!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserttraitsuball.html [asserttraitsuperall!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserttraitsuperall.html [asserttypeeqall!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserttypeeqall.html [asserttypeneall!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.asserttypeneall.html [constassert!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.constassert.html [constasserteq!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.constasserteq.html [constassertne!]: https://docs.rs/staticassertions/1.1.0/staticassertions/macro.constassertne.html