diff options
Diffstat (limited to '')
| -rw-r--r-- | src/doc/book/nostarch/chapter03.md | 528 |
1 files changed, 186 insertions, 342 deletions
diff --git a/src/doc/book/nostarch/chapter03.md b/src/doc/book/nostarch/chapter03.md index 281f31d33..249032fd7 100644 --- a/src/doc/book/nostarch/chapter03.md +++ b/src/doc/book/nostarch/chapter03.md @@ -18,19 +18,19 @@ Specifically, you’ll learn about variables, basic types, functions, comments, and control flow. These foundations will be in every Rust program, and learning them early will give you a strong core to start from. -> #### Keywords +> ### Keywords > -> The Rust language has a set of *keywords* that are reserved for use by -> the language only, much as in other languages. Keep in mind that you cannot -> use these words as names of variables or functions. Most of the keywords have -> special meanings, and you’ll be using them to do various tasks in your Rust -> programs; a few have no current functionality associated with them but have -> been reserved for functionality that might be added to Rust in the future. You -> can find a list of the keywords in Appendix A. +> The Rust language has a set of *keywords* that are reserved for use by the +language only, much as in other languages. Keep in mind that you cannot use +these words as names of variables or functions. Most of the keywords have +special meanings, and you’ll be using them to do various tasks in your Rust +programs; a few have no current functionality associated with them but have +been reserved for functionality that might be added to Rust in the future. You +can find a list of the keywords in Appendix A. ## Variables and Mutability -As mentioned in the “Storing Values with Variables” section, by default +As mentioned in “Storing Values with Variables” on page XX, by default, variables are immutable. This is one of many nudges Rust gives you to write your code in a way that takes advantage of the safety and easy concurrency that Rust offers. However, you still have the option to make your variables mutable. @@ -38,12 +38,11 @@ Let’s explore how and why Rust encourages you to favor immutability and why sometimes you might want to opt out. When a variable is immutable, once a value is bound to a name, you can’t change -that value. To illustrate this, let’s generate a new project called *variables* -in your *projects* directory by using `cargo new variables`. +that value. To illustrate this, generate a new project called *variables* in +your *projects* directory by using `cargo new variables`. Then, in your new *variables* directory, open *src/main.rs* and replace its -code with the following code. This code won’t compile just yet, we’ll first -examine the immutability error. +code with the following code, which won’t compile just yet: Filename: src/main.rs @@ -56,8 +55,8 @@ fn main() { } ``` -Save and run the program using `cargo run`. You should receive an error -message, as shown in this output: +Save and run the program using `cargo run`. You should receive an error message +regarding an immutability error, as shown in this output: ``` $ cargo run @@ -80,9 +79,8 @@ Compiler errors can be frustrating, but really they only mean your program isn’t safely doing what you want it to do yet; they do *not* mean that you’re not a good programmer! Experienced Rustaceans still get compiler errors. -The error message indicates that the cause of the error is that you `` cannot -assign twice to immutable variable `x` ``, because you tried to assign a second -value to the immutable `x` variable. +You received the error message `cannot assign twice to immutable variable `x`` +because you tried to assign a second value to the immutable `x` variable. It’s important that we get compile-time errors when we attempt to change a value that’s designated as immutable because this very situation can lead to @@ -91,15 +89,15 @@ never change and another part of our code changes that value, it’s possible that the first part of the code won’t do what it was designed to do. The cause of this kind of bug can be difficult to track down after the fact, especially when the second piece of code changes the value only *sometimes*. The Rust -compiler guarantees that when you state a value won’t change, it really won’t -change, so you don’t have to keep track of it yourself. Your code is thus +compiler guarantees that when you state that a value won’t change, it really +won’t change, so you don’t have to keep track of it yourself. Your code is thus easier to reason through. But mutability can be very useful, and can make code more convenient to write. -Variables are immutable only by default; as you did in Chapter 2, you can make -them mutable by adding `mut` in front of the variable name. Adding `mut` also -conveys intent to future readers of the code by indicating that other parts of -the code will be changing this variable’s value. +Although variables are immutable by default, you can make them mutable by +adding `mut` in front of the variable name as you did in Chapter 2. Adding +`mut` also conveys intent to future readers of the code by indicating that +other parts of the code will be changing this variable’s value. For example, let’s change *src/main.rs* to the following: @@ -125,18 +123,10 @@ The value of x is: 5 The value of x is: 6 ``` -We’re allowed to change the value bound to `x` from `5` to `6` when `mut` -is used. Ultimately, deciding whether to use mutability or not is up to you and +We’re allowed to change the value bound to `x` from `5` to `6` when `mut` is +used. Ultimately, deciding whether to use mutability or not is up to you and depends on what you think is clearest in that particular situation. -<!--- Just to voice some thoughts here: there's a kind of bad pattern I see sometimes -with the Rust dev mindset around performance. In my experience it happens maybe less -often than you'd think that cloning shows up in the profile as a performance hit. I -wonder if we should maybe tone down or remove the discussion of performance above -because it's far stronger for the developer to pick a clear representation for their -program and then improve performance after they've found that model. /JT ---> -<!-- Ok, I've removed the discussion of performance here. Good call. /Carol --> - ### Constants Like immutable variables, *constants* are values that are bound to a name and @@ -146,9 +136,9 @@ and variables. First, you aren’t allowed to use `mut` with constants. Constants aren’t just immutable by default—they’re always immutable. You declare constants using the `const` keyword instead of the `let` keyword, and the type of the value *must* -be annotated. We’re about to cover types and type annotations in the next -section, “Data Types,” so don’t worry about the details right now. Just know -that you must always annotate the type. +be annotated. We’ll cover types and type annotations in “Data Types” on page +XX, so don’t worry about the details right now. Just know that you must always +annotate the type. Constants can be declared in any scope, including the global scope, which makes them useful for values that many parts of code need to know about. @@ -169,15 +159,15 @@ program). Rust’s naming convention for constants is to use all uppercase with underscores between words. The compiler is able to evaluate a limited set of operations at compile time, which lets us choose to write out this value in a way that’s easier to understand and verify, rather than setting this constant -to the value 10,800. See the Rust Reference’s section on constant evaluation at -*https://doc.rust-lang.org/reference/const_eval.html* for more information on -what operations can be used when declaring constants. +to the value `10,800`. See the Rust Reference’s section on constant evaluation +at *https://doc.rust-lang.org/reference/const_eval.html* for more information +on what operations can be used when declaring constants. -Constants are valid for the entire time a program runs, within the scope they -were declared in. This property makes constants useful for values in your -application domain that multiple parts of the program might need to know about, -such as the maximum number of points any player of a game is allowed to earn or -the speed of light. +Constants are valid for the entire time a program runs, within the scope in +which they were declared. This property makes constants useful for values in +your application domain that multiple parts of the program might need to know +about, such as the maximum number of points any player of a game is allowed to +earn, or the speed of light. Naming hardcoded values used throughout your program as constants is useful in conveying the meaning of that value to future maintainers of the code. It also @@ -195,21 +185,6 @@ variable name to itself until either it itself is shadowed or the scope ends. We can shadow a variable by using the same variable’s name and repeating the use of the `let` keyword as follows: -<!--- A potential reword of the above for clarity: - -As you saw in the guessing game tutorial in Chapter 2, you can declare a new -variable with the same name as a previous variable. Rustaceans say that the -first variable is *shadowed* by the second, which means that the second -variable is what the compiler will see when you use the name of the variable. -In effect, the second variable overshadows the first, taking any uses of the -variable name to itself until either it itself is shadowed or the scope ends. -We can shadow a variable by using the same variable’s name and repeating the -use of the `let` keyword as follows: - -/JT ---> -<!-- Sounds good to me, I've made the change to JT's version. What do you -think, Liz? /Carol --> - Filename: src/main.rs ``` @@ -226,17 +201,6 @@ fn main() { println!("The value of x is: {x}"); } ``` -<!--- We haven't really introduced block scoping yet. I know we're starting -with variables, but I wonder if we should introduce scopes before shadowing, -or explain that each block has its own set of variables. -/JT ---> -<!-- Chapter 4 goes into scopes in more detail. I feel like block scoping is a -pretty common programming concept, and the behavior of scopes in Rust that -we're demonstrating here is the same behavior as scopes have in most other -common programming languages. I don't recall getting comments from readers -being confused about scopes at this point. I added a small phrase in the next -paragraph that the curly brackets are creating a new scope... do you think -that's enough, Liz? /Carol --> This program first binds `x` to a value of `5`. Then it creates a new variable `x` by repeating `let x =`, taking the original value and adding `1` so the @@ -246,10 +210,6 @@ variable, multiplying the previous value by `2` to give `x` a value of `12`. When that scope is over, the inner shadowing ends and `x` returns to being `6`. When we run this program, it will output the following: -<!--- I lean towards reiterating that each `let x` is creating a new variable. -/JT --> -<!-- I've added a few mentions to that effect in the previous paragraph, what do you think, Liz? /Carol --> - ``` $ cargo run Compiling variables v0.1.0 (file:///projects/variables) @@ -259,46 +219,21 @@ The value of x in the inner scope is: 12 The value of x is: 6 ``` -Shadowing is different from marking a variable as `mut`, because we’ll get a +Shadowing is different from marking a variable as `mut` because we’ll get a compile-time error if we accidentally try to reassign to this variable without using the `let` keyword. By using `let`, we can perform a few transformations on a value but have the variable be immutable after those transformations have been completed. -<!--- so, to be clear, we're not overwriting the variable, so when the -shadowing variable goes out of scope the earlier variables become visible to -the compiler? ---> -<!-- Well, we *are* overwriting it *in the inner scope* -- there's no way to -access the original value from the outer scope within the inner scope after -the shadowing. But yes, shadowing only applies to the scope it happens in, -which is what this example illustrates. Is there something that could be -made clearer? /Carol --> -<!-- JT, what do you think, is this clear enough as is or is there some way to clarify in the text? /LC --> -<!--- I made a couple notes above trying to see if we could tease out a good -explanation. Shadowing is effectively creating new variables and then these -variables get a kind of "higher priority" when you look up the same variable -name. Shadowing priority is kind of a "most recent wins", and it stays until -that variable is shadowed by a following one or that variable goes out of scope. -/JT --> - The other difference between `mut` and shadowing is that because we’re effectively creating a new variable when we use the `let` keyword again, we can change the type of the value but reuse the same name. For example, say our program asks a user to show how many spaces they want between some text by inputting space characters, and then we want to store that input as a number: -<!--- Question: the further I read, the more I wonder if we should put the shadowing -stuff later. Is it valuable here as a kind of "building the right mental model" or -are we using up too much of our complexity budget for building that mental model -relatively early in the journey? Once we're introducing shadowing into new types -we're getting relatively deep into Rust-specific coding patterns /JT --> -<!-- I think it's important to address this here because shadowing is extremely -common in idiomatic Rust code, but can be unfamiliar. I'm not sure where it -would be appropriate to address if not here. /Carol --> - ``` - let spaces = " "; - let spaces = spaces.len(); +let spaces = " "; +let spaces = spaces.len(); ``` The first `spaces` variable is a string type and the second `spaces` variable @@ -308,8 +243,8 @@ the simpler `spaces` name. However, if we try to use `mut` for this, as shown here, we’ll get a compile-time error: ``` - let mut spaces = " "; - spaces = spaces.len(); +let mut spaces = " "; +spaces = spaces.len(); ``` The error says we’re not allowed to mutate a variable’s type: @@ -339,20 +274,16 @@ Keep in mind that Rust is a *statically typed* language, which means that it must know the types of all variables at compile time. The compiler can usually infer what type we want to use based on the value and how we use it. In cases when many types are possible, such as when we converted a `String` to a numeric -type using `parse` in the “Comparing the Guess to the Secret Number” section in -Chapter 2, we must add a type annotation, like this: +type using `parse` in “Comparing the Guess to the Secret Number” on page XX, we +must add a type annotation, like this: ``` let guess: u32 = "42".parse().expect("Not a number!"); ``` -If we don’t add the `: u32` type annotation above, Rust will display the -following error, which means the compiler needs more information from us to -know which type we want to use: - -<!--- To help visual parsing, you might want to say "If we don't add the `: u32` type -annotation above... /JT ---> -<!-- Done /Carol --> +If we don’t add the `: u32` type annotation shown in the preceding code, Rust +will display the following error, which means the compiler needs more +information from us to know which type we want to use: ``` $ cargo build @@ -377,20 +308,20 @@ these from other programming languages. Let’s jump into how they work in Rust. An *integer* is a number without a fractional component. We used one integer type in Chapter 2, the `u32` type. This type declaration indicates that the value it’s associated with should be an unsigned integer (signed integer types -start with `i`, instead of `u`) that takes up 32 bits of space. Table 3-1 shows +start with `i` instead of `u`) that takes up 32 bits of space. Table 3-1 shows the built-in integer types in Rust. We can use any of these variants to declare the type of an integer value. Table 3-1: Integer Types in Rust -| Length | Signed | Unsigned | -|---------|---------|----------| -| 8-bit | `i8` | `u8` | -| 16-bit | `i16` | `u16` | -| 32-bit | `i32` | `u32` | -| 64-bit | `i64` | `u64` | -| 128-bit | `i128` | `u128` | -| arch | `isize` | `usize` | +| Length | Signed | Unsigned | +|---|---|---| +| 8-bit | `i8` | `u8` | +| 16-bit | `i16` | `u16` | +| 32-bit | `i32` | `u32` | +| 64-bit | `i64` | `u64` | +| 128-bit | `i128` | `u128` | +| arch | `isize` | `usize` | Each variant can be either signed or unsigned and has an explicit size. *Signed* and *unsigned* refer to whether it’s possible for the number to be @@ -420,55 +351,54 @@ have the same value as if you had specified `1000`. Table 3-2: Integer Literals in Rust -| Number literals | Example | -|------------------|---------------| -| Decimal | `98_222` | -| Hex | `0xff` | -| Octal | `0o77` | -| Binary | `0b1111_0000` | -| Byte (`u8` only) | `b'A'` | +| Number literals | Example | +|---|---| +| Decimal | `98_222` | +| Hex | `0xff` | +| Octal | `0o77` | +| Binary | `0b1111_0000` | +| Byte (`u8` only) | `b'A'` | So how do you know which type of integer to use? If you’re unsure, Rust’s defaults are generally good places to start: integer types default to `i32`. The primary situation in which you’d use `isize` or `usize` is when indexing some sort of collection. -> ##### Integer Overflow +> ### Integer Overflow > > Let’s say you have a variable of type `u8` that can hold values between 0 and -> 255. If you try to change the variable to a value outside of that range, such -> as 256, *integer overflow* will occur, which can result in one of two -> behaviors. When you’re compiling in debug mode, Rust includes checks for -> integer overflow that cause your program to *panic* at runtime if this -> behavior occurs. Rust uses the term panicking when a program exits with an -> error; we’ll discuss panics in more depth in the “Unrecoverable Errors with -> `panic!`” section in Chapter 9. +255. If you try to change the variable to a value outside that range, such as +256, *integer overflow* will occur, which can result in one of two behaviors. +When you’re compiling in debug mode, Rust includes checks for integer overflow +that cause your program to *panic* at runtime if this behavior occurs. Rust +uses the term *panicking* when a program exits with an error; we’ll discuss +panics in more depth in “Unrecoverable Errors with panic!” on page XX. > > When you’re compiling in release mode with the `--release` flag, Rust does -> *not* include checks for integer overflow that cause panics. Instead, if -> overflow occurs, Rust performs *two’s complement wrapping*. In short, values -> greater than the maximum value the type can hold “wrap around” to the minimum -> of the values the type can hold. In the case of a `u8`, the value 256 becomes -> 0, the value 257 becomes 1, and so on. The program won’t panic, but the -> variable will have a value that probably isn’t what you were expecting it to -> have. Relying on integer overflow’s wrapping behavior is considered an error. +*not* include checks for integer overflow that cause panics. Instead, if +overflow occurs, Rust performs *two’s complement wrapping*. In short, values +greater than the maximum value the type can hold “wrap around” to the minimum +of the values the type can hold. In the case of a `u8`, the value 256 becomes +0, the value 257 becomes 1, and so on. The program won’t panic, but the +variable will have a value that probably isn’t what you were expecting it to +have. Relying on integer overflow’s wrapping behavior is considered an error. > > To explicitly handle the possibility of overflow, you can use these families -> of methods provided by the standard library for primitive numeric types: +of methods provided by the standard library for primitive numeric types: > -> - Wrap in all modes with the `wrapping_*` methods, such as `wrapping_add` -> - Return the `None` value if there is overflow with the `checked_*` methods -> - Return the value and a boolean indicating whether there was overflow with -> the `overflowing_*` methods -> - Saturate at the value’s minimum or maximum values with `saturating_*` -> methods +> * Wrap in all modes with the `wrapping_*` methods, such as `wrapping_add`. +> * Return the `None` value if there is overflow with the `checked_*` methods. +> * Return the value and a boolean indicating whether there was overflow with +the `overflowing_*` methods. +> * Saturate at the value’s minimum or maximum values with the `saturating_*` +methods. #### Floating-Point Types Rust also has two primitive types for *floating-point numbers*, which are numbers with decimal points. Rust’s floating-point types are `f32` and `f64`, which are 32 bits and 64 bits in size, respectively. The default type is `f64` -because on modern CPUs it’s roughly the same speed as `f32` but is capable of +because on modern CPUs, it’s roughly the same speed as `f32` but is capable of more precision. All floating-point types are signed. Here’s an example that shows floating-point numbers in action: @@ -488,9 +418,9 @@ Floating-point numbers are represented according to the IEEE-754 standard. The #### Numeric Operations -Rust supports the basic mathematical operations you’d expect for all of the -number types: addition, subtraction, multiplication, division, and remainder. -Integer division rounds down to the nearest integer. The following code shows +Rust supports the basic mathematical operations you’d expect for all the number +types: addition, subtraction, multiplication, division, and remainder. Integer +division truncates toward zero to the nearest integer. The following code shows how you’d use each numeric operation in a `let` statement: Filename: src/main.rs @@ -508,7 +438,7 @@ fn main() { // division let quotient = 56.7 / 32.2; - let floored = 2 / 3; // Results in 0 + let truncated = -5 / 3; // Results in -1 // remainder let remainder = 43 % 5; @@ -536,12 +466,12 @@ fn main() { ``` The main way to use Boolean values is through conditionals, such as an `if` -expression. We’ll cover how `if` expressions work in Rust in the “Control -Flow” section. +expression. We’ll cover how `if` expressions work in Rust in “Control Flow” on +page XX. #### The Character Type -Rust’s `char` type is the language’s most primitive alphabetic type. Here’s +Rust’s `char` type is the language’s most primitive alphabetic type. Here are some examples of declaring `char` values: Filename: src/main.rs @@ -563,7 +493,7 @@ Values range from `U+0000` to `U+D7FF` and `U+E000` to `U+10FFFF` inclusive. However, a “character” isn’t really a concept in Unicode, so your human intuition for what a “character” is may not match up with what a `char` is in Rust. We’ll discuss this topic in detail in “Storing UTF-8 Encoded Text with -Strings” in Chapter 8. +Strings” on page XX. ### Compound Types @@ -572,9 +502,9 @@ primitive compound types: tuples and arrays. #### The Tuple Type -A tuple is a general way of grouping together a number of values with a variety -of types into one compound type. Tuples have a fixed length: once declared, -they cannot grow or shrink in size. +A *tuple* is a general way of grouping together a number of values with a +variety of types into one compound type. Tuples have a fixed length: once +declared, they cannot grow or shrink in size. We create a tuple by writing a comma-separated list of values inside parentheses. Each position in the tuple has a type, and the types of the @@ -589,7 +519,7 @@ fn main() { } ``` -The variable `tup` binds to the entire tuple, because a tuple is considered a +The variable `tup` binds to the entire tuple because a tuple is considered a single compound element. To get the individual values out of a tuple, we can use pattern matching to destructure a tuple value, like this: @@ -607,7 +537,7 @@ fn main() { This program first creates a tuple and binds it to the variable `tup`. It then uses a pattern with `let` to take `tup` and turn it into three separate -variables, `x`, `y`, and `z`. This is called *destructuring*, because it breaks +variables, `x`, `y`, and `z`. This is called *destructuring* because it breaks the single tuple into three parts. Finally, the program prints the value of `y`, which is `6.4`. @@ -632,28 +562,11 @@ This program creates the tuple `x` and then accesses each element of the tuple using their respective indices. As with most programming languages, the first index in a tuple is 0. -<!--- Indexing into a tuple using a constant, just like accessing a field of a struct, -I think is maybe a more natural way to think of this than thinking of `x.0`, `x.1`, etc -as separate variables. In the struct case, we don't think of each field as a separate -variable, but instead that there's a path to get to the contained values that can be -used and checked at compile time. /JT ---> -<!-- I think JT was actually confused with what this paragraph was trying to -say, it was explaining that this particular example created new variables and -bound them to the values of the tuple elements, not that the tuple elements -*were* separate variables, so I've reworded this paragraph. Please check that -this makes sense, Liz! /Carol --> - The tuple without any values has a special name, *unit*. This value and its corresponding type are both written `()` and represent an empty value or an empty return type. Expressions implicitly return the unit value if they don’t return any other value. -<!--- It's trick to see the difference between `()` and `()`. Maybe we can say: "The -tuple without any values has a special name, *unit*. This value, and its corresponding -type -- also written `()` -- represent an empty value or an empty return type." /JT ---> -<!-- I've tried to clear this up, but didn't take JT's suggestion exactly, -there were too many subphrases in my opinion /Carol --> - #### The Array Type Another way to have a collection of multiple values is with an *array*. Unlike @@ -674,7 +587,7 @@ fn main() { Arrays are useful when you want your data allocated on the stack rather than the heap (we will discuss the stack and the heap more in Chapter 4) or when you want to ensure you always have a fixed number of elements. An array isn’t as -flexible as the vector type, though. A vector is a similar collection type +flexible as the vector type, though. A *vector* is a similar collection type provided by the standard library that *is* allowed to grow or shrink in size. If you’re unsure whether to use an array or a vector, chances are you should use a vector. Chapter 8 discusses vectors in more detail. @@ -711,7 +624,7 @@ The array named `a` will contain `5` elements that will all be set to the value `3` initially. This is the same as writing `let a = [3, 3, 3, 3, 3];` but in a more concise way. -##### Accessing Array Elements +#### Accessing Array Elements An array is a single chunk of memory of a known, fixed size that can be allocated on the stack. You can access elements of an array using indexing, @@ -728,11 +641,11 @@ fn main() { } ``` -In this example, the variable named `first` will get the value `1`, because -that is the value at index `[0]` in the array. The variable named `second` will -get the value `2` from index `[1]` in the array. +In this example, the variable named `first` will get the value `1` because that +is the value at index `[0]` in the array. The variable named `second` will get +the value `2` from index `[1]` in the array. -##### Invalid Array Element Access +#### Invalid Array Element Access Let’s see what happens if you try to access an element of an array that is past the end of the array. Say you run this code, similar to the guessing game in @@ -768,12 +681,13 @@ fn main() { ``` This code compiles successfully. If you run this code using `cargo run` and -enter 0, 1, 2, 3, or 4, the program will print out the corresponding value at -that index in the array. If you instead enter a number past the end of the -array, such as 10, you’ll see output like this: +enter `0`, `1`, `2`, `3`, or `4`, the program will print out the corresponding +value at that index in the array. If you instead enter a number past the end of +the array, such as `10`, you’ll see output like this: ``` -thread 'main' panicked at 'index out of bounds: the len is 5 but the index is 10', src/main.rs:19:19 +thread 'main' panicked at 'index out of bounds: the len is 5 but the index is +10', src/main.rs:19:19 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` @@ -793,13 +707,6 @@ kind of error by immediately exiting instead of allowing the memory access and continuing. Chapter 9 discusses more of Rust’s error handling and how you can write readable, safe code that neither panics nor allows invalid memory access. -<!--- I get the idea, though I'm feeling a little uneasy with leaving the reader -thinking "panic > invalid access" as the end of the story. Maybe we can tag something -on to the end: "Chapter 9 discusses more of Rust's error handling, and how you can -write readable, safe code that doesn't panic and doesn't allow invalid memory access. -/JT ---> -<!-- I've incorporated JT's suggestion with a bit of rewording above /Carol --> - ## Functions Functions are prevalent in Rust code. You’ve already seen one of the most @@ -836,14 +743,6 @@ called from inside the `main` function. Note that we defined `another_function` as well. Rust doesn’t care where you define your functions, only that they’re defined somewhere in a scope that can be seen by the caller. -<!--- nit: Rust does want the functions in a place the caller can see. If they're -not in scope, Rust won't let the program build. Maybe we can say: -"only that they're defined somewhere the caller can see them". -or alt: "only that they're defined somewhere in a scope that can be seen by the -caller" -/JT ---> -<!-- Done! /Carol --> - Let’s start a new binary project named *functions* to explore functions further. Place the `another_function` example in *src/main.rs* and run it. You should see the following output: @@ -858,8 +757,8 @@ Another function. ``` The lines execute in the order in which they appear in the `main` function. -First, the “Hello, world!” message prints, and then `another_function` is -called and its message is printed. +First the “Hello, world!” message prints, and then `another_function` is called +and its message is printed. ### Parameters @@ -885,9 +784,6 @@ fn another_function(x: i32) { } ``` -<!--- nit: might want to use `{x}` /JT ---> -<!-- Done! /Carol --> - Try running this program; you should get the following output: ``` @@ -909,9 +805,6 @@ definitions means the compiler almost never needs you to use them elsewhere in the code to figure out what type you mean. The compiler is also able to give more helpful error messages if it knows what types the function expects. -<!--- Also helps give much better error messages /JT ---> -<!-- Added a note! /Carol --> - When defining multiple parameters, separate the parameter declarations with commas, like this: @@ -957,19 +850,14 @@ understand. Other languages don’t have the same distinctions, so let’s look what statements and expressions are and how their differences affect the bodies of functions. -*Statements* are instructions that perform some action and do not return a -value. *Expressions* evaluate to a resulting value. Let’s look at some examples. +* **Statements **: are instructions that perform some action and do not return +a value. +* **Expressions **: evaluate to a resultant value. Let’s look at some examples. We’ve actually already used statements and expressions. Creating a variable and assigning a value to it with the `let` keyword is a statement. In Listing 3-1, `let y = 6;` is a statement. -<!--- To help clarify how they're related, we could say that "`let y = 6;`" is a -statement, and the `6` being assigned to `y` is an expression. edit: I see we -say this later, just thought it might be a little nicer to give an examples of -each just following their definition. /JT ---> -<!-- I think I'm going to leave this as-is /Carol --> - Filename: src/main.rs ``` @@ -1007,33 +895,16 @@ error: expected expression, found statement (`let`) | = note: variable declaration using `let` is a statement -error[E0658]: `let` expressions in this position are experimental +error[E0658]: `let` expressions in this position are unstable --> src/main.rs:2:14 | 2 | let x = (let y = 6); | ^^^^^^^^^ | - = note: see issue #53667 <https://github.com/rust-lang/rust/issues/53667> for more information - = help: you can write `matches!(<expr>, <pattern>)` instead of `let <pattern> = <expr>` - -warning: unnecessary parentheses around assigned value - --> src/main.rs:2:13 - | -2 | let x = (let y = 6); - | ^ ^ - | - = note: `#[warn(unused_parens)]` on by default -help: remove these parentheses - | -2 - let x = (let y = 6); -2 + let x = let y = 6; - | + = note: see issue #53667 <https://github.com/rust-lang/rust/issues/53667> for +more information ``` -<!--- The errors in more recent Rust look slightly different here, if we want -to update before publication. /JT ---> -<!-- Updated here and I will also check when we're in Word /Carol --> - The `let y = 6` statement does not return a value, so there isn’t anything for `x` to bind to. This is different from what happens in other languages, such as C and Ruby, where the assignment returns the value of the assignment. In those @@ -1052,30 +923,22 @@ Filename: src/main.rs ``` fn main() { - let y = { + 1 let y = {2 let x = 3; - x + 1 + 3 x + 1 }; println!("The value of y is: {y}"); } ``` -This expression: - -``` -{ - let x = 3; - x + 1 -} -``` - -is a block that, in this case, evaluates to `4`. That value gets bound to `y` -as part of the `let` statement. Note that the `x + 1` line doesn’t have a -semicolon at the end, unlike most of the lines you’ve seen so far. Expressions -do not include ending semicolons. If you add a semicolon to the end of an -expression, you turn it into a statement, and it will then not return a value. -Keep this in mind as you explore function return values and expressions next. +The expression [2] is a block that, in this case, evaluates to `4`. That value +gets bound to `y` as part of the `let` statement [1]. Note the line without a +semicolon at the end [3], which is unlike most of the lines you’ve seen so far. +Expressions do not include ending semicolons. If you add a semicolon to the end +of an expression, you turn it into a statement, and it will then not return a +value. Keep this in mind as you explore function return values and expressions +next. ### Functions with Return Values @@ -1128,10 +991,6 @@ Second, the `five` function has no parameters and defines the type of the return value, but the body of the function is a lonely `5` with no semicolon because it’s an expression whose value we want to return. -<!--- If you want, you could point out that the `println!` line that main ends -on is a statement, hence why main doesn't have a return value. /JT ---> -<!-- I don't think I want to :) /Carol --> - Let’s look at another example: Filename: src/main.rs @@ -1150,7 +1009,7 @@ fn plus_one(x: i32) -> i32 { Running this code will print `The value of x is: 6`. But if we place a semicolon at the end of the line containing `x + 1`, changing it from an -expression to a statement, we’ll get an error. +expression to a statement, we’ll get an error: Filename: src/main.rs @@ -1179,10 +1038,10 @@ error[E0308]: mismatched types | | | implicitly returns `()` as its body has no tail or `return` expression 8 | x + 1; - | - help: consider removing this semicolon + | - help: remove this semicolon ``` -The main error message, “mismatched types,” reveals the core issue with this +The main error message, `mismatched types`, reveals the core issue with this code. The definition of the function `plus_one` says that it will return an `i32`, but statements don’t evaluate to a value, which is expressed by `()`, the unit type. Therefore, nothing is returned, which contradicts the function @@ -1236,16 +1095,16 @@ fn main() { ``` Rust also has another kind of comment, documentation comments, which we’ll -discuss in the “Publishing a Crate to Crates.io” section of Chapter 14. +discuss in “Publishing a Crate to Crates.io” on page XX. ## Control Flow -The ability to run some code depending on if a condition is true, or run some -code repeatedly while a condition is true, are basic building blocks in most -programming languages. The most common constructs that let you control the flow -of execution of Rust code are `if` expressions and loops. +The ability to run some code depending on whether a condition is `true` and to +run some code repeatedly while a condition is `true` are basic building blocks +in most programming languages. The most common constructs that let you control +the flow of execution of Rust code are `if` expressions and loops. -### `if` Expressions +### if Expressions An `if` expression allows you to branch your code depending on conditions. You provide a condition and then state, “If this condition is met, run this block @@ -1270,16 +1129,16 @@ fn main() { All `if` expressions start with the keyword `if`, followed by a condition. In this case, the condition checks whether or not the variable `number` has a -value less than 5. We place the block of code to execute if the condition is true -immediately after the condition inside curly brackets. Blocks of code +value less than 5. We place the block of code to execute if the condition is +`true` immediately after the condition inside curly brackets. Blocks of code associated with the conditions in `if` expressions are sometimes called *arms*, -just like the arms in `match` expressions that we discussed in the “Comparing -the Guess to the Secret Number” section of Chapter 2. +just like the arms in `match` expressions that we discussed in “Comparing the +Guess to the Secret Number” on page XX. -Optionally, we can also include an `else` expression, which we chose -to do here, to give the program an alternative block of code to execute should -the condition evaluate to false. If you don’t provide an `else` expression and -the condition is false, the program will just skip the `if` block and move on +Optionally, we can also include an `else` expression, which we chose to do +here, to give the program an alternative block of code to execute should the +condition evaluate to `false`. If you don’t provide an `else` expression and +the condition is `false`, the program will just skip the `if` block and move on to the next bit of code. Try running this code; you should see the following output: @@ -1359,7 +1218,7 @@ fn main() { Running this code will print `number was something other than zero`. -#### Handling Multiple Conditions with `else if` +#### Handling Multiple Conditions with else if You can use multiple conditions by combining `if` and `else` in an `else if` expression. For example: @@ -1394,17 +1253,17 @@ number is divisible by 3 ``` When this program executes, it checks each `if` expression in turn and executes -the first body for which the condition holds true. Note that even though 6 is -divisible by 2, we don’t see the output `number is divisible by 2`, nor do we -see the `number is not divisible by 4, 3, or 2` text from the `else` block. -That’s because Rust only executes the block for the first true condition, and -once it finds one, it doesn’t even check the rest. +the first body for which the condition evaluates to `true`. Note that even +though 6 is divisible by 2, we don’t see the output `number is divisible by 2`, +nor do we see the `number is not divisible by 4, 3, or 2` text from the `else` +block. That’s because Rust only executes the block for the first `true` +condition, and once it finds one, it doesn’t even check the rest. Using too many `else if` expressions can clutter your code, so if you have more than one, you might want to refactor your code. Chapter 6 describes a powerful Rust branching construct called `match` for these cases. -#### Using `if` in a `let` Statement +#### Using if in a let Statement Because `if` is an expression, we can use it on the right side of a `let` statement to assign the outcome to a variable, as in Listing 3-2. @@ -1420,19 +1279,8 @@ fn main() { } ``` -<!--- Style nit: `{number}`. /JT ---> -<!-- Fixed! /Carol --> - Listing 3-2: Assigning the result of an `if` expression to a variable -<!--- I was wondering when listings got numbered and when they didn't. Many of -the above don't get a number a title, though maybe it'd help readability? /JT ---> -<!-- Liz: Chapter 3 doesn't have many listing numbers because on the first -round of printing, we hadn't really figured out what we were doing with listing -numbers yet. I'm happy to add more listing numbers in Chapter 3, but it'll take -me some time to go through and add appropriate captions, check cross -references, etc. Let me know if you'd like me to spend that time. /Carol --> - The `number` variable will be bound to a value based on the outcome of the `if` expression. Run this code to see what happens: @@ -1475,7 +1323,8 @@ error[E0308]: `if` and `else` have incompatible types --> src/main.rs:4:44 | 4 | let number = if condition { 5 } else { "six" }; - | - ^^^^^ expected integer, found `&str` + | - ^^^^^ expected integer, found +`&str` | | | expected because of this ``` @@ -1493,12 +1342,12 @@ if it had to keep track of multiple hypothetical types for any variable. It’s often useful to execute a block of code more than once. For this task, Rust provides several *loops*, which will run through the code inside the loop -body to the end and then start immediately back at the beginning. To -experiment with loops, let’s make a new project called *loops*. +body to the end and then start immediately back at the beginning. To experiment +with loops, let’s make a new project called *loops*. Rust has three kinds of loops: `loop`, `while`, and `for`. Let’s try each one. -#### Repeating Code with `loop` +#### Repeating Code with loop The `loop` keyword tells Rust to execute a block of code over and over again forever or until you explicitly tell it to stop. @@ -1517,9 +1366,9 @@ fn main() { ``` When we run this program, we’ll see `again!` printed over and over continuously -until we stop the program manually. Most terminals support the keyboard shortcut -<span class="keystroke">ctrl-c</span> to interrupt a program that is stuck in -a continual loop. Give it a try: +until we stop the program manually. Most terminals support the keyboard +shortcut ctrl-C to interrupt a program that is stuck in a continual loop. Give +it a try: ``` $ cargo run @@ -1533,25 +1382,20 @@ again! ^Cagain! ``` -The symbol `^C` represents where you pressed <span class="keystroke">ctrl-c -</span>. You may or may not see the word `again!` printed after the `^C`, -depending on where the code was in the loop when it received the interrupt -signal. +The symbol `^C` represents where you pressed ctrl-C. You may or may not see the +word `again!` printed after the `^C`, depending on where the code was in the +loop when it received the interrupt signal. Fortunately, Rust also provides a way to break out of a loop using code. You can place the `break` keyword within the loop to tell the program when to stop -executing the loop. Recall that we did this in the guessing game in the -“Quitting After a Correct Guess” section of Chapter 2 to exit the program when -the user won the game by guessing the correct number. +executing the loop. Recall that we did this in the guessing game in “Quitting +After a Correct Guess” on page XX to exit the program when the user won the +game by guessing the correct number. We also used `continue` in the guessing game, which in a loop tells the program to skip over any remaining code in this iteration of the loop and go to the next iteration. -<!--- Before you show loop labels below, you might want to give a code example -of using `break` to break a loop. /JT ---> -<!-- I've rearranged the sections to take this suggestion here /Carol --> - #### Returning Values from Loops One of the uses of a `loop` is to retry an operation you know might fail, such @@ -1580,20 +1424,18 @@ fn main() { Before the loop, we declare a variable named `counter` and initialize it to `0`. Then we declare a variable named `result` to hold the value returned from the loop. On every iteration of the loop, we add `1` to the `counter` variable, -and then check whether the counter is equal to `10`. When it is, we use the +and then check whether the `counter` is equal to `10`. When it is, we use the `break` keyword with the value `counter * 2`. After the loop, we use a semicolon to end the statement that assigns the value to `result`. Finally, we -print the value in `result`, which in this case is 20. +print the value in `result`, which in this case is `20`. #### Loop Labels to Disambiguate Between Multiple Loops -<!-- Liz: New heading for this section, what do you think? /Carol --> - If you have loops within loops, `break` and `continue` apply to the innermost -loop at that point. You can optionally specify a *loop label* on a loop that we -can then use with `break` or `continue` to specify that those keywords apply to -the labeled loop instead of the innermost loop. Loop labels must begin with a -single quote. Here’s an example with two nested loops: +loop at that point. You can optionally specify a *loop label* on a loop that +you can then use with `break` or `continue` to specify that those keywords +apply to the labeled loop instead of the innermost loop. Loop labels must begin +with a single quote. Here’s an example with two nested loops: ``` fn main() { @@ -1639,10 +1481,10 @@ remaining = 10 End count = 2 ``` -#### Conditional Loops with `while` +#### Conditional Loops with while A program will often need to evaluate a condition within a loop. While the -condition is true, the loop runs. When the condition ceases to be true, the +condition is `true`, the loop runs. When the condition ceases to be `true`, the program calls `break`, stopping the loop. It’s possible to implement behavior like this using a combination of `loop`, `if`, `else`, and `break`; you could try that now in a program, if you’d like. However, this pattern is so common @@ -1666,13 +1508,14 @@ fn main() { } ``` -Listing 3-3: Using a `while` loop to run code while a condition holds true +Listing 3-3: Using a `while` loop to run code while a condition evaluates to +`true` This construct eliminates a lot of nesting that would be necessary if you used -`loop`, `if`, `else`, and `break`, and it’s clearer. While a condition holds -true, the code runs; otherwise, it exits the loop. +`loop`, `if`, `else`, and `break`, and it’s clearer. While a condition +evaluates to `true`, the code runs; otherwise, it exits the loop. -#### Looping Through a Collection with `for` +#### Looping Through a Collection with for You can choose to use the `while` construct to loop over the elements of a collection, such as an array. For example, the loop in Listing 3-4 prints each @@ -1697,8 +1540,8 @@ Listing 3-4: Looping through each element of a collection using a `while` loop Here, the code counts up through the elements in the array. It starts at index `0`, and then loops until it reaches the final index in the array (that is, -when `index < 5` is no longer true). Running this code will print every element -in the array: +when `index < 5` is no longer `true`). Running this code will print every +element in the array: ``` $ cargo run @@ -1717,8 +1560,8 @@ will reach a value of `5` at some point, the loop stops executing before trying to fetch a sixth value from the array. However, this approach is error prone; we could cause the program to panic if -the index value or test condition are incorrect. For example, if you changed -the definition of the `a` array to have four elements but forgot to update the +the index value or test condition is incorrect. For example, if you changed the +definition of the `a` array to have four elements but forgot to update the condition to `while index < 4`, the code would panic. It’s also slow, because the compiler adds runtime code to perform the conditional check of whether the index is within the bounds of the array on every iteration through the loop. @@ -1775,15 +1618,16 @@ This code is a bit nicer, isn’t it? ## Summary -You made it! That was a sizable chapter: you learned about variables, scalar -and compound data types, functions, comments, `if` expressions, and loops! -To practice with the concepts discussed in this chapter, try building -programs to do the following: +You made it! This was a sizable chapter: you learned about variables, scalar +and compound data types, functions, comments, `if` expressions, and loops! To +practice with the concepts discussed in this chapter, try building programs to +do the following: * Convert temperatures between Fahrenheit and Celsius. -* Generate the nth Fibonacci number. +* Generate the *n*th Fibonacci number. * Print the lyrics to the Christmas carol “The Twelve Days of Christmas,” - taking advantage of the repetition in the song. +taking advantage of the repetition in the song. When you’re ready to move on, we’ll talk about a concept in Rust that *doesn’t* commonly exist in other programming languages: ownership. + |