README.md
1# Inplace it!
2
3[](https://crates.io/crates/inplace_it)
4[](https://github.com/NotIntMan/inplace_it/blob/master/LICENSE.txt)
5[](https://github.com/NotIntMan/inplace_it/actions)
6
7Place small arrays on the stack with a low cost!
8
9The only price you should pay for this is the price of choosing
10a type based on the size of the requested array! This is just one `match` and `call`!
11
12## What?
13
14This crate is created for one purpose: allocating small arrays on the stack.
15The simplest way to use it is:
16
17```rust
18use inplace_it::{inplace_or_alloc_array, UninitializedSliceMemoryGuard};
19
20inplace_or_alloc_array(
21 150, // size of needed array to allocate
22 |mut uninit_guard: UninitializedSliceMemoryGuard<u16>| { // and this is consumer of uninitialized memory
23 assert_eq!(160, uninit_guard.len());
24
25 {
26 // You can borrow guard to reuse memory
27 let borrowed_uninit_guard = uninit_guard.borrow();
28 // Let's initialize memory
29 // Note that borrowed_uninit_guard will be consumed (destroyed to produce initialized memory guard)
30 let init_guard = borrowed_uninit_guard.init(|index| index as u16 + 1);
31 // Memory now contains elements [1, 2, ..., 160]
32 // Lets check it. Sum of [1, 2, ..., 160] = 12880
33 let sum: u16 = init_guard.iter().sum();
34 assert_eq!(sum, 12880);
35 }
36
37 {
38 // If you don't want to reuse memory, you can init new guard directly
39 let init_guard = uninit_guard.init(|index| index as u16 * 2);
40 // Memory now contains elements [0, 2, 4, ..., 318]
41 // Lets check it. Sum of [0, 2, 4, ..., 318] = 25440
42 let sum: u16 = init_guard.iter().sum();
43 assert_eq!(sum, 25440);
44 }
45 }
46)
47```
48
49## Why?
50
51Because allocation on the stack (i.e. placing variables) is **MUCH FASTER** then usual
52allocating in the heap.
53
54## Moar!
55
56You can read the [API reference](https://docs.rs/inplace_it) for more details
57or create an [new issue](https://github.com/NotIntMan/inplace_it/issues/new)
58to submit a bug, feature request or just ask a question.
59
60## Release notes
61
62### 0.3.3
63* Some sugar for easy placing from `Iterator`'s.
64
65### 0.3.2
66* Placing of uninit memory moved out from `try_inplace_array` to disallow compiler to optimize it.
67
68### 0.3.1
69* Initialize with an exact-size iterator.
70
71### 0.3.0
72* API safety. No more unsafe external functions.
73* Drop correctness. No more dropping of uninitialized memory.
74
75### 0.2.2
76* Fixed drop-correctness for safe functions. Now unsafe function do not drop your data but safe function do it correctly.
77
){kind=link}
){kind=link}
){kind=link}