flense 0.1.0

Purpose-oriented lensing
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

use core::marker::PhantomData;

use crate::{
    Field,
    type_lists::{
        ConsSet,
        GetPtr,
        SculptPtr,
        TupleSet,
    },
};

/// Mutable reified lens.
pub struct LensMut<'a, T>
where
    T: TupleSet,
{
    storage: T::ConsPtr,
    _phantom: PhantomData<&'a ()>,
}

impl<'a, T> LensMut<'a, T>
where
    T: TupleSet,
{
    #[inline]
    pub(crate) const fn new(storage: T::ConsPtr) -> Self {
        Self {
            storage,
            _phantom: PhantomData,
        }
    }

    /// Split `self` into two mutable lenses.
    ///
    /// `Lhs` is the tuple of fields that should appear in the left-hand
    /// returned lens; the right-hand lens contains the remaining fields.
    ///
    /// `Indices` is a single tuple-nested list of shrinking-list positions (one
    /// per element of `Lhs`) and should be inferred; pass `_` at the call site.
    #[expect(clippy::type_complexity, reason = "help")]
    #[inline]
    pub fn split<Lhs, Indices>(
        self,
    ) -> (
        LensMut<'a, Lhs>,
        LensMut<
            'a,
            <<T::ConsPtr as SculptPtr<Lhs::ConsPtr, Indices>>::Remainder as ConsSet>::Tuple,
        >,
    )
    where
        Lhs: TupleSet,
        T::ConsPtr: SculptPtr<Lhs::ConsPtr, Indices>,
        <T::ConsPtr as SculptPtr<Lhs::ConsPtr, Indices>>::Remainder: ConsSet<
            Tuple: TupleSet<ConsPtr = <T::ConsPtr as SculptPtr<Lhs::ConsPtr, Indices>>::Remainder>,
        >,
    {
        let (lhs_storage, rem_storage) = self.storage.sculpt_ptr();
        (
            LensMut {
                storage: lhs_storage,
                _phantom: PhantomData,
            },
            LensMut {
                storage: rem_storage,
                _phantom: PhantomData,
            },
        )
    }

    /// Returns a pointer to the first lensed element of a field.
    #[inline]
    pub fn as_ptr<Elt, Index>(&self) -> *const Elt::Type
    where
        Elt: Field + 'static,
        T::ConsPtr: GetPtr<Elt, Index>,
    {
        self.storage.get_ptr().as_ptr()
    }

    /// Returns a mutable pointer to the first lensed element of a field.
    #[inline]
    pub fn as_mut_ptr<Elt, Index>(&mut self) -> *mut Elt::Type
    where
        Elt: Field + 'static,
        T::ConsPtr: GetPtr<Elt, Index>,
    {
        self.storage.get_ptr().as_ptr()
    }

    /// Returns a shared reference to the lensed field.
    #[expect(
        clippy::should_implement_trait,
        reason = "signature is generic over the field type, not interchangeable with `AsRef`"
    )]
    #[inline]
    #[must_use]
    pub fn as_ref<Elt, Index>(&self) -> &Elt::Type
    where
        Elt: Field + 'static,
        T::ConsPtr: GetPtr<Elt, Index>,
    {
        // SAFETY: `Adapter` guarantees the stored pointer is valid for reads
        // of `Elt::Type` and properly aligned. Tying the returned reference
        // to `&self` reborrows the lens shared for the call's lifetime, so
        // no `&mut Elt::Type` can coexist.
        unsafe { &*self.storage.get_ptr().as_ptr() }
    }

    /// Returns a unique reference to the lensed field.
    #[expect(
        clippy::should_implement_trait,
        reason = "signature is generic over the field type, not interchangeable with `AsMut`"
    )]
    #[inline]
    #[must_use]
    pub fn as_mut<Elt, Index>(&mut self) -> &mut Elt::Type
    where
        Elt: Field + 'static,
        T::ConsPtr: GetPtr<Elt, Index>,
    {
        // SAFETY: `Adapter` guarantees the stored pointer is valid for reads
        // and writes of `Elt::Type` and properly aligned. `&mut self`
        // reborrows the lens uniquely for the call's lifetime, so the
        // returned `&mut` cannot alias any other reference reachable through
        // the lens.
        unsafe { &mut *self.storage.get_ptr().as_ptr() }
    }
}