2022-01-18 22:40:27 +00:00
|
|
|
|
<!-- DO NOT EDIT THIS FILE.
|
|
|
|
|
|
|
|
|
|
This file is periodically generated from the content in the `/src/`
|
|
|
|
|
directory, so all fixes need to be made in `/src/`.
|
|
|
|
|
-->
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
[TOC]
|
|
|
|
|
|
|
|
|
|
# Generic Types, Traits, and Lifetimes
|
|
|
|
|
|
|
|
|
|
Every programming language has tools for effectively handling the duplication
|
2022-03-11 01:33:08 +00:00
|
|
|
|
of concepts. In Rust, one such tool is *generics*: abstract stand-ins for
|
|
|
|
|
concrete types or other properties. We can express the behavior of generics or
|
|
|
|
|
how they relate to other generics without knowing what will be in their place
|
|
|
|
|
when compiling and running the code.
|
|
|
|
|
|
|
|
|
|
Functions can take parameters of some generic type, instead of a concrete type
|
2022-08-20 13:24:57 +00:00
|
|
|
|
like `i32` or `String`, in the same way they take parameters with unknown
|
|
|
|
|
values to run the same code on multiple concrete values. In fact, we’ve already
|
2022-08-24 13:12:29 +00:00
|
|
|
|
used generics in Chapter 6 with `Option<T>`, in Chapter 8 with `Vec<T>` and
|
|
|
|
|
`HashMap<K, V>`, and in Chapter 9 with `Result<T, E>`. In this chapter, you’ll
|
2021-11-15 03:06:18 +00:00
|
|
|
|
explore how to define your own types, functions, and methods with generics!
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
First we’ll review how to extract a function to reduce code duplication. We’ll
|
2022-03-11 01:33:08 +00:00
|
|
|
|
then use the same technique to make a generic function from two functions that
|
2021-11-15 03:06:18 +00:00
|
|
|
|
differ only in the types of their parameters. We’ll also explain how to use
|
|
|
|
|
generic types in struct and enum definitions.
|
|
|
|
|
|
|
|
|
|
Then you’ll learn how to use *traits* to define behavior in a generic way. You
|
2022-03-11 01:33:08 +00:00
|
|
|
|
can combine traits with generic types to constrain a generic type to accept
|
|
|
|
|
only those types that have a particular behavior, as opposed to just any type.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Finally, we’ll discuss *lifetimes*: a variety of generics that give the
|
2021-11-15 03:06:18 +00:00
|
|
|
|
compiler information about how references relate to each other. Lifetimes allow
|
2022-03-11 01:33:08 +00:00
|
|
|
|
us to give the compiler enough information about borrowed values so that it can
|
|
|
|
|
ensure references will be valid in more situations than it could without our
|
|
|
|
|
help.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
## Removing Duplication by Extracting a Function
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Generics allow us to replace specific types with a placeholder that represents
|
2022-08-20 13:11:14 +00:00
|
|
|
|
multiple types to remove code duplication. Before diving into generics syntax,
|
2022-08-20 13:24:57 +00:00
|
|
|
|
let’s first look at how to remove duplication in a way that doesn’t involve
|
|
|
|
|
generic types by extracting a function that replaces specific values with a
|
|
|
|
|
placeholder that represents multiple values. Then we’ll apply the same
|
2022-08-20 13:11:14 +00:00
|
|
|
|
technique to extract a generic function! By looking at how to recognize
|
|
|
|
|
duplicated code you can extract into a function, you’ll start to recognize
|
|
|
|
|
duplicated code that can use generics.
|
2022-03-11 01:33:08 +00:00
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
We’ll begin with the short program in Listing 10-1 that finds the largest
|
|
|
|
|
number in a list.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn main() {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
1 let number_list = vec![34, 50, 25, 100, 65];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
2 let mut largest = &number_list[0];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
3 for number in &number_list {
|
|
|
|
|
4 if number > largest {
|
|
|
|
|
5 largest = number;
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest number is {largest}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-1: Finding the largest number in a list of numbers
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
We store a list of integers in the variable `number_list` [1] and place a
|
|
|
|
|
reference to the first number in the list in a variable named `largest` [2]. We
|
|
|
|
|
then iterate through all the numbers in the list [3], and if the current number
|
|
|
|
|
is greater than the number stored in `largest` [4], we replace the reference in
|
|
|
|
|
that variable [5]. However, if the current number is less than or equal to the
|
|
|
|
|
largest number seen so far, the variable doesn’t change, and the code moves on
|
|
|
|
|
to the next number in the list. After considering all the numbers in the list,
|
|
|
|
|
`largest` should refer to the largest number, which in this case is 100.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
We’ve now been tasked with finding the largest number in two different lists of
|
2022-03-11 01:33:08 +00:00
|
|
|
|
numbers. To do so, we can choose to duplicate the code in Listing 10-1 and use
|
|
|
|
|
the same logic at two different places in the program, as shown in Listing 10-2.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn main() {
|
|
|
|
|
let number_list = vec![34, 50, 25, 100, 65];
|
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
let mut largest = &number_list[0];
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
for number in &number_list {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
if number > largest {
|
|
|
|
|
largest = number;
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest number is {largest}");
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
let mut largest = &number_list[0];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
for number in &number_list {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
if number > largest {
|
|
|
|
|
largest = number;
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest number is {largest}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-2: Code to find the largest number in *two* lists of numbers
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Although this code works, duplicating code is tedious and error prone. We also
|
2022-03-11 01:33:08 +00:00
|
|
|
|
have to remember to update the code in multiple places when we want to change
|
|
|
|
|
it.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
To eliminate this duplication, we’ll create an abstraction by defining a
|
|
|
|
|
function that operates on any list of integers passed in a parameter. This
|
2021-11-15 03:06:18 +00:00
|
|
|
|
solution makes our code clearer and lets us express the concept of finding the
|
|
|
|
|
largest number in a list abstractly.
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
In Listing 10-3, we extract the code that finds the largest number into a
|
|
|
|
|
function named `largest`. Then we call the function to find the largest number
|
|
|
|
|
in the two lists from Listing 10-2. We could also use the function on any other
|
|
|
|
|
list of `i32` values we might have in the future.
|
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
2022-06-02 01:00:53 +00:00
|
|
|
|
fn largest(list: &[i32]) -> &i32 {
|
|
|
|
|
let mut largest = &list[0];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
for item in list {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
if item > largest {
|
|
|
|
|
largest = item;
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
largest
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
|
|
|
|
let number_list = vec![34, 50, 25, 100, 65];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
let result = largest(&number_list);
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest number is {result}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
let result = largest(&number_list);
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest number is {result}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-3: Abstracted code to find the largest number in two lists
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
The `largest` function has a parameter called `list`, which represents any
|
2022-03-11 01:33:08 +00:00
|
|
|
|
concrete slice of `i32` values we might pass into the function. As a result,
|
2022-08-20 13:24:57 +00:00
|
|
|
|
when we call the function, the code runs on the specific values that we pass in.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
In summary, here are the steps we took to change the code from Listing 10-2 to
|
2021-11-15 03:06:18 +00:00
|
|
|
|
Listing 10-3:
|
|
|
|
|
|
|
|
|
|
1. Identify duplicate code.
|
2022-08-24 13:12:29 +00:00
|
|
|
|
1. Extract the duplicate code into the body of the function, and specify the
|
2022-08-20 13:24:57 +00:00
|
|
|
|
inputs and return values of that code in the function signature.
|
|
|
|
|
1. Update the two instances of duplicated code to call the function instead.
|
2022-09-13 17:38:46 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Next, we’ll use these same steps with generics to reduce code duplication. In
|
|
|
|
|
the same way that the function body can operate on an abstract `list` instead
|
|
|
|
|
of specific values, generics allow code to operate on abstract types.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
For example, say we had two functions: one that finds the largest item in a
|
|
|
|
|
slice of `i32` values and one that finds the largest item in a slice of `char`
|
|
|
|
|
values. How would we eliminate that duplication? Let’s find out!
|
|
|
|
|
|
|
|
|
|
## Generic Data Types
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
We use generics to create definitions for items like function signatures or
|
2021-11-15 03:06:18 +00:00
|
|
|
|
structs, which we can then use with many different concrete data types. Let’s
|
|
|
|
|
first look at how to define functions, structs, enums, and methods using
|
|
|
|
|
generics. Then we’ll discuss how generics affect code performance.
|
|
|
|
|
|
|
|
|
|
### In Function Definitions
|
|
|
|
|
|
|
|
|
|
When defining a function that uses generics, we place the generics in the
|
|
|
|
|
signature of the function where we would usually specify the data types of the
|
|
|
|
|
parameters and return value. Doing so makes our code more flexible and provides
|
|
|
|
|
more functionality to callers of our function while preventing code duplication.
|
|
|
|
|
|
|
|
|
|
Continuing with our `largest` function, Listing 10-4 shows two functions that
|
2022-08-20 13:24:57 +00:00
|
|
|
|
both find the largest value in a slice. We’ll then combine these into a single
|
2022-03-11 01:33:08 +00:00
|
|
|
|
function that uses generics.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
2022-06-02 01:00:53 +00:00
|
|
|
|
fn largest_i32(list: &[i32]) -> &i32 {
|
|
|
|
|
let mut largest = &list[0];
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
for item in list {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
if item > largest {
|
|
|
|
|
largest = item;
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
largest
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
fn largest_char(list: &[char]) -> &char {
|
|
|
|
|
let mut largest = &list[0];
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
for item in list {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
if item > largest {
|
|
|
|
|
largest = item;
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
largest
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
|
|
|
|
let number_list = vec![34, 50, 25, 100, 65];
|
|
|
|
|
|
|
|
|
|
let result = largest_i32(&number_list);
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest number is {result}");
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
let char_list = vec!['y', 'm', 'a', 'q'];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
let result = largest_char(&char_list);
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest char is {result}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-4: Two functions that differ only in their names and in the types in
|
|
|
|
|
their signatures
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
The `largest_i32` function is the one we extracted in Listing 10-3 that finds
|
|
|
|
|
the largest `i32` in a slice. The `largest_char` function finds the largest
|
|
|
|
|
`char` in a slice. The function bodies have the same code, so let’s eliminate
|
|
|
|
|
the duplication by introducing a generic type parameter in a single function.
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
To parameterize the types in a new single function, we need to name the type
|
|
|
|
|
parameter, just as we do for the value parameters to a function. You can use
|
|
|
|
|
any identifier as a type parameter name. But we’ll use `T` because, by
|
2022-08-20 13:24:57 +00:00
|
|
|
|
convention, type parameter names in Rust are short, often just one letter, and
|
2022-08-24 13:12:29 +00:00
|
|
|
|
Rust’s type-naming convention is CamelCase. Short for *type*, `T` is the
|
2022-08-20 13:11:14 +00:00
|
|
|
|
default choice of most Rust programmers.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
When we use a parameter in the body of the function, we have to declare the
|
|
|
|
|
parameter name in the signature so the compiler knows what that name means.
|
|
|
|
|
Similarly, when we use a type parameter name in a function signature, we have
|
|
|
|
|
to declare the type parameter name before we use it. To define the generic
|
2022-08-20 13:24:57 +00:00
|
|
|
|
`largest` function, we place type name declarations inside angle brackets,
|
|
|
|
|
`<>`, between the name of the function and the parameter list, like this:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
2022-06-02 01:00:53 +00:00
|
|
|
|
fn largest<T>(list: &[T]) -> &T {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
We read this definition as: the function `largest` is generic over some type
|
|
|
|
|
`T`. This function has one parameter named `list`, which is a slice of values
|
2022-06-02 01:00:53 +00:00
|
|
|
|
of type `T`. The `largest` function will return a reference to a value of the
|
2021-11-15 03:06:18 +00:00
|
|
|
|
same type `T`.
|
|
|
|
|
|
|
|
|
|
Listing 10-5 shows the combined `largest` function definition using the generic
|
|
|
|
|
data type in its signature. The listing also shows how we can call the function
|
|
|
|
|
with either a slice of `i32` values or `char` values. Note that this code won’t
|
|
|
|
|
compile yet, but we’ll fix it later in this chapter.
|
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
2022-06-02 01:00:53 +00:00
|
|
|
|
fn largest<T>(list: &[T]) -> &T {
|
|
|
|
|
let mut largest = &list[0];
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
for item in list {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
if item > largest {
|
|
|
|
|
largest = item;
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
largest
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
fn main() {
|
|
|
|
|
let number_list = vec![34, 50, 25, 100, 65];
|
|
|
|
|
|
|
|
|
|
let result = largest(&number_list);
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest number is {result}");
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
let char_list = vec!['y', 'm', 'a', 'q'];
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
let result = largest(&char_list);
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The largest char is {result}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-5: The `largest` function using generic type parameters; this
|
|
|
|
|
doesn’t compile yet
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
If we compile this code right now, we’ll get this error:
|
|
|
|
|
|
|
|
|
|
```
|
2022-08-20 13:11:14 +00:00
|
|
|
|
error[E0369]: binary operation `>` cannot be applied to type `&T`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
--> src/main.rs:5:17
|
|
|
|
|
|
|
|
|
|
|
5 | if item > largest {
|
2022-08-20 13:11:14 +00:00
|
|
|
|
| ---- ^ ------- &T
|
2021-11-15 03:06:18 +00:00
|
|
|
|
| |
|
2022-08-20 13:11:14 +00:00
|
|
|
|
| &T
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
|
help: consider restricting type parameter `T`
|
|
|
|
|
|
|
2022-08-20 13:11:14 +00:00
|
|
|
|
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T {
|
|
|
|
|
| ++++++++++++++++++++++
|
2021-11-15 03:06:18 +00:00
|
|
|
|
```
|
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
The help text mentions `std::cmp::PartialOrd`, which is a *trait*, and we’re
|
|
|
|
|
going to talk about traits in the next section. For now, know that this error
|
|
|
|
|
states that the body of `largest` won’t work for all possible types that `T`
|
|
|
|
|
could be. Because we want to compare values of type `T` in the body, we can
|
|
|
|
|
only use types whose values can be ordered. To enable comparisons, the standard
|
|
|
|
|
library has the `std::cmp::PartialOrd` trait that you can implement on types
|
2022-08-20 13:24:57 +00:00
|
|
|
|
(see Appendix C for more on this trait). By following the help text’s
|
2022-06-02 01:00:53 +00:00
|
|
|
|
suggestion, we restrict the types valid for `T` to only those that implement
|
|
|
|
|
`PartialOrd` and this example will compile, because the standard library
|
|
|
|
|
implements `PartialOrd` on both `i32` and `char`.
|
2022-03-11 01:33:08 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
### In Struct Definitions
|
|
|
|
|
|
|
|
|
|
We can also define structs to use a generic type parameter in one or more
|
2022-03-11 01:33:08 +00:00
|
|
|
|
fields using the `<>` syntax. Listing 10-6 defines a `Point<T>` struct to hold
|
|
|
|
|
`x` and `y` coordinate values of any type.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
2022-08-21 01:02:46 +00:00
|
|
|
|
1 struct Point<T> {
|
|
|
|
|
2 x: T,
|
|
|
|
|
3 y: T,
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
|
|
|
|
let integer = Point { x: 5, y: 10 };
|
|
|
|
|
let float = Point { x: 1.0, y: 4.0 };
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-6: A `Point<T>` struct that holds `x` and `y` values of type `T`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
The syntax for using generics in struct definitions is similar to that used in
|
2022-08-20 13:24:57 +00:00
|
|
|
|
function definitions. First we declare the name of the type parameter inside
|
2022-08-21 01:02:46 +00:00
|
|
|
|
angle brackets just after the name of the struct [1]. Then we use the generic
|
|
|
|
|
type in the struct definition where we would otherwise specify concrete data
|
|
|
|
|
types [23].
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Note that because we’ve used only one generic type to define `Point<T>`, this
|
|
|
|
|
definition says that the `Point<T>` struct is generic over some type `T`, and
|
|
|
|
|
the fields `x` and `y` are *both* that same type, whatever that type may be. If
|
|
|
|
|
we create an instance of a `Point<T>` that has values of different types, as in
|
|
|
|
|
Listing 10-7, our code won’t compile.
|
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
struct Point<T> {
|
|
|
|
|
x: T,
|
|
|
|
|
y: T,
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
fn main() {
|
|
|
|
|
let wont_work = Point { x: 5, y: 4.0 };
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-7: The fields `x` and `y` must be the same type because both have
|
|
|
|
|
the same generic data type `T`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-08-24 13:12:29 +00:00
|
|
|
|
In this example, when we assign the integer value `5` to `x`, we let the
|
|
|
|
|
compiler know that the generic type `T` will be an integer for this instance of
|
|
|
|
|
`Point<T>`. Then when we specify `4.0` for `y`, which we’ve defined to have the
|
2021-11-15 03:06:18 +00:00
|
|
|
|
same type as `x`, we’ll get a type mismatch error like this:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
error[E0308]: mismatched types
|
|
|
|
|
--> src/main.rs:7:38
|
|
|
|
|
|
|
|
|
|
|
7 | let wont_work = Point { x: 5, y: 4.0 };
|
2022-08-21 01:02:46 +00:00
|
|
|
|
| ^^^ expected integer, found floating-
|
|
|
|
|
point number
|
2021-11-15 03:06:18 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
To define a `Point` struct where `x` and `y` are both generics but could have
|
|
|
|
|
different types, we can use multiple generic type parameters. For example, in
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Listing 10-8, we change the definition of `Point` to be generic over types `T`
|
|
|
|
|
and `U` where `x` is of type `T` and `y` is of type `U`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
struct Point<T, U> {
|
|
|
|
|
x: T,
|
|
|
|
|
y: U,
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
|
|
|
|
let both_integer = Point { x: 5, y: 10 };
|
|
|
|
|
let both_float = Point { x: 1.0, y: 4.0 };
|
|
|
|
|
let integer_and_float = Point { x: 5, y: 4.0 };
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-8: A `Point<T, U>` generic over two types so that `x` and `y` can be
|
|
|
|
|
values of different types
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Now all the instances of `Point` shown are allowed! You can use as many generic
|
|
|
|
|
type parameters in a definition as you want, but using more than a few makes
|
2022-08-20 13:24:57 +00:00
|
|
|
|
your code hard to read. If you’re finding you need lots of generic types in
|
2022-03-11 01:33:08 +00:00
|
|
|
|
your code, it could indicate that your code needs restructuring into smaller
|
|
|
|
|
pieces.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### In Enum Definitions
|
|
|
|
|
|
|
|
|
|
As we did with structs, we can define enums to hold generic data types in their
|
|
|
|
|
variants. Let’s take another look at the `Option<T>` enum that the standard
|
|
|
|
|
library provides, which we used in Chapter 6:
|
|
|
|
|
|
|
|
|
|
```
|
2022-08-20 13:24:57 +00:00
|
|
|
|
enum Option<T> {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
Some(T),
|
|
|
|
|
None,
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
This definition should now make more sense to you. As you can see, the
|
|
|
|
|
`Option<T>` enum is generic over type `T` and has two variants: `Some`, which
|
2021-11-15 03:06:18 +00:00
|
|
|
|
holds one value of type `T`, and a `None` variant that doesn’t hold any value.
|
2022-03-11 01:33:08 +00:00
|
|
|
|
By using the `Option<T>` enum, we can express the abstract concept of an
|
2021-11-15 03:06:18 +00:00
|
|
|
|
optional value, and because `Option<T>` is generic, we can use this abstraction
|
|
|
|
|
no matter what the type of the optional value is.
|
|
|
|
|
|
|
|
|
|
Enums can use multiple generic types as well. The definition of the `Result`
|
|
|
|
|
enum that we used in Chapter 9 is one example:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
enum Result<T, E> {
|
|
|
|
|
Ok(T),
|
|
|
|
|
Err(E),
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The `Result` enum is generic over two types, `T` and `E`, and has two variants:
|
|
|
|
|
`Ok`, which holds a value of type `T`, and `Err`, which holds a value of type
|
|
|
|
|
`E`. This definition makes it convenient to use the `Result` enum anywhere we
|
|
|
|
|
have an operation that might succeed (return a value of some type `T`) or fail
|
|
|
|
|
(return an error of some type `E`). In fact, this is what we used to open a
|
|
|
|
|
file in Listing 9-3, where `T` was filled in with the type `std::fs::File` when
|
|
|
|
|
the file was opened successfully and `E` was filled in with the type
|
|
|
|
|
`std::io::Error` when there were problems opening the file.
|
|
|
|
|
|
|
|
|
|
When you recognize situations in your code with multiple struct or enum
|
|
|
|
|
definitions that differ only in the types of the values they hold, you can
|
|
|
|
|
avoid duplication by using generic types instead.
|
|
|
|
|
|
|
|
|
|
### In Method Definitions
|
|
|
|
|
|
|
|
|
|
We can implement methods on structs and enums (as we did in Chapter 5) and use
|
2022-08-20 13:24:57 +00:00
|
|
|
|
generic types in their definitions too. Listing 10-9 shows the `Point<T>`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
struct we defined in Listing 10-6 with a method named `x` implemented on it.
|
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
struct Point<T> {
|
|
|
|
|
x: T,
|
|
|
|
|
y: T,
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
impl<T> Point<T> {
|
|
|
|
|
fn x(&self) -> &T {
|
|
|
|
|
&self.x
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
2022-09-13 16:04:18 +00:00
|
|
|
|
let p = Point { x: 5, y: 10 };
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
println!("p.x = {}", p.x());
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-9: Implementing a method named `x` on the `Point<T>` struct that
|
|
|
|
|
will return a reference to the `x` field of type `T`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Here, we’ve defined a method named `x` on `Point<T>` that returns a reference
|
|
|
|
|
to the data in the field `x`.
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Note that we have to declare `T` just after `impl` so we can use `T` to specify
|
2021-11-15 03:06:18 +00:00
|
|
|
|
that we’re implementing methods on the type `Point<T>`. By declaring `T` as a
|
|
|
|
|
generic type after `impl`, Rust can identify that the type in the angle
|
2022-03-11 01:33:08 +00:00
|
|
|
|
brackets in `Point` is a generic type rather than a concrete type. We could
|
|
|
|
|
have chosen a different name for this generic parameter than the generic
|
|
|
|
|
parameter declared in the struct definition, but using the same name is
|
|
|
|
|
conventional. Methods written within an `impl` that declares the generic type
|
|
|
|
|
will be defined on any instance of the type, no matter what concrete type ends
|
|
|
|
|
up substituting for the generic type.
|
|
|
|
|
|
|
|
|
|
We can also specify constraints on generic types when defining methods on the
|
|
|
|
|
type. We could, for example, implement methods only on `Point<f32>` instances
|
|
|
|
|
rather than on `Point<T>` instances with any generic type. In Listing 10-10 we
|
|
|
|
|
use the concrete type `f32`, meaning we don’t declare any types after `impl`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
impl Point<f32> {
|
|
|
|
|
fn distance_from_origin(&self) -> f32 {
|
|
|
|
|
(self.x.powi(2) + self.y.powi(2)).sqrt()
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-10: An `impl` block that only applies to a struct with a particular
|
|
|
|
|
concrete type for the generic type parameter `T`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
This code means the type `Point<f32>` will have a `distance_from_origin`
|
|
|
|
|
method; other instances of `Point<T>` where `T` is not of type `f32` will not
|
|
|
|
|
have this method defined. The method measures how far our point is from the
|
|
|
|
|
point at coordinates (0.0, 0.0) and uses mathematical operations that are
|
2022-08-20 13:24:57 +00:00
|
|
|
|
available only for floating-point types.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Generic type parameters in a struct definition aren’t always the same as those
|
2022-03-11 01:33:08 +00:00
|
|
|
|
you use in that same struct’s method signatures. Listing 10-11 uses the generic
|
2021-11-15 03:06:18 +00:00
|
|
|
|
types `X1` and `Y1` for the `Point` struct and `X2` `Y2` for the `mixup` method
|
|
|
|
|
signature to make the example clearer. The method creates a new `Point`
|
|
|
|
|
instance with the `x` value from the `self` `Point` (of type `X1`) and the `y`
|
|
|
|
|
value from the passed-in `Point` (of type `Y2`).
|
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
struct Point<X1, Y1> {
|
|
|
|
|
x: X1,
|
|
|
|
|
y: Y1,
|
|
|
|
|
}
|
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
1 impl<X1, Y1> Point<X1, Y1> {
|
2022-09-13 16:04:18 +00:00
|
|
|
|
2 fn mixup<X2, Y2>(
|
|
|
|
|
self,
|
|
|
|
|
other: Point<X2, Y2>,
|
|
|
|
|
) -> Point<X1, Y2> {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
Point {
|
|
|
|
|
x: self.x,
|
|
|
|
|
y: other.y,
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
3 let p1 = Point { x: 5, y: 10.4 };
|
|
|
|
|
4 let p2 = Point { x: "Hello", y: 'c' };
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
5 let p3 = p1.mixup(p2);
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
6 println!("p3.x = {}, p3.y = {}", p3.x, p3.y);
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-11: A method that uses generic types different from its struct’s
|
|
|
|
|
definition
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
In `main`, we’ve defined a `Point` that has an `i32` for `x` (with value `5`)
|
2022-08-21 01:02:46 +00:00
|
|
|
|
and an `f64` for `y` (with value `10.4` [3]). The `p2` variable is a `Point`
|
|
|
|
|
struct that has a string slice for `x` (with value `"Hello"`) and a `char` for
|
|
|
|
|
`y` (with value `c` [4]). Calling `mixup` on `p1` with the argument `p2` gives
|
|
|
|
|
us `p3` [5], which will have an `i32` for `x` because `x` came from `p1`. The
|
|
|
|
|
`p3` variable will have a `char` for `y` because `y` came from `p2`. The
|
|
|
|
|
`println!` macro call [6] will print `p3.x = 5, p3.y = c`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
The purpose of this example is to demonstrate a situation in which some generic
|
|
|
|
|
parameters are declared with `impl` and some are declared with the method
|
|
|
|
|
definition. Here, the generic parameters `X1` and `Y1` are declared after
|
2022-08-21 01:02:46 +00:00
|
|
|
|
`impl` [1] because they go with the struct definition. The generic parameters
|
|
|
|
|
`X2` and `Y2` are declared after `fn mixup` [2] because they’re only relevant
|
|
|
|
|
to the method.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Performance of Code Using Generics
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
You might be wondering whether there is a runtime cost when using generic type
|
2022-08-20 13:24:57 +00:00
|
|
|
|
parameters. The good news is that using generic types won’t make your program
|
2022-08-20 13:11:14 +00:00
|
|
|
|
run any slower than it would with concrete types.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Rust accomplishes this by performing monomorphization of the code using
|
2021-11-15 03:06:18 +00:00
|
|
|
|
generics at compile time. *Monomorphization* is the process of turning generic
|
|
|
|
|
code into specific code by filling in the concrete types that are used when
|
2022-03-11 01:33:08 +00:00
|
|
|
|
compiled. In this process, the compiler does the opposite of the steps we used
|
|
|
|
|
to create the generic function in Listing 10-5: the compiler looks at all the
|
|
|
|
|
places where generic code is called and generates code for the concrete types
|
|
|
|
|
the generic code is called with.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Let’s look at how this works by using the standard library’s generic
|
2021-11-15 03:06:18 +00:00
|
|
|
|
`Option<T>` enum:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
let integer = Some(5);
|
|
|
|
|
let float = Some(5.0);
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
When Rust compiles this code, it performs monomorphization. During that
|
|
|
|
|
process, the compiler reads the values that have been used in `Option<T>`
|
|
|
|
|
instances and identifies two kinds of `Option<T>`: one is `i32` and the other
|
2022-06-02 01:00:53 +00:00
|
|
|
|
is `f64`. As such, it expands the generic definition of `Option<T>` into two
|
|
|
|
|
definitions specialized to `i32` and `f64`, thereby replacing the generic
|
|
|
|
|
definition with the specific ones.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
The monomorphized version of the code looks similar to the following (the
|
|
|
|
|
compiler uses different names than what we’re using here for illustration):
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
enum Option_i32 {
|
|
|
|
|
Some(i32),
|
|
|
|
|
None,
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
enum Option_f64 {
|
|
|
|
|
Some(f64),
|
|
|
|
|
None,
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
|
|
|
|
let integer = Option_i32::Some(5);
|
|
|
|
|
let float = Option_f64::Some(5.0);
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The generic `Option<T>` is replaced with the specific definitions created by
|
|
|
|
|
the compiler. Because Rust compiles generic code into code that specifies the
|
|
|
|
|
type in each instance, we pay no runtime cost for using generics. When the code
|
|
|
|
|
runs, it performs just as it would if we had duplicated each definition by
|
|
|
|
|
hand. The process of monomorphization makes Rust’s generics extremely efficient
|
|
|
|
|
at runtime.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
## Traits: Defining Shared Behavior
|
|
|
|
|
|
2022-08-24 13:12:29 +00:00
|
|
|
|
A *trait* defines the functionality a particular type has and can share with
|
|
|
|
|
other types. We can use traits to define shared behavior in an abstract way. We
|
|
|
|
|
can use *trait bounds* to specify that a generic type can be any type that has
|
2022-03-11 01:33:08 +00:00
|
|
|
|
certain behavior.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
> Note: Traits are similar to a feature often called *interfaces* in other
|
2022-08-20 13:24:57 +00:00
|
|
|
|
languages, although with some differences.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Defining a Trait
|
|
|
|
|
|
|
|
|
|
A type’s behavior consists of the methods we can call on that type. Different
|
|
|
|
|
types share the same behavior if we can call the same methods on all of those
|
|
|
|
|
types. Trait definitions are a way to group method signatures together to
|
|
|
|
|
define a set of behaviors necessary to accomplish some purpose.
|
|
|
|
|
|
|
|
|
|
For example, let’s say we have multiple structs that hold various kinds and
|
|
|
|
|
amounts of text: a `NewsArticle` struct that holds a news story filed in a
|
2022-08-24 13:12:29 +00:00
|
|
|
|
particular location and a `Tweet` that can have, at most, 280 characters along
|
2021-11-15 03:06:18 +00:00
|
|
|
|
with metadata that indicates whether it was a new tweet, a retweet, or a reply
|
|
|
|
|
to another tweet.
|
|
|
|
|
|
|
|
|
|
We want to make a media aggregator library crate named `aggregator` that can
|
|
|
|
|
display summaries of data that might be stored in a `NewsArticle` or `Tweet`
|
2022-08-20 13:24:57 +00:00
|
|
|
|
instance. To do this, we need a summary from each type, and we’ll request that
|
|
|
|
|
summary by calling a `summarize` method on an instance. Listing 10-12 shows the
|
|
|
|
|
definition of a public `Summary` trait that expresses this behavior.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/lib.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub trait Summary {
|
|
|
|
|
fn summarize(&self) -> String;
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-12: A `Summary` trait that consists of the behavior provided by a
|
|
|
|
|
`summarize` method
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Here, we declare a trait using the `trait` keyword and then the trait’s name,
|
2022-08-24 13:12:29 +00:00
|
|
|
|
which is `Summary` in this case. We also declare the trait as `pub` so that
|
2021-11-15 03:06:18 +00:00
|
|
|
|
crates depending on this crate can make use of this trait too, as we’ll see in
|
|
|
|
|
a few examples. Inside the curly brackets, we declare the method signatures
|
|
|
|
|
that describe the behaviors of the types that implement this trait, which in
|
2022-09-13 16:04:18 +00:00
|
|
|
|
this case is `fn summarize(&self) -> String`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
After the method signature, instead of providing an implementation within curly
|
|
|
|
|
brackets, we use a semicolon. Each type implementing this trait must provide
|
|
|
|
|
its own custom behavior for the body of the method. The compiler will enforce
|
|
|
|
|
that any type that has the `Summary` trait will have the method `summarize`
|
|
|
|
|
defined with this signature exactly.
|
|
|
|
|
|
|
|
|
|
A trait can have multiple methods in its body: the method signatures are listed
|
2022-08-24 13:12:29 +00:00
|
|
|
|
one per line, and each line ends in a semicolon.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Implementing a Trait on a Type
|
|
|
|
|
|
|
|
|
|
Now that we’ve defined the desired signatures of the `Summary` trait’s methods,
|
|
|
|
|
we can implement it on the types in our media aggregator. Listing 10-13 shows
|
|
|
|
|
an implementation of the `Summary` trait on the `NewsArticle` struct that uses
|
|
|
|
|
the headline, the author, and the location to create the return value of
|
|
|
|
|
`summarize`. For the `Tweet` struct, we define `summarize` as the username
|
2022-08-20 13:24:57 +00:00
|
|
|
|
followed by the entire text of the tweet, assuming that the tweet content is
|
2021-11-15 03:06:18 +00:00
|
|
|
|
already limited to 280 characters.
|
|
|
|
|
|
|
|
|
|
Filename: src/lib.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub struct NewsArticle {
|
|
|
|
|
pub headline: String,
|
|
|
|
|
pub location: String,
|
|
|
|
|
pub author: String,
|
|
|
|
|
pub content: String,
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
impl Summary for NewsArticle {
|
|
|
|
|
fn summarize(&self) -> String {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
format!(
|
|
|
|
|
"{}, by {} ({})",
|
|
|
|
|
self.headline,
|
|
|
|
|
self.author,
|
|
|
|
|
self.location
|
|
|
|
|
)
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
pub struct Tweet {
|
|
|
|
|
pub username: String,
|
|
|
|
|
pub content: String,
|
|
|
|
|
pub reply: bool,
|
|
|
|
|
pub retweet: bool,
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl Summary for Tweet {
|
|
|
|
|
fn summarize(&self) -> String {
|
|
|
|
|
format!("{}: {}", self.username, self.content)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-13: Implementing the `Summary` trait on the `NewsArticle` and
|
|
|
|
|
`Tweet` types
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Implementing a trait on a type is similar to implementing regular methods. The
|
2022-03-11 01:33:08 +00:00
|
|
|
|
difference is that after `impl`, we put the trait name we want to implement,
|
|
|
|
|
then use the `for` keyword, and then specify the name of the type we want to
|
|
|
|
|
implement the trait for. Within the `impl` block, we put the method signatures
|
|
|
|
|
that the trait definition has defined. Instead of adding a semicolon after each
|
|
|
|
|
signature, we use curly brackets and fill in the method body with the specific
|
|
|
|
|
behavior that we want the methods of the trait to have for the particular type.
|
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
Now that the library has implemented the `Summary` trait on `NewsArticle` and
|
|
|
|
|
`Tweet`, users of the crate can call the trait methods on instances of
|
|
|
|
|
`NewsArticle` and `Tweet` in the same way we call regular methods. The only
|
2022-03-11 01:33:08 +00:00
|
|
|
|
difference is that the user must bring the trait into scope as well as the
|
|
|
|
|
types. Here’s an example of how a binary crate could use our `aggregator`
|
|
|
|
|
library crate:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
use aggregator::{Summary, Tweet};
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn main() {
|
|
|
|
|
let tweet = Tweet {
|
|
|
|
|
username: String::from("horse_ebooks"),
|
|
|
|
|
content: String::from(
|
|
|
|
|
"of course, as you probably already know, people",
|
|
|
|
|
),
|
|
|
|
|
reply: false,
|
|
|
|
|
retweet: false,
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
println!("1 new tweet: {}", tweet.summarize());
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This code prints `1 new tweet: horse_ebooks: of course, as you probably already
|
|
|
|
|
know, people`.
|
|
|
|
|
|
|
|
|
|
Other crates that depend on the `aggregator` crate can also bring the `Summary`
|
2022-03-11 01:33:08 +00:00
|
|
|
|
trait into scope to implement `Summary` on their own types. One restriction to
|
2022-09-13 16:04:18 +00:00
|
|
|
|
note is that we can implement a trait on a type only if either the trait or the
|
|
|
|
|
type, or both, are local to our crate. For example, we can implement standard
|
2022-03-11 01:33:08 +00:00
|
|
|
|
library traits like `Display` on a custom type like `Tweet` as part of our
|
2022-08-20 13:24:57 +00:00
|
|
|
|
`aggregator` crate functionality because the type `Tweet` is local to our
|
2022-03-11 01:33:08 +00:00
|
|
|
|
`aggregator` crate. We can also implement `Summary` on `Vec<T>` in our
|
2022-08-20 13:24:57 +00:00
|
|
|
|
`aggregator` crate because the trait `Summary` is local to our `aggregator`
|
2022-03-11 01:33:08 +00:00
|
|
|
|
crate.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
But we can’t implement external traits on external types. For example, we can’t
|
2022-08-20 13:24:57 +00:00
|
|
|
|
implement the `Display` trait on `Vec<T>` within our `aggregator` crate because
|
|
|
|
|
`Display` and `Vec<T>` are both defined in the standard library and aren’t
|
|
|
|
|
local to our `aggregator` crate. This restriction is part of a property called
|
|
|
|
|
*coherence*, and more specifically the *orphan rule*, so named because the
|
|
|
|
|
parent type is not present. This rule ensures that other people’s code can’t
|
|
|
|
|
break your code and vice versa. Without the rule, two crates could implement
|
|
|
|
|
the same trait for the same type, and Rust wouldn’t know which implementation
|
|
|
|
|
to use.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Default Implementations
|
|
|
|
|
|
|
|
|
|
Sometimes it’s useful to have default behavior for some or all of the methods
|
|
|
|
|
in a trait instead of requiring implementations for all methods on every type.
|
|
|
|
|
Then, as we implement the trait on a particular type, we can keep or override
|
|
|
|
|
each method’s default behavior.
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
In Listing 10-14, we specify a default string for the `summarize` method of the
|
2022-03-11 01:33:08 +00:00
|
|
|
|
`Summary` trait instead of only defining the method signature, as we did in
|
|
|
|
|
Listing 10-12.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/lib.rs
|
|
|
|
|
|
|
|
|
|
```
|
2022-09-13 16:04:18 +00:00
|
|
|
|
pub trait Summary {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn summarize(&self) -> String {
|
|
|
|
|
String::from("(Read more...)")
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-14: Defining a `Summary` trait with a default implementation of the
|
|
|
|
|
`summarize` method
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
To use a default implementation to summarize instances of `NewsArticle`, we
|
|
|
|
|
specify an empty `impl` block with `impl Summary for NewsArticle {}`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Even though we’re no longer defining the `summarize` method on `NewsArticle`
|
|
|
|
|
directly, we’ve provided a default implementation and specified that
|
|
|
|
|
`NewsArticle` implements the `Summary` trait. As a result, we can still call
|
|
|
|
|
the `summarize` method on an instance of `NewsArticle`, like this:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
let article = NewsArticle {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
headline: String::from(
|
|
|
|
|
"Penguins win the Stanley Cup Championship!"
|
|
|
|
|
),
|
2021-11-15 03:06:18 +00:00
|
|
|
|
location: String::from("Pittsburgh, PA, USA"),
|
|
|
|
|
author: String::from("Iceburgh"),
|
|
|
|
|
content: String::from(
|
|
|
|
|
"The Pittsburgh Penguins once again are the best \
|
|
|
|
|
hockey team in the NHL.",
|
|
|
|
|
),
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
println!("New article available! {}", article.summarize());
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
This code prints `New article available! (Read more...)`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
Creating a default implementation doesn’t require us to change anything about
|
|
|
|
|
the implementation of `Summary` on `Tweet` in Listing 10-13. The reason is that
|
|
|
|
|
the syntax for overriding a default implementation is the same as the syntax
|
|
|
|
|
for implementing a trait method that doesn’t have a default implementation.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Default implementations can call other methods in the same trait, even if those
|
|
|
|
|
other methods don’t have a default implementation. In this way, a trait can
|
|
|
|
|
provide a lot of useful functionality and only require implementors to specify
|
|
|
|
|
a small part of it. For example, we could define the `Summary` trait to have a
|
|
|
|
|
`summarize_author` method whose implementation is required, and then define a
|
|
|
|
|
`summarize` method that has a default implementation that calls the
|
|
|
|
|
`summarize_author` method:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub trait Summary {
|
|
|
|
|
fn summarize_author(&self) -> String;
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn summarize(&self) -> String {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
format!(
|
|
|
|
|
"(Read more from {}...)",
|
|
|
|
|
self.summarize_author()
|
|
|
|
|
)
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
To use this version of `Summary`, we only need to define `summarize_author`
|
|
|
|
|
when we implement the trait on a type:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
impl Summary for Tweet {
|
|
|
|
|
fn summarize_author(&self) -> String {
|
|
|
|
|
format!("@{}", self.username)
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
After we define `summarize_author`, we can call `summarize` on instances of the
|
|
|
|
|
`Tweet` struct, and the default implementation of `summarize` will call the
|
|
|
|
|
definition of `summarize_author` that we’ve provided. Because we’ve implemented
|
|
|
|
|
`summarize_author`, the `Summary` trait has given us the behavior of the
|
2022-08-24 13:12:29 +00:00
|
|
|
|
`summarize` method without requiring us to write any more code. Here’s what
|
2022-08-21 01:02:46 +00:00
|
|
|
|
that looks like:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
let tweet = Tweet {
|
|
|
|
|
username: String::from("horse_ebooks"),
|
|
|
|
|
content: String::from(
|
|
|
|
|
"of course, as you probably already know, people",
|
|
|
|
|
),
|
|
|
|
|
reply: false,
|
|
|
|
|
retweet: false,
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
println!("1 new tweet: {}", tweet.summarize());
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This code prints `1 new tweet: (Read more from @horse_ebooks...)`.
|
|
|
|
|
|
|
|
|
|
Note that it isn’t possible to call the default implementation from an
|
|
|
|
|
overriding implementation of that same method.
|
|
|
|
|
|
|
|
|
|
### Traits as Parameters
|
|
|
|
|
|
|
|
|
|
Now that you know how to define and implement traits, we can explore how to use
|
2022-08-20 13:24:57 +00:00
|
|
|
|
traits to define functions that accept many different types. We’ll use the
|
2022-03-11 01:33:08 +00:00
|
|
|
|
`Summary` trait we implemented on the `NewsArticle` and `Tweet` types in
|
|
|
|
|
Listing 10-13 to define a `notify` function that calls the `summarize` method
|
|
|
|
|
on its `item` parameter, which is of some type that implements the `Summary`
|
|
|
|
|
trait. To do this, we use the `impl Trait` syntax, like this:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub fn notify(item: &impl Summary) {
|
|
|
|
|
println!("Breaking news! {}", item.summarize());
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Instead of a concrete type for the `item` parameter, we specify the `impl`
|
|
|
|
|
keyword and the trait name. This parameter accepts any type that implements the
|
|
|
|
|
specified trait. In the body of `notify`, we can call any methods on `item`
|
|
|
|
|
that come from the `Summary` trait, such as `summarize`. We can call `notify`
|
|
|
|
|
and pass in any instance of `NewsArticle` or `Tweet`. Code that calls the
|
|
|
|
|
function with any other type, such as a `String` or an `i32`, won’t compile
|
|
|
|
|
because those types don’t implement `Summary`.
|
|
|
|
|
|
|
|
|
|
#### Trait Bound Syntax
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The `impl Trait` syntax works for straightforward cases but is actually syntax
|
|
|
|
|
sugar for a longer form known as a *trait bound*; it looks like this:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub fn notify<T: Summary>(item: &T) {
|
|
|
|
|
println!("Breaking news! {}", item.summarize());
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This longer form is equivalent to the example in the previous section but is
|
|
|
|
|
more verbose. We place trait bounds with the declaration of the generic type
|
|
|
|
|
parameter after a colon and inside angle brackets.
|
|
|
|
|
|
|
|
|
|
The `impl Trait` syntax is convenient and makes for more concise code in simple
|
2022-03-11 01:33:08 +00:00
|
|
|
|
cases, while the fuller trait bound syntax can express more complexity in other
|
2022-06-02 01:00:53 +00:00
|
|
|
|
cases. For example, we can have two parameters that implement `Summary`. Doing
|
|
|
|
|
so with the `impl Trait` syntax looks like this:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub fn notify(item1: &impl Summary, item2: &impl Summary) {
|
|
|
|
|
```
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Using `impl Trait` is appropriate if we want this function to allow `item1` and
|
|
|
|
|
`item2` to have different types (as long as both types implement `Summary`). If
|
|
|
|
|
we want to force both parameters to have the same type, however, we must use a
|
|
|
|
|
trait bound, like this:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub fn notify<T: Summary>(item1: &T, item2: &T) {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The generic type `T` specified as the type of the `item1` and `item2`
|
|
|
|
|
parameters constrains the function such that the concrete type of the value
|
|
|
|
|
passed as an argument for `item1` and `item2` must be the same.
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
#### Specifying Multiple Trait Bounds with the + Syntax
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
We can also specify more than one trait bound. Say we wanted `notify` to use
|
2022-03-11 01:33:08 +00:00
|
|
|
|
display formatting as well as `summarize` on `item`: we specify in the `notify`
|
|
|
|
|
definition that `item` must implement both `Display` and `Summary`. We can do
|
|
|
|
|
so using the `+` syntax:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub fn notify(item: &(impl Summary + Display)) {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The `+` syntax is also valid with trait bounds on generic types:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
pub fn notify<T: Summary + Display>(item: &T) {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
With the two trait bounds specified, the body of `notify` can call `summarize`
|
|
|
|
|
and use `{}` to format `item`.
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
#### Clearer Trait Bounds with where Clauses
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Using too many trait bounds has its downsides. Each generic has its own trait
|
|
|
|
|
bounds, so functions with multiple generic type parameters can contain lots of
|
|
|
|
|
trait bound information between the function’s name and its parameter list,
|
|
|
|
|
making the function signature hard to read. For this reason, Rust has alternate
|
|
|
|
|
syntax for specifying trait bounds inside a `where` clause after the function
|
2022-08-20 13:24:57 +00:00
|
|
|
|
signature. So, instead of writing this:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 {
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
we can use a `where` clause, like this:
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
|
|
|
|
```
|
2022-09-13 16:04:18 +00:00
|
|
|
|
fn some_function<T, U>(t: &T, u: &U) -> i32
|
2022-08-20 13:11:14 +00:00
|
|
|
|
where
|
|
|
|
|
T: Display + Clone,
|
2022-08-21 01:02:46 +00:00
|
|
|
|
U: Clone + Debug,
|
2021-11-15 03:06:18 +00:00
|
|
|
|
{
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This function’s signature is less cluttered: the function name, parameter list,
|
|
|
|
|
and return type are close together, similar to a function without lots of trait
|
|
|
|
|
bounds.
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
### Returning Types That Implement Traits
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
We can also use the `impl Trait` syntax in the return position to return a
|
|
|
|
|
value of some type that implements a trait, as shown here:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn returns_summarizable() -> impl Summary {
|
|
|
|
|
Tweet {
|
|
|
|
|
username: String::from("horse_ebooks"),
|
|
|
|
|
content: String::from(
|
|
|
|
|
"of course, as you probably already know, people",
|
|
|
|
|
),
|
|
|
|
|
reply: false,
|
|
|
|
|
retweet: false,
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
By using `impl Summary` for the return type, we specify that the
|
|
|
|
|
`returns_summarizable` function returns some type that implements the `Summary`
|
|
|
|
|
trait without naming the concrete type. In this case, `returns_summarizable`
|
2022-03-11 01:33:08 +00:00
|
|
|
|
returns a `Tweet`, but the code calling this function doesn’t need to know that.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The ability to specify a return type only by the trait it implements is
|
|
|
|
|
especially useful in the context of closures and iterators, which we cover in
|
|
|
|
|
Chapter 13. Closures and iterators create types that only the compiler knows or
|
|
|
|
|
types that are very long to specify. The `impl Trait` syntax lets you concisely
|
|
|
|
|
specify that a function returns some type that implements the `Iterator` trait
|
|
|
|
|
without needing to write out a very long type.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
However, you can only use `impl Trait` if you’re returning a single type. For
|
|
|
|
|
example, this code that returns either a `NewsArticle` or a `Tweet` with the
|
|
|
|
|
return type specified as `impl Summary` wouldn’t work:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn returns_summarizable(switch: bool) -> impl Summary {
|
|
|
|
|
if switch {
|
|
|
|
|
NewsArticle {
|
|
|
|
|
headline: String::from(
|
|
|
|
|
"Penguins win the Stanley Cup Championship!",
|
|
|
|
|
),
|
|
|
|
|
location: String::from("Pittsburgh, PA, USA"),
|
|
|
|
|
author: String::from("Iceburgh"),
|
|
|
|
|
content: String::from(
|
|
|
|
|
"The Pittsburgh Penguins once again are the best \
|
|
|
|
|
hockey team in the NHL.",
|
|
|
|
|
),
|
|
|
|
|
}
|
|
|
|
|
} else {
|
|
|
|
|
Tweet {
|
|
|
|
|
username: String::from("horse_ebooks"),
|
|
|
|
|
content: String::from(
|
|
|
|
|
"of course, as you probably already know, people",
|
|
|
|
|
),
|
|
|
|
|
reply: false,
|
|
|
|
|
retweet: false,
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Returning either a `NewsArticle` or a `Tweet` isn’t allowed due to restrictions
|
|
|
|
|
around how the `impl Trait` syntax is implemented in the compiler. We’ll cover
|
2022-08-20 13:24:57 +00:00
|
|
|
|
how to write a function with this behavior in “Using Trait Objects That Allow
|
|
|
|
|
for Values of Different Types” on page XX.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Using Trait Bounds to Conditionally Implement Methods
|
|
|
|
|
|
|
|
|
|
By using a trait bound with an `impl` block that uses generic type parameters,
|
|
|
|
|
we can implement methods conditionally for types that implement the specified
|
2022-06-02 01:00:53 +00:00
|
|
|
|
traits. For example, the type `Pair<T>` in Listing 10-15 always implements the
|
2022-08-20 13:24:57 +00:00
|
|
|
|
`new` function to return a new instance of `Pair<T>` (recall from “Defining
|
|
|
|
|
Methods” on page XX that `Self` is a type alias for the type of the `impl`
|
|
|
|
|
block, which in this case is `Pair<T>`). But in the next `impl` block,
|
2021-11-15 03:06:18 +00:00
|
|
|
|
`Pair<T>` only implements the `cmp_display` method if its inner type `T`
|
|
|
|
|
implements the `PartialOrd` trait that enables comparison *and* the `Display`
|
2022-09-13 16:04:18 +00:00
|
|
|
|
trait that enables printing.
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
Filename: src/lib.rs
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
|
|
|
|
```
|
2022-09-13 16:04:18 +00:00
|
|
|
|
use std::fmt::Display;
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
struct Pair<T> {
|
|
|
|
|
x: T,
|
|
|
|
|
y: T,
|
|
|
|
|
}
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
impl<T> Pair<T> {
|
|
|
|
|
fn new(x: T, y: T) -> Self {
|
|
|
|
|
Self { x, y }
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
impl<T: Display + PartialOrd> Pair<T> {
|
|
|
|
|
fn cmp_display(&self) {
|
|
|
|
|
if self.x >= self.y {
|
|
|
|
|
println!("The largest member is x = {}", self.x);
|
|
|
|
|
} else {
|
|
|
|
|
println!("The largest member is y = {}", self.y);
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-15: Conditionally implementing methods on a generic type depending
|
|
|
|
|
on trait bounds
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
We can also conditionally implement a trait for any type that implements
|
|
|
|
|
another trait. Implementations of a trait on any type that satisfies the trait
|
2022-08-20 13:24:57 +00:00
|
|
|
|
bounds are called *blanket implementations* and are used extensively in the
|
2021-11-15 03:06:18 +00:00
|
|
|
|
Rust standard library. For example, the standard library implements the
|
|
|
|
|
`ToString` trait on any type that implements the `Display` trait. The `impl`
|
|
|
|
|
block in the standard library looks similar to this code:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
impl<T: Display> ToString for T {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
--snip--
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Because the standard library has this blanket implementation, we can call the
|
|
|
|
|
`to_string` method defined by the `ToString` trait on any type that implements
|
|
|
|
|
the `Display` trait. For example, we can turn integers into their corresponding
|
|
|
|
|
`String` values like this because integers implement `Display`:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
let s = 3.to_string();
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Blanket implementations appear in the documentation for the trait in the
|
|
|
|
|
“Implementors” section.
|
|
|
|
|
|
|
|
|
|
Traits and trait bounds let us write code that uses generic type parameters to
|
|
|
|
|
reduce duplication but also specify to the compiler that we want the generic
|
|
|
|
|
type to have particular behavior. The compiler can then use the trait bound
|
|
|
|
|
information to check that all the concrete types used with our code provide the
|
|
|
|
|
correct behavior. In dynamically typed languages, we would get an error at
|
2022-08-20 13:24:57 +00:00
|
|
|
|
runtime if we called a method on a type which didn’t define the method. But
|
|
|
|
|
Rust moves these errors to compile time so we’re forced to fix the problems
|
|
|
|
|
before our code is even able to run. Additionally, we don’t have to write code
|
|
|
|
|
that checks for behavior at runtime because we’ve already checked at compile
|
|
|
|
|
time. Doing so improves performance without having to give up the flexibility
|
|
|
|
|
of generics.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
## Validating References with Lifetimes
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Lifetimes are another kind of generic that we’ve already been using. Rather
|
|
|
|
|
than ensuring that a type has the behavior we want, lifetimes ensure that
|
|
|
|
|
references are valid as long as we need them to be.
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
One detail we didn’t discuss in “References and Borrowing” on page XX is that
|
|
|
|
|
every reference in Rust has a *lifetime*, which is the scope for which that
|
|
|
|
|
reference is valid. Most of the time, lifetimes are implicit and inferred, just
|
2022-08-24 13:12:29 +00:00
|
|
|
|
like most of the time, types are inferred. We must annotate types only when
|
2022-08-20 13:24:57 +00:00
|
|
|
|
multiple types are possible. In a similar way, we must annotate lifetimes when
|
|
|
|
|
the lifetimes of references could be related in a few different ways. Rust
|
|
|
|
|
requires us to annotate the relationships using generic lifetime parameters to
|
|
|
|
|
ensure the actual references used at runtime will definitely be valid.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Annotating lifetimes is not even a concept most other programming languages
|
|
|
|
|
have, so this is going to feel unfamiliar. Although we won’t cover lifetimes in
|
|
|
|
|
their entirety in this chapter, we’ll discuss common ways you might encounter
|
2022-03-11 01:33:08 +00:00
|
|
|
|
lifetime syntax so you can get comfortable with the concept.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Preventing Dangling References with Lifetimes
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The main aim of lifetimes is to prevent *dangling references*, which cause a
|
2021-11-15 03:06:18 +00:00
|
|
|
|
program to reference data other than the data it’s intended to reference.
|
2022-06-02 01:00:53 +00:00
|
|
|
|
Consider the program in Listing 10-16, which has an outer scope and an inner
|
2021-11-15 03:06:18 +00:00
|
|
|
|
scope.
|
|
|
|
|
|
|
|
|
|
```
|
2022-06-02 02:02:18 +00:00
|
|
|
|
fn main() {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
1 let r;
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
{
|
2022-08-21 01:02:46 +00:00
|
|
|
|
2 let x = 5;
|
|
|
|
|
3 r = &x;
|
|
|
|
|
4 }
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
5 println!("r: {r}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-16: An attempt to use a reference whose value has gone out of scope
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
> Note: The examples in Listing 10-16, 10-17, and 10-23 declare variables
|
|
|
|
|
without giving them an initial value, so the variable name exists in the outer
|
|
|
|
|
scope. At first glance, this might appear to be in conflict with Rust’s having
|
|
|
|
|
no null values. However, if we try to use a variable before giving it a value,
|
|
|
|
|
we’ll get a compile-time error, which shows that Rust indeed does not allow
|
|
|
|
|
null values.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-08-21 01:02:46 +00:00
|
|
|
|
The outer scope declares a variable named `r` with no initial value [1], and
|
|
|
|
|
the inner scope declares a variable named `x` with the initial value of `5`
|
|
|
|
|
[2]. Inside the inner scope, we attempt to set the value of `r` as a reference
|
|
|
|
|
to `x` [3]. Then the inner scope ends [4], and we attempt to print the value in
|
|
|
|
|
`r` [5]. This code won’t compile because the value that `r` is referring to has
|
|
|
|
|
gone out of scope before we try to use it. Here is the error message:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
error[E0597]: `x` does not live long enough
|
2022-06-02 02:02:18 +00:00
|
|
|
|
--> src/main.rs:6:13
|
|
|
|
|
|
|
|
|
|
|
6 | r = &x;
|
|
|
|
|
| ^^ borrowed value does not live long enough
|
|
|
|
|
7 | }
|
|
|
|
|
| - `x` dropped here while still borrowed
|
|
|
|
|
8 |
|
2022-08-21 01:02:46 +00:00
|
|
|
|
9 | println!("r: {r}");
|
|
|
|
|
| - borrow later used here
|
2021-11-15 03:06:18 +00:00
|
|
|
|
```
|
|
|
|
|
|
2022-08-24 13:12:29 +00:00
|
|
|
|
The error message says that the variable `x` “does not live long enough.” The
|
2022-08-20 13:24:57 +00:00
|
|
|
|
reason is that `x` will be out of scope when the inner scope ends on line 7.
|
|
|
|
|
But `r` is still valid for the outer scope; because its scope is larger, we say
|
|
|
|
|
that it “lives longer.” If Rust allowed this code to work, `r` would be
|
|
|
|
|
referencing memory that was deallocated when `x` went out of scope, and
|
|
|
|
|
anything we tried to do with `r` wouldn’t work correctly. So how does Rust
|
|
|
|
|
determine that this code is invalid? It uses a borrow checker.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### The Borrow Checker
|
|
|
|
|
|
|
|
|
|
The Rust compiler has a *borrow checker* that compares scopes to determine
|
2022-06-02 01:00:53 +00:00
|
|
|
|
whether all borrows are valid. Listing 10-17 shows the same code as Listing
|
|
|
|
|
10-16 but with annotations showing the lifetimes of the variables.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
2022-06-02 02:02:18 +00:00
|
|
|
|
fn main() {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
let r; // ---------+-- 'a
|
|
|
|
|
// |
|
|
|
|
|
{ // |
|
|
|
|
|
let x = 5; // -+-- 'b |
|
|
|
|
|
r = &x; // | |
|
|
|
|
|
} // -+ |
|
|
|
|
|
// |
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("r: {r}"); // |
|
2021-11-15 03:06:18 +00:00
|
|
|
|
} // ---------+
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-17: Annotations of the lifetimes of `r` and `x`, named `'a` and
|
|
|
|
|
`'b`, respectively
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Here, we’ve annotated the lifetime of `r` with `'a` and the lifetime of `x`
|
|
|
|
|
with `'b`. As you can see, the inner `'b` block is much smaller than the outer
|
|
|
|
|
`'a` lifetime block. At compile time, Rust compares the size of the two
|
|
|
|
|
lifetimes and sees that `r` has a lifetime of `'a` but that it refers to memory
|
|
|
|
|
with a lifetime of `'b`. The program is rejected because `'b` is shorter than
|
|
|
|
|
`'a`: the subject of the reference doesn’t live as long as the reference.
|
|
|
|
|
|
2022-08-24 13:12:29 +00:00
|
|
|
|
Listing 10-18 fixes the code so it doesn’t have a dangling reference and it
|
2021-11-15 03:06:18 +00:00
|
|
|
|
compiles without any errors.
|
|
|
|
|
|
|
|
|
|
```
|
2022-06-02 02:02:18 +00:00
|
|
|
|
fn main() {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
let x = 5; // ----------+-- 'b
|
|
|
|
|
// |
|
|
|
|
|
let r = &x; // --+-- 'a |
|
|
|
|
|
// | |
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("r: {r}"); // | |
|
2021-11-15 03:06:18 +00:00
|
|
|
|
// --+ |
|
|
|
|
|
} // ----------+
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-18: A valid reference because the data has a longer lifetime than
|
|
|
|
|
the reference
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Here, `x` has the lifetime `'b`, which in this case is larger than `'a`. This
|
|
|
|
|
means `r` can reference `x` because Rust knows that the reference in `r` will
|
|
|
|
|
always be valid while `x` is valid.
|
|
|
|
|
|
|
|
|
|
Now that you know where the lifetimes of references are and how Rust analyzes
|
|
|
|
|
lifetimes to ensure references will always be valid, let’s explore generic
|
|
|
|
|
lifetimes of parameters and return values in the context of functions.
|
|
|
|
|
|
|
|
|
|
### Generic Lifetimes in Functions
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
We’ll write a function that returns the longer of two string slices. This
|
|
|
|
|
function will take two string slices and return a single string slice. After
|
2022-06-02 01:00:53 +00:00
|
|
|
|
we’ve implemented the `longest` function, the code in Listing 10-19 should
|
2022-03-11 01:33:08 +00:00
|
|
|
|
print `The longest string is abcd`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn main() {
|
|
|
|
|
let string1 = String::from("abcd");
|
|
|
|
|
let string2 = "xyz";
|
|
|
|
|
|
|
|
|
|
let result = longest(string1.as_str(), string2);
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The longest string is {result}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-19: A `main` function that calls the `longest` function to find the
|
|
|
|
|
longer of two string slices
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Note that we want the function to take string slices, which are references,
|
2022-03-11 01:33:08 +00:00
|
|
|
|
rather than strings, because we don’t want the `longest` function to take
|
2022-08-20 13:24:57 +00:00
|
|
|
|
ownership of its parameters. Refer to “String Slices as Parameters” on page XX
|
|
|
|
|
for more discussion about why the parameters we use in Listing 10-19 are the
|
|
|
|
|
ones we want.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
If we try to implement the `longest` function as shown in Listing 10-20, it
|
2021-11-15 03:06:18 +00:00
|
|
|
|
won’t compile.
|
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn longest(x: &str, y: &str) -> &str {
|
|
|
|
|
if x.len() > y.len() {
|
|
|
|
|
x
|
|
|
|
|
} else {
|
|
|
|
|
y
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-20: An implementation of the `longest` function that returns the
|
|
|
|
|
longer of two string slices but does not yet compile
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Instead, we get the following error that talks about lifetimes:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
error[E0106]: missing lifetime specifier
|
|
|
|
|
--> src/main.rs:9:33
|
|
|
|
|
|
|
|
|
|
|
9 | fn longest(x: &str, y: &str) -> &str {
|
|
|
|
|
| ---- ---- ^ expected named lifetime parameter
|
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
= help: this function's return type contains a borrowed value,
|
|
|
|
|
but the signature does not say whether it is borrowed from `x` or `y`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
help: consider introducing a named lifetime parameter
|
|
|
|
|
|
|
|
|
|
|
9 | fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
|
2022-08-20 13:11:14 +00:00
|
|
|
|
| ++++ ++ ++ ++
|
2021-11-15 03:06:18 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The help text reveals that the return type needs a generic lifetime parameter
|
|
|
|
|
on it because Rust can’t tell whether the reference being returned refers to
|
|
|
|
|
`x` or `y`. Actually, we don’t know either, because the `if` block in the body
|
|
|
|
|
of this function returns a reference to `x` and the `else` block returns a
|
|
|
|
|
reference to `y`!
|
|
|
|
|
|
|
|
|
|
When we’re defining this function, we don’t know the concrete values that will
|
|
|
|
|
be passed into this function, so we don’t know whether the `if` case or the
|
|
|
|
|
`else` case will execute. We also don’t know the concrete lifetimes of the
|
|
|
|
|
references that will be passed in, so we can’t look at the scopes as we did in
|
2022-06-02 01:00:53 +00:00
|
|
|
|
Listings 10-17 and 10-18 to determine whether the reference we return will
|
2021-11-15 03:06:18 +00:00
|
|
|
|
always be valid. The borrow checker can’t determine this either, because it
|
|
|
|
|
doesn’t know how the lifetimes of `x` and `y` relate to the lifetime of the
|
|
|
|
|
return value. To fix this error, we’ll add generic lifetime parameters that
|
|
|
|
|
define the relationship between the references so the borrow checker can
|
|
|
|
|
perform its analysis.
|
|
|
|
|
|
|
|
|
|
### Lifetime Annotation Syntax
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Lifetime annotations don’t change how long any of the references live. Rather,
|
|
|
|
|
they describe the relationships of the lifetimes of multiple references to each
|
|
|
|
|
other without affecting the lifetimes. Just as functions can accept any type
|
|
|
|
|
when the signature specifies a generic type parameter, functions can accept
|
|
|
|
|
references with any lifetime by specifying a generic lifetime parameter.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Lifetime annotations have a slightly unusual syntax: the names of lifetime
|
2022-03-11 01:33:08 +00:00
|
|
|
|
parameters must start with an apostrophe (`'`) and are usually all lowercase
|
|
|
|
|
and very short, like generic types. Most people use the name `'a` for the first
|
|
|
|
|
lifetime annotation. We place lifetime parameter annotations after the `&` of a
|
|
|
|
|
reference, using a space to separate the annotation from the reference’s type.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Here are some examples: a reference to an `i32` without a lifetime parameter, a
|
|
|
|
|
reference to an `i32` that has a lifetime parameter named `'a`, and a mutable
|
|
|
|
|
reference to an `i32` that also has the lifetime `'a`.
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
&i32 // a reference
|
|
|
|
|
&'a i32 // a reference with an explicit lifetime
|
|
|
|
|
&'a mut i32 // a mutable reference with an explicit lifetime
|
|
|
|
|
```
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
One lifetime annotation by itself doesn’t have much meaning because the
|
2021-11-15 03:06:18 +00:00
|
|
|
|
annotations are meant to tell Rust how generic lifetime parameters of multiple
|
2022-06-02 01:00:53 +00:00
|
|
|
|
references relate to each other. Let’s examine how the lifetime annotations
|
|
|
|
|
relate to each other in the context of the `longest` function.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Lifetime Annotations in Function Signatures
|
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
To use lifetime annotations in function signatures, we need to declare the
|
|
|
|
|
generic *lifetime* parameters inside angle brackets between the function name
|
2022-08-20 13:11:14 +00:00
|
|
|
|
and the parameter list, just as we did with generic *type* parameters.
|
2022-06-02 01:00:53 +00:00
|
|
|
|
|
|
|
|
|
We want the signature to express the following constraint: the returned
|
2022-03-11 01:33:08 +00:00
|
|
|
|
reference will be valid as long as both the parameters are valid. This is the
|
|
|
|
|
relationship between lifetimes of the parameters and the return value. We’ll
|
|
|
|
|
name the lifetime `'a` and then add it to each reference, as shown in Listing
|
2022-06-02 01:00:53 +00:00
|
|
|
|
10-21.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
2022-08-20 13:24:57 +00:00
|
|
|
|
fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
|
|
|
|
|
if x.len() > y.len() {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
x
|
|
|
|
|
} else {
|
|
|
|
|
y
|
2022-09-13 16:04:18 +00:00
|
|
|
|
}
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-21: The `longest` function definition specifying that all the
|
|
|
|
|
references in the signature must have the same lifetime `'a`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
This code should compile and produce the result we want when we use it with the
|
2022-06-02 01:00:53 +00:00
|
|
|
|
`main` function in Listing 10-19.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
The function signature now tells Rust that for some lifetime `'a`, the function
|
|
|
|
|
takes two parameters, both of which are string slices that live at least as
|
|
|
|
|
long as lifetime `'a`. The function signature also tells Rust that the string
|
|
|
|
|
slice returned from the function will live at least as long as lifetime `'a`.
|
|
|
|
|
In practice, it means that the lifetime of the reference returned by the
|
2022-06-02 02:02:18 +00:00
|
|
|
|
`longest` function is the same as the smaller of the lifetimes of the values
|
|
|
|
|
referred to by the function arguments. These relationships are what we want
|
|
|
|
|
Rust to use when analyzing this code.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Remember, when we specify the lifetime parameters in this function signature,
|
|
|
|
|
we’re not changing the lifetimes of any values passed in or returned. Rather,
|
|
|
|
|
we’re specifying that the borrow checker should reject any values that don’t
|
|
|
|
|
adhere to these constraints. Note that the `longest` function doesn’t need to
|
|
|
|
|
know exactly how long `x` and `y` will live, only that some scope can be
|
|
|
|
|
substituted for `'a` that will satisfy this signature.
|
|
|
|
|
|
|
|
|
|
When annotating lifetimes in functions, the annotations go in the function
|
|
|
|
|
signature, not in the function body. The lifetime annotations become part of
|
2022-03-11 01:33:08 +00:00
|
|
|
|
the contract of the function, much like the types in the signature. Having
|
2021-11-15 03:06:18 +00:00
|
|
|
|
function signatures contain the lifetime contract means the analysis the Rust
|
|
|
|
|
compiler does can be simpler. If there’s a problem with the way a function is
|
|
|
|
|
annotated or the way it is called, the compiler errors can point to the part of
|
|
|
|
|
our code and the constraints more precisely. If, instead, the Rust compiler
|
|
|
|
|
made more inferences about what we intended the relationships of the lifetimes
|
|
|
|
|
to be, the compiler might only be able to point to a use of our code many steps
|
|
|
|
|
away from the cause of the problem.
|
|
|
|
|
|
|
|
|
|
When we pass concrete references to `longest`, the concrete lifetime that is
|
|
|
|
|
substituted for `'a` is the part of the scope of `x` that overlaps with the
|
|
|
|
|
scope of `y`. In other words, the generic lifetime `'a` will get the concrete
|
|
|
|
|
lifetime that is equal to the smaller of the lifetimes of `x` and `y`. Because
|
|
|
|
|
we’ve annotated the returned reference with the same lifetime parameter `'a`,
|
|
|
|
|
the returned reference will also be valid for the length of the smaller of the
|
|
|
|
|
lifetimes of `x` and `y`.
|
|
|
|
|
|
|
|
|
|
Let’s look at how the lifetime annotations restrict the `longest` function by
|
2022-06-02 01:00:53 +00:00
|
|
|
|
passing in references that have different concrete lifetimes. Listing 10-22 is
|
2021-11-15 03:06:18 +00:00
|
|
|
|
a straightforward example.
|
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn main() {
|
|
|
|
|
let string1 = String::from("long string is long");
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
let string2 = String::from("xyz");
|
|
|
|
|
let result = longest(string1.as_str(), string2.as_str());
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The longest string is {result}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-22: Using the `longest` function with references to `String` values
|
|
|
|
|
that have different concrete lifetimes
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
In this example, `string1` is valid until the end of the outer scope, `string2`
|
|
|
|
|
is valid until the end of the inner scope, and `result` references something
|
2022-08-20 13:24:57 +00:00
|
|
|
|
that is valid until the end of the inner scope. Run this code and you’ll see
|
2022-03-11 01:33:08 +00:00
|
|
|
|
that the borrow checker approves; it will compile and print `The longest string
|
|
|
|
|
is long string is long`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Next, let’s try an example that shows that the lifetime of the reference in
|
|
|
|
|
`result` must be the smaller lifetime of the two arguments. We’ll move the
|
|
|
|
|
declaration of the `result` variable outside the inner scope but leave the
|
|
|
|
|
assignment of the value to the `result` variable inside the scope with
|
2022-03-11 01:33:08 +00:00
|
|
|
|
`string2`. Then we’ll move the `println!` that uses `result` to outside the
|
2022-06-02 01:00:53 +00:00
|
|
|
|
inner scope, after the inner scope has ended. The code in Listing 10-23 will
|
2022-03-11 01:33:08 +00:00
|
|
|
|
not compile.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn main() {
|
|
|
|
|
let string1 = String::from("long string is long");
|
|
|
|
|
let result;
|
|
|
|
|
{
|
|
|
|
|
let string2 = String::from("xyz");
|
|
|
|
|
result = longest(string1.as_str(), string2.as_str());
|
|
|
|
|
}
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("The longest string is {result}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-23: Attempting to use `result` after `string2` has gone out of scope
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
When we try to compile this code, we get this error:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
error[E0597]: `string2` does not live long enough
|
|
|
|
|
--> src/main.rs:6:44
|
|
|
|
|
|
|
|
|
|
|
6 | result = longest(string1.as_str(), string2.as_str());
|
2022-08-20 13:24:57 +00:00
|
|
|
|
| ^^^^^^^^^^^^^^^^ borrowed value
|
|
|
|
|
does not live long enough
|
2021-11-15 03:06:18 +00:00
|
|
|
|
7 | }
|
|
|
|
|
| - `string2` dropped here while still borrowed
|
2022-08-21 01:02:46 +00:00
|
|
|
|
8 | println!("The longest string is {result}");
|
|
|
|
|
| ------ borrow later used here
|
2021-11-15 03:06:18 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The error shows that for `result` to be valid for the `println!` statement,
|
|
|
|
|
`string2` would need to be valid until the end of the outer scope. Rust knows
|
|
|
|
|
this because we annotated the lifetimes of the function parameters and return
|
|
|
|
|
values using the same lifetime parameter `'a`.
|
|
|
|
|
|
|
|
|
|
As humans, we can look at this code and see that `string1` is longer than
|
2022-08-24 13:12:29 +00:00
|
|
|
|
`string2`, and therefore, `result` will contain a reference to `string1`.
|
|
|
|
|
Because `string1` has not gone out of scope yet, a reference to `string1` will
|
|
|
|
|
still be valid for the `println!` statement. However, the compiler can’t see
|
|
|
|
|
that the reference is valid in this case. We’ve told Rust that the lifetime of
|
|
|
|
|
the reference returned by the `longest` function is the same as the smaller of
|
|
|
|
|
the lifetimes of the references passed in. Therefore, the borrow checker
|
|
|
|
|
disallows the code in Listing 10-23 as possibly having an invalid reference.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Try designing more experiments that vary the values and lifetimes of the
|
|
|
|
|
references passed in to the `longest` function and how the returned reference
|
|
|
|
|
is used. Make hypotheses about whether or not your experiments will pass the
|
|
|
|
|
borrow checker before you compile; then check to see if you’re right!
|
|
|
|
|
|
|
|
|
|
### Thinking in Terms of Lifetimes
|
|
|
|
|
|
|
|
|
|
The way in which you need to specify lifetime parameters depends on what your
|
|
|
|
|
function is doing. For example, if we changed the implementation of the
|
|
|
|
|
`longest` function to always return the first parameter rather than the longest
|
|
|
|
|
string slice, we wouldn’t need to specify a lifetime on the `y` parameter. The
|
|
|
|
|
following code will compile:
|
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn longest<'a>(x: &'a str, y: &str) -> &'a str {
|
|
|
|
|
x
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
We’ve specified a lifetime parameter `'a` for the parameter `x` and the return
|
|
|
|
|
type, but not for the parameter `y`, because the lifetime of `y` does not have
|
|
|
|
|
any relationship with the lifetime of `x` or the return value.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
When returning a reference from a function, the lifetime parameter for the
|
|
|
|
|
return type needs to match the lifetime parameter for one of the parameters. If
|
|
|
|
|
the reference returned does *not* refer to one of the parameters, it must refer
|
2022-03-11 01:33:08 +00:00
|
|
|
|
to a value created within this function. However, this would be a dangling
|
|
|
|
|
reference because the value will go out of scope at the end of the function.
|
|
|
|
|
Consider this attempted implementation of the `longest` function that won’t
|
|
|
|
|
compile:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn longest<'a>(x: &str, y: &str) -> &'a str {
|
|
|
|
|
let result = String::from("really long string");
|
|
|
|
|
result.as_str()
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Here, even though we’ve specified a lifetime parameter `'a` for the return
|
|
|
|
|
type, this implementation will fail to compile because the return value
|
|
|
|
|
lifetime is not related to the lifetime of the parameters at all. Here is the
|
|
|
|
|
error message we get:
|
|
|
|
|
|
|
|
|
|
```
|
2022-08-20 13:11:14 +00:00
|
|
|
|
error[E0515]: cannot return reference to local variable `result`
|
2021-11-15 03:06:18 +00:00
|
|
|
|
--> src/main.rs:11:5
|
|
|
|
|
|
|
|
|
|
|
11 | result.as_str()
|
2022-08-20 13:24:57 +00:00
|
|
|
|
| ^^^^^^^^^^^^^^^ returns a reference to data owned by the
|
|
|
|
|
current function
|
2021-11-15 03:06:18 +00:00
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The problem is that `result` goes out of scope and gets cleaned up at the end
|
|
|
|
|
of the `longest` function. We’re also trying to return a reference to `result`
|
|
|
|
|
from the function. There is no way we can specify lifetime parameters that
|
|
|
|
|
would change the dangling reference, and Rust won’t let us create a dangling
|
|
|
|
|
reference. In this case, the best fix would be to return an owned data type
|
|
|
|
|
rather than a reference so the calling function is then responsible for
|
|
|
|
|
cleaning up the value.
|
|
|
|
|
|
|
|
|
|
Ultimately, lifetime syntax is about connecting the lifetimes of various
|
|
|
|
|
parameters and return values of functions. Once they’re connected, Rust has
|
|
|
|
|
enough information to allow memory-safe operations and disallow operations that
|
|
|
|
|
would create dangling pointers or otherwise violate memory safety.
|
|
|
|
|
|
|
|
|
|
### Lifetime Annotations in Struct Definitions
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
So far, the structs we’ve defined all hold owned types. We can define structs
|
|
|
|
|
to hold references, but in that case we would need to add a lifetime annotation
|
|
|
|
|
on every reference in the struct’s definition. Listing 10-24 has a struct named
|
2022-03-11 01:33:08 +00:00
|
|
|
|
`ImportantExcerpt` that holds a string slice.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/main.rs
|
|
|
|
|
|
|
|
|
|
```
|
2022-08-21 01:02:46 +00:00
|
|
|
|
1 struct ImportantExcerpt<'a> {
|
|
|
|
|
2 part: &'a str,
|
2021-11-15 03:06:18 +00:00
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
fn main() {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
3 let novel = String::from(
|
|
|
|
|
"Call me Ishmael. Some years ago..."
|
|
|
|
|
);
|
|
|
|
|
4 let first_sentence = novel
|
|
|
|
|
.split('.')
|
|
|
|
|
.next()
|
|
|
|
|
.expect("Could not find a '.'");
|
|
|
|
|
5 let i = ImportantExcerpt {
|
2021-11-15 03:06:18 +00:00
|
|
|
|
part: first_sentence,
|
|
|
|
|
};
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-24: A struct that holds a reference, requiring a lifetime annotation
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
This struct has the single field `part` that holds a string slice, which is a
|
2022-08-21 01:02:46 +00:00
|
|
|
|
reference [2]. As with generic data types, we declare the name of the generic
|
2021-11-15 03:06:18 +00:00
|
|
|
|
lifetime parameter inside angle brackets after the name of the struct so we can
|
2022-08-21 01:02:46 +00:00
|
|
|
|
use the lifetime parameter in the body of the struct definition [1]. This
|
2021-11-15 03:06:18 +00:00
|
|
|
|
annotation means an instance of `ImportantExcerpt` can’t outlive the reference
|
|
|
|
|
it holds in its `part` field.
|
|
|
|
|
|
|
|
|
|
The `main` function here creates an instance of the `ImportantExcerpt` struct
|
2022-08-21 01:02:46 +00:00
|
|
|
|
[5] that holds a reference to the first sentence of the `String` [4] owned by
|
|
|
|
|
the variable `novel` [3]. The data in `novel` exists before the
|
|
|
|
|
`ImportantExcerpt` instance is created. In addition, `novel` doesn’t go out of
|
|
|
|
|
scope until after the `ImportantExcerpt` goes out of scope, so the reference in
|
|
|
|
|
the `ImportantExcerpt` instance is valid.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
### Lifetime Elision
|
|
|
|
|
|
|
|
|
|
You’ve learned that every reference has a lifetime and that you need to specify
|
2022-08-20 13:24:57 +00:00
|
|
|
|
lifetime parameters for functions or structs that use references. However, we
|
|
|
|
|
had a function in Listing 4-9, shown again in Listing 10-25, that compiled
|
|
|
|
|
without lifetime annotations.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
Filename: src/lib.rs
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn first_word(s: &str) -> &str {
|
|
|
|
|
let bytes = s.as_bytes();
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
for (i, &item) in bytes.iter().enumerate() {
|
|
|
|
|
if item == b' ' {
|
|
|
|
|
return &s[0..i];
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
&s[..]
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-09-13 16:54:09 +00:00
|
|
|
|
Listing 10-25: A function we defined in Listing 4-9 that compiled without
|
|
|
|
|
lifetime annotations, even though the parameter and return type are references
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
The reason this function compiles without lifetime annotations is historical:
|
|
|
|
|
in early versions (pre-1.0) of Rust, this code wouldn’t have compiled because
|
|
|
|
|
every reference needed an explicit lifetime. At that time, the function
|
|
|
|
|
signature would have been written like this:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn first_word<'a>(s: &'a str) -> &'a str {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
After writing a lot of Rust code, the Rust team found that Rust programmers
|
|
|
|
|
were entering the same lifetime annotations over and over in particular
|
|
|
|
|
situations. These situations were predictable and followed a few deterministic
|
|
|
|
|
patterns. The developers programmed these patterns into the compiler’s code so
|
|
|
|
|
the borrow checker could infer the lifetimes in these situations and wouldn’t
|
|
|
|
|
need explicit annotations.
|
|
|
|
|
|
|
|
|
|
This piece of Rust history is relevant because it’s possible that more
|
|
|
|
|
deterministic patterns will emerge and be added to the compiler. In the future,
|
|
|
|
|
even fewer lifetime annotations might be required.
|
|
|
|
|
|
|
|
|
|
The patterns programmed into Rust’s analysis of references are called the
|
|
|
|
|
*lifetime elision rules*. These aren’t rules for programmers to follow; they’re
|
|
|
|
|
a set of particular cases that the compiler will consider, and if your code
|
|
|
|
|
fits these cases, you don’t need to write the lifetimes explicitly.
|
|
|
|
|
|
|
|
|
|
The elision rules don’t provide full inference. If Rust deterministically
|
|
|
|
|
applies the rules but there is still ambiguity as to what lifetimes the
|
|
|
|
|
references have, the compiler won’t guess what the lifetime of the remaining
|
2022-03-11 01:33:08 +00:00
|
|
|
|
references should be. Instead of guessing, the compiler will give you an error
|
|
|
|
|
that you can resolve by adding the lifetime annotations.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-09-13 16:04:18 +00:00
|
|
|
|
Lifetimes on function or method parameters are called *input lifetimes*, and
|
|
|
|
|
lifetimes on return values are called *output lifetimes*.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The compiler uses three rules to figure out the lifetimes of the references
|
|
|
|
|
when there aren’t explicit annotations. The first rule applies to input
|
|
|
|
|
lifetimes, and the second and third rules apply to output lifetimes. If the
|
|
|
|
|
compiler gets to the end of the three rules and there are still references for
|
|
|
|
|
which it can’t figure out lifetimes, the compiler will stop with an error.
|
|
|
|
|
These rules apply to `fn` definitions as well as `impl` blocks.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The first rule is that the compiler assigns a lifetime parameter to each
|
2022-08-20 13:24:57 +00:00
|
|
|
|
parameter that’s a reference. In other words, a function with one parameter
|
|
|
|
|
gets one lifetime parameter: `fn foo<'a>(x: &'a i32)`; a function with two
|
2022-03-11 01:33:08 +00:00
|
|
|
|
parameters gets two separate lifetime parameters: `fn foo<'a, 'b>(x: &'a i32,
|
|
|
|
|
y: &'b i32)`; and so on.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The second rule is that, if there is exactly one input lifetime parameter, that
|
2021-11-15 03:06:18 +00:00
|
|
|
|
lifetime is assigned to all output lifetime parameters: `fn foo<'a>(x: &'a i32)
|
|
|
|
|
-> &'a i32`.
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
The third rule is that, if there are multiple input lifetime parameters, but
|
|
|
|
|
one of them is `&self` or `&mut self` because this is a method, the lifetime of
|
|
|
|
|
`self` is assigned to all output lifetime parameters. This third rule makes
|
|
|
|
|
methods much nicer to read and write because fewer symbols are necessary.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
Let’s pretend we’re the compiler. We’ll apply these rules to figure out the
|
|
|
|
|
lifetimes of the references in the signature of the `first_word` function in
|
2022-06-02 01:00:53 +00:00
|
|
|
|
Listing 10-25. The signature starts without any lifetimes associated with the
|
2022-03-11 01:33:08 +00:00
|
|
|
|
references:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn first_word(s: &str) -> &str {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then the compiler applies the first rule, which specifies that each parameter
|
|
|
|
|
gets its own lifetime. We’ll call it `'a` as usual, so now the signature is
|
|
|
|
|
this:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn first_word<'a>(s: &'a str) -> &str {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The second rule applies because there is exactly one input lifetime. The second
|
|
|
|
|
rule specifies that the lifetime of the one input parameter gets assigned to
|
|
|
|
|
the output lifetime, so the signature is now this:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn first_word<'a>(s: &'a str) -> &'a str {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Now all the references in this function signature have lifetimes, and the
|
|
|
|
|
compiler can continue its analysis without needing the programmer to annotate
|
|
|
|
|
the lifetimes in this function signature.
|
|
|
|
|
|
|
|
|
|
Let’s look at another example, this time using the `longest` function that had
|
2022-06-02 01:00:53 +00:00
|
|
|
|
no lifetime parameters when we started working with it in Listing 10-20:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn longest(x: &str, y: &str) -> &str {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Let’s apply the first rule: each parameter gets its own lifetime. This time we
|
|
|
|
|
have two parameters instead of one, so we have two lifetimes:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
fn longest<'a, 'b>(x: &'a str, y: &'b str) -> &str {
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
You can see that the second rule doesn’t apply because there is more than one
|
|
|
|
|
input lifetime. The third rule doesn’t apply either, because `longest` is a
|
|
|
|
|
function rather than a method, so none of the parameters are `self`. After
|
|
|
|
|
working through all three rules, we still haven’t figured out what the return
|
|
|
|
|
type’s lifetime is. This is why we got an error trying to compile the code in
|
2022-06-02 01:00:53 +00:00
|
|
|
|
Listing 10-20: the compiler worked through the lifetime elision rules but still
|
2021-11-15 03:06:18 +00:00
|
|
|
|
couldn’t figure out all the lifetimes of the references in the signature.
|
|
|
|
|
|
|
|
|
|
Because the third rule really only applies in method signatures, we’ll look at
|
|
|
|
|
lifetimes in that context next to see why the third rule means we don’t have to
|
|
|
|
|
annotate lifetimes in method signatures very often.
|
|
|
|
|
|
|
|
|
|
### Lifetime Annotations in Method Definitions
|
|
|
|
|
|
|
|
|
|
When we implement methods on a struct with lifetimes, we use the same syntax as
|
|
|
|
|
that of generic type parameters shown in Listing 10-11. Where we declare and
|
|
|
|
|
use the lifetime parameters depends on whether they’re related to the struct
|
|
|
|
|
fields or the method parameters and return values.
|
|
|
|
|
|
|
|
|
|
Lifetime names for struct fields always need to be declared after the `impl`
|
2022-08-20 13:24:57 +00:00
|
|
|
|
keyword and then used after the struct’s name because those lifetimes are part
|
2021-11-15 03:06:18 +00:00
|
|
|
|
of the struct’s type.
|
|
|
|
|
|
|
|
|
|
In method signatures inside the `impl` block, references might be tied to the
|
|
|
|
|
lifetime of references in the struct’s fields, or they might be independent. In
|
|
|
|
|
addition, the lifetime elision rules often make it so that lifetime annotations
|
|
|
|
|
aren’t necessary in method signatures. Let’s look at some examples using the
|
2022-06-02 01:00:53 +00:00
|
|
|
|
struct named `ImportantExcerpt` that we defined in Listing 10-24.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
First we’ll use a method named `level` whose only parameter is a reference to
|
2021-11-15 03:06:18 +00:00
|
|
|
|
`self` and whose return value is an `i32`, which is not a reference to anything:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
impl<'a> ImportantExcerpt<'a> {
|
|
|
|
|
fn level(&self) -> i32 {
|
|
|
|
|
3
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
The lifetime parameter declaration after `impl` and its use after the type name
|
|
|
|
|
are required, but we’re not required to annotate the lifetime of the reference
|
|
|
|
|
to `self` because of the first elision rule.
|
|
|
|
|
|
|
|
|
|
Here is an example where the third lifetime elision rule applies:
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
impl<'a> ImportantExcerpt<'a> {
|
|
|
|
|
fn announce_and_return_part(&self, announcement: &str) -> &str {
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("Attention please: {announcement}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
self.part
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
There are two input lifetimes, so Rust applies the first lifetime elision rule
|
|
|
|
|
and gives both `&self` and `announcement` their own lifetimes. Then, because
|
|
|
|
|
one of the parameters is `&self`, the return type gets the lifetime of `&self`,
|
|
|
|
|
and all lifetimes have been accounted for.
|
|
|
|
|
|
|
|
|
|
### The Static Lifetime
|
|
|
|
|
|
2022-03-11 01:33:08 +00:00
|
|
|
|
One special lifetime we need to discuss is `'static`, which denotes that the
|
|
|
|
|
affected reference *can* live for the entire duration of the program. All
|
|
|
|
|
string literals have the `'static` lifetime, which we can annotate as follows:
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
let s: &'static str = "I have a static lifetime.";
|
|
|
|
|
```
|
|
|
|
|
|
2022-08-20 13:24:57 +00:00
|
|
|
|
The text of this string is stored directly in the program’s binary, which is
|
|
|
|
|
always available. Therefore, the lifetime of all string literals is `'static`.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
You might see suggestions to use the `'static` lifetime in error messages. But
|
|
|
|
|
before specifying `'static` as the lifetime for a reference, think about
|
|
|
|
|
whether the reference you have actually lives the entire lifetime of your
|
2022-03-11 01:33:08 +00:00
|
|
|
|
program or not, and whether you want it to. Most of the time, an error message
|
2022-06-02 01:00:53 +00:00
|
|
|
|
suggesting the `'static` lifetime results from attempting to create a dangling
|
|
|
|
|
reference or a mismatch of the available lifetimes. In such cases, the solution
|
2022-08-20 13:24:57 +00:00
|
|
|
|
is to fix those problems, not to specify the `'static` lifetime.
|
2021-11-15 03:06:18 +00:00
|
|
|
|
|
|
|
|
|
## Generic Type Parameters, Trait Bounds, and Lifetimes Together
|
|
|
|
|
|
|
|
|
|
Let’s briefly look at the syntax of specifying generic type parameters, trait
|
|
|
|
|
bounds, and lifetimes all in one function!
|
|
|
|
|
|
|
|
|
|
```
|
|
|
|
|
use std::fmt::Display;
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|
2021-11-15 03:06:18 +00:00
|
|
|
|
fn longest_with_an_announcement<'a, T>(
|
|
|
|
|
x: &'a str,
|
|
|
|
|
y: &'a str,
|
|
|
|
|
ann: T,
|
|
|
|
|
) -> &'a str
|
|
|
|
|
where
|
|
|
|
|
T: Display,
|
|
|
|
|
{
|
2022-08-21 01:02:46 +00:00
|
|
|
|
println!("Announcement! {ann}");
|
2021-11-15 03:06:18 +00:00
|
|
|
|
if x.len() > y.len() {
|
|
|
|
|
x
|
|
|
|
|
} else {
|
|
|
|
|
y
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
2022-06-02 01:00:53 +00:00
|
|
|
|
This is the `longest` function from Listing 10-21 that returns the longer of
|
2021-11-15 03:06:18 +00:00
|
|
|
|
two string slices. But now it has an extra parameter named `ann` of the generic
|
|
|
|
|
type `T`, which can be filled in by any type that implements the `Display`
|
|
|
|
|
trait as specified by the `where` clause. This extra parameter will be printed
|
|
|
|
|
using `{}`, which is why the `Display` trait bound is necessary. Because
|
|
|
|
|
lifetimes are a type of generic, the declarations of the lifetime parameter
|
|
|
|
|
`'a` and the generic type parameter `T` go in the same list inside the angle
|
|
|
|
|
brackets after the function name.
|
|
|
|
|
|
|
|
|
|
## Summary
|
|
|
|
|
|
|
|
|
|
We covered a lot in this chapter! Now that you know about generic type
|
|
|
|
|
parameters, traits and trait bounds, and generic lifetime parameters, you’re
|
|
|
|
|
ready to write code without repetition that works in many different situations.
|
|
|
|
|
Generic type parameters let you apply the code to different types. Traits and
|
|
|
|
|
trait bounds ensure that even though the types are generic, they’ll have the
|
|
|
|
|
behavior the code needs. You learned how to use lifetime annotations to ensure
|
|
|
|
|
that this flexible code won’t have any dangling references. And all of this
|
|
|
|
|
analysis happens at compile time, which doesn’t affect runtime performance!
|
|
|
|
|
|
|
|
|
|
Believe it or not, there is much more to learn on the topics we discussed in
|
|
|
|
|
this chapter: Chapter 17 discusses trait objects, which are another way to use
|
|
|
|
|
traits. There are also more complex scenarios involving lifetime annotations
|
|
|
|
|
that you will only need in very advanced scenarios; for those, you should read
|
|
|
|
|
the Rust Reference at *https://doc.rust-lang.org/reference/trait-bounds.html*.
|
|
|
|
|
But next, you’ll learn how to write tests in Rust so you can make sure your
|
|
|
|
|
code is working the way it should.
|
2022-08-20 13:24:57 +00:00
|
|
|
|
|