Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/nvzqz/static-assertions

Ensure correct assumptions about constants, types, and more in Rust
https://github.com/nvzqz/static-assertions

assert compile-time rust static-assertions testing

Last synced: about 20 hours ago
JSON representation

Ensure correct assumptions about constants, types, and more in Rust

Host: GitHub
URL: https://github.com/nvzqz/static-assertions
Owner: nvzqz
License: apache-2.0
Created: 2017-08-12T18:02:22.000Z (over 7 years ago)
Default Branch: master
Last Pushed: 2023-11-18T10:20:29.000Z (about 1 year ago)
Last Synced: 2024-10-29T16:20:02.502Z (3 months ago)
Topics: assert, compile-time, rust, static-assertions, testing
Language: Rust
Homepage: https://docs.rs/static_assertions
Size: 547 KB
Stars: 576
Watchers: 17
Forks: 23
Open Issues: 35
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE-APACHE

Awesome Lists containing this project

README

        [![Banner](https://raw.githubusercontent.com/nvzqz/static-assertions-rs/assets/Banner.png)](https://github.com/nvzqz/static-assertions-rs)



    

        

        

    

    

        

    

    

    


    

        

    

    

        

    



Compile-time assertions for Rust, brought to you by

[Nikolai Vazquez](https://twitter.com/NikolaiVazquez).

This library lets you ensure correct assumptions about constants, types, and

more. See the [docs] and [FAQ](#faq) for more info!

## Installation

This crate is available

[on crates.io](https://crates.io/crates/static_assertions) and can be used by

adding the following to your project's

[`Cargo.toml`](https://doc.rust-lang.org/cargo/reference/manifest.html):

```toml

[dependencies]

static_assertions = "1.1.0"

```

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

```rust

#[macro_use]

extern crate static_assertions;

```

## Usage

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!`]

## 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:

    ```rust

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

    const_assert!(DATA.len() < 512);

    ```

  - Have a type that absolutely must implement certain traits? With

    [`assert_impl_all!`], one can ensure this:

    ```rust

    struct Foo {

        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 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`:

  ```toml

  [dev-dependencies]

  static_assertions = "1.1.0"

  ```

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

  ```rust

  #[cfg(test)]

  const_assert_eq!(MEANING_OF_LIFE, 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](https://github.com/rust-lang/rust/issues/54912)

  and

  [issue #1](https://github.com/nvzqz/static-assertions-rs/issues/1)

  for more info.

## Changes

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

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

## License

This project is released under either:

- [MIT License](https://github.com/nvzqz/static-assertions-rs/blob/master/LICENSE-MIT)

- [Apache License (Version 2.0)](https://github.com/nvzqz/static-assertions-rs/blob/master/LICENSE-APACHE)

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

[`assert_cfg!`]:             https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_cfg.html

[`assert_eq_align!`]:        https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_align.html

[`assert_eq_size!`]:         https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_size.html

[`assert_eq_size_ptr!`]:     https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_size_ptr.html

[`assert_eq_size_val!`]:     https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_eq_size_val.html

[`assert_fields!`]:          https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_fields.html

[`assert_impl_all!`]:        https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_impl_all.html

[`assert_impl_any!`]:        https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_impl_any.html

[`assert_impl_one!`]:        https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_impl_one.html

[`assert_not_impl_all!`]:    https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_not_impl_all.html

[`assert_not_impl_any!`]:    https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_not_impl_any.html

[`assert_obj_safe!`]:        https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_obj_safe.html

[`assert_trait_sub_all!`]:   https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_trait_sub_all.html

[`assert_trait_super_all!`]: https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_trait_super_all.html

[`assert_type_eq_all!`]:     https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_type_eq_all.html

[`assert_type_ne_all!`]:     https://docs.rs/static_assertions/1.1.0/static_assertions/macro.assert_type_ne_all.html

[`const_assert!`]:           https://docs.rs/static_assertions/1.1.0/static_assertions/macro.const_assert.html

[`const_assert_eq!`]:        https://docs.rs/static_assertions/1.1.0/static_assertions/macro.const_assert_eq.html

[`const_assert_ne!`]:        https://docs.rs/static_assertions/1.1.0/static_assertions/macro.const_assert_ne.html