@@ -60,6 +60,80 @@ This crate exposes the following macros:
6060- [ ` const_assert_eq! ` ]
6161- [ ` const_assert_ne! ` ]
6262
63+ ## FAQ
64+
65+ - ** Q:** When would I want to use this?
66+
67+ ** A:** This library is useful for when wanting to ensure properties of
68+ constants, types, and traits.
69+
70+ Basic examples:
71+
72+ - With the release of 1.39, ` str::len ` can be called in a ` const `
73+ context. Using [ ` const_assert! ` ] , one can check that a string generated from
74+ elsewhere is of a given size:
75+
76+ ``` rust
77+ const DATA : & str = include_str! (" path/to/string.txt" );
78+
79+ const_assert! (DATA . len () < 512 );
80+ ```
81+
82+ - Have a type that absolutely must implement certain traits ? With
83+ [`assert_impl_all! `], one can ensure this :
84+
85+ ```rust
86+ struct Foo {
87+ value : // ...
88+ }
89+
90+ assert_impl_all! (Foo : Send , Sync );
91+ ```
92+
93+ - * * Q : ** Will this affect my compiled binary ?
94+
95+ * * A : ** Nope! There is zero runtime cost to using this because all checks are
96+ at compile - time , and so no code is emitted to run .
97+
98+ - * * Q : ** How can I contribute ?
99+
100+ * * A : ** A couple of ways!
101+
102+ You can try to come up with some form of static analysis that you 'd like to
103+ see implemented . Create a [new issue ] and describe how you 'd imagine your
104+ assertion to work , with example code to demonstrate .
105+
106+ - * * Q : ** Will this affect my compile times ?
107+
108+ * * A : ** Likely not by anything perceivable . If this is a concern , this library
109+ can be put in `dev - dependencies `:
110+
111+ ```toml
112+ [dev - dependencies ]
113+ static_assertions = " 1.0.0"
114+ ```
115+
116+ and then assertions can be conditionally run behind ` #[cfg(test)] ` :
117+
118+ ``` rust
119+ #[cfg(test)]
120+ const_assert_eq! (MEANING_OF_LIFE , 42 );
121+ ```
122+
123+ However, the assertions will only be checked when running ` cargo test ` . This
124+ somewhat defeats the purpose of catching false static conditions up-front with
125+ a compilation failure.
126+
127+ - ** Q:** What is ` const _ ` ?
128+
129+ ** A:** It's a way of creating an unnamed constant. This is used so that macros
130+ can be called from a global scope. This library makes use of the side effects
131+ of evaluating the ` const ` expression. See the feature's
132+ [ tracking issue] ( https://github.com/rust-lang/rust/issues/54912 )
133+ and
134+ [ issue #1 ] ( https://github.com/nvzqz/static-assertions-rs/issues/1 )
135+ fore more info.
136+
63137## Changes
64138
65139See [ ` CHANGELOG.md ` ] ( https://github.com/nvzqz/static-assertions-rs/blob/master/CHANGELOG.md )
0 commit comments