README.md
1[](https://github.com/nvzqz/static-assertions-rs)
2
3<div align="center">
4 <a href="https://crates.io/crates/static_assertions">
5 <img src="https://img.shields.io/crates/v/static_assertions.svg" alt="Crates.io">
6 <img src="https://img.shields.io/crates/d/static_assertions.svg" alt="Downloads">
7 </a>
8 <a href="https://travis-ci.org/nvzqz/static-assertions-rs">
9 <img src="https://travis-ci.org/nvzqz/static-assertions-rs.svg?branch=master" alt="Build Status">
10 </a>
11 <img src="https://img.shields.io/badge/rustc-^1.37.0-blue.svg" alt="rustc ^1.37.0">
12 <br>
13 <a href="https://www.patreon.com/nvzqz">
14 <img src="https://c5.patreon.com/external/logo/become_a_patron_button.png" alt="Become a Patron!" height="35">
15 </a>
16 <a href="https://www.paypal.me/nvzqz">
17 <img src="https://buymecoffee.intm.org/img/button-paypal-white.png" alt="Buy me a coffee" height="35">
18 </a>
19</div>
20
21Compile-time assertions for Rust, brought to you by
22[Nikolai Vazquez](https://twitter.com/NikolaiVazquez).
23
24This library lets you ensure correct assumptions about constants, types, and
25more. See the [docs] and [FAQ](#faq) for more info!
26
27## Installation
28
29This crate is available
30[on crates.io](https://crates.io/crates/static_assertions) and can be used by
31adding the following to your project's
32[`Cargo.toml`](https://doc.rust-lang.org/cargo/reference/manifest.html):
33
34```toml
35[dependencies]
36static_assertions = "1.1.0"
37```
38
39and this to your crate root (`main.rs` or `lib.rs`):
40
41```rust
42#[macro_use]
43extern crate static_assertions;
44```
45
46## Usage
47
48This crate exposes the following macros:
49- [`assert_cfg!`]
50- [`assert_eq_align!`]
51- [`assert_eq_size!`]
52- [`assert_eq_size_ptr!`]
53- [`assert_eq_size_val!`]
54- [`assert_fields!`]
55- [`assert_impl_all!`]
56- [`assert_impl_any!`]
57- [`assert_impl_one!`]
58- [`assert_not_impl_all!`]
59- [`assert_not_impl_any!`]
60- [`assert_obj_safe!`]
61- [`assert_trait_sub_all!`]
62- [`assert_trait_super_all!`]
63- [`assert_type_eq_all!`]
64- [`assert_type_ne_all!`]
65- [`const_assert!`]
66- [`const_assert_eq!`]
67- [`const_assert_ne!`]
68
69## FAQ
70
71- **Q:** When would I want to use this?
72
73 **A:** This library is useful for when wanting to ensure properties of
74 constants, types, and traits.
75
76 Basic examples:
77
78 - With the release of 1.39, `str::len` can be called in a `const`
79 context. Using [`const_assert!`], one can check that a string generated from
80 elsewhere is of a given size:
81
82 ```rust
83 const DATA: &str = include_str!("path/to/string.txt");
84
85 const_assert!(DATA.len() < 512);
86 ```
87
88 - Have a type that absolutely must implement certain traits? With
89 [`assert_impl_all!`], one can ensure this:
90
91 ```rust
92 struct Foo {
93 value: // ...
94 }
95
96 assert_impl_all!(Foo: Send, Sync);
97 ```
98
99- **Q:** How can I contribute?
100
101 **A:** A couple of ways! You can:
102
103 - Attempt coming up with some form of static analysis that you'd like to see
104 implemented. Create a [new issue] and describe how you'd imagine your
105 assertion to work, with example code to demonstrate.
106
107 - Implement your own static assertion and create a [pull request].
108
109 - Give feedback. What are some pain points? Where is it unpleasant?
110
111 - Write docs. If you're familiar with how this library works, sharing your
112 knowledge with the rest its users would be great!
113
114- **Q:** Will this affect my compiled binary?
115
116 **A:** Nope! There is zero runtime cost to using this because all checks are
117 at compile-time, and so no code is emitted to run.
118
119- **Q:** Will this affect my compile times?
120
121 **A:** Likely not by anything perceivable. If this is a concern, this library
122 can be put in `dev-dependencies`:
123
124 ```toml
125 [dev-dependencies]
126 static_assertions = "1.1.0"
127 ```
128
129 and then assertions can be conditionally run behind `#[cfg(test)]`:
130
131 ```rust
132 #[cfg(test)]
133 const_assert_eq!(MEANING_OF_LIFE, 42);
134 ```
135
136 However, the assertions will only be checked when running `cargo test`. This
137 somewhat defeats the purpose of catching false static conditions up-front with
138 a compilation failure.
139
140- **Q:** What is `const _`?
141
142 **A:** It's a way of creating an unnamed constant. This is used so that macros
143 can be called from a global scope without requiring a scope-unique label. This
144 library makes use of the side effects of evaluating the `const` expression.
145 See the feature's
146 [tracking issue](https://github.com/rust-lang/rust/issues/54912)
147 and
148 [issue #1](https://github.com/nvzqz/static-assertions-rs/issues/1)
149 for more info.
150
151## Changes
152
153See [`CHANGELOG.md`](https://github.com/nvzqz/static-assertions-rs/blob/master/CHANGELOG.md)
154for a complete list of what has changed from one version to another.
155
156## License
157
158This project is released under either:
159
160- [MIT License](https://github.com/nvzqz/static-assertions-rs/blob/master/LICENSE-MIT)
161
162- [Apache License (Version 2.0)](https://github.com/nvzqz/static-assertions-rs/blob/master/LICENSE-APACHE)
163
164at your choosing.
165
166[new issue]: https://github.com/nvzqz/static-assertions-rs/issues/new
167[pull request]: https://github.com/nvzqz/static-assertions-rs/pulls
168[docs]: https://docs.rs/static_assertions
169
170[`assert_cfg!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_cfg.html
171[`assert_eq_align!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_align.html
172[`assert_eq_size!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_size.html
173[`assert_eq_size_ptr!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_size_ptr.html
174[`assert_eq_size_val!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_size_val.html
175[`assert_fields!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_fields.html
176[`assert_impl_all!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_impl_all.html
177[`assert_impl_any!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_impl_any.html
178[`assert_impl_one!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_impl_one.html
179[`assert_not_impl_all!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_not_impl_all.html
180[`assert_not_impl_any!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_not_impl_any.html
181[`assert_obj_safe!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_obj_safe.html
182[`assert_trait_sub_all!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_trait_sub_all.html
183[`assert_trait_super_all!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_trait_super_all.html
184[`assert_type_eq_all!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_type_eq_all.html
185[`assert_type_ne_all!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_type_ne_all.html
186[`const_assert!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.const_assert.html
187[`const_assert_eq!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.const_assert_eq.html
188[`const_assert_ne!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.const_assert_ne.html
189
){kind=link}
