runtime_sized_array/
lib.rs

1//! Provides a variable-length array (VLA), also called variable-sized or runtime-sized.
2//!
3//! It is an array data structure whose length is determined at run time (instead of at compile time).
4//!
5//! The main purpose of VLAs is to simplify programming of numerical algorithms.
6//!
7//! # Note
8//!
9//! Unlike a dynamic array, a VLA cannot change its size, which is determined once,
10//! at the time of creation.
11//! But they may be more comfortable in use than static arrays, whose size must be known at compile time.
12//!
13//! What is more, the VLA, provided by this crate in some cases is more
14//! efficient than [`std::vec::Vec`](std::vec::Vec). That's because of some optimizations and closeness to
15//! c++ arrays, allocated by `malloc`. That's why some methods are unsafe.
16//!
17//! # Examples
18//!
19//! ## Creating arrays
20//!
21//! ```
22//! use runtime_sized_array::Array;
23//!
24//! let arr1: Array<i32> = Array::new(10).expect("cant' create new array");
25//!
26//! let mut vec = vec![1,2,3];
27//! let ptr = vec.as_mut_ptr();
28//! let size = vec.len();
29//! let arr2: Array<i32> = unsafe { Array::from_pointer(ptr, size) };
30//!
31//! let arr3: Array<i32> = vec.into();
32//!
33//! ```
34//!
35//! ## Iterating
36//!
37//! ```
38//! use runtime_sized_array::Array;
39//!
40//! let mut array : Array<i32> = vec![1,2,3].into();
41//!
42//! // mutable iterator
43//! for item in array.iter_mut() {
44//!     *item += 1;
45//! }
46//!
47//! // immutable iterator
48//! for item in array.iter() {
49//!     println!("{item}");
50//! }
51//!
52//! // immutable iterator
53//! for item in &array {
54//!     println!("{item}");
55//! }
56//!
57//! // again mutable iterator
58//! for item in &mut array {
59//!     *item *= 0;
60//! }
61//! ```
62//!
63//! ## Access to elements
64//!
65//! Safe access:
66//!
67//! ```
68//! use runtime_sized_array::Array;
69//!
70//! let mut arr: Array<i32> = vec![1,2,4].into();
71//!
72//! // immutable access
73//! assert_eq!(arr.try_get(1), Some(&2));
74//! assert_eq!(arr.try_get(10), None);
75//!
76//! // mutable access
77//! *arr.try_get_mut(1).unwrap() = 5;
78//! assert_eq!(arr.try_get_mut(10), None);
79//!
80//! // alternative mutable access
81//! assert_eq!(arr.try_set(1, 5), Some(()));
82//! assert_eq!(arr.try_set(10, 4), None);
83//!
84//! // by brackets
85//! arr[0] = 17;
86//! assert_eq!(arr[0], 17);
87//!
88//! ```
89//!
90//! Unsafe access:
91//!
92//! ```
93//! use runtime_sized_array::Array;
94//!
95//! let mut arr: Array<i32> = vec![1,2,4].into();
96//!
97//! // immutable access
98//! unsafe { assert_eq!(arr.get(1), &2) }
99//! // arr.get(10) - undefined behaviour
100//!
101//! unsafe { *arr.get_mut(1) = 2; }
102//! // *arr.get_mut(10) == 4; - undefined behaviour
103//!
104//! // alternative mutable access
105//! unsafe { arr.set(1, 5); }
106//! // arr.set(10, 4); - undefined behaviour
107//!
108//! unsafe {
109//!     *arr.get_mut_ptr(0) = 10;
110//!     assert_eq!(*arr.get_ptr(0), 10)
111//! }
112//!
113//! ```
114//!
115//!
116
117
118
119
120#![feature(ptr_const_cast)]
121#![feature(rustc_attrs)]
122
123mod array;
124mod array_iters;
125mod error;
126
127pub use array::Array;
128pub use array_iters::{Iter, IterMut, IntoIter};
129pub use error::ArrayError;
runtime_sized_array/lib.rs

runtime_sized_array/
lib.rs
