ggmath 0.17.1

A linear algebra library for games and graphics with generic SIMD types.
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

use core::mem::{ManuallyDrop, transmute, transmute_copy};

/// Variant of [`transmute`] that checks memory-layout compatibility at runtime
/// instead of at compile time.
///
/// This makes it possible to transmute between generic types and dependently
/// sized types.
///
/// # Safety
///
/// Exactly like [`transmute`].
///
/// [`transmute`]: core::mem::transmute
#[inline]
#[track_caller]
pub const unsafe fn transmute_generic<T, U>(value: T) -> U {
    assert!(size_of::<T>() == size_of::<U>());

    // SAFETY: The caller must ensure that the bits of the input are valid for
    // the output type.
    unsafe { transmute_copy::<ManuallyDrop<T>, U>(&ManuallyDrop::new(value)) }
}

/// Transmutes a reference to a reference of a different type.
///
/// # Safety
///
/// Exactly like [`transmute`] for references, except that here immediate size
/// and alignment validity is automatically checked, and the lifetime of the
/// reference cannot be accidently changed.
///
/// [`transmute`]: core::mem::transmute
#[inline]
#[track_caller]
pub const unsafe fn transmute_ref<T, U>(value: &T) -> &U {
    assert!(size_of::<T>() >= size_of::<U>());
    assert!(align_of::<T>() >= align_of::<U>());

    // SAFETY: The output size was just checked to be no more than the input
    // size, the output alignment was just checked to be no more than the input
    // alignment, the lifetimes match because of the function signature, and the
    // caller must ensure that the bits of the input value are valid for the
    // output type.
    unsafe { transmute::<&T, &U>(value) }
}

/// Transmutes a mutable reference to a mutable reference of a different type.
///
/// # Safety
///
/// Exactly like [`transmute`] for mutable references, except that here size and
/// alignment validity is automatically checked, and the lifetime cannot be
/// accidently changed.
///
/// [`transmute`]: core::mem::transmute
#[inline]
#[track_caller]
pub const unsafe fn transmute_mut<T, U>(value: &mut T) -> &mut U {
    assert!(size_of::<T>() >= size_of::<U>());
    assert!(align_of::<T>() >= align_of::<U>());

    // SAFETY: The output size was just checked to be no more than the input
    // size, the output alignment was just checked to be no more than the input
    // alignment, the lifetimes match because of the function signature, the
    // input is mutably borrowed until the output reference is dropped, and the
    // caller must ensure that the bits of the input value are valid for the
    // output type.
    unsafe { transmute::<&mut T, &mut U>(value) }
}

#[cfg(test)]
mod tests {
    use crate::utils::{transmute_generic, transmute_mut, transmute_ref};

    #[test]
    fn test_transmute_generic() {
        assert_eq!(unsafe { transmute_generic::<i32, u32>(1984) }, 1984);
    }

    #[test]
    fn test_transmute_ref() {
        assert_eq!(unsafe { transmute_ref::<i32, u32>(&1984) }, &1984);
    }

    #[test]
    fn test_transmute_mut() {
        let mut value = 1984;
        assert_eq!(unsafe { transmute_mut::<i32, u32>(&mut value) }, &mut 1984);
    }
}