I started on the error handling chapter. I feel... okay about it. I dunno.

I decided to go with an example that we start with a panic, and then convert to a result. I think this draws the connection a bit better than showing two totally different examples, but at the downside of showing function panic that probably shouldn't. Reasonable folks may differ on this tradeoff; I'm open to arguments.

I decided to stop here rather than go on to all the From stuff, because I wanted to make sure that this was on track first. Should we use a different example? Is the length of time spent talking about panic vs abort a waste of time right here? How should I end up demonstrating try!, just making another dummy function from main()?

Instead of talking about variable bindings, would it be better to use the term variables (like other languages) and explain the rest in terms of references?

Let's explore. Are variable bindings:

• a core concept
• a way of explaining/thinking about what's happening
• an implementation detail

Variable (mathematics): (from Wikipedia) In elementary mathematics, a variable is an alphabetic character representing a number, called the value of the variable, which is either arbitrary or not fully specified or unknown.

Variable (computer science): (from Wikipedia) In computer programming, a variable or scalar is a storage location paired with an associated symbolic name (an identifier), which contains some known or unknown quantity of information referred to as a value. The variable name is the usual way to reference the stored value; this separation of name and content allows the name to be used independently of the exact information it represents. The identifier in computer source code can be bound to a value during run time, and the value of the variable may thus change during the course of program execution.

Variable: (my definition) A symbolic name that represents a value or reference.

Niko Matsakis uses the terms variables and references in his into_rust() videos and I'm not confused. Even rustc's error messages use the term variable.

So what is a variable binding and how is it different from a variable? In writing about this, it became clear that after 2 years following Rust, I still don't know. Some possibilities:

• A variable implies changeability/mutability, so we need a different concept to make immutability clear.
• A value/reference is a separate concept from the symbolic name we use to represent it.
• A separate concept is needed to explain why an immutable variable can contain a mutable reference.
• To make it clear that moving a variable binding does not necessarily mean copying its memory.
• To make it clear that declaring a binding does not necessarily mean copying or allocating memory.

Am I missing an aspect to the variable bindings concept?

I think saying a variable is bound to a value or bound to a reference is a great way of expressing it, but does it really mean something different to a variable contains a value or contains a reference?

Does a distinction between variable bindings and variables need to be drawn?

Is there the possibility of having a version of the Book in a single web page or pdf format? I want to search across the chapters and having them be separate links makes this difficult to do so.

This time, drop all the crate stuff.

This example is still abstract, but is based off the original stuff that cargo new generates for you. @carols10cents @jonathandturner what do you think?

Reviewers: Please read the added text for these chapters and leave any comments you have on this PR! Thank you for your help!

Carol TODO:

• [x] Add filenames to code examples where it makes sense
• [x] Switch underscores used for emphasis to asterisks for consistency

This example from Learn Rust doesn't work -

extern crate rand;

use std::io;
use std::cmp::Ordering;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1, 101);

    println!("The secret number is: {}", secret_number);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin().read_line(&mut guess)
        .ok()
        .expect("failed to read line");

    println!("You guessed: {}", guess);

    match guess.cmp(&secret_number) {
        Ordering::Less    => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal   => println!("You win!"),
    }
}

I am using Rust 1.5 on OSX and the example doesn't work on Rust playground either.

Google and other search engines are still serving search results from the first edition of the book; for example, this link was the first result for "rust ownership". I noticed that they're being served up with a status code of 200 - should this be 301 or 410 to let them be purged from the index and replaced with a current URL?

Versions

Book:

• https://doc.rust-lang.org/book/ch02-00-guessing-game-tutorial.html
• https://doc.rust-lang.org/nightly/book/ch02-00-guessing-game-tutorial.html

rustc: rustc 1.31.0 (abe02cefd 2018-12-04)

cargo: cargo 1.31.0 (339d9f9c8 2018-11-16)

What is the issue:

When going through the Guessing Game tutorial:

Listing 2-3 contains some code that should use rand:

use std::io;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1, 101);

    println!("The secret number is: {}", secret_number);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin().read_line(&mut guess)
        .expect("Failed to read line");

    println!("You guessed: {}", guess);
}

This code does not compile, with the following errors:

azvorygi@bit-shifter:~/Code/rst$ cargo run
   Compiling rst v0.1.0 (/users/azvorygi/Code/rst)                                                                                                                                            
error[E0432]: unresolved import `rand`                                                                                                                                                        
 --> src/main.rs:2:5                                                                                                                                                                          
  |                                                                                                                                                                                           
2 | use rand::Rng;                                                                                                                                                                            
  |     ^^^^ maybe a missing `extern crate rand;`?                                                                                                                                            
                                                                                                                                                                                              
warning: unused import: `rand::Rng`                                                                                                                                                           
 --> src/main.rs:2:5                                                                                                                                                                          
  |                                                                                                                                                                                           
2 | use rand::Rng;                                                                                                                                                                            
  |     ^^^^^^^^^                                                                                                                                                                             
  |                                                                                                                                                                                           
  = note: #[warn(unused_imports)] on by default                                                                                                                                               
                                                                                                                                                                                              
error[E0599]: no method named `gen_range` found for type `rand::ThreadRng` in the current scope                                                                                               
 --> src/main.rs:7:44                                                                                                                                                                         
  |                                                                                                                                                                                           
7 |     let secret_number = rand::thread_rng().gen_range(1, 101);                                                                                                                             
  |                                            ^^^^^^^^^                                                                                                                                      
  |                                                                                                                                                                                           
  = help: items from traits can only be used if the trait is in scope                                                                                                                         
help: the following trait is implemented but not in scope, perhaps add a `use` for it:                                                                                                        
  |                                                                                                                                                                                           
1 | use rand::Rng;                                                                                                                                                                            
  |                                                                                                                                                                                           
                                                                                                                                                                                              
error: aborting due to 2 previous errors                                                                                                                                                      
                                                                                                                                                                                              
Some errors occurred: E0432, E0599.                                                                                                                                                           
For more information about an error, try `rustc --explain E0432`.                                                                                                                             
error: Could not compile `rst`.                                                                                                                                                               

This is of course after adding the following to my Cargo.toml:

[dependencies]
rand = "0.3.14"

Here's a github repo with my repo when it is breaking: https://github.com/zvory/guessing-game-breaking

One thing we do when showing errors is show file:///projects/bindings in Cargo's output. It'd be nice to somehow catch that this is always the text we use, as it's really easy to copy/paste something and forget to change it.

Hey guys!

First of all - thank you very much for the great language and the great book. I'm new to coding, so I'm sorry if anything (or everything) I say is stupid.

At least for me, there is a very bad example in the "6.3 Concise Control Flow with if let" chapter. It says:

if let Some(3) = some_u8_value {
    println!("three");
}

I had been somewhat at a loss as to why or how this expression is any better than say

if Some(3) == some_u8_value {
    println!("three");
}

and it took me some time to come to the conclusion that in this particular case it probably isn't better at all, if not worse for arguably "weird" (for me in that state of mind) syntax. By weird, I mean that at the time the part after "if" looked like

let 3 = x

for me, which had just turned my head around :)

Long story short, I think it is more clear to explain "if let" through use of unwrapping the optional value (if it is there), like so:

if let Some(x) = some_u8_value {
    println!("The unwrapped value is {}", x);
}

I hope that makes sense.

This pull requests adds a section in the new features appendix about the loop_break_value feature (which should be stabilized after all the documentation is ready), tracked in issue rust-lang/rust#37339.

I reused the basic example I made for Rust by Example, but if something more realistic (maybe with threads and channels) is OK here I'm happy to change it.

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  • Messenger
  • 15
  • &mut self
• I have checked the latest main branch to see if this has already been fixed, in this file:
  • https://github.com/rust-lang/book/blob/2bd5d42c9956369132228da6409f0e68da56c51a/src/ch15-05-interior-mutability.md?plain=1#L195
  • https://github.com/rust-lang/book/blob/2bd5d42c9956369132228da6409f0e68da56c51a/listings/ch15-smart-pointers/listing-15-21/output.txt#L6

URL to the section(s) of the book with this problem: https://doc.rust-lang.org/book/ch15-05-interior-mutability.html#a-use-case-for-interior-mutability-mock-objects

Description of the problem:

The following sentence is incorrect:

We also can’t take the suggestion from the error text to use &mut self instead, because then the signature of send wouldn’t match the signature in the Messenger trait definition

because the suggestion of the compiler is to modify Line 2, the signature in the Messenger trait definition itself, NOT Line 57 which is the implementation of send in MockMessenger.

Suggested fix:

We also can't take the suggestion from the error text to use &mut self instead, because we are testing an API and it's not a good idea to modify the API for the sole purpose of testing. Usually, the test engineers do not have permission to modify the API they're testing.

To clarify the scope of references, I suggest the comment should be moved after the "let r3 = &mut s;" statement. "println!("{}", r1);" or "println!("{}", r2);" is possible before "let r3 = &mut s;" .

The chapter starts off by using assert_eq!(…); with assert_eq!(actual, expected); argument ordering, but then suddenly swaps the order to assert_eq!(expected, actual); with assert_eq!(4, add_two(2));

Further more it then states …

We could write the assertion in this test as assert_eq!(add_two(2), 4), which would result in the same failure message that displays `` assertion failed: (left == right).

… which seems weird as in the chapter assert_eq!(4, add_two(2)) actually is the odd one out, not assert_eq!(add_two(2), 4).

By swapping the args the message of "which would result in the same failure message" remains true, but the text feels a bit more consistent and predictable.

• I have searched open and closed issues and pull requests for duplicates, using these search terms:
  • "15"
  • "15.6"
• I have checked the latest main branch to see if this has already been fixed, in this file:
  • main/src/ch15-06-reference-cycles.md

URL to the section(s) of the book with this problem:

• https://doc.rust-lang.org/book/ch15-06-reference-cycles.html

Description of the problem: The quoted text below informs the user that the code commented out in the second attached image will cause a stack overflow error if executed. Overall, the book does an amazing job at teaching Rust to the reader, but in this section, it fails to explain why exactly this stack overflow error occurs. Stack overflow errors often stem from recursive logic bugs, but no such logic exists in those code snippets which makes the cause of the error difficult to ascertain.

... "If you uncomment the last println! and run the program, Rust will try to print this cycle with a pointing to b pointing to a and so forth until it overflows the stack. "

Suggested fix: I feel that a quick discussion of how the error relates to the Debug trait would greatly benefit this section and provide users with some extra detail to aid in their understanding of the language.

Thanks for the book and all the work that went into it! I really appreciate it.

Following might be an idea for an improvement of chapter 13.3.

In earlier sections, tasks were given and later picked up on again. Here, in section 12.5, one of the tasks was:

[...] try controlling case sensitivity through either a command line argument or an environment variable.

The solution for me was the use of optional flags (-i, --ignore-case, --case-sensitive)

After the changes from 13.3 using an iterator, a solution for the optional flags is needed, to make the program and unit tests work again.

I think, it would be nice if the chapter 13.3 picks up on the tasks from chapter 12.5 and helps (or gives hints) with a solution for optional arguments.

I tried to find a solution, while keeping the focus on the topic of iterators. But I believe, it's not the most elegant one.

  pub fn build(mut args: impl Iterator<Item = String>
    ) -> Result<Config, &'static str> {

        
        // decide that one or the other takes precedence (arg > env)
        // Default: it is off
        // ENV can put it on
        // Arg can overrrule env
        let mut ignore_case = env::var("IGNORE_CASE").is_ok();
        let mut query:String = String::new();
        let mut file_path:String = String::new();


        args.next(); // ignore program name
        while None != match args.next() {
                Some(arg) => {

                    println!("Arg is: {arg}");
                    if arg.eq("-i") || arg.eq("--ignore-case"){
                        ignore_case = true;
                    }else if arg.eq("--case-sensitive"){
                        ignore_case = false
                    }else{
                        if query.is_empty(){
                            query = arg
                        }else if file_path.is_empty() {
                            file_path = arg
                        }
                    }
                    Some(true,)
                },
                _ => None,
            }  {
                dbg!("Still parsing config..");   
            }

        if query.is_empty() || file_path.is_empty(){
            return Err("Too many arguments!");
        }else{
            return Ok(Config{ query, file_path, ignore_case })
        }
    }    
}