rec_cell 0.1.0

// This module provides simple wrappers around (&RecCell, &[mut] RecToken)
// pairs. Unlike the rather unsafe `GhostCursor`, these cursors do not add any
// new functionality that interacts with the core safety guarantees of RecCell.

use core::{fmt::Debug, marker::PhantomData, ptr::NonNull};

use crate::{RecCell, RecToken, utils::into_ok};

/// Internal sealing trait; downstream crates cannot implement [`CellLike`].
pub trait Sealed {}

/// A cell or collection of cells that a cursor can visit.
///
/// This sealed trait is implemented for `RecCell`, slices of cells, and arrays
/// of cells. It enables [`Cursor::map`] and related methods to move between
/// those shapes while retaining the token borrow.
pub trait CellLike<'t>: Sealed {
    /// The read-only cursor for this cell shape.
    type Cursor<'a>
    where
        't: 'a,
        Self: 'a;
    /// The mutable cursor for this cell shape.
    type CursorMut<'a>
    where
        't: 'a,
        Self: 'a;

    /// Creates a read-only cursor while borrowing `token` immutably.
    fn as_cursor<'a>(&'a self, token: &'a RecToken<'t>) -> Self::Cursor<'a>;
    /// Creates a mutable cursor while borrowing `token` mutably.
    fn as_cursor_mut<'a>(&'a self, token: &'a mut RecToken<'t>) -> Self::CursorMut<'a>;
}

impl<T> Sealed for RecCell<'_, T> {}

impl<'t, T> CellLike<'t> for RecCell<'t, T> {
    type Cursor<'a>
        = Cursor<'a, 't, T>
    where
        't: 'a,
        Self: 'a;
    type CursorMut<'a>
        = CursorMut<'a, 't, T>
    where
        't: 'a,
        Self: 'a;

    fn as_cursor<'a>(&'a self, token: &'a RecToken<'t>) -> Cursor<'a, 't, T> {
        self.cursor(token)
    }

    fn as_cursor_mut<'a>(&'a self, token: &'a mut RecToken<'t>) -> CursorMut<'a, 't, T> {
        self.cursor_mut(token)
    }
}

impl<T> Sealed for [RecCell<'_, T>] {}

impl<'t, T> CellLike<'t> for [RecCell<'t, T>] {
    type Cursor<'a>
        = SliceCursor<'a, 't, T>
    where
        't: 'a,
        Self: 'a;
    type CursorMut<'a>
        = SliceCursorMut<'a, 't, T>
    where
        't: 'a,
        Self: 'a;

    fn as_cursor<'a>(&'a self, token: &'a RecToken<'t>) -> Self::Cursor<'a> {
        SliceCursor::new(self, token)
    }

    fn as_cursor_mut<'a>(&'a self, token: &'a mut RecToken<'t>) -> Self::CursorMut<'a> {
        SliceCursorMut::new(self, token)
    }
}

impl<T, const N: usize> Sealed for [RecCell<'_, T>; N] {}

impl<'t, T, const N: usize> CellLike<'t> for [RecCell<'t, T>; N] {
    type Cursor<'a>
        = Cursor<'a, 't, [T; N]>
    where
        't: 'a,
        Self: 'a;
    type CursorMut<'a>
        = CursorMut<'a, 't, [T; N]>
    where
        't: 'a,
        Self: 'a;

    fn as_cursor<'a>(&'a self, token: &'a RecToken<'t>) -> Self::Cursor<'a> {
        RecCell::from_array_of_cells(self).cursor(token)
    }

    fn as_cursor_mut<'a>(&'a self, token: &'a mut RecToken<'t>) -> Self::CursorMut<'a> {
        RecCell::from_array_of_cells(self).cursor_mut(token)
    }
}

impl<'t, T> RecCell<'t, T> {
    /// Creates a read-only cursor anchored at this cell.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    ///
    /// RecToken::new(|token| {
    ///     let cell = RecCell::new(7);
    ///     let cursor = cell.cursor(&token);
    ///     assert_eq!(cursor.get(), &7);
    ///     let (cell, token) = cursor.into_inner();
    ///     assert_eq!(cell.borrow(token), &7);
    /// });
    /// ```
    pub const fn cursor<'a>(&'a self, token: &'a RecToken<'t>) -> Cursor<'a, 't, T> {
        Cursor {
            cell: self,
            token: RecTokenRef::new(token),
        }
    }

    /// Creates a mutable cursor anchored at this cell.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    ///
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(7);
    ///     let mut cursor = cell.cursor_mut(&mut token);
    ///     assert_eq!(cursor.get(), &7);
    ///     *cursor.get_mut() = 8;
    ///     assert_eq!(cursor.replace(9), 8);
    ///     assert_eq!(cursor.take(), 9);
    ///     let (cell, token) = cursor.into_inner();
    ///     assert_eq!(cell.borrow(token), &0);
    /// });
    /// ```
    pub const fn cursor_mut<'a>(&'a self, token: &'a mut RecToken<'t>) -> CursorMut<'a, 't, T> {
        CursorMut {
            cell: self,
            token: RecTokenMut::new(token),
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
struct RecTokenRef<'a, 't>(PhantomData<&'a RecToken<'t>>);

impl Debug for RecTokenRef<'_, '_> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        Debug::fmt(self.get(), f)
    }
}

impl<'a, 't> RecTokenRef<'a, 't> {
    const fn new(_: &'a RecToken<'t>) -> Self {
        Self(PhantomData)
    }
    #[allow(clippy::unused_self, clippy::trivially_copy_pass_by_ref)]
    const fn get(&self) -> &RecToken<'t> {
        // SAFETY: `RecToken` is a ZST; the phantom borrow carries the real lifetime.
        unsafe { NonNull::dangling().as_ref() }
    }
    #[allow(clippy::unused_self)]
    const fn into_inner(self) -> &'a RecToken<'t> {
        // SAFETY: `RecToken` is a ZST; the phantom borrow carries the real lifetime.
        unsafe { NonNull::dangling().as_ref() }
    }
}

#[derive(PartialEq, Eq, PartialOrd, Ord)]
struct RecTokenMut<'a, 't>(PhantomData<&'a mut RecToken<'t>>);

impl Debug for RecTokenMut<'_, '_> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        Debug::fmt(self.get(), f)
    }
}

impl<'a, 't> RecTokenMut<'a, 't> {
    const fn new(_: &'a mut RecToken<'t>) -> Self {
        Self(PhantomData)
    }
    #[allow(clippy::unused_self)]
    const fn get(&self) -> &RecToken<'t> {
        // SAFETY: `RecToken` is a ZST; the phantom borrow carries the real lifetime.
        unsafe { NonNull::dangling().as_ref() }
    }
    #[allow(clippy::unused_self)]
    const fn get_mut(&mut self) -> &mut RecToken<'t> {
        // SAFETY: `RecToken` is a ZST; the phantom borrow carries the real lifetime.
        unsafe { NonNull::dangling().as_mut() }
    }
    #[allow(clippy::unused_self)]
    const fn into_inner(self) -> &'a mut RecToken<'t> {
        // SAFETY: `RecToken` is a ZST; the phantom borrow carries the real lifetime.
        unsafe { NonNull::dangling().as_mut() }
    }
}

/// A read-only cursor over a [`RecCell`].
///
/// See [`RecCell::cursor`] for details.
pub struct Cursor<'a, 't, T> {
    cell: &'a RecCell<'t, T>,
    token: RecTokenRef<'a, 't>,
}

impl<T> Debug for Cursor<'_, '_, T> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("Cursor")
            .field("cell", &self.cell)
            .field("token", &self.token)
            .finish()
    }
}

impl<'a, 't, T> Cursor<'a, 't, T> {
    /// Returns the anchored cell and the token borrow held by this cursor.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|token| {
    ///     let cell = RecCell::new(1);
    ///     let (cell, token) = cell.cursor(&token).into_inner();
    ///     assert_eq!(cell.borrow(token), &1);
    /// });
    /// ```
    #[must_use]
    pub const fn into_inner(self) -> (&'a RecCell<'t, T>, &'a RecToken<'t>) {
        (self.cell, self.token.into_inner())
    }

    /// Returns the value at the cursor's current cell.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|token| assert_eq!(RecCell::new(1).cursor(&token).get(), &1));
    /// ```
    #[must_use]
    pub const fn get(&self) -> &T {
        self.cell.borrow(self.token.get())
    }

    /// Consumes this cursor and maps its current value to another cell shape.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    ///
    /// struct PointsToNext<'a, 't>(&'a RecCell<'t, i32>);
    /// RecToken::new(|token| {
    ///     let next = RecCell::new(2);
    ///     let cell = RecCell::new(PointsToNext(&next));
    ///     assert_eq!(cell.cursor(&token).map(|next| next.0).get(), &2);
    /// });
    /// ```
    pub fn map<C: CellLike<'t>>(self, f: impl FnOnce(&T) -> &'a C) -> C::Cursor<'a> {
        into_ok(self.try_map(|t| Ok(f(t))))
    }

    /// Fallible version of [`Self::map`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    ///
    /// struct PointsToNext<'a, 't>(Option<&'a RecCell<'t, i32>>);
    /// RecToken::new(|token| {
    ///     let next = RecCell::new(2);
    ///     let cell = RecCell::new(PointsToNext(Some(&next)));
    ///     let mapped = cell.cursor(&token).try_map(|next| next.0.ok_or(()));
    ///     assert_eq!(mapped.unwrap().get(), &2);
    ///
    ///     let cell = RecCell::new(PointsToNext(None));
    ///     let mapped = cell.cursor(&token).try_map(|next| next.0.ok_or(()));
    ///     assert!(mapped.is_err());
    /// });
    /// ```
    pub fn try_map<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&T) -> Result<&'a C, E>,
    ) -> Result<C::Cursor<'a>, E> {
        let (cell, token) = self.into_inner();
        let new_cell = f(cell.borrow(token))?;
        Ok(new_cell.as_cursor(token))
    }

    /// Updates this cursor to a cell selected from its current value.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// use std::mem::MaybeUninit;
    ///
    /// struct PointsToNext<'a, 't>(i32, &'a RecCell<'t, Self>);
    /// RecToken::new(|token| {
    ///     let [mut a, mut b] = [const { MaybeUninit::<PointsToNext>::uninit() }; 2];
    ///     let ([a, b], token) = RecCell::new_cyclic(&mut a, token, |a| {
    ///         let b_value = PointsToNext(20, a);
    ///         let b = RecCell::from_mut(b.write(b_value));
    ///         let a_value = PointsToNext(10, b);
    ///         ([a, b], a_value)
    ///     });
    ///     let mut cursor = a.cursor(&token);
    ///     assert_eq!(cursor.get().0, 10);
    ///
    ///     cursor.update(|v| v.1);
    ///     assert_eq!(cursor.get().0, 20);
    ///     cursor.update(|v| v.1);
    ///     assert_eq!(cursor.get().0, 10);
    /// });
    /// ```
    pub fn update(&mut self, f: impl FnOnce(&T) -> &'a RecCell<'t, T>) {
        into_ok(self.try_update(|t| Ok(f(t))));
    }

    /// Fallible version of [`Self::update`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// use std::mem::MaybeUninit;
    ///
    /// struct PointsToNext<'a, 't>(i32, Option<&'a RecCell<'t, Self>>);
    /// RecToken::new(|token| {
    ///     let [mut a, mut b] = [const { MaybeUninit::<PointsToNext>::uninit() }; 2];
    ///     let b = RecCell::from_mut(b.write(PointsToNext(20, None)));
    ///     let a = RecCell::from_mut(a.write(PointsToNext(10, Some(&b))));
    ///
    ///     let mut cursor = a.cursor(&token);
    ///     assert_eq!(cursor.get().0, 10);
    ///
    ///     cursor.try_update(|v| v.1.ok_or(())).unwrap();
    ///     assert_eq!(cursor.get().0, 20);
    ///
    ///     // A failed update leaves the cursor unchanged.
    ///     cursor.try_update(|v| v.1.ok_or(())).unwrap_err();
    ///     assert_eq!(cursor.get().0, 20);
    /// });
    /// ```
    pub fn try_update<E>(
        &mut self,
        f: impl FnOnce(&T) -> Result<&'a RecCell<'t, T>, E>,
    ) -> Result<(), E> {
        self.cell = f(self.cell.borrow(self.token.get()))?;
        Ok(())
    }

    /// Maps the current cell without borrowing its value.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|token| {
    ///     let cell = RecCell::new(1);
    ///     // Construct a &[RecCell<i32>; 1] from a &RecCell<i32>.
    ///     // This does not require reading the value.
    ///     // The CellLike trait makes the result a cursor on [i32; 1].
    ///     let array_cursor = cell.cursor(&token).map_cell(core::array::from_ref);
    ///     assert_eq!(array_cursor.get(), &[1]);
    /// });
    /// ```
    pub fn map_cell<C: CellLike<'t>>(
        self,
        f: impl FnOnce(&'a RecCell<'t, T>) -> &'a C,
    ) -> C::Cursor<'a> {
        into_ok(self.try_map_cell(|c| Ok(f(c))))
    }

    /// Fallible version of [`Self::map_cell`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|token| {
    ///     let cell = RecCell::new(1);
    ///     let next = RecCell::new(2);
    ///     let cursor = cell.cursor(&token).try_map_cell(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get(), &2);
    /// });
    /// ```
    pub fn try_map_cell<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&'a RecCell<'t, T>) -> Result<&'a C, E>,
    ) -> Result<C::Cursor<'a>, E> {
        let (cell, token) = self.into_inner();
        let new_cell = f(cell)?;
        Ok(new_cell.as_cursor(token))
    }
}

/// A mutable cursor over a [`RecCell`].
///
/// See [`RecCell::cursor_mut`] for details.
pub struct CursorMut<'a, 't, T> {
    cell: &'a RecCell<'t, T>,
    token: RecTokenMut<'a, 't>,
}

impl<T> Debug for CursorMut<'_, '_, T> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("CursorMut")
            .field("cell", &self.cell)
            .field("token", &self.token)
            .finish()
    }
}

impl<'a, 't, T> CursorMut<'a, 't, T> {
    /// Creates a mutable cursor anchored at `cell`.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{CursorMut, RecCell, RecToken};
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(1);
    ///     assert_eq!(cell.cursor_mut(&mut token).get_mut(), &mut 1);
    /// });
    /// ```
    pub const fn new(cell: &'a RecCell<'t, T>, token: &'a mut RecToken<'t>) -> Self {
        Self {
            cell,
            token: RecTokenMut::new(token),
        }
    }

    /// Returns the anchored cell and exclusive token borrow held by this
    /// cursor.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(1);
    ///     let (cell, token) = cell.cursor_mut(&mut token).into_inner();
    ///     assert_eq!(cell.borrow_mut(token), &mut 1);
    /// });
    /// ```
    #[must_use]
    pub const fn into_inner(self) -> (&'a RecCell<'t, T>, &'a mut RecToken<'t>) {
        (self.cell, self.token.into_inner())
    }

    /// Returns the current value immutably.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|mut token| assert_eq!(RecCell::new(1).cursor_mut(&mut token).get(), &1));
    /// ```
    #[must_use]
    pub const fn get(&self) -> &T {
        self.cell.borrow(self.token.get())
    }

    /// Returns the current value mutably.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(1);
    ///     let mut cursor = cell.cursor_mut(&mut token);
    ///     *cursor.get_mut() = 2;
    ///     assert_eq!(cursor.get(), &2);
    /// });
    /// ```
    pub const fn get_mut(&mut self) -> &mut T {
        self.cell.borrow_mut(self.token.get_mut())
    }

    /// Replaces the current value and returns its previous value.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(1);
    ///     let mut cursor = cell.cursor_mut(&mut token);
    ///     assert_eq!(cursor.replace(2), 1);
    ///     assert_eq!(cursor.get_mut(), &mut 2);
    /// });
    /// ```
    pub const fn replace(&mut self, value: T) -> T {
        core::mem::replace(self.get_mut(), value)
    }

    /// Replaces the current value with `T::default()` and returns it.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(1);
    ///     let mut cursor = cell.cursor_mut(&mut token);
    ///     assert_eq!(cursor.take(), 1);
    ///     assert_eq!(cursor.get_mut(), &mut 0);
    /// });
    /// ```
    pub fn take(&mut self) -> T
    where
        T: Default,
    {
        core::mem::take(self.get_mut())
    }

    /// Maps the current mutable value to another cell shape.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    ///
    /// struct PointsToNext<'a, 't>(&'a RecCell<'t, i32>);
    /// RecToken::new(|mut token| {
    ///     let next = RecCell::new(2);
    ///     let cell = RecCell::new(PointsToNext(&next));
    ///     assert_eq!(cell.cursor_mut(&mut token).map(|next| next.0).get_mut(), &mut 2);
    /// });
    /// ```
    pub fn map<C: CellLike<'t>>(self, f: impl FnOnce(&mut T) -> &'a C) -> C::CursorMut<'a> {
        into_ok(self.try_map(|t| Ok(f(t))))
    }

    /// Fallible version of [`Self::map`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    ///
    /// struct PointsToNext<'a, 't>(Option<&'a RecCell<'t, i32>>);
    /// RecToken::new(|mut token| {
    ///     let next = RecCell::new(2);
    ///     let cell = RecCell::new(PointsToNext(Some(&next)));
    ///     let mapped = cell.cursor_mut(&mut token).try_map(|next| next.0.ok_or(()));
    ///     assert_eq!(mapped.unwrap().get_mut(), &mut 2);
    ///
    ///     let cell = RecCell::new(PointsToNext(None));
    ///     let mapped = cell.cursor_mut(&mut token).try_map(|next| next.0.ok_or(()));
    ///     assert!(mapped.is_err());
    /// });
    /// ```
    pub fn try_map<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&mut T) -> Result<&'a C, E>,
    ) -> Result<C::CursorMut<'a>, E> {
        let (cell, token) = self.into_inner();
        let new_cell = f(cell.borrow_mut(token))?;
        Ok(new_cell.as_cursor_mut(token))
    }

    /// Updates this cursor using its current mutable value.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// use std::mem::MaybeUninit;
    ///
    /// struct PointsToNext<'a, 't>(i32, &'a RecCell<'t, Self>);
    /// RecToken::new(|token| {
    ///     let [mut a, mut b] = [const { MaybeUninit::<PointsToNext>::uninit() }; 2];
    ///     let ([a, b], mut token) = RecCell::new_cyclic(&mut a, token, |a| {
    ///         let b_value = PointsToNext(20, a);
    ///         let b = RecCell::from_mut(b.write(b_value));
    ///         let a_value = PointsToNext(10, b);
    ///         ([a, b], a_value)
    ///     });
    ///     let mut cursor = a.cursor_mut(&mut token);
    ///     assert_eq!(cursor.get().0, 10);
    ///
    ///     cursor.update(|v| { v.0 += 1; v.1 });
    ///     assert_eq!(cursor.get().0, 20);
    ///     cursor.update(|v| { v.0 += 2; v.1 });
    ///     assert_eq!(cursor.get().0, 11);
    ///     cursor.update(|v| v.1);
    ///     assert_eq!(cursor.get().0, 22);
    /// });
    /// ```
    pub fn update(&mut self, f: impl FnOnce(&mut T) -> &'a RecCell<'t, T>) {
        into_ok(self.try_update(|t| Ok(f(t))));
    }

    /// Fallible version of [`Self::update`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// use std::mem::MaybeUninit;
    ///
    /// struct PointsToNext<'a, 't>(i32, Option<&'a RecCell<'t, Self>>);
    /// RecToken::new(|mut token| {
    ///     let [mut a, mut b] = [const { MaybeUninit::<PointsToNext>::uninit() }; 2];
    ///     let b = RecCell::from_mut(b.write(PointsToNext(20, None)));
    ///     let a = RecCell::from_mut(a.write(PointsToNext(10, Some(&b))));
    ///
    ///     let mut cursor = a.cursor_mut(&mut token);
    ///     cursor.get_mut().0 += 1;
    ///     assert_eq!(cursor.get().0, 11);
    ///
    ///     cursor.try_update(|v| v.1.ok_or(())).unwrap();
    ///     cursor.get_mut().0 += 1;
    ///     assert_eq!(cursor.get().0, 21);
    ///
    ///     // A failed update leaves the cursor unchanged.
    ///     cursor.try_update(|v| v.1.ok_or(())).unwrap_err();
    ///     cursor.get_mut().0 += 1;
    ///     assert_eq!(cursor.get().0, 22);
    /// });
    /// ```
    pub fn try_update<E>(
        &mut self,
        f: impl FnOnce(&mut T) -> Result<&'a RecCell<'t, T>, E>,
    ) -> Result<(), E> {
        self.cell = f(self.cell.borrow_mut(self.token.get_mut()))?;
        Ok(())
    }

    /// Maps the current cell without borrowing its value.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(1);
    ///     // Construct a &[RecCell<i32>; 1] from a &RecCell<i32>.
    ///     // This does not require reading the value.
    ///     // The CellLike trait makes the result a cursor on [i32; 1].
    ///     let mut array_cursor = cell.cursor_mut(&mut token).map_cell(core::array::from_ref);
    ///     assert_eq!(array_cursor.get_mut(), &mut [1]);
    /// });
    /// ```
    pub fn map_cell<C: CellLike<'t>>(
        self,
        f: impl FnOnce(&'a RecCell<'t, T>) -> &'a C,
    ) -> C::CursorMut<'a> {
        into_ok(self.try_map_cell(|c| Ok(f(c))))
    }

    /// Fallible version of [`Self::map_cell`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken};
    /// RecToken::new(|mut token| {
    ///     let cell = RecCell::new(1); let next = RecCell::new(2);
    ///     let mut cursor = cell.cursor_mut(&mut token).try_map_cell(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get_mut(), &mut 2);
    /// });
    /// ```
    pub fn try_map_cell<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&'a RecCell<'t, T>) -> Result<&'a C, E>,
    ) -> Result<C::CursorMut<'a>, E> {
        let (cell, token) = self.into_inner();
        let new_cell = f(cell)?;
        Ok(new_cell.as_cursor_mut(token))
    }
}

/// A read-only cursor over a slice of [`RecCell`]s.
///
/// # Examples
///
/// ```
/// use rec_cell::{RecCell, RecToken, SliceCursor};
/// RecToken::new(|token| {
///     let cells = [RecCell::new(1), RecCell::new(2)];
///     let cursor = SliceCursor::new(&cells, &token);
///     assert_eq!(cursor.get(), &[1, 2]);
///     let (cells, token) = cursor.into_inner();
///     assert_eq!(RecCell::borrow_slice(cells, token), &[1, 2]);
/// });
/// ```
pub struct SliceCursor<'a, 't, T> {
    cells: &'a [RecCell<'t, T>],
    token: RecTokenRef<'a, 't>,
}

impl<T> Clone for SliceCursor<'_, '_, T> {
    fn clone(&self) -> Self {
        *self
    }
}
impl<T> Copy for SliceCursor<'_, '_, T> {}

impl<T> Debug for SliceCursor<'_, '_, T> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("SliceCursor")
            .field("cells", &self.cells)
            .field("token", &self.token)
            .finish()
    }
}

impl<'a, 't, T> SliceCursor<'a, 't, T> {
    /// Creates a read-only cursor over `cells`.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let cells = [RecCell::new(1)];
    ///     assert_eq!(SliceCursor::new(&cells, &token).get(), &[1]);
    /// });
    /// ```
    pub const fn new(cells: &'a [RecCell<'t, T>], token: &'a RecToken<'t>) -> Self {
        Self {
            cells,
            token: RecTokenRef::new(token),
        }
    }

    /// Returns the cells and token borrow held by this cursor.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let cells = [RecCell::new(1)];
    ///     let (cells, token) = SliceCursor::new(&cells, &token).into_inner();
    ///     assert_eq!(RecCell::borrow_slice(cells, token), &[1]);
    /// });
    /// ```
    #[must_use]
    pub const fn into_inner(self) -> (&'a [RecCell<'t, T>], &'a RecToken<'t>) {
        (self.cells, self.token.into_inner())
    }

    /// Returns the current slice of values.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let cells = [RecCell::new(1)];
    ///     assert_eq!(SliceCursor::new(&cells, &token).get(), &[1]);
    /// });
    /// ```
    #[must_use]
    pub const fn get(&self) -> &[T] {
        RecCell::borrow_slice(self.cells, self.token.get())
    }

    /// Maps the current slice to another cell shape.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let cells = [RecCell::new(1)]; let next = RecCell::new(2);
    ///     assert_eq!(SliceCursor::new(&cells, &token).map(|_| &next).get(), &2);
    /// });
    /// ```
    pub fn map<C: CellLike<'t>>(self, f: impl FnOnce(&[T]) -> &'a C) -> C::Cursor<'a> {
        into_ok(self.try_map(|values| Ok(f(values))))
    }

    /// Fallible version of [`Self::map`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let cells = [RecCell::new(1)]; let next = RecCell::new(2);
    ///     let cursor = SliceCursor::new(&cells, &token).try_map(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get(), &2);
    /// });
    /// ```
    pub fn try_map<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&[T]) -> Result<&'a C, E>,
    ) -> Result<C::Cursor<'a>, E> {
        let (cells, token) = self.into_inner();
        let new_cell = f(RecCell::borrow_slice(cells, token))?;
        Ok(new_cell.as_cursor(token))
    }

    /// Updates this cursor to a slice selected from its current values.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let first = [RecCell::new(1)]; let next = [RecCell::new(2)];
    ///     let mut cursor = SliceCursor::new(&first, &token);
    ///     cursor.update(|_| &next);
    ///     assert_eq!(cursor.get(), &[2]);
    /// });
    /// ```
    pub fn update(&mut self, f: impl FnOnce(&[T]) -> &'a [RecCell<'t, T>]) {
        into_ok(self.try_update(|values| Ok(f(values))));
    }

    /// Fallible version of [`Self::update`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let first = [RecCell::new(1)]; let next = [RecCell::new(2)];
    ///     let mut cursor = SliceCursor::new(&first, &token);
    ///     cursor.try_update(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get(), &[2]);
    /// });
    /// ```
    pub fn try_update<E>(
        &mut self,
        f: impl FnOnce(&[T]) -> Result<&'a [RecCell<'t, T>], E>,
    ) -> Result<(), E> {
        self.cells = f(RecCell::borrow_slice(self.cells, self.token.get()))?;
        Ok(())
    }

    /// Maps the current cell slice without borrowing its values.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let cells = [RecCell::new(1), RecCell::new(2)];
    ///     let first_cursor = SliceCursor::new(&cells, &token)
    ///         .map_cell(|cells| &cells[0]);
    ///     assert_eq!(first_cursor.get(), &1);
    /// });
    /// ```
    pub fn map_cell<C: CellLike<'t>>(
        self,
        f: impl FnOnce(&'a [RecCell<'t, T>]) -> &'a C,
    ) -> C::Cursor<'a> {
        into_ok(self.try_map_cell(|cells| Ok(f(cells))))
    }

    /// Fallible version of [`Self::map_cell`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursor};
    /// RecToken::new(|token| {
    ///     let cells = [RecCell::new(1)]; let next = RecCell::new(2);
    ///     let cursor = SliceCursor::new(&cells, &token).try_map_cell(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get(), &2);
    /// });
    /// ```
    pub fn try_map_cell<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&'a [RecCell<'t, T>]) -> Result<&'a C, E>,
    ) -> Result<C::Cursor<'a>, E> {
        let (cells, token) = self.into_inner();
        let new_cell = f(cells)?;
        Ok(new_cell.as_cursor(token))
    }
}

/// A mutable cursor over a slice of [`RecCell`]s.
///
/// # Examples
///
/// ```
/// use rec_cell::{RecCell, RecToken, SliceCursorMut};
/// RecToken::new(|mut token| {
///     let cells = [RecCell::new(1), RecCell::new(2)];
///     let mut cursor = SliceCursorMut::new(&cells, &mut token);
///     cursor.get_mut()[0] = 3;
///     assert_eq!(cursor.get(), &[3, 2]);
///     let (cells, token) = cursor.into_inner();
///     assert_eq!(RecCell::borrow_slice(cells, token), &[3, 2]);
/// });
/// ```
pub struct SliceCursorMut<'a, 't, T> {
    cells: &'a [RecCell<'t, T>],
    token: RecTokenMut<'a, 't>,
}

impl<T> Debug for SliceCursorMut<'_, '_, T> {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("SliceCursorMut")
            .field("cells", &self.cells)
            .field("token", &self.token)
            .finish()
    }
}

impl<'a, 't, T> SliceCursorMut<'a, 't, T> {
    /// Creates a mutable cursor over `cells`.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1)];
    ///     assert_eq!(SliceCursorMut::new(&cells, &mut token).get(), &[1]);
    /// });
    /// ```
    pub const fn new(cells: &'a [RecCell<'t, T>], token: &'a mut RecToken<'t>) -> Self {
        Self {
            cells,
            token: RecTokenMut::new(token),
        }
    }

    /// Returns the cells and exclusive token borrow held by this cursor.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1)];
    ///     let (cells, token) = SliceCursorMut::new(&cells, &mut token).into_inner();
    ///     assert_eq!(RecCell::borrow_slice(cells, token), &[1]);
    /// });
    /// ```
    #[must_use]
    pub const fn into_inner(self) -> (&'a [RecCell<'t, T>], &'a mut RecToken<'t>) {
        (self.cells, self.token.into_inner())
    }

    /// Returns the current slice immutably.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1)];
    ///     assert_eq!(SliceCursorMut::new(&cells, &mut token).get(), &[1]);
    /// });
    /// ```
    #[must_use]
    pub const fn get(&self) -> &[T] {
        RecCell::borrow_slice(self.cells, self.token.get())
    }

    /// Returns the current slice mutably.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1)]; let mut cursor = SliceCursorMut::new(&cells, &mut token);
    ///     cursor.get_mut()[0] = 2;
    ///     assert_eq!(cursor.get(), &[2]);
    /// });
    /// ```
    pub const fn get_mut(&mut self) -> &mut [T] {
        RecCell::borrow_slice_mut(self.cells, self.token.get_mut())
    }

    /// Maps the current mutable slice to another cell shape.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1)]; let next = RecCell::new(2);
    ///     assert_eq!(SliceCursorMut::new(&cells, &mut token).map(|_| &next).get(), &2);
    /// });
    /// ```
    pub fn map<C: CellLike<'t>>(self, f: impl FnOnce(&mut [T]) -> &'a C) -> C::CursorMut<'a> {
        into_ok(self.try_map(|values| Ok(f(values))))
    }

    /// Fallible version of [`Self::map`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1)]; let next = RecCell::new(2);
    ///     let cursor = SliceCursorMut::new(&cells, &mut token).try_map(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get(), &2);
    /// });
    /// ```
    pub fn try_map<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&mut [T]) -> Result<&'a C, E>,
    ) -> Result<C::CursorMut<'a>, E> {
        let (cells, token) = self.into_inner();
        let new_cell = f(RecCell::borrow_slice_mut(cells, token))?;
        Ok(new_cell.as_cursor_mut(token))
    }

    /// Updates this cursor using its current mutable values.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let first = [RecCell::new(1)]; let next = [RecCell::new(2)];
    ///     let mut cursor = SliceCursorMut::new(&first, &mut token);
    ///     cursor.update(|_| &next);
    ///     assert_eq!(cursor.get(), &[2]);
    /// });
    /// ```
    pub fn update(&mut self, f: impl FnOnce(&mut [T]) -> &'a [RecCell<'t, T>]) {
        into_ok(self.try_update(|values| Ok(f(values))));
    }

    /// Fallible version of [`Self::update`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let first = [RecCell::new(1)]; let next = [RecCell::new(2)];
    ///     let mut cursor = SliceCursorMut::new(&first, &mut token);
    ///     cursor.try_update(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get(), &[2]);
    /// });
    /// ```
    pub fn try_update<E>(
        &mut self,
        f: impl FnOnce(&mut [T]) -> Result<&'a [RecCell<'t, T>], E>,
    ) -> Result<(), E> {
        self.cells = f(RecCell::borrow_slice_mut(self.cells, self.token.get_mut()))?;
        Ok(())
    }

    /// Maps the current cell slice without borrowing its values.
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1), RecCell::new(2)];
    ///     let mut first_cursor = SliceCursorMut::new(&cells, &mut token)
    ///         .map_cell(|cells| &cells[0]);
    ///     assert_eq!(first_cursor.get_mut(), &mut 1);
    /// });
    /// ```
    pub fn map_cell<C: CellLike<'t>>(
        self,
        f: impl FnOnce(&'a [RecCell<'t, T>]) -> &'a C,
    ) -> C::CursorMut<'a> {
        into_ok(self.try_map_cell(|cells| Ok(f(cells))))
    }

    /// Fallible version of [`Self::map_cell`].
    ///
    /// # Examples
    ///
    /// ```
    /// use rec_cell::{RecCell, RecToken, SliceCursorMut};
    /// RecToken::new(|mut token| {
    ///     let cells = [RecCell::new(1)]; let next = RecCell::new(2);
    ///     let cursor = SliceCursorMut::new(&cells, &mut token).try_map_cell(|_| Ok::<_, ()>(&next)).unwrap();
    ///     assert_eq!(cursor.get(), &2);
    /// });
    /// ```
    pub fn try_map_cell<C: CellLike<'t>, E>(
        self,
        f: impl FnOnce(&'a [RecCell<'t, T>]) -> Result<&'a C, E>,
    ) -> Result<C::CursorMut<'a>, E> {
        let (cells, token) = self.into_inner();
        let new_cell = f(cells)?;
        Ok(new_cell.as_cursor_mut(token))
    }
}