Selective AsRef/AsMut impl

CHANGELOG.md

@@ -59,6 +59,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   ([#279](https://github.com/JelteF/derive_more/pull/279))
 - `derive_more::derive` module exporting only macros, without traits.
   ([#290](https://github.com/JelteF/derive_more/pull/290))
+- Add support for selective forwarding to `AsRef`/`AsMut` derives.
+  ([#298](https://github.com/JelteF/derive_more/pull/298))
 
 ### Changed
 

impl/Cargo.toml

@@ -48,7 +48,7 @@ default = []
 
 add = []
 add_assign = []
-as_ref = []
+as_ref = ["syn/extra-traits", "syn/visit"]
 constructor = []
 debug = ["syn/extra-traits", "dep:unicode-xid"]
 deref = []

impl/doc/as_mut.md

@@ -31,7 +31,7 @@ impl AsMut<String> for MyWrapper {
 }
 ```
 
-It's also possible to use the `#[as_mut(forward)]` attribute to forward
+The `#[as_mut(forward)]` attribute can be used to forward
 to the `as_mut` implementation of the field. So here `SingleFieldForward`
 implements all `AsMut` for all types that `Vec<i32>` implements `AsMut` for.
 
@@ -46,22 +46,96 @@ let mut item = SingleFieldForward(vec![]);
 let _: &mut [i32] = (&mut item).as_mut();
 ```
 
-This generates:
+This generates code equivalent to:
 
 ```rust
 # struct SingleFieldForward(Vec<i32>);
-impl<__AsT: ?::core::marker::Sized> ::core::convert::AsMut<__AsT> for SingleFieldForward
+impl<T: ?Sized> AsMut<T> for SingleFieldForward
 where
-    Vec<i32>: ::core::convert::AsMut<__AsT>,
+    Vec<i32>: AsMut<T>,
 {
     #[inline]
-    fn as_mut(&mut self) -> &mut __AsT {
-        <Vec<i32> as ::core::convert::AsMut<__AsT>>::as_mut(&mut self.0)
+    fn as_mut(&mut self) -> &mut T {
+        self.0.as_mut()
     }
 }
 ```
 
+It's also possible to specify concrete types to derive impls for with `#[as_mut(<types>)]`.
 
+These types can include both the type of the field, and types for which the field type implements `AsMut`.
+
+```rust
+# use derive_more::AsMut;
+#
+#[derive(AsMut)]
+#[as_mut(str, [u8], String)]
+struct Types(String);
+
+let mut item = Types("test".to_owned());
+let _: &mut str = item.as_mut();
+let _: &mut [u8] = item.as_mut();
+let _: &mut String = item.as_mut();_
+```
+
+When either the field type or the type specified to convert into contain generic parameters,
+they're compared for string equality, and when there's no match assumed to be different types.
+
+For example
+
+```rust
+# use derive_more::AsMut;
+#
+#[derive(AsMut)]
+#[as_mut(i32)]
+struct Generic<T>(T);
+```
+
+Generates a forwarded impl
+
+```rust
+# struct Generic<T>(T);
+#
+impl<T: AsMut<i32>> AsMut<i32> for Generic<T> {
+    fn as_mut(&mut self) -> &mut i32 {
+        self.0.as_mut()
+    }
+}
+```
+
+And
+
+```rust
+# use derive_more::AsMut;
+#
+#[derive(AsMut)]
+#[as_mut(T)]
+struct Generic<T>(T);
+```
+
+Generates
+
+```rust
+# struct Generic<T>(T);
+#
+impl<T> AsMut<T> for Generic<T> {
+    fn as_mut(&mut self) -> &mut T {
+        &mut self.0
+    }
+}
+```
+
+Generating code like this is not supported
+
+```rust
+# struct Generic<T>(T);
+#
+impl AsMut<i32> for Generic<i32> {
+    fn as_mut(&mut self) -> &mut i32 {
+        &mut self.0
+    }
+}
+```
 
 
 ## Structs with Multiple Fields
@@ -75,7 +149,7 @@ An implementation will be generated for each indicated field.
 #
 #[derive(AsMut)]
 struct MyWrapper {
-    #[as_mut]
+    #[as_mut(str)]
     name: String,
     #[as_mut]
     num: i32,
@@ -91,9 +165,9 @@ Generates:
 #     num: i32,
 #     valid: bool,
 # }
-impl AsMut<String> for MyWrapper {
+impl AsMut<str> for MyWrapper {
     fn as_mut(&mut self) -> &mut String {
-        &mut self.name
+        self.name.as_mut()
     }
 }
 
@@ -104,6 +178,19 @@ impl AsMut<i32> for MyWrapper {
 }
 ```
 
+Only conversions that use a single field are possible with this derive.
+Something like this wouldn't work, due to the nature of the `AsMut` trait:
+
+```rust,compile_fail
+# use derive_more::AsMut
+#
+#[derive(AsMut)]
+#[as_mut((str, [u8]))]
+struct MyWrapper(String, Vec<u8>)
+```
+
+If you need to convert into multiple references, consider using the
+[`Into`](crate::Into) derive with `#[into(ref_mut)]`.
 
 ### Skipping
 
@@ -176,6 +263,27 @@ struct ForwardWithOther {
 }
 ```
 
+Multiple forwarded impls with different concrete types, however, can be used.
+
+```rust
+# use derive_more::AsMut;
+#
+#[derive(AsMut)]
+struct Types {
+    #[as_mut(str)]
+    str: String,
+    #[as_mut([u8])]
+    vec: Vec<u8>,
+}
+
+let mut item = Types {
+    str: "test".to_owned(),
+    vec: vec![0u8],
+};
+
+let _: &mut str = item.as_mut();
+let _: &mut [u8] = item.as_mut();
+```
 
 
 

impl/doc/as_ref.md

@@ -31,7 +31,7 @@ impl AsRef<String> for MyWrapper {
 }
 ```
 
-It's also possible to use the `#[as_ref(forward)]` attribute to forward
+The `#[as_ref(forward)]` attribute can be used to forward
 to the `as_ref` implementation of the field. So here `SingleFieldForward`
 implements all `AsRef` for all types that `Vec<i32>` implements `AsRef` for.
 
@@ -46,22 +46,96 @@ let item = SingleFieldForward(vec![]);
 let _: &[i32] = (&item).as_ref();
 ```
 
-This generates:
+This generates code equivalent to:
 
 ```rust
 # struct SingleFieldForward(Vec<i32>);
-impl<__AsT: ?::core::marker::Sized> ::core::convert::AsRef<__AsT> for SingleFieldForward
+impl<T: ?Sized> AsRef<T> for SingleFieldForward
 where
-    Vec<i32>: ::core::convert::AsRef<__AsT>,
+    Vec<i32>: AsRef<T>,
 {
     #[inline]
-    fn as_ref(&self) -> &__AsT {
-        <Vec<i32> as ::core::convert::AsRef<__AsT>>::as_ref(&self.0)
+    fn as_ref(&self) -> &T {
+        self.0.as_ref()
     }
 }
 ```
 
+It's also possible to specify concrete types to derive impls for with `#[as_ref(<types>)]`.
 
+These types can include both the type of the field, and types for which the field type implements `AsRef`.
+
+```rust
+# use derive_more::AsRef;
+#
+#[derive(AsRef)]
+#[as_ref(str, [u8], String)]
+struct Types(String);
+
+let item = Types("test".to_owned());
+let _: &str = item.as_ref();
+let _: &[u8] = item.as_ref();
+let _: &String = item.as_ref();
+```
+
+When either the field type or the type specified to convert into contain generic parameters,
+they're compared for string equality, and when there's no match assumed to be different types.
+
+For example
+
+```rust
+# use derive_more::AsRef;
+#
+#[derive(AsRef)]
+#[as_ref(i32)]
+struct Generic<T>(T);
+```
+
+Generates a forwarded impl
+
+```rust
+# struct Generic<T>(T);
+#
+impl<T: AsRef<i32>> AsRef<i32> for Generic<T> {
+    fn as_ref(&self) -> &i32 {
+        self.0.as_ref()
+    }
+}
+```
+
+And
+
+```rust
+# use derive_more::AsRef;
+#
+#[derive(AsRef)]
+#[as_ref(T)]
+struct Generic<T>(T);
+```
+
+Generates
+
+```rust
+# struct Generic<T>(T);
+#
+impl<T> AsRef<T> for Generic<T> {
+    fn as_ref(&self) -> &T {
+        &self.0
+    }
+}
+```
+
+Generating code like this is not supported
+
+```rust
+# struct Generic<T>(T);
+#
+impl AsRef<i32> for Generic<i32> {
+    fn as_ref(&self) -> &i32 {
+        &self.0
+    }
+}
+```
 
 
 ## Structs with Multiple Fields
@@ -75,7 +149,7 @@ An implementation will be generated for each indicated field.
 #
 #[derive(AsRef)]
 struct MyWrapper {
-    #[as_ref]
+    #[as_ref(str)]
     name: String,
     #[as_ref]
     num: i32,
@@ -91,9 +165,9 @@ Generates:
 #     num: i32,
 #     valid: bool,
 # }
-impl AsRef<String> for MyWrapper {
-    fn as_ref(&self) -> &String {
-        &self.name
+impl AsRef<str> for MyWrapper {
+    fn as_ref(&self) -> &str {
+        self.name.as_ref()
     }
 }
 
@@ -104,6 +178,20 @@ impl AsRef<i32> for MyWrapper {
 }
 ```
 
+Only conversions that use a single field are possible with this derive.
+Something like this wouldn't work, due to the nature of the `AsRef` trait:
+
+```rust,compile_fail
+# use derive_more::AsRef
+#
+#[derive(AsRef)]
+#[as_ref((str, [u8]))]
+struct MyWrapper(String, Vec<u8>)
+```
+
+If you need to convert into multiple references, consider using the
+[`Into`](crate::Into) derive with `#[into(ref)]`.
+
 
 ### Skipping
 
@@ -176,6 +264,27 @@ struct ForwardWithOther {
 }
 ```
 
+Multiple forwarded impls with different concrete types, however, can be used.
+
+```rust
+# use derive_more::AsRef;
+#
+#[derive(AsRef)]
+struct Types {
+    #[as_ref(str)]
+    str: String,
+    #[as_ref([u8])]
+    vec: Vec<u8>,
+}
+
+let item = Types {
+    str: "test".to_owned(),
+    vec: vec![0u8],
+};
+
+let _: &str = item.as_ref();
+let _: &[u8] = item.as_ref();
+```