Into Conversions In-Depth
Preface
This is the continuation of the "Into conversions" section from the general overview page. This page describes the important caveats of using impl Into that you should know before enabling them.
Make sure you are familiar with the standard From and Into traits before you proceed. Reading their docs is pretty much enough. For example, you should know that every type that implements From<T> automatically implements Into<T>. Also, you should know that you can pass a value of type T at no cost directly to a function that accepts impl Into<T> thanks to this blanket impl in std.
WARNING
This is generally a controversial topic 🐱. Some people like to be more explicit, but others prefer the shorter notation. This also depends on the kind of code you are writing.
If you prefer being explicit in code, feel free not to use Into conversions at all. They are fully opt-in. This article isn't prescriptive. The syntax savings are arguably small, so use your best judgement, and refer to this page if you can't decide.
We'll cover the following:
Use Into conversions
The main advantage of impl Into in setters is that it reduces the boilerplate for the caller. The code becomes shorter and cleaner, although not without the drawbacks.
Into conversions usually make sense only if all of the following are true (AND):
The Rules of Into
- The code where the builder is supposed to be used is not performance-sensitive.
- The builder is going to be used with literal values a lot or require wrapping the values.
Shorter syntax for literals
Here is an example that shows the non-exhaustive list of standard types where it's usually fine to enable Into conversions.
TIP
Switch between the UI tabs in the code snippets below to see how the code looks like with Into Conversions enabled and with the Default syntax.
use bon::Builder;
#[derive(Builder)]
struct Example {
#[builder(into)]
string: String,
#[builder(into)]
path_buf: std::path::PathBuf,
#[builder(into)]
ip_addr: std::net::IpAddr,
}
Example::builder()
// We can pass `&str` literal
.string("string literal")
// We can pass `&str` literal or a String
.path_buf("string/literal")
// We can pass an array of IP components or `Ipv4Addr` or `Ipv6Addr`
.ip_addr([127, 0, 0, 1])
.build();use bon::Builder;
#[derive(Builder)]
struct Example {
// No attributes
string: String,
// No attributes
path_buf: std::path::PathBuf,
// No attributes
ip_addr: std::net::IpAddr,
}
Example::builder()
// We have to convert `&str -> String` manually
.string("string literal".to_owned())
// We have to convert `&str -> PathBuf` manually
.path_buf("string/literal".into())
// We have to convert `[u8; 4] -> IpAddr` manually
.ip_addr([127, 0, 0, 1].into())
.build();Automatic enum wrapping
If you are working with enums a lot, you may implement the From<EnumVariant> for your enum and avoid wrapping your enum variants when passing them to the builder. Pay attention to the difference in the focused code below.
use bon::builder;
#[builder]
fn evaluate(#[builder(into)] expr: Expr) { /* */ }
evaluate()
.expr(BinaryExpr {
/* */
})
.call();
enum Expr {
Binary(BinaryExpr),
Unary(UnaryExpr)
}
struct BinaryExpr { /* */ }
struct UnaryExpr { /* */ }
impl From<BinaryExpr> for Expr {
fn from(expr: BinaryExpr) -> Self {
Self::Binary(expr)
}
}
impl From<UnaryExpr> for Expr {
fn from(expr: UnaryExpr) -> Self {
Self::Unary(expr)
}
}use bon::builder;
#[builder]
fn evaluate(expr: Expr) { /* */ }
evaluate()
.expr(Expr::Binary(BinaryExpr {
/* */
}))
.call();
enum Expr {
Binary(BinaryExpr),
Unary(UnaryExpr)
}
struct BinaryExpr { /* */ }
struct UnaryExpr { /* */ }
impl From<BinaryExpr> for Expr {
fn from(expr: BinaryExpr) -> Self {
Self::Binary(expr)
}
}
impl From<UnaryExpr> for Expr {
fn from(expr: UnaryExpr) -> Self {
Self::Unary(expr)
}
}As you can see, the difference isn't significant in this case. It makes more sense when you have deeply nested enums.
Avoid Into conversions
Performance-sensitive code
If allocations can pose a bottleneck for your application and you need to see every place in code where an allocation is performed, you should avoid using impl Into overall. It can lead to implicitly moving data to the heap or cloning it.
Example:
use bon::builder;
#[builder]
fn process_heavy_json(#[builder(into)] data: String) { /* */ }
let json = String::from(
r#"{
"key": "Pretend this is a huge JSON string with hundreds of MB in size"
}"#
);
process_heavy_json()
// Whoops, we passed a `&String`.
// The builder will clone the data internally.
.data(&json)
.call();The problem here is that we unintentionally passed a String by reference instead of moving the ownership of the String to process_heavy_json(). This code implicitly uses this From impl from the standard library.
Primitive numeric literals
impl Into breaks type inference for numeric literal values. For example, the following code doesn't compile.
fn half(x: impl Into<u32>) -> u32 {
x.into() / 2
}
half(10); The compile error is the following (Rust playground link):
half(10);
---- ^^ the trait `std::convert::From<i32>` is not implemented for `u32`,
| which is required by `{integer}: std::convert::Into<u32>`
|
required by a bound introduced by this callThe reason for this error is that rustc can't infer the type for the numeric literal 10 because it could be one of the following types: u8, u16, u32, which all implement Into<u32>. There isn't a suffix like 10_u16 in this code to tell the compiler the type of the numeric literal 10. When the compiler can't infer the type of a numeric literal it falls back to assigning the type i32 for an integer literal and f64 for a floating point literal. In this case i32 is inferred, which isn't convertible to u32.
Requiring an explicit type suffix in numeric literals would be the opposite of good ergonomics that impl Into is trying to achieve in the first place.
Weakened generics inference
If you have a function that returns a generic type, then the compiler needs to infer that generic type from usage unless it's specified explicitly. A classic example of such a function is str::parse() or serde_json::from_str().
Example:
use bon::builder;
use std::net::IpAddr;
#[builder]
fn connect(ip_addr: IpAddr) { /* */ }
let ip_addr = "127.0.0.1".parse().unwrap();
connect()
.ip_addr(ip_addr)
.call();Notice how we didn't add a type annotation for the variable ip_addr. The compiler can deduce (infer) the type of ip_addr because it sees that the variable is passed to the ip_addr() setter method that expects a parameter of type IpAddr. It's a really simple exercise for the compiler in this case because all the context to solve it is there.
However, if you use an Into conversion, not even Sherlock Holmes can answer the question "What type did you intend to parse?":
use bon::builder;
use std::net::IpAddr;
#[builder]
fn connect(ip_addr: IpAddr) { /* */ }
fn connect(#[builder(into)] ip_addr: IpAddr) { /* */ }
let ip_addr = "127.0.0.1".parse().unwrap();
connect()
.ip_addr(ip_addr)
.call();In this case, there is a compile error:
error[E0284]: type annotations needed
|
9 | let ip_addr = "127.0.0.1".parse().unwrap();
| ^^^^^^^ ----- type must be known at this point
|
= note: cannot satisfy `<_ as std::str::FromStr>::Err == _`
help: consider giving `ip_addr` an explicit type
|
9 | let ip_addr: /* Type */ = "127.0.0.1".parse().unwrap();
| ++++++++++++This is because now the ip_addr setter looks like this:
fn ip_addr(self, value: impl Into<IpAddr>) -> NextBuilderState { /* */ }This signature implies that the value parameter can be of any type that implements Into<IpAddr>. There are several types that implement such a trait. Among them: Ipv4Addr and Ipv6Addr, and, obviously, IpAddr itself (thanks to this blanket impl).
This means the setter for ip_addr can no longer hint the compiler a single type that it accepts. Thus the compiler can't decide which type to assign to the ip_addr variable in the original code, because there can be many that make sense. I.e. the code will compile if any of the Ipv4Addr or Ipv6Addr or IpAddr type annotations are added to the ip_addr variable, but the compiler has no right to decide which of them to use on your behalf.
This is the drawback of using not only impl Into, but any generics at all.
None literals inference
impl Into breaks type inference for None literals. For example, this code doesn't use Into conversions and compiles fine:
use bon::Builder;
#[derive(Builder)]
struct Example {
member: Option<String>
}
Example::builder()
// Suppose we want to be explicit about omitting the `member`,
// so we intentionally invoke the `maybe_` setter and pass `None` to it
.maybe_member(None)
.build();Now, let's enable an Into conversion for the member:
use bon::Builder;
#[derive(Builder)]
struct Example {
#[builder(into)]
member: Option<String>
}
Example::builder()
.maybe_member(None)
.build();When we compile this code we get the following error:
.maybe_member(None)
------------ ^^^^ cannot infer type of the type parameter `T`
declared on the enum `Option`The problem here is that the compiler doesn't know the complete type of the None literal. It definitely knows that it's a value of type Option<_>, but it doesn't know what type to use in place of the _. There could be many potential candidates for the _ inside of the Option<_>. This is because the signature of the maybe_member() setter changed:
fn maybe_member(self, value: Option<String>) -> NextBuilderState
fn maybe_member(self, value: Option<impl Into<String>>) -> NextBuilderStateBefore we enabled Into conversions the signature provided a hint for the compiler because the setter expected a single concrete type Option<String>, so it was obvious that the None literal was of type Option<String>.
However, after we enabled Into conversions, the signature no longer provides a single concrete type. It says that it accepts an Option of any type that implements Into<String>.
It means that the None literal could be of types Option<&str> or Option<String>, for example, so the compiler can't decide which one you meant. And this matters, because Option<&str> and Option<String> are totally different types. Simplified, Option<&str> is 16 bytes in size and Option<String> is 24 bytes, even when they are None.
To work around this problem the caller would need to explicitly specify the generic parameter for the Option type when passing the None literal:
use bon::Builder;
#[derive(Builder)]
struct Example {
#[builder(into)]
member: Option<String>
}
Example::builder()
.maybe_member(None::<String>)
.build();Code complexity
This is quite subjective, but impl Into<T> is a bit harder to read than just T. It makes the signature of the setter slightly bigger and requires you to understand what the impl Trait does, and what its implications are.
If you want to keep your code simpler and more accessible (especially for beginner rustaceans), just avoid the Into conversions.