Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/yegor256/microstack
The most primitive and the fastest implementation of a fixed-size last-in-first-out stack on stack in Rust, for Copy-implementing types
https://github.com/yegor256/microstack
crate data-structures rust stack stack-based
Last synced: about 2 months ago
JSON representation
The most primitive and the fastest implementation of a fixed-size last-in-first-out stack on stack in Rust, for Copy-implementing types
- Host: GitHub
- URL: https://github.com/yegor256/microstack
- Owner: yegor256
- License: mit
- Created: 2023-05-06T05:01:47.000Z (over 1 year ago)
- Default Branch: master
- Last Pushed: 2024-10-22T19:29:37.000Z (2 months ago)
- Last Synced: 2024-10-23T10:22:26.849Z (2 months ago)
- Topics: crate, data-structures, rust, stack, stack-based
- Language: Rust
- Homepage: https://crates.io/crates/microstack
- Size: 102 KB
- Stars: 11
- Watchers: 3
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
[](https://github.com/yegor256/microstack/actions/workflows/cargo.yml)
[](https://crates.io/crates/microstack)
[](https://codecov.io/gh/yegor256/microstack)
[](https://hitsofcode.com/view/github/yegor256/microstack)
[](https://github.com/yegor256/microstack/blob/master/LICENSE.txt)
[](https://docs.rs/microstack/latest/microstack/)
This is the simplest and the fastest (faster than [`Vec`](https://doc.rust-lang.org/std/vec/struct.Vec.html)!) implementation of a
last-in-first-out [stack data structure](https://en.wikipedia.org/wiki/Stack_%28abstract_data_type%29),
on [stack](https://en.wikipedia.org/wiki/Call_stack),
when stack elements are `Copy` implementing primitives.
This is basically a wrapper around an [uninitialized](https://doc.rust-lang.org/nomicon/uninitialized.html) array.
When it is created on stack, its elements contain no specific data.
Then, when you `push_unchecked(x)`, the head of the stack is moved forward
and `x` is placed into the element of the array. When you `pop_unchecked()`,
the head is moved backward and the data is retrieved from the array.
There are no boundary checks, that's why both `push_unchecked()` and `pop_unchecked()` may lead to undefined
behavior. Use `push()` and `pop()`, which are safer, but slower.
For even slower but even safer behavior, you can use `try_push()` and `try_pop()`.
First, add this to `Cargo.toml`:
```toml
[dependencies]
microstack = "0.0.7"
```
Then, use it like this (mind the `unsafe` blocks, they give the fastest performance,
but [undefined behavior](https://doc.rust-lang.org/reference/behavior-considered-undefined.html)
if you go over the stack boundaries):
```rust
use microstack::Stack;
let mut s : Stack<&str, 10> = Stack::new(); // allocation on stack
unsafe { s.push_unchecked("foo") }; // no boundary checks here
unsafe { s.push_unchecked("bar") }; // and here
assert_eq!("bar", unsafe { s.pop_unchecked() }); // and here again
assert_eq!(1, s.len());
```
Pay attention, here the stack is created with an extra
[const generic argument](https://practice.rs/generics-traits/const-generics.html) equal to `10`. This is
the total size of the stack data structure, which is allocated on stack when `::new()` is called.
Read [the API documentation](https://docs.rs/microstack/latest/microstack/).
## How to Contribute
First, install [Rust](https://www.rust-lang.org/tools/install) and then:
```bash
$ cargo test -vv
```
If everything goes well, fork repository, make changes, send us a [pull request](https://www.yegor256.com/2014/04/15/github-guidelines.html).
We will review your changes and apply them to the `master` branch shortly,
provided they don't violate our quality standards. To avoid frustration,
before sending us your pull request please run `cargo test` again. Also,
run `cargo fmt` and `cargo clippy`.
Also, before you start making changes, run benchmarks:
```bash
$ rustup run nightly cargo bench
```
Then, after the changes you make, run it again. Compare the results. If your changes
degrade performance, think twice before submitting a pull request.