Skip to content

Commit 4edfc29

Browse files
committed
Add FAQ to README.md
1 parent 4ea64cf commit 4edfc29

File tree

1 file changed

+74
-0
lines changed

1 file changed

+74
-0
lines changed

README.md

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -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

65139
See [`CHANGELOG.md`](https://github.com/nvzqz/static-assertions-rs/blob/master/CHANGELOG.md)

0 commit comments

Comments
 (0)