semisafe 1.0.1

Semi-safe utilities for performance-critical Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

//! Provides semi-safe helpers for the `slice` type.

use std::slice::SliceIndex;

/// Returns element or subslice at `index` without bounds checks in release
/// builds.
///
/// Use this only when surrounding code guarantees that `index` selects a valid
/// in-bounds region of `arr`. In debug builds this delegates to [`slice::get`]
/// and panics on invalid indexes or ranges. In release builds, violating that
/// precondition causes undefined behavior.
///
/// # Panics
///
/// Panics in debug builds if `index` is out of bounds for `arr`.
///
/// # Examples
///
/// ```
/// let values = [10, 20, 30];
/// let value = semisafe::slice::get(&values, 1);
/// assert_eq!(*value, 20);
/// ```
#[inline(always)]
pub fn get<T, I: SliceIndex<[T]>>(arr: &[T], index: I) -> &<I as SliceIndex<[T]>>::Output {
    #[cfg(debug_assertions)]
    {
        arr.get(index).expect("array index out of bounds")
    }

    #[cfg(not(debug_assertions))]
    {
        unsafe { arr.get_unchecked(index) }
    }
}

/// Returns mutable element or subslice at `index` without bounds checks in
/// release builds.
///
/// Use this only when surrounding code guarantees that `index` selects a valid
/// in-bounds region of `arr`. In debug builds this delegates to
/// [`slice::get_mut`] and panics on invalid indexes or ranges. In release
/// builds, violating that precondition causes undefined behavior.
///
/// # Panics
///
/// Panics in debug builds if `index` is out of bounds for `arr`.
///
/// # Examples
///
/// ```
/// let mut values = [10, 20, 30];
/// *semisafe::slice::get_mut(&mut values, 1) = 99;
/// assert_eq!(values, [10, 99, 30]);
/// ```
#[inline(always)]
pub fn get_mut<T, I: SliceIndex<[T]>>(
    arr: &mut [T],
    index: I,
) -> &mut <I as SliceIndex<[T]>>::Output {
    #[cfg(debug_assertions)]
    {
        arr.get_mut(index).expect("array index out of bounds")
    }

    #[cfg(not(debug_assertions))]
    {
        unsafe { arr.get_unchecked_mut(index) }
    }
}

/// Splits `arr` at `index` without bounds checks in release builds.
///
/// Use this only when surrounding code guarantees that `index <= arr.len()`.
/// In debug builds this delegates to [`slice::split_at`] and panics when index
/// is out of bounds. In release builds, violating that precondition causes
/// undefined behavior.
///
/// # Panics
///
/// Panics in debug builds if `index > arr.len()`.
///
/// # Examples
///
/// ```
/// let values = [1, 2, 3, 4];
/// let (left, right) = semisafe::slice::split_at(&values, 2);
/// assert_eq!(left, &[1, 2]);
/// assert_eq!(right, &[3, 4]);
/// ```
#[inline(always)]
pub const fn split_at<T>(arr: &[T], index: usize) -> (&[T], &[T]) {
    #[cfg(debug_assertions)]
    {
        arr.split_at(index)
    }

    #[cfg(not(debug_assertions))]
    {
        unsafe { arr.split_at_unchecked(index) }
    }
}

/// Splits `arr` at `index` into two mutable slices without bounds checks in
/// release builds.
///
/// Use this only when surrounding code guarantees that `index <= arr.len()`.
/// In debug builds this delegates to [`slice::split_at_mut`] and panics when
/// index is out of bounds. In release builds, violating that precondition
/// causes undefined behavior.
///
/// # Panics
///
/// Panics in debug builds if `index > arr.len()`.
///
/// # Examples
///
/// ```
/// let mut values = [1, 2, 3, 4];
/// let (left, right) = semisafe::slice::split_at_mut(&mut values, 2);
/// left[0] = 10;
/// right[0] = 30;
/// assert_eq!(values, [10, 2, 30, 4]);
/// ```
#[inline(always)]
pub const fn split_at_mut<T>(arr: &mut [T], index: usize) -> (&mut [T], &mut [T]) {
    #[cfg(debug_assertions)]
    {
        arr.split_at_mut(index)
    }

    #[cfg(not(debug_assertions))]
    {
        unsafe { arr.split_at_mut_unchecked(index) }
    }
}

/// Copies all elements from `src` into `dest`, using a memcpy.
///
/// The length of `src` must be the same as `dest`.
///
/// # Panics
///
/// This function will panic in debug builds if the two slices have different lengths.
///
/// # Examples
///
/// ```
/// let src = [1, 2, 3, 4];
/// let mut dest = [0, 0, 0, 0];
/// semisafe::slice::copy(&src, &mut dest);
/// assert_eq!(src, dest);
/// ```
pub const fn copy<T: Copy>(src: &[T], dest: &mut [T]) {
    #[cfg(debug_assertions)]
    {
        dest.copy_from_slice(src);
    }

    #[cfg(not(debug_assertions))]
    {
        unsafe { core::ptr::copy_nonoverlapping(src.as_ptr(), dest.as_mut_ptr(), src.len()) }
    }
}