Merge branch 'master' into wee-little-typo

Author: marioidival

src/macros.md

@@ -16,12 +16,12 @@ macro_rules! say_hello {
     // `()` indicates that the macro takes no argument.
     () => {
         // The macro will expand into the contents of this block.
-        println!("Hello!");
+        println!("Hello!")
     };
 }
 
 fn main() {
-    // This call will expand into `println!("Hello");`
+    // This call will expand into `println!("Hello")`
     say_hello!()
 }
 ```

src/std_misc/file/read_lines.md

@@ -1,53 +1,60 @@
 # `read_lines`
 
-## Beginner friendly method
-This method is NOT efficient. It's here for beginners
-who can't understand the efficient method yet.
+## A naive approach
 
-```rust,no_run
-use std::fs::File;
-use std::io::{ self, BufRead, BufReader };
+This might be a reasonable first attempt for a beginner's first
+implementation for reading lines from a file.
 
-fn read_lines(filename: String) -> io::Lines<BufReader<File>> {
-    // Open the file in read-only mode.
-    let file = File::open(filename).unwrap(); 
-    // Read the file line by line, and return an iterator of the lines of the file.
-    return io::BufReader::new(file).lines(); 
-}
+```rust,norun
+use std::fs::read_to_string;
 
-fn main() {
-    // Stores the iterator of lines of the file in lines variable.
-    let lines = read_lines("./hosts".to_string());
-    // Iterate over the lines of the file, and in this case print them.
-    for line in lines {
-        println!("{}", line.unwrap());
+fn read_lines(filename: &str) -> Vec<String> {
+    let mut result = Vec::new();
+
+    for line in read_to_string(filename).unwrap().lines() {
+        result.push(line.to_string())
     }
+
+    result
 }
 ```
 
-Running this program simply prints the lines individually.
-```shell
-$ echo -e "127.0.0.1\n192.168.0.1\n" > hosts
-$ rustc read_lines.rs && ./read_lines
-127.0.0.1
-192.168.0.1
+Since the method `lines()` returns an iterator over the lines in the file,
+we can also perform a map inline and collect the results, yielding a more
+concise and fluent expression.
+
+```rust,norun
+use std::fs::read_to_string;
+
+fn read_lines(filename: &str) -> Vec<String> {
+    read_to_string(filename) 
+        .unwrap()  // panic on possible file-reading errors
+        .lines()  // split the string into an iterator of string slices
+        .map(String::from)  // make each slice into a string
+        .collect()  // gather them together into a vector
+}
 ```
 
-## Efficient method
-The method `lines()` returns an iterator over the lines
-of a file.
+Note that in both examples above, we must convert the `&str` reference
+returned from `lines()` to the owned type `String`, using `.to_string()`
+and `String::from` respectively.
 
-`File::open` expects a generic, `AsRef<Path>`.  That's what
-`read_lines()` expects as input.
+## A more efficient approach
+
+Here we pass ownership of the open `File` to a `BufReader` struct. `BufReader` uses an internal
+buffer to reduce intermediate allocations.
+
+We also update `read_lines` to return an iterator instead of allocating new
+`String` objects in memory for each line.
 
 ```rust,no_run
 use std::fs::File;
 use std::io::{self, BufRead};
 use std::path::Path;
 
 fn main() {
-    // File hosts must exist in current path before this produces output
-    if let Ok(lines) = read_lines("./hosts") {
+    // File hosts.txt must exist in the current path
+    if let Ok(lines) = read_lines("./hosts.txt") {
         // Consumes the iterator, returns an (Optional) String
         for line in lines {
             if let Ok(ip) = line {
@@ -68,11 +75,15 @@ where P: AsRef<Path>, {
 
 Running this program simply prints the lines individually.
 ```shell
-$ echo -e "127.0.0.1\n192.168.0.1\n" > hosts
+$ echo -e "127.0.0.1\n192.168.0.1\n" > hosts.txt
 $ rustc read_lines.rs && ./read_lines
 127.0.0.1
 192.168.0.1
 ```
 
-This process is more efficient than creating a `String` in memory
-especially working with larger files.
+(Note that since `File::open` expects a generic `AsRef<Path>` as argument, we define our
+generic `read_lines()` method with the same generic constraint, using the `where` keyword.)
+
+This process is more efficient than creating a `String` in memory with all of the file's
+contents. This can especially cause performance issues when working with larger files.
+

src/unsafe/asm.md

@@ -18,11 +18,13 @@ Inline assembly is currently supported on the following architectures:
 Let us start with the simplest possible example:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 unsafe {
     asm!("nop");
 }
+# }
 ```
 
 This will insert a NOP (no operation) instruction into the assembly generated by the compiler.
@@ -36,13 +38,15 @@ Now inserting an instruction that does nothing is rather boring. Let us do somet
 actually acts on data:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let x: u64;
 unsafe {
     asm!("mov {}, 5", out(reg) x);
 }
 assert_eq!(x, 5);
+# }
 ```
 
 This will write the value `5` into the `u64` variable `x`.
@@ -61,6 +65,7 @@ the template and will read the variable from there after the inline assembly fin
 Let us see another example that also uses an input:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let i: u64 = 3;
@@ -74,6 +79,7 @@ unsafe {
     );
 }
 assert_eq!(o, 8);
+# }
 ```
 
 This will add `5` to the input in variable `i` and write the result to variable `o`.
@@ -97,13 +103,15 @@ readability, and allows reordering instructions without changing the argument or
 We can further refine the above example to avoid the `mov` instruction:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let mut x: u64 = 3;
 unsafe {
     asm!("add {0}, 5", inout(reg) x);
 }
 assert_eq!(x, 8);
+# }
 ```
 
 We can see that `inout` is used to specify an argument that is both input and output.
@@ -112,6 +120,7 @@ This is different from specifying an input and output separately in that it is g
 It is also possible to specify different variables for the input and output parts of an `inout` operand:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let x: u64 = 3;
@@ -120,6 +129,7 @@ unsafe {
     asm!("add {0}, 5", inout(reg) x => y);
 }
 assert_eq!(y, 8);
+# }
 ```
 
 ## Late output operands
@@ -135,6 +145,7 @@ There is also a `inlateout` variant of this specifier.
 Here is an example where `inlateout` *cannot* be used in `release` mode or other optimized cases:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let mut a: u64 = 4;
@@ -150,6 +161,7 @@ unsafe {
     );
 }
 assert_eq!(a, 12);
+# }
 ```
 The above could work well in unoptimized cases (`Debug` mode), but if you want optimized performance (`release` mode or other optimized cases), it could not work.
 
@@ -158,6 +170,7 @@ That is because in optimized cases, the compiler is free to allocate the same re
 However the following example can use `inlateout` since the output is only modified after all input registers have been read:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let mut a: u64 = 4;
@@ -166,6 +179,7 @@ unsafe {
     asm!("add {0}, {1}", inlateout(reg) a, in(reg) b);
 }
 assert_eq!(a, 8);
+# }
 ```
 
 As you can see, this assembly fragment will still work correctly if `a` and `b` are assigned to the same register.
@@ -177,12 +191,14 @@ Therefore, Rust inline assembly provides some more specific constraint specifier
 While `reg` is generally available on any architecture, explicit registers are highly architecture specific. E.g. for x86 the general purpose registers `eax`, `ebx`, `ecx`, `edx`, `ebp`, `esi`, and `edi` among others can be addressed by their name.
 
 ```rust,no_run
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let cmd = 0xd1;
 unsafe {
     asm!("out 0x64, eax", in("eax") cmd);
 }
+# }
 ```
 
 In this example we call the `out` instruction to output the content of the `cmd` variable to port `0x64`. Since the `out` instruction only accepts `eax` (and its sub registers) as operand we had to use the `eax` constraint specifier.
@@ -192,6 +208,7 @@ In this example we call the `out` instruction to output the content of the `cmd`
 Consider this example which uses the x86 `mul` instruction:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 fn mul(a: u64, b: u64) -> u128 {
@@ -211,6 +228,7 @@ fn mul(a: u64, b: u64) -> u128 {
 
     ((hi as u128) << 64) + lo as u128
 }
+# }
 ```
 
 This uses the `mul` instruction to multiply two 64-bit inputs with a 128-bit result.
@@ -229,6 +247,7 @@ We need to tell the compiler about this since it may need to save and restore th
 ```rust
 use std::arch::asm;
 
+# #[cfg(target_arch = "x86_64")]
 fn main() {
     // three entries of four bytes each
     let mut name_buf = [0_u8; 12];
@@ -262,6 +281,9 @@ fn main() {
     let name = core::str::from_utf8(&name_buf).unwrap();
     println!("CPU Manufacturer ID: {}", name);
 }
+
+# #[cfg(not(target_arch = "x86_64"))]
+# fn main() {}
 ```
 
 In the example above we use the `cpuid` instruction to read the CPU manufacturer ID.
@@ -276,6 +298,7 @@ To work around this we use `rdi` to store the pointer to the output array, save
 This can also be used with a general register class to obtain a scratch register for use inside the asm code:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 // Multiply x by 6 using shifts and adds
@@ -291,6 +314,7 @@ unsafe {
     );
 }
 assert_eq!(x, 4 * 6);
+# }
 ```
 
 ## Symbol operands and ABI clobbers
@@ -300,6 +324,7 @@ By default, `asm!` assumes that any register not specified as an output will hav
 [`clobber_abi`]: ../../reference/inline-assembly.html#abi-clobbers
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 extern "C" fn foo(arg: i32) -> i32 {
@@ -325,6 +350,7 @@ fn call_foo(arg: i32) -> i32 {
         result
     }
 }
+# }
 ```
 
 ## Register template modifiers
@@ -336,6 +362,7 @@ By default the compiler will always choose the name that refers to the full regi
 This default can be overridden by using modifiers on the template string operands, just like you would with format strings:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let mut x: u16 = 0xab;
@@ -345,6 +372,7 @@ unsafe {
 }
 
 assert_eq!(x, 0xabab);
+# }
 ```
 
 In this example, we use the `reg_abcd` register class to restrict the register allocator to the 4 legacy x86 registers (`ax`, `bx`, `cx`, `dx`) of which the first two bytes can be addressed independently.
@@ -361,13 +389,15 @@ You have to manually use the memory address syntax specified by the target archi
 For example, on x86/x86_64 using Intel assembly syntax, you should wrap inputs/outputs in `[]` to indicate they are memory operands:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 fn load_fpu_control_word(control: u16) {
     unsafe {
         asm!("fldcw [{}]", in(reg) &control, options(nostack));
     }
 }
+# }
 ```
 
 ## Labels
@@ -383,6 +413,7 @@ As a consequence, you should only use GNU assembler **numeric** [local labels] i
 Moreover, on x86 when using the default Intel syntax, due to [an LLVM bug], you shouldn't use labels exclusively made of `0` and `1` digits, e.g. `0`, `11` or `101010`, as they may end up being interpreted as binary values. Using `options(att_syntax)` will avoid any ambiguity, but that affects the syntax of the _entire_ `asm!` block. (See [Options](#options), below, for more on `options`.)
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let mut a = 0;
@@ -400,6 +431,7 @@ unsafe {
     );
 }
 assert_eq!(a, 5);
+# }
 ```
 
 This will decrement the `{0}` register value from 10 to 3, then add 2 and store it in `a`.
@@ -419,6 +451,7 @@ By default, an inline assembly block is treated the same way as an external FFI
 Let's take our previous example of an `add` instruction:
 
 ```rust
+# #[cfg(target_arch = "x86_64")] {
 use std::arch::asm;
 
 let mut a: u64 = 4;
@@ -431,6 +464,7 @@ unsafe {
     );
 }
 assert_eq!(a, 8);
+# }
 ```
 
 Options can be provided as an optional final argument to the `asm!` macro. We specified three options here:

src/variable_bindings/mut.md

@@ -15,9 +15,8 @@ fn main() {
 
     println!("After mutation: {}", mutable_binding);
 
-    // Error!
+    // Error! Cannot assign a new value to an immutable variable
     _immutable_binding += 1;
-    // FIXME ^ Comment out this line
 }
 ```