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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
//! [![github]](https://github.com/dtolnay/dyn-clone) [![crates-io]](https://crates.io/crates/dyn-clone) [![docs-rs]](https://docs.rs/dyn-clone)
//!
//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
//! [crates-io]: https://img.shields.io/badge/crates.io-fc8d62?style=for-the-badge&labelColor=555555&logo=rust
//! [docs-rs]: https://img.shields.io/badge/docs.rs-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
//!
//! <br>
//!
//! This crate provides a [`DynClone`] trait that can be used in trait objects,
//! and a [`clone_box`] function that can clone any sized or dynamically sized
//! implementation of `DynClone`. Types that implement the standard library's
//! [`std::clone::Clone`] trait are automatically usable by a `DynClone` trait
//! object.
//!
//! [`DynClone`]: trait.DynClone.html
//! [`clone_box`]: fn.clone_box.html
//! [`std::clone::Clone`]: https://doc.rust-lang.org/std/clone/trait.Clone.html
//!
//! # Example
//!
//! ```
//! use dyn_clone::DynClone;
//!
//! trait MyTrait: DynClone {
//!     fn recite(&self);
//! }
//!
//! impl MyTrait for String {
//!     fn recite(&self) {
//!         println!("{} ♫", self);
//!     }
//! }
//!
//! fn main() {
//!     let line = "The slithy structs did gyre and gimble the namespace";
//!
//!     // Build a trait object holding a String.
//!     // This requires String to implement MyTrait and std::clone::Clone.
//!     let x: Box<dyn MyTrait> = Box::new(String::from(line));
//!
//!     x.recite();
//!
//!     // The type of x2 is a Box<dyn MyTrait> cloned from x.
//!     let x2 = dyn_clone::clone_box(&*x);
//!
//!     x2.recite();
//! }
//! ```
//!
//! This crate includes a macro for concisely implementing `impl
//! std::clone::Clone for Box<dyn MyTrait>` in terms of `dyn_clone::clone_box`.
//!
//! ```
//! # use dyn_clone::DynClone;
//! #
//! // As before.
//! trait MyTrait: DynClone {
//!     /* ... */
//! }
//!
//! dyn_clone::clone_trait_object!(MyTrait);
//!
//! // Now data structures containing Box<dyn MyTrait> can derive Clone:
//! #[derive(Clone)]
//! struct Container {
//!     trait_object: Box<dyn MyTrait>,
//! }
//! ```
//!
//! The `clone_trait_object!` macro expands to just the following, which you can
//! handwrite instead if you prefer:
//!
//! ```
//! # use dyn_clone::DynClone;
//! #
//! # trait MyTrait: DynClone {}
//! #
//! impl Clone for Box<dyn MyTrait> {
//!     fn clone(&self) -> Self {
//!         dyn_clone::clone_box(&**self)
//!     }
//! }
//!
//! // and similar for Box<dyn MyTrait + Send>, Box<dyn MyTrait + Sync>, Box<dyn MyTrait + Send + Sync>
//! ```

#![doc(html_root_url = "https://docs.rs/dyn_clone/1.0.9")]
#![no_std]
#![allow(clippy::missing_panics_doc, clippy::ptr_as_ptr)]

extern crate alloc;

use crate::sealed::{Private, Sealed};

#[macro_use]
mod macros;

#[doc(hidden)]
pub mod private {
    pub use alloc::boxed::Box;
    pub use core::clone::Clone;
    pub use core::marker::{Send, Sync};
}

mod sealed {
    pub trait Sealed {}
    impl<T: Clone> Sealed for T {}
    impl Sealed for str {}
    impl<T: Clone> Sealed for [T] {}
    pub struct Private;
}

/// This trait is implemented by any type that implements [`std::clone::Clone`].
///
/// [`std::clone::Clone`]: https://doc.rust-lang.org/std/clone/trait.Clone.html
pub trait DynClone: Sealed {
    // Not public API
    #[doc(hidden)]
    fn __clone_box(&self, _: Private) -> *mut ();
}

use alloc::boxed::Box;
use alloc::rc::Rc;
use alloc::sync::Arc;

/// `&T`&ensp;&mdash;&blacktriangleright;&ensp;`T`
pub fn clone<T>(t: &T) -> T
where
    T: DynClone,
{
    unsafe { *Box::from_raw(<T as DynClone>::__clone_box(t, Private) as *mut T) }
}

/// `&T`&ensp;&mdash;&blacktriangleright;&ensp;`Box<T>`
pub fn clone_box<T>(t: &T) -> Box<T>
where
    T: ?Sized + DynClone,
{
    let mut fat_ptr = t as *const T;
    unsafe {
        let data_ptr = &mut fat_ptr as *mut *const T as *mut *mut ();
        assert_eq!(*data_ptr as *const (), t as *const T as *const ());
        *data_ptr = <T as DynClone>::__clone_box(t, Private);
    }
    unsafe { Box::from_raw(fat_ptr as *mut T) }
}

/// `&mut Arc<T>`&ensp;&mdash;&blacktriangleright;&ensp;`&mut T`
pub fn arc_make_mut<T>(arc: &mut Arc<T>) -> &mut T
where
    T: ?Sized + DynClone,
{
    // Atomic. Find out whether the Arc in the argument is the single holder of
    // a reference count (strong or weak) on the target object. If yes, it is
    // guaranteed to remain that way throughout the rest of this function
    // because no other threads could bump the reference count through any other
    // Arc (because no others exist) or through this Arc (because the current
    // thread holds an exclusive borrow of it).
    let is_unique = Arc::get_mut(arc).is_some();
    if !is_unique {
        // Non-atomic.
        let clone = Arc::from(clone_box(&**arc));
        // Atomic. Check the reference counts again to find out whether the old
        // object needs to be dropped. Probably not, but it can happen if all
        // the other holders of a reference count went away during the time that
        // the clone operation took.
        *arc = clone;
    }
    // Non-atomic. TODO: replace with Arc::get_mut_unchecked when stable.
    let ptr = Arc::as_ptr(arc) as *mut T;
    unsafe { &mut *ptr }
}

/// `&mut Rc<T>`&ensp;&mdash;&blacktriangleright;&ensp;`&mut T`
pub fn rc_make_mut<T>(rc: &mut Rc<T>) -> &mut T
where
    T: ?Sized + DynClone,
{
    let is_unique = Rc::get_mut(rc).is_some();
    if !is_unique {
        let clone = Rc::from(clone_box(&**rc));
        *rc = clone;
    }
    let ptr = Rc::as_ptr(rc) as *mut T;
    unsafe { &mut *ptr }
}

impl<T> DynClone for T
where
    T: Clone,
{
    fn __clone_box(&self, _: Private) -> *mut () {
        Box::<T>::into_raw(Box::new(self.clone())) as *mut ()
    }
}

impl DynClone for str {
    fn __clone_box(&self, _: Private) -> *mut () {
        Box::<str>::into_raw(Box::from(self)) as *mut ()
    }
}

impl<T> DynClone for [T]
where
    T: Clone,
{
    fn __clone_box(&self, _: Private) -> *mut () {
        Box::<[T]>::into_raw(self.iter().cloned().collect()) as *mut ()
    }
}