//! Shareable mutable containers.

//!

//! Rust memory safety is based on this rule: Given an object `T`, it is only possible to

//! have one of the following:

//!

//! - Several immutable references (`&T`) to the object (also known as **aliasing**).

//! - One mutable reference (`&mut T`) to the object (also known as **mutability**).

//!

//! This is enforced by the Rust compiler. However, there are situations where this rule is not

//! flexible enough. Sometimes it is required to have multiple references to an object and yet

//! mutate it.

//!

//! Shareable mutable containers exist to permit mutability in a controlled manner, even in the

//! presence of aliasing. [`Cell<T>`], [`RefCell<T>`], and [`OnceCell<T>`] allow doing this in

//! a single-threaded way—they do not implement [`Sync`]. (If you need to do aliasing and

//! mutation among multiple threads, [`Mutex<T>`], [`RwLock<T>`], [`OnceLock<T>`] or [`atomic`]

//! types are the correct data structures to do so).

//!

//! Values of the `Cell<T>`, `RefCell<T>`, and `OnceCell<T>` types may be mutated through shared

//! references (i.e. the common `&T` type), whereas most Rust types can only be mutated through

//! unique (`&mut T`) references. We say these cell types provide 'interior mutability'

//! (mutable via `&T`), in contrast with typical Rust types that exhibit 'inherited mutability'

//! (mutable only via `&mut T`).

//!

//! Cell types come in four flavors: `Cell<T>`, `RefCell<T>`, `OnceCell<T>`, and `LazyCell<T>`.

//! Each provides a different way of providing safe interior mutability.

//!

//! ## `Cell<T>`

//!

//! [`Cell<T>`] implements interior mutability by moving values in and out of the cell. That is, an

//! `&mut T` to the inner value can never be obtained, and the value itself cannot be directly

//! obtained without replacing it with something else. Both of these rules ensure that there is

//! never more than one reference pointing to the inner value. This type provides the following

//! methods:

//!

//!  - For types that implement [`Copy`], the [`get`](Cell::get) method retrieves the current

//!    interior value by duplicating it.

//!  - For types that implement [`Default`], the [`take`](Cell::take) method replaces the current

//!    interior value with [`Default::default()`] and returns the replaced value.

//!  - All types have:

//!    - [`replace`](Cell::replace): replaces the current interior value and returns the replaced

//!      value.

//!    - [`into_inner`](Cell::into_inner): this method consumes the `Cell<T>` and returns the

//!      interior value.

//!    - [`set`](Cell::set): this method replaces the interior value, dropping the replaced value.

//!

//! `Cell<T>` is typically used for more simple types where copying or moving values isn't too

//! resource intensive (e.g. numbers), and should usually be preferred over other cell types when

//! possible. For larger and non-copy types, `RefCell` provides some advantages.

//!

//! ## `RefCell<T>`

//!

//! [`RefCell<T>`] uses Rust's lifetimes to implement "dynamic borrowing", a process whereby one can

//! claim temporary, exclusive, mutable access to the inner value. Borrows for `RefCell<T>`s are

//! tracked at _runtime_, unlike Rust's native reference types which are entirely tracked

//! statically, at compile time.

//!

//! An immutable reference to a `RefCell`'s inner value (`&T`) can be obtained with

//! [`borrow`](`RefCell::borrow`), and a mutable borrow (`&mut T`) can be obtained with

//! [`borrow_mut`](`RefCell::borrow_mut`). When these functions are called, they first verify that

//! Rust's borrow rules will be satisfied: any number of immutable borrows are allowed or a

//! single mutable borrow is allowed, but never both. If a borrow is attempted that would violate

//! these rules, the thread will panic.

//!

//! The corresponding [`Sync`] version of `RefCell<T>` is [`RwLock<T>`].

//!

//! ## `OnceCell<T>`

//!

//! [`OnceCell<T>`] is somewhat of a hybrid of `Cell` and `RefCell` that works for values that

//! typically only need to be set once. This means that a reference `&T` can be obtained without

//! moving or copying the inner value (unlike `Cell`) but also without runtime checks (unlike

//! `RefCell`). However, its value can also not be updated once set unless you have a mutable

//! reference to the `OnceCell`.

//!

//! `OnceCell` provides the following methods:

//!

//! - [`get`](OnceCell::get): obtain a reference to the inner value

//! - [`set`](OnceCell::set): set the inner value if it is unset (returns a `Result`)

//! - [`get_or_init`](OnceCell::get_or_init): return the inner value, initializing it if needed

//! - [`get_mut`](OnceCell::get_mut): provide a mutable reference to the inner value, only available

//!   if you have a mutable reference to the cell itself.

//!

//! The corresponding [`Sync`] version of `OnceCell<T>` is [`OnceLock<T>`].

//!

//! ## `LazyCell<T, F>`

//!

//! A common pattern with OnceCell is, for a given OnceCell, to use the same function on every

//! call to [`OnceCell::get_or_init`] with that cell. This is what is offered by [`LazyCell`],

//! which pairs cells of `T` with functions of `F`, and always calls `F` before it yields `&T`.

//! This happens implicitly by simply attempting to dereference the LazyCell to get its contents,

//! so its use is much more transparent with a place which has been initialized by a constant.

//!

//! More complicated patterns that don't fit this description can be built on `OnceCell<T>` instead.

//!

//! `LazyCell` works by providing an implementation of `impl Deref` that calls the function,

//! so you can just use it by dereference (e.g. `*lazy_cell` or `lazy_cell.deref()`).

//!

//! The corresponding [`Sync`] version of `LazyCell<T, F>` is [`LazyLock<T, F>`].

//!

//! # When to choose interior mutability

//!

//! The more common inherited mutability, where one must have unique access to mutate a value, is

//! one of the key language elements that enables Rust to reason strongly about pointer aliasing,

//! statically preventing crash bugs. Because of that, inherited mutability is preferred, and

//! interior mutability is something of a last resort. Since cell types enable mutation where it

//! would otherwise be disallowed though, there are occasions when interior mutability might be

//! appropriate, or even *must* be used, e.g.

//!

//! * Introducing mutability 'inside' of something immutable

//! * Implementation details of logically-immutable methods.

//! * Mutating implementations of [`Clone`].

//!

//! ## Introducing mutability 'inside' of something immutable

//!

//! Many shared smart pointer types, including [`Rc<T>`] and [`Arc<T>`], provide containers that can

//! be cloned and shared between multiple parties. Because the contained values may be

//! multiply-aliased, they can only be borrowed with `&`, not `&mut`. Without cells it would be

//! impossible to mutate data inside of these smart pointers at all.

//!

//! It's very common then to put a `RefCell<T>` inside shared pointer types to reintroduce

//! mutability:

//!

//! ```

//! use std::cell::{RefCell, RefMut};

//! use std::collections::HashMap;

//! use std::rc::Rc;

//!

//! fn main() {

//!     let shared_map: Rc<RefCell<_>> = Rc::new(RefCell::new(HashMap::new()));

//!     // Create a new block to limit the scope of the dynamic borrow

//!     {

//!         let mut map: RefMut<'_, _> = shared_map.borrow_mut();

//!         map.insert("africa", 92388);

//!         map.insert("kyoto", 11837);

//!         map.insert("piccadilly", 11826);

//!         map.insert("marbles", 38);

//!     }

//!

//!     // Note that if we had not let the previous borrow of the cache fall out

//!     // of scope then the subsequent borrow would cause a dynamic thread panic.

//!     // This is the major hazard of using `RefCell`.

//!     let total: i32 = shared_map.borrow().values().sum();

//!     println!("{total}");

//! }

//! ```

//!

//! Note that this example uses `Rc<T>` and not `Arc<T>`. `RefCell<T>`s are for single-threaded

//! scenarios. Consider using [`RwLock<T>`] or [`Mutex<T>`] if you need shared mutability in a

//! multi-threaded situation.

//!

//! ## Implementation details of logically-immutable methods

//!

//! Occasionally it may be desirable not to expose in an API that there is mutation happening

//! "under the hood". This may be because logically the operation is immutable, but e.g., caching

//! forces the implementation to perform mutation; or because you must employ mutation to implement

//! a trait method that was originally defined to take `&self`.

//!

//! ```

//! # #![allow(dead_code)]

//! use std::cell::OnceCell;

//!

//! struct Graph {

//!     edges: Vec<(i32, i32)>,

//!     span_tree_cache: OnceCell<Vec<(i32, i32)>>

//! }

//!

//! impl Graph {

//!     fn minimum_spanning_tree(&self) -> Vec<(i32, i32)> {

//!         self.span_tree_cache

//!             .get_or_init(|| self.calc_span_tree())

//!             .clone()

//!     }

//!

//!     fn calc_span_tree(&self) -> Vec<(i32, i32)> {

//!         // Expensive computation goes here

//!         vec![]

//!     }

//! }

//! ```

//!

//! ## Mutating implementations of `Clone`

//!

//! This is simply a special - but common - case of the previous: hiding mutability for operations

//! that appear to be immutable. The [`clone`](Clone::clone) method is expected to not change the

//! source value, and is declared to take `&self`, not `&mut self`. Therefore, any mutation that

//! happens in the `clone` method must use cell types. For example, [`Rc<T>`] maintains its

//! reference counts within a `Cell<T>`.

//!

//! ```

//! use std::cell::Cell;

//! use std::ptr::NonNull;

//! use std::process::abort;

//! use std::marker::PhantomData;

//!

//! struct Rc<T: ?Sized> {

//!     ptr: NonNull<RcInner<T>>,

//!     phantom: PhantomData<RcInner<T>>,

//! }

//!

//! struct RcInner<T: ?Sized> {

//!     strong: Cell<usize>,

//!     refcount: Cell<usize>,

//!     value: T,

//! }

//!

//! impl<T: ?Sized> Clone for Rc<T> {

//!     fn clone(&self) -> Rc<T> {

//!         self.inc_strong();

//!         Rc {

//!             ptr: self.ptr,

//!             phantom: PhantomData,

//!         }

//!     }

//! }

//!

//! trait RcInnerPtr<T: ?Sized> {

//!

//!     fn inner(&self) -> &RcInner<T>;

//!

//!     fn strong(&self) -> usize {

//!         self.inner().strong.get()

//!     }

//!

//!     fn inc_strong(&self) {

//!         self.inner()

//!             .strong

//!             .set(self.strong()

//!                      .checked_add(1)

//!                      .unwrap_or_else(|| abort() ));

//!     }

//! }

//!

//! impl<T: ?Sized> RcInnerPtr<T> for Rc<T> {

//!    fn inner(&self) -> &RcInner<T> {

//!        unsafe {

//!            self.ptr.as_ref()

//!        }

//!    }

//! }

//! ```

//!

//! [`Arc<T>`]: ../../std/sync/struct.Arc.html

//! [`Rc<T>`]: ../../std/rc/struct.Rc.html

//! [`RwLock<T>`]: ../../std/sync/struct.RwLock.html

//! [`Mutex<T>`]: ../../std/sync/struct.Mutex.html

//! [`OnceLock<T>`]: ../../std/sync/struct.OnceLock.html

//! [`LazyLock<T, F>`]: ../../std/sync/struct.LazyLock.html

//! [`Sync`]: ../../std/marker/trait.Sync.html

//! [`atomic`]: crate::sync::atomic

#![stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

use crate::cmp::Ordering;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::fmt::{self, Debug, Display};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::marker::{PhantomData, Unsize};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::mem;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::ops::{CoerceUnsized, Deref, DerefMut, DerefPure, DispatchFromDyn};

#[cfg(not(feature = "ferrocene_certified"))]

use crate::panic::const_panic;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::pin::PinCoerceUnsized;

#[cfg(not(feature = "ferrocene_certified"))]

use crate::ptr::{self, NonNull};

#[cfg(not(feature = "ferrocene_certified"))]

mod lazy;

#[cfg(not(feature = "ferrocene_certified"))]

mod once;

#[stable(feature = "lazy_cell", since = "1.80.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub use lazy::LazyCell;

#[stable(feature = "once_cell", since = "1.70.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub use once::OnceCell;

/// A mutable memory location.

///

/// # Memory layout

///

/// `Cell<T>` has the same [memory layout and caveats as

/// `UnsafeCell<T>`](UnsafeCell#memory-layout). In particular, this means that

/// `Cell<T>` has the same in-memory representation as its inner type `T`.

///

/// # Examples

///

/// In this example, you can see that `Cell<T>` enables mutation inside an

/// immutable struct. In other words, it enables "interior mutability".

///

/// ```

/// use std::cell::Cell;

///

/// struct SomeStruct {

///     regular_field: u8,

///     special_field: Cell<u8>,

/// }

///

/// let my_struct = SomeStruct {

///     regular_field: 0,

///     special_field: Cell::new(1),

/// };

///

/// let new_value = 100;

///

/// // ERROR: `my_struct` is immutable

/// // my_struct.regular_field = new_value;

///

/// // WORKS: although `my_struct` is immutable, `special_field` is a `Cell`,

/// // which can always be mutated

/// my_struct.special_field.set(new_value);

/// assert_eq!(my_struct.special_field.get(), new_value);

/// ```

///

/// See the [module-level documentation](self) for more.

#[rustc_diagnostic_item = "Cell"]

#[stable(feature = "rust1", since = "1.0.0")]

#[repr(transparent)]

#[rustc_pub_transparent]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct Cell<T: ?Sized> {

    value: UnsafeCell<T>,

}

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

unsafe impl<T: ?Sized> Send for Cell<T> where T: Send {}

// Note that this negative impl isn't strictly necessary for correctness,

// as `Cell` wraps `UnsafeCell`, which is itself `!Sync`.

// However, given how important `Cell`'s `!Sync`-ness is,

// having an explicit negative impl is nice for documentation purposes

// and results in nicer error messages.

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: ?Sized> !Sync for Cell<T> {}

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: Copy> Clone for Cell<T> {

    #[inline]

    fn clone(&self) -> Cell<T> {

        Cell::new(self.get())

    }

}

#[stable(feature = "rust1", since = "1.0.0")]

#[rustc_const_unstable(feature = "const_default", issue = "143894")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: [const] Default> const Default for Cell<T> {

    /// Creates a `Cell<T>`, with the `Default` value for T.

    #[inline]

    fn default() -> Cell<T> {

        Cell::new(Default::default())

    }

}

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: PartialEq + Copy> PartialEq for Cell<T> {

    #[inline]

    fn eq(&self, other: &Cell<T>) -> bool {

        self.get() == other.get()

    }

}

#[stable(feature = "cell_eq", since = "1.2.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: Eq + Copy> Eq for Cell<T> {}

#[stable(feature = "cell_ord", since = "1.10.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: PartialOrd + Copy> PartialOrd for Cell<T> {

    #[inline]

    fn partial_cmp(&self, other: &Cell<T>) -> Option<Ordering> {

        self.get().partial_cmp(&other.get())

    }

    #[inline]

    fn lt(&self, other: &Cell<T>) -> bool {

        self.get() < other.get()

    }

    #[inline]

    fn le(&self, other: &Cell<T>) -> bool {

        self.get() <= other.get()

    }

    #[inline]

    fn gt(&self, other: &Cell<T>) -> bool {

        self.get() > other.get()

    }

    #[inline]

    fn ge(&self, other: &Cell<T>) -> bool {

        self.get() >= other.get()

    }

}

#[stable(feature = "cell_ord", since = "1.10.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: Ord + Copy> Ord for Cell<T> {

    #[inline]

    fn cmp(&self, other: &Cell<T>) -> Ordering {

        self.get().cmp(&other.get())

    }

}

#[stable(feature = "cell_from", since = "1.12.0")]

#[rustc_const_unstable(feature = "const_convert", issue = "143773")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T> const From<T> for Cell<T> {

    /// Creates a new `Cell<T>` containing the given value.

    fn from(t: T) -> Cell<T> {

        Cell::new(t)

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T> Cell<T> {

    /// Creates a new `Cell` containing the given value.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c = Cell::new(5);

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_cell_new", since = "1.24.0")]

    #[inline]

    /// Sets the contained value.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c = Cell::new(5);

    ///

    /// c.set(10);

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    /// Swaps the values of two `Cell`s.

    ///

    /// The difference with `std::mem::swap` is that this function doesn't

    /// require a `&mut` reference.

    ///

    /// # Panics

    ///

    /// This function will panic if `self` and `other` are different `Cell`s that partially overlap.

    /// (Using just standard library methods, it is impossible to create such partially overlapping `Cell`s.

    /// However, unsafe code is allowed to e.g. create two `&Cell<[i32; 2]>` that partially overlap.)

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c1 = Cell::new(5i32);

    /// let c2 = Cell::new(10i32);

    /// c1.swap(&c2);

    /// assert_eq!(10, c1.get());

    /// assert_eq!(5, c2.get());

    /// ```

    #[inline]

    #[stable(feature = "move_cell", since = "1.17.0")]

    pub fn swap(&self, other: &Self) {

        // This function documents that it *will* panic, and intrinsics::is_nonoverlapping doesn't

        // do the check in const, so trying to use it here would be inviting unnecessary fragility.

        fn is_nonoverlapping<T>(src: *const T, dst: *const T) -> bool {

            let src_usize = src.addr();

            let dst_usize = dst.addr();

            let diff = src_usize.abs_diff(dst_usize);

            diff >= size_of::<T>()

        }

        if ptr::eq(self, other) {

            // Swapping wouldn't change anything.

            return;

        }

        if !is_nonoverlapping(self, other) {

            // See <https://github.com/rust-lang/rust/issues/80778> for why we need to stop here.

            panic!("`Cell::swap` on overlapping non-identical `Cell`s");

        }

        // SAFETY: This can be risky if called from separate threads, but `Cell`

        // is `!Sync` so this won't happen. This also won't invalidate any

        // pointers since `Cell` makes sure nothing else will be pointing into

        // either of these `Cell`s. We also excluded shenanigans like partially overlapping `Cell`s,

        // so `swap` will just properly copy two full values of type `T` back and forth.

        unsafe {

            mem::swap(&mut *self.value.get(), &mut *other.value.get());

        }

    }

    /// Replaces the contained value with `val`, and returns the old contained value.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let cell = Cell::new(5);

    /// assert_eq!(cell.get(), 5);

    /// assert_eq!(cell.replace(10), 5);

    /// assert_eq!(cell.get(), 10);

    /// ```

    #[inline]

    #[stable(feature = "move_cell", since = "1.17.0")]

    #[rustc_const_stable(feature = "const_cell", since = "1.88.0")]

    #[rustc_confusables("swap")]

        // SAFETY: This can cause data races if called from a separate thread,

        // but `Cell` is `!Sync` so this won't happen.

    /// Unwraps the value, consuming the cell.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c = Cell::new(5);

    /// let five = c.into_inner();

    ///

    /// assert_eq!(five, 5);

    /// ```

    #[stable(feature = "move_cell", since = "1.17.0")]

    #[rustc_const_stable(feature = "const_cell_into_inner", since = "1.83.0")]

    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]

    pub const fn into_inner(self) -> T {

        self.value.into_inner()

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: Copy> Cell<T> {

    /// Returns a copy of the contained value.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c = Cell::new(5);

    ///

    /// let five = c.get();

    /// ```

    #[inline]

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_cell", since = "1.88.0")]

        // SAFETY: This can cause data races if called from a separate thread,

        // but `Cell` is `!Sync` so this won't happen.

    /// Updates the contained value using a function.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c = Cell::new(5);

    /// c.update(|x| x + 1);

    /// assert_eq!(c.get(), 6);

    /// ```

    #[inline]

    #[stable(feature = "cell_update", since = "1.88.0")]

    pub fn update(&self, f: impl FnOnce(T) -> T) {

        let old = self.get();

        self.set(f(old));

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: ?Sized> Cell<T> {

    /// Returns a raw pointer to the underlying data in this cell.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c = Cell::new(5);

    ///

    /// let ptr = c.as_ptr();

    /// ```

    #[inline]

    #[stable(feature = "cell_as_ptr", since = "1.12.0")]

    #[rustc_const_stable(feature = "const_cell_as_ptr", since = "1.32.0")]

    #[rustc_as_ptr]

    #[rustc_never_returns_null_ptr]

    pub const fn as_ptr(&self) -> *mut T {

        self.value.get()

    }

    /// Returns a mutable reference to the underlying data.

    ///

    /// This call borrows `Cell` mutably (at compile-time) which guarantees

    /// that we possess the only reference.

    ///

    /// However be cautious: this method expects `self` to be mutable, which is

    /// generally not the case when using a `Cell`. If you require interior

    /// mutability by reference, consider using `RefCell` which provides

    /// run-time checked mutable borrows through its [`borrow_mut`] method.

    ///

    /// [`borrow_mut`]: RefCell::borrow_mut()

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let mut c = Cell::new(5);

    /// *c.get_mut() += 1;

    ///

    /// assert_eq!(c.get(), 6);

    /// ```

    #[inline]

    #[stable(feature = "cell_get_mut", since = "1.11.0")]

    #[rustc_const_stable(feature = "const_cell", since = "1.88.0")]

    pub const fn get_mut(&mut self) -> &mut T {

        self.value.get_mut()

    }

    /// Returns a `&Cell<T>` from a `&mut T`

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let slice: &mut [i32] = &mut [1, 2, 3];

    /// let cell_slice: &Cell<[i32]> = Cell::from_mut(slice);

    /// let slice_cell: &[Cell<i32>] = cell_slice.as_slice_of_cells();

    ///

    /// assert_eq!(slice_cell.len(), 3);

    /// ```

    #[inline]

    #[stable(feature = "as_cell", since = "1.37.0")]

    #[rustc_const_stable(feature = "const_cell", since = "1.88.0")]

    pub const fn from_mut(t: &mut T) -> &Cell<T> {

        // SAFETY: `&mut` ensures unique access.

        unsafe { &*(t as *mut T as *const Cell<T>) }

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: Default> Cell<T> {

    /// Takes the value of the cell, leaving `Default::default()` in its place.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let c = Cell::new(5);

    /// let five = c.take();

    ///

    /// assert_eq!(five, 5);

    /// assert_eq!(c.into_inner(), 0);

    /// ```

    #[stable(feature = "move_cell", since = "1.17.0")]

}

#[unstable(feature = "coerce_unsized", issue = "18598")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: CoerceUnsized<U>, U> CoerceUnsized<Cell<U>> for Cell<T> {}

// Allow types that wrap `Cell` to also implement `DispatchFromDyn`

// and become dyn-compatible method receivers.

// Note that currently `Cell` itself cannot be a method receiver

// because it does not implement Deref.

// In other words:

// `self: Cell<&Self>` won't work

// `self: CellWrapper<Self>` becomes possible

#[unstable(feature = "dispatch_from_dyn", issue = "none")]

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: DispatchFromDyn<U>, U> DispatchFromDyn<Cell<U>> for Cell<T> {}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T> Cell<[T]> {

    /// Returns a `&[Cell<T>]` from a `&Cell<[T]>`

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let slice: &mut [i32] = &mut [1, 2, 3];

    /// let cell_slice: &Cell<[i32]> = Cell::from_mut(slice);

    /// let slice_cell: &[Cell<i32>] = cell_slice.as_slice_of_cells();

    ///

    /// assert_eq!(slice_cell.len(), 3);

    /// ```

    #[stable(feature = "as_cell", since = "1.37.0")]

    #[rustc_const_stable(feature = "const_cell", since = "1.88.0")]

    pub const fn as_slice_of_cells(&self) -> &[Cell<T>] {

        // SAFETY: `Cell<T>` has the same memory layout as `T`.

        unsafe { &*(self as *const Cell<[T]> as *const [Cell<T>]) }

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T, const N: usize> Cell<[T; N]> {

    /// Returns a `&[Cell<T>; N]` from a `&Cell<[T; N]>`

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::Cell;

    ///

    /// let mut array: [i32; 3] = [1, 2, 3];

    /// let cell_array: &Cell<[i32; 3]> = Cell::from_mut(&mut array);

    /// let array_cell: &[Cell<i32>; 3] = cell_array.as_array_of_cells();

    /// ```

    #[stable(feature = "as_array_of_cells", since = "CURRENT_RUSTC_VERSION")]

    #[rustc_const_stable(feature = "as_array_of_cells", since = "CURRENT_RUSTC_VERSION")]

    pub const fn as_array_of_cells(&self) -> &[Cell<T>; N] {

        // SAFETY: `Cell<T>` has the same memory layout as `T`.

        unsafe { &*(self as *const Cell<[T; N]> as *const [Cell<T>; N]) }

    }

}

/// A mutable memory location with dynamically checked borrow rules

///

/// See the [module-level documentation](self) for more.

#[rustc_diagnostic_item = "RefCell"]

#[stable(feature = "rust1", since = "1.0.0")]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct RefCell<T: ?Sized> {

    borrow: Cell<BorrowCounter>,

    // Stores the location of the earliest currently active borrow.

    // This gets updated whenever we go from having zero borrows

    // to having a single borrow. When a borrow occurs, this gets included

    // in the generated `BorrowError`/`BorrowMutError`

    #[cfg(feature = "debug_refcell")]

    borrowed_at: Cell<Option<&'static crate::panic::Location<'static>>>,

    value: UnsafeCell<T>,

}

/// An error returned by [`RefCell::try_borrow`].

#[stable(feature = "try_borrow", since = "1.13.0")]

#[non_exhaustive]

#[derive(Debug)]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct BorrowError {

    #[cfg(feature = "debug_refcell")]

    location: &'static crate::panic::Location<'static>,

}

#[stable(feature = "try_borrow", since = "1.13.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl Display for BorrowError {

    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {

        #[cfg(feature = "debug_refcell")]

        let res = write!(

            f,

            "RefCell already mutably borrowed; a previous borrow was at {}",

            self.location

        );

        #[cfg(not(feature = "debug_refcell"))]

        let res = Display::fmt("RefCell already mutably borrowed", f);

        res

    }

}

/// An error returned by [`RefCell::try_borrow_mut`].

#[stable(feature = "try_borrow", since = "1.13.0")]

#[non_exhaustive]

#[derive(Debug)]

#[cfg(not(feature = "ferrocene_certified"))]

pub struct BorrowMutError {

    #[cfg(feature = "debug_refcell")]

    location: &'static crate::panic::Location<'static>,

}

#[stable(feature = "try_borrow", since = "1.13.0")]

#[cfg(not(feature = "ferrocene_certified"))]

impl Display for BorrowMutError {

    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {

        #[cfg(feature = "debug_refcell")]

        let res = write!(f, "RefCell already borrowed; a previous borrow was at {}", self.location);

        #[cfg(not(feature = "debug_refcell"))]

        let res = Display::fmt("RefCell already borrowed", f);

        res

    }

}

// This ensures the panicking code is outlined from `borrow_mut` for `RefCell`.

#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]

#[track_caller]

#[cold]

#[cfg(not(feature = "ferrocene_certified"))]

const fn panic_already_borrowed(err: BorrowMutError) -> ! {

    const_panic!(

        "RefCell already borrowed",

        "{err}",

        err: BorrowMutError = err,

    )

}

// This ensures the panicking code is outlined from `borrow` for `RefCell`.

#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))]

#[track_caller]

#[cold]

#[cfg(not(feature = "ferrocene_certified"))]

const fn panic_already_mutably_borrowed(err: BorrowError) -> ! {

    const_panic!(

        "RefCell already mutably borrowed",

        "{err}",

        err: BorrowError = err,

    )

}

// Positive values represent the number of `Ref` active. Negative values

// represent the number of `RefMut` active. Multiple `RefMut`s can only be

// active at a time if they refer to distinct, nonoverlapping components of a

// `RefCell` (e.g., different ranges of a slice).

//

// `Ref` and `RefMut` are both two words in size, and so there will likely never

// be enough `Ref`s or `RefMut`s in existence to overflow half of the `usize`

// range. Thus, a `BorrowCounter` will probably never overflow or underflow.

// However, this is not a guarantee, as a pathological program could repeatedly

// create and then mem::forget `Ref`s or `RefMut`s. Thus, all code must

// explicitly check for overflow and underflow in order to avoid unsafety, or at

// least behave correctly in the event that overflow or underflow happens (e.g.,

// see BorrowRef::new).

#[cfg(not(feature = "ferrocene_certified"))]

type BorrowCounter = isize;

#[cfg(not(feature = "ferrocene_certified"))]

const UNUSED: BorrowCounter = 0;

#[inline(always)]

#[cfg(not(feature = "ferrocene_certified"))]

const fn is_writing(x: BorrowCounter) -> bool {

    x < UNUSED

}

#[inline(always)]

#[cfg(not(feature = "ferrocene_certified"))]

const fn is_reading(x: BorrowCounter) -> bool {

    x > UNUSED

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T> RefCell<T> {

    /// Creates a new `RefCell` containing `value`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_refcell_new", since = "1.24.0")]

    #[inline]

    pub const fn new(value: T) -> RefCell<T> {

        RefCell {

            value: UnsafeCell::new(value),

            borrow: Cell::new(UNUSED),

            #[cfg(feature = "debug_refcell")]

            borrowed_at: Cell::new(None),

        }

    }

    /// Consumes the `RefCell`, returning the wrapped value.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    ///

    /// let five = c.into_inner();

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

    #[rustc_const_stable(feature = "const_cell_into_inner", since = "1.83.0")]

    #[rustc_allow_const_fn_unstable(const_precise_live_drops)]

    #[inline]

    pub const fn into_inner(self) -> T {

        // Since this function takes `self` (the `RefCell`) by value, the

        // compiler statically verifies that it is not currently borrowed.

        self.value.into_inner()

    }

    /// Replaces the wrapped value with a new one, returning the old value,

    /// without deinitializing either one.

    ///

    /// This function corresponds to [`std::mem::replace`](../mem/fn.replace.html).

    ///

    /// # Panics

    ///

    /// Panics if the value is currently borrowed.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    /// let cell = RefCell::new(5);

    /// let old_value = cell.replace(6);

    /// assert_eq!(old_value, 5);

    /// assert_eq!(cell, RefCell::new(6));

    /// ```

    #[inline]

    #[stable(feature = "refcell_replace", since = "1.24.0")]

    #[track_caller]

    #[rustc_confusables("swap")]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn replace(&self, t: T) -> T {

        mem::replace(&mut self.borrow_mut(), t)

    }

    /// Replaces the wrapped value with a new one computed from `f`, returning

    /// the old value, without deinitializing either one.

    ///

    /// # Panics

    ///

    /// Panics if the value is currently borrowed.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    /// let cell = RefCell::new(5);

    /// let old_value = cell.replace_with(|&mut old| old + 1);

    /// assert_eq!(old_value, 5);

    /// assert_eq!(cell, RefCell::new(6));

    /// ```

    #[inline]

    #[stable(feature = "refcell_replace_swap", since = "1.35.0")]

    #[track_caller]

    pub fn replace_with<F: FnOnce(&mut T) -> T>(&self, f: F) -> T {

        let mut_borrow = &mut *self.borrow_mut();

        let replacement = f(mut_borrow);

        mem::replace(mut_borrow, replacement)

    }

    /// Swaps the wrapped value of `self` with the wrapped value of `other`,

    /// without deinitializing either one.

    ///

    /// This function corresponds to [`std::mem::swap`](../mem/fn.swap.html).

    ///

    /// # Panics

    ///

    /// Panics if the value in either `RefCell` is currently borrowed, or

    /// if `self` and `other` point to the same `RefCell`.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    /// let c = RefCell::new(5);

    /// let d = RefCell::new(6);

    /// c.swap(&d);

    /// assert_eq!(c, RefCell::new(6));

    /// assert_eq!(d, RefCell::new(5));

    /// ```

    #[inline]

    #[stable(feature = "refcell_swap", since = "1.24.0")]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn swap(&self, other: &Self) {

        mem::swap(&mut *self.borrow_mut(), &mut *other.borrow_mut())

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: ?Sized> RefCell<T> {

    /// Immutably borrows the wrapped value.

    ///

    /// The borrow lasts until the returned `Ref` exits scope. Multiple

    /// immutable borrows can be taken out at the same time.

    ///

    /// # Panics

    ///

    /// Panics if the value is currently mutably borrowed. For a non-panicking variant, use

    /// [`try_borrow`](#method.try_borrow).

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    ///

    /// let borrowed_five = c.borrow();

    /// let borrowed_five2 = c.borrow();

    /// ```

    ///

    /// An example of panic:

    ///

    /// ```should_panic

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    ///

    /// let m = c.borrow_mut();

    /// let b = c.borrow(); // this causes a panic

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

    #[inline]

    #[track_caller]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn borrow(&self) -> Ref<'_, T> {

        match self.try_borrow() {

            Ok(b) => b,

            Err(err) => panic_already_mutably_borrowed(err),

        }

    }

    /// Immutably borrows the wrapped value, returning an error if the value is currently mutably

    /// borrowed.

    ///

    /// The borrow lasts until the returned `Ref` exits scope. Multiple immutable borrows can be

    /// taken out at the same time.

    ///

    /// This is the non-panicking variant of [`borrow`](#method.borrow).

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    ///

    /// {

    ///     let m = c.borrow_mut();

    ///     assert!(c.try_borrow().is_err());

    /// }

    ///

    /// {

    ///     let m = c.borrow();

    ///     assert!(c.try_borrow().is_ok());

    /// }

    /// ```

    #[stable(feature = "try_borrow", since = "1.13.0")]

    #[inline]

    #[cfg_attr(feature = "debug_refcell", track_caller)]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn try_borrow(&self) -> Result<Ref<'_, T>, BorrowError> {

        match BorrowRef::new(&self.borrow) {

            Some(b) => {

                #[cfg(feature = "debug_refcell")]

                {

                    // `borrowed_at` is always the *first* active borrow

                    if b.borrow.get() == 1 {

                        self.borrowed_at.replace(Some(crate::panic::Location::caller()));

                    }

                }

                // SAFETY: `BorrowRef` ensures that there is only immutable access

                // to the value while borrowed.

                let value = unsafe { NonNull::new_unchecked(self.value.get()) };

                Ok(Ref { value, borrow: b })

            }

            None => Err(BorrowError {

                // If a borrow occurred, then we must already have an outstanding borrow,

                // so `borrowed_at` will be `Some`

                #[cfg(feature = "debug_refcell")]

                location: self.borrowed_at.get().unwrap(),

            }),

        }

    }

    /// Mutably borrows the wrapped value.

    ///

    /// The borrow lasts until the returned `RefMut` or all `RefMut`s derived

    /// from it exit scope. The value cannot be borrowed while this borrow is

    /// active.

    ///

    /// # Panics

    ///

    /// Panics if the value is currently borrowed. For a non-panicking variant, use

    /// [`try_borrow_mut`](#method.try_borrow_mut).

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new("hello".to_owned());

    ///

    /// *c.borrow_mut() = "bonjour".to_owned();

    ///

    /// assert_eq!(&*c.borrow(), "bonjour");

    /// ```

    ///

    /// An example of panic:

    ///

    /// ```should_panic

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    /// let m = c.borrow();

    ///

    /// let b = c.borrow_mut(); // this causes a panic

    /// ```

    #[stable(feature = "rust1", since = "1.0.0")]

    #[inline]

    #[track_caller]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn borrow_mut(&self) -> RefMut<'_, T> {

        match self.try_borrow_mut() {

            Ok(b) => b,

            Err(err) => panic_already_borrowed(err),

        }

    }

    /// Mutably borrows the wrapped value, returning an error if the value is currently borrowed.

    ///

    /// The borrow lasts until the returned `RefMut` or all `RefMut`s derived

    /// from it exit scope. The value cannot be borrowed while this borrow is

    /// active.

    ///

    /// This is the non-panicking variant of [`borrow_mut`](#method.borrow_mut).

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    ///

    /// {

    ///     let m = c.borrow();

    ///     assert!(c.try_borrow_mut().is_err());

    /// }

    ///

    /// assert!(c.try_borrow_mut().is_ok());

    /// ```

    #[stable(feature = "try_borrow", since = "1.13.0")]

    #[inline]

    #[cfg_attr(feature = "debug_refcell", track_caller)]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn try_borrow_mut(&self) -> Result<RefMut<'_, T>, BorrowMutError> {

        match BorrowRefMut::new(&self.borrow) {

            Some(b) => {

                #[cfg(feature = "debug_refcell")]

                {

                    self.borrowed_at.replace(Some(crate::panic::Location::caller()));

                }

                // SAFETY: `BorrowRefMut` guarantees unique access.

                let value = unsafe { NonNull::new_unchecked(self.value.get()) };

                Ok(RefMut { value, borrow: b, marker: PhantomData })

            }

            None => Err(BorrowMutError {

                // If a borrow occurred, then we must already have an outstanding borrow,

                // so `borrowed_at` will be `Some`

                #[cfg(feature = "debug_refcell")]

                location: self.borrowed_at.get().unwrap(),

            }),

        }

    }

    /// Returns a raw pointer to the underlying data in this cell.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    ///

    /// let ptr = c.as_ptr();

    /// ```

    #[inline]

    #[stable(feature = "cell_as_ptr", since = "1.12.0")]

    #[rustc_as_ptr]

    #[rustc_never_returns_null_ptr]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn as_ptr(&self) -> *mut T {

        self.value.get()

    }

    /// Returns a mutable reference to the underlying data.

    ///

    /// Since this method borrows `RefCell` mutably, it is statically guaranteed

    /// that no borrows to the underlying data exist. The dynamic checks inherent

    /// in [`borrow_mut`] and most other methods of `RefCell` are therefore

    /// unnecessary. Note that this method does not reset the borrowing state if borrows were previously leaked

    /// (e.g., via [`forget()`] on a [`Ref`] or [`RefMut`]). For that purpose,

    /// consider using the unstable [`undo_leak`] method.

    ///

    /// This method can only be called if `RefCell` can be mutably borrowed,

    /// which in general is only the case directly after the `RefCell` has

    /// been created. In these situations, skipping the aforementioned dynamic

    /// borrowing checks may yield better ergonomics and runtime-performance.

    ///

    /// In most situations where `RefCell` is used, it can't be borrowed mutably.

    /// Use [`borrow_mut`] to get mutable access to the underlying data then.

    ///

    /// [`borrow_mut`]: RefCell::borrow_mut()

    /// [`forget()`]: mem::forget

    /// [`undo_leak`]: RefCell::undo_leak()

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let mut c = RefCell::new(5);

    /// *c.get_mut() += 1;

    ///

    /// assert_eq!(c, RefCell::new(6));

    /// ```

    #[inline]

    #[stable(feature = "cell_get_mut", since = "1.11.0")]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn get_mut(&mut self) -> &mut T {

        self.value.get_mut()

    }

    /// Undo the effect of leaked guards on the borrow state of the `RefCell`.

    ///

    /// This call is similar to [`get_mut`] but more specialized. It borrows `RefCell` mutably to

    /// ensure no borrows exist and then resets the state tracking shared borrows. This is relevant

    /// if some `Ref` or `RefMut` borrows have been leaked.

    ///

    /// [`get_mut`]: RefCell::get_mut()

    ///

    /// # Examples

    ///

    /// ```

    /// #![feature(cell_leak)]

    /// use std::cell::RefCell;

    ///

    /// let mut c = RefCell::new(0);

    /// std::mem::forget(c.borrow_mut());

    ///

    /// assert!(c.try_borrow().is_err());

    /// c.undo_leak();

    /// assert!(c.try_borrow().is_ok());

    /// ```

    #[unstable(feature = "cell_leak", issue = "69099")]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const fn undo_leak(&mut self) -> &mut T {

        *self.borrow.get_mut() = UNUSED;

        self.get_mut()

    }

    /// Immutably borrows the wrapped value, returning an error if the value is

    /// currently mutably borrowed.

    ///

    /// # Safety

    ///

    /// Unlike `RefCell::borrow`, this method is unsafe because it does not

    /// return a `Ref`, thus leaving the borrow flag untouched. Mutably

    /// borrowing the `RefCell` while the reference returned by this method

    /// is alive is undefined behavior.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);

    ///

    /// {

    ///     let m = c.borrow_mut();

    ///     assert!(unsafe { c.try_borrow_unguarded() }.is_err());

    /// }

    ///

    /// {

    ///     let m = c.borrow();

    ///     assert!(unsafe { c.try_borrow_unguarded() }.is_ok());

    /// }

    /// ```

    #[stable(feature = "borrow_state", since = "1.37.0")]

    #[inline]

    #[rustc_const_unstable(feature = "const_ref_cell", issue = "137844")]

    pub const unsafe fn try_borrow_unguarded(&self) -> Result<&T, BorrowError> {

        if !is_writing(self.borrow.get()) {

            // SAFETY: We check that nobody is actively writing now, but it is

            // the caller's responsibility to ensure that nobody writes until

            // the returned reference is no longer in use.

            // Also, `self.value.get()` refers to the value owned by `self`

            // and is thus guaranteed to be valid for the lifetime of `self`.

            Ok(unsafe { &*self.value.get() })

        } else {

            Err(BorrowError {

                // If a borrow occurred, then we must already have an outstanding borrow,

                // so `borrowed_at` will be `Some`

                #[cfg(feature = "debug_refcell")]

                location: self.borrowed_at.get().unwrap(),

            })

        }

    }

}

#[cfg(not(feature = "ferrocene_certified"))]

impl<T: Default> RefCell<T> {

    /// Takes the wrapped value, leaving `Default::default()` in its place.

    ///

    /// # Panics

    ///

    /// Panics if the value is currently borrowed.

    ///

    /// # Examples

    ///

    /// ```

    /// use std::cell::RefCell;

    ///

    /// let c = RefCell::new(5);