Skip to content

Commit

Permalink
Add clarifications for documentation (#28)
Browse files Browse the repository at this point in the history 
This PR modifies the text of `lib.rs` and `trait ImplicitClone`
documentations, hopefully clarifying some points that caused #6.

Also while writing new documentation, I've noticed missing
implementation for a `Copy` type `&T`. There was present implementation
for `&'static str`, but it not only does not have to be `'static`, it
does not even have to be `str` - it can be `T: ?Sized`.

Added some tests for the `lib.rs` types, as means of more documentation
and examples of using the crate.

I believe this will be my last PR before 0.4.1.

---------

Co-authored-by: Cecile Tonglet <[email protected]>
  • Loading branch information
@kirillsemyonkin @cecton
kirillsemyonkin and cecton authored Aug 17, 2023
1 parent d3bb992 commit 5f2072c
Show file tree
Hide file tree
Showing 2 changed files with 126 additions and 30 deletions.
35 changes: 22 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,25 +9,33 @@

# ImplicitClone

A library that introduces the marker trait [`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html) which allows
reproducing the behavior of the trait [`Copy`][std::marker::Copy] but calls the
[`Clone`][std::clone::Clone] implementation instead and must be implemented in the host
library.
This library introduces the marker trait [`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html) intended for
cheap-to-clone types that should be allowed to be cloned implicitly. It enables host libraries
using this crate to have the syntax of [`Copy`][std::marker::Copy] while actually calling the
[`Clone`][std::clone::Clone] implementation instead (usually when host library does such syntax
in a macro).

The idea is that you must implement this trait on types that are cheap to clone
([`std::rc::Rc`][std::rc::Rc] and [`std::sync::Arc`][std::sync::Arc] types are
automatically implemented). Then the host library must use the trait
[`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html) to allow their users to pass objects that will be
cloned automatically.
The idea is that you must implement this trait on your cheap-to-clone types, and then the host
library using the trait will allow users to pass values of your types and they will be cloned
automatically.

Standard types that the [`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html) is already implemented for:

- [`std::rc::Rc`][std::rc::Rc]
- [`std::sync::Arc`][std::sync::Arc]
- Tuples with 1-12 elements, all of which are also [`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html)
- [`Option`][std::option::Option], where inner value is [`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html)
- Some built-in [`Copy`][std::marker::Copy] types, like `()`, `bool`, `&T`, etc.

This crate is in the category `rust-patterns` but this is actually a Rust anti-pattern. In Rust
the user should always handle borrowing and ownership by themselves. Nevertheless, this pattern
is sometimes desirable. For example, UI frameworks that rely on propagating properties from
ancestors to children will always need to use Rc'ed types to allow every child component to
update. This is the case in React-like framework like Yew.
ancestors to multiple children will always need to use `Rc`'d types to cheaply and concisely
update every child component. This is the case in React-like frameworks like
[Yew](https://yew.rs/).

This crates also provide a few convenient immutable types for handling cheap-to-clone string,
array and maps which you can find in the modules [`sync`](https://docs.rs/implicit-clone/latest/implicit_clone/sync/) and
This crate also provides a few convenient immutable types for handling cheap-to-clone strings,
arrays and maps, you can find them in the modules [`sync`](https://docs.rs/implicit-clone/latest/implicit_clone/sync/) and
[`unsync`](https://docs.rs/implicit-clone/latest/implicit_clone/unsync/). Those types implement [`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html) and
hold only types that implement [`ImplicitClone`](https://docs.rs/implicit-clone/latest/implicit_clone/trait.ImplicitClone.html) as well. **One big
particularity: iterating on these types yields clones of the items and not references.** This
Expand All @@ -37,5 +45,6 @@ can be particularly handy when using a React-like framework.
[std::clone::Clone]: https://doc.rust-lang.org/std/clone/trait.Clone.html
[std::rc::Rc]: https://doc.rust-lang.org/std/rc/struct.Rc.html
[std::sync::Arc]: https://doc.rust-lang.org/std/sync/struct.Arc.html
[std::option::Option]: https://doc.rust-lang.org/stable/std/option/enum.Option.html

<!-- cargo-rdme end -->
121 changes: 104 additions & 17 deletions src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,25 +7,33 @@
#![cfg_attr(docsrs, feature(doc_cfg))]
//! # ImplicitClone
//!
//! A library that introduces the marker trait [`ImplicitClone`](crate::ImplicitClone) which allows
//! reproducing the behavior of the trait [`Copy`][std::marker::Copy] but calls the
//! [`Clone`][std::clone::Clone] implementation instead and must be implemented in the host
//! library.
//! This library introduces the marker trait [`ImplicitClone`](crate::ImplicitClone) intended for
//! cheap-to-clone types that should be allowed to be cloned implicitly. It enables host libraries
//! using this crate to have the syntax of [`Copy`][std::marker::Copy] while actually calling the
//! [`Clone`][std::clone::Clone] implementation instead (usually when host library does such syntax
//! in a macro).
//!
//! The idea is that you must implement this trait on types that are cheap to clone
//! ([`std::rc::Rc`][std::rc::Rc] and [`std::sync::Arc`][std::sync::Arc] types are
//! automatically implemented). Then the host library must use the trait
//! [`ImplicitClone`](crate::ImplicitClone) to allow their users to pass objects that will be
//! cloned automatically.
//! The idea is that you must implement this trait on your cheap-to-clone types, and then the host
//! library using the trait will allow users to pass values of your types and they will be cloned
//! automatically.
//!
//! Standard types that the [`ImplicitClone`](crate::ImplicitClone) is already implemented for:
//!
//! - [`std::rc::Rc`][std::rc::Rc]
//! - [`std::sync::Arc`][std::sync::Arc]
//! - Tuples with 1-12 elements, all of which are also [`ImplicitClone`](crate::ImplicitClone)
//! - [`Option`][std::option::Option], where inner value is [`ImplicitClone`](crate::ImplicitClone)
//! - Some built-in [`Copy`][std::marker::Copy] types, like `()`, `bool`, `&T`, etc.
//!
//! This crate is in the category `rust-patterns` but this is actually a Rust anti-pattern. In Rust
//! the user should always handle borrowing and ownership by themselves. Nevertheless, this pattern
//! is sometimes desirable. For example, UI frameworks that rely on propagating properties from
//! ancestors to children will always need to use Rc'ed types to allow every child component to
//! update. This is the case in React-like framework like Yew.
//! ancestors to multiple children will always need to use `Rc`'d types to cheaply and concisely
//! update every child component. This is the case in React-like frameworks like
//! [Yew](https://yew.rs/).
//!
//! This crates also provide a few convenient immutable types for handling cheap-to-clone string,
//! array and maps which you can find in the modules [`sync`](crate::sync) and
//! This crate also provides a few convenient immutable types for handling cheap-to-clone strings,
//! arrays and maps, you can find them in the modules [`sync`](crate::sync) and
//! [`unsync`](crate::unsync). Those types implement [`ImplicitClone`](crate::ImplicitClone) and
//! hold only types that implement [`ImplicitClone`](crate::ImplicitClone) as well. **One big
//! particularity: iterating on these types yields clones of the items and not references.** This
Expand All @@ -35,18 +43,21 @@
//! [std::clone::Clone]: https://doc.rust-lang.org/std/clone/trait.Clone.html
//! [std::rc::Rc]: https://doc.rust-lang.org/std/rc/struct.Rc.html
//! [std::sync::Arc]: https://doc.rust-lang.org/std/sync/struct.Arc.html
//! [std::option::Option]: https://doc.rust-lang.org/stable/std/option/enum.Option.html
/// Thread-safe version of immutable types.
pub mod sync;
/// Single-threaded version of immutable types.
pub mod unsync;

/// Marker trait for types that can be cloned implicitly.
/// Marker trait for cheap-to-clone types that should be allowed to be cloned implicitly.
///
/// Behaves exactly like [`Copy`] but calls the [`Clone`] implementation instead and must be
/// implemented in the host library.
/// Enables host libraries to have the same syntax as [`Copy`] while calling the [`Clone`]
/// implementation instead.
pub trait ImplicitClone: Clone {}

impl<T: ?Sized> ImplicitClone for &T {}

impl<T: ImplicitClone> ImplicitClone for Option<T> {}

macro_rules! impl_implicit_clone {
Expand All @@ -62,7 +73,7 @@ impl_implicit_clone!(
f32, f64,
bool,
usize, isize,
&'static str, char,
char,
(),
);

Expand Down Expand Up @@ -119,3 +130,79 @@ macro_rules! imap_deconstruct {
)*
};
}

#[cfg(test)]
mod test {
use super::*;

fn host_library<T: ImplicitClone>(value: &T) -> T {
value.clone()
}

macro_rules! host_library {
($a:expr) => {
host_library(&$a)
};
}

struct NonImplicitCloneType;

#[test]
fn custom() {
#[derive(Clone)]
struct ImplicitCloneType;

impl ImplicitClone for ImplicitCloneType {}

host_library!(ImplicitCloneType);
}

#[test]
fn copy_types() {
macro_rules! test_all {
($($t:ty),* $(,)?) => {
$(host_library!(<$t>::default());)*
};
}

#[rustfmt::skip]
test_all!(
u8, u16, u32, u64, u128,
i8, i16, i32, i64, i128,
f32, f64,
bool,
usize, isize, char,
(),
);
}

#[test]
fn ref_type() {
host_library!(&NonImplicitCloneType);
// `host_library!(NonImplicitCloneType)` doesn't compile
}

#[test]
fn option() {
host_library!(Some("foo"));
// `host_library!(Some(NonImplicitCloneType));` doesn't compile
}

#[test]
fn tuples() {
host_library!((1,));
host_library!((1, 2));
host_library!((1, 2, 3));
host_library!((1, 2, 3, 4));
host_library!((1, 2, 3, 4, 5));
host_library!((1, 2, 3, 4, 5, 6));
host_library!((1, 2, 3, 4, 5, 6, 7));
host_library!((1, 2, 3, 4, 5, 6, 7, 8));
host_library!((1, 2, 3, 4, 5, 6, 7, 8, 9));
host_library!((1, 2, 3, 4, 5, 6, 7, 8, 9, 10));
host_library!((1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11));
host_library!((1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12));
// `host_library!((1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13));` doesn't compile
// `host_library!((NonImplicitCloneType,));` doesn't compile
}
}

0 comments on commit 5f2072c

Please sign in to comment.