semisafe 0.1.0

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

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) }
    }
}