2 unstable releases
0.2.0 | Sep 22, 2024 |
---|---|
0.1.0 | Sep 20, 2024 |
#453 in Rust patterns
59 downloads per month
83KB
1K
SLoC
Supply
Provider API for arbitrary number of lifetimes.
supply
implements an API similar to that proposed in
RFC 3192. It allows
accessing data based on type tags. Expanding on RFC 3192, supply
allows accessing data with an arbitrary number of lifetimes. Additionally,
supply
allows for multiple values to be requested at once.
supply
also builds on the Any
API to allow arbitrary number
of lifetimes in type erased trait objects. Combined almost any need for passing
data between type erased components should be easy to implement.
It is recommended to use the prelude which has the common API elements.
use supply::prelude::*;
Most users should start with implementing the [Provider
] trait on one or more
types they want to expose extra information from. Then the .request::<T>()
method
can be used to request a specific type of information from the provider. This
is the core API flow of supply
. Below is an example with a couple of the more advanced
features for demonstration. See the [provide
] module for a more detailed guide.
For users looking for a more powerful Any
, you should see the
[anything
] module for a guide on using [Anything
].
use supply::prelude::*;
use supply::tag::AddLt;
struct Person<'a> {
name: &'a str,
age: u8,
}
// Implementing Provider allows requesting data from a Person value.
impl<'r, 'a> Provider<'r> for Person<'a> {
type Lifetimes = l!['a];
fn provide(&'r self, want: &mut dyn Want<Self::Lifetimes>) {
// Provide the name and age fields.
want.provide_tag::<&str>(self.name)
.provide_value(self.age);
}
}
// Make an example person to request data from.
let name = String::from("bob");
let provided_name;
{
let person = Person {
name: &name,
age: 42,
};
// Convert to a trait object to show Provider is object safe.
let provider: &dyn ProviderDyn<l!['_]> = &person;
// Request the person's name.
provided_name = provider.request::<&str>();
assert_eq!(provided_name, Some("bob"));
// Request the person's age.
let provided_age = provider.request::<u8>();
assert_eq!(provided_age, Some(42));
// Request something Person doesn't provide.
// We just don't get a value from the request.
let provided_something = provider.request::<f32>();
assert_eq!(provided_something, None);
};
// Because the name was tagged as &'a str we can still access it here.
assert_eq!(provided_name, Some("bob"));
Alternatives
core
/std
No surprise but the [core::any
] module exists, and its very good if you just need
to work with 'static
types.
Additionally, [Error
][core::error::Error] has the unstable provide API (derived from RFC 3192).
However, this implementation of provide is limited to error types and has only the lifetime of
the source value available.
Mapping to supply
's API
Click to show
1. In core/std, this function is implemented independently for multiple types.2. In supply, Want is a trait instead of a struct for more flexibility.
no_std
Support
This crate is #![no_std]
by default, it can be used anywhere Rust can.
Minimum Supported Rust Version
Requires Rust 1.79.0.
This crate follows the "Latest stable Rust" policy. The listed MSRV won't be changed unless needed. However, updating the MSRV anywhere up to the latest stable at time of release is allowed.
Contributing
Contributions in any form (issues, pull requests, etc.) to this project must adhere to Rust's Code of Conduct.
Unless you explicitly state otherwise, any contribution intentionally submitted for
inclusion in supply
by you shall be licensed as below, without any
additional terms or conditions.
License
This project is licensed under either of
at your option.