4 releases
0.6.2 | Feb 4, 2024 |
---|---|
0.6.1 | Sep 20, 2023 |
0.6.0 | May 6, 2023 |
0.5.0 | Apr 12, 2023 |
#325 in Rust patterns
15,260 downloads per month
Used in 14 crates
(via rc-zip)
37KB
656 lines
crate ownable
Derive macro for structs/enums with Cow
To automatically convert Type<'a>
to Type<'static>
and more.
Example
This can be very helpful for types which use borrow with serde.
#[derive(IntoOwned, ToBorrowed, ToOwned)]
// #[derive(serde::Serialize, serde::Deserialize)]
pub struct Type<'a> {
// #[serde(borrow)]
cow: Cow<'a, str>,
#[ownable(clone)] owned: String, // always clone this field
}
Will derive something functionally similar to:
impl Type<'_> {
/// Copy the structure and clone the original values if it's not owned.
/// This is always a deep copy of the structure.
pub fn into_owned(self) -> Type<'static> {
Type {
cow: Cow::Owned(Cow::into_owned(self.cow)),
owned: self.owned.clone(), // always cloned, as requested
}
}
/// Copy the structure and clone the original values.
/// This is always a deep copy.
pub fn to_owned(&self) -> Type<'static> {
Type {
cow: Cow::Owned(str::to_owned(self.cow.borrow())),
owned: self.owned.clone(), // always cloned, as requested
}
}
/// Copy the structure and reference the original values.
/// This is always a deep copy of the structure.
pub fn to_borrowed(&self) -> Type {
Type {
cow: Cow::Borrowed(self.cow.borrow()),
owned: self.owned.clone(), // always cloned, as requested
}
}
}
But actually each function only calls a function of traits, which are derived.
If the derive does not work it can be implemented by hand and still derived for types which use it.
Generics
The derive macro supports all kinds of generics: lifetimes, types, consts. And the first two with bounds and all as many times as you want.
References
References are not supported out of the box, because they can't be changed into an owned type.
But it's possible to specify which lifetime(s) are used solely for references and then those will be always copied (the reference) and thus the lifetime is not changed.
Please note that not only the type containing a reference but also types containing such a type are required to be marked.
Example
#[derive(IntoOwned, ToBorrowed, ToOwned)]
#[ownable(reference = "'b")]
pub struct Inner<'a, 'b> {
cow: Cow<'a, str>,
referenced: &'b str,
}
// Also types, containing types with references, must be marked.
#[derive(IntoOwned, ToBorrowed, ToOwned)]
#[ownable(reference = "'b")]
pub struct Outer<'a, 'b> {
inner: Inner<'a, 'b>,
}
Will derive functions with these signatures:
impl<'b> Inner<'_, 'b> {
pub fn into_owned(self) -> Inner<'static, 'b> {
// Call the trait, which is also derived
}
pub fn to_owned(&self) -> Inner<'static, 'b> {
// Call the trait, which is also derived
}
pub fn to_borrowed(&self) -> Inner<'_, 'b> {
// Call the trait, which is also derived
}
}
// The `Outer` will look similar.
Possible Errors
If the following error occurs then one of the fields has a missing trait.
error[E0277]: the trait bound `String: IntoOwned` is not satisfied
This can sometimes be fixed with #[ownable(clone)]
as seen in the example above,
otherwise AsCopy
/AsClone
can help.
And as the last resort the impl for the surrounding structure can be hand written.
Attributes
clone
With #[ownable(clone)]
and #[ownable(clone = false|true)]
it's possible to denote that this
enum|struct/variant/field should always be cloned. It can be overwritten (i.e. set to true at
top level and then false at the fields to not be cloned).
For an example see the at the top.
function
With #[ownable(function = false)]
at top level (enum/struct) the functions mentioned above
are not implemented, only the traits.
reference
With #[ownable(reference = "..")]
one or more comma separated lifetimes can be supplied to
be used for references only, see References above.
AsCopy/AsClone
If the impls for the copy types are not enough or #[ownable(clone)]
does not work in that
position then AsCopy
and AsClone
can be used to wrap a value which then
works in this environment as expected. Both are transparent and do use only exact the same
space as the original type and all impls (Eq, Display, Hash, ...) only pass the calls though
to the inner type
Example
Example of an more complex type:
#[derive(IntoOwned, ToBorrowed, ToOwned)]
pub struct Type<'a> {
cow: Cow<'a, str>,
nested: Option<Box<Type<'a>>>,
map: HashMap<AsClone<String>, Cow<'a, str>>,
#[ownable(clone)] owned: String, // always clone this field
number: usize, // many copy types have a trait impl, and thus can be used without the `#[ownable(clone)]`
}
Features
std
- Traits are also implemented for types which are not in core or alloc (currentlyHashMap
andHashSet
).
std
is enabled by default.
Usage
With defaults (includes std
):
[dependencies]
ownable = "0.5"
With no_std
(but still requires alloc):
[dependencies]
ownable = { version = "0.5", default-features = false }
License
This project is licensed under either of
at your option.
Contributing
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~275–730KB
~17K SLoC