From: Ralf Jung Date: Sun, 5 Jul 2015 15:26:09 +0000 (+0200) Subject: finalize part 08 X-Git-Url: https://git.ralfj.de/rust-101.git/commitdiff_plain/c25f3400060ea1a02f8fa9de69c39fd7b020e8a5?ds=inline finalize part 08 --- diff --git a/solutions/src/bigint.rs b/solutions/src/bigint.rs index 91e3ccf..120ae6c 100644 --- a/solutions/src/bigint.rs +++ b/solutions/src/bigint.rs @@ -166,12 +166,14 @@ impl fmt::Debug for BigInt { impl<'a, 'b> ops::Add<&'a BigInt> for &'b BigInt { type Output = BigInt; fn add(self, rhs: &'a BigInt) -> Self::Output { - let mut result_vec:Vec = Vec::with_capacity(cmp::max(self.data.len(), rhs.data.len())); + let max_len = cmp::max(self.data.len(), rhs.data.len()); + let mut result_vec:Vec = Vec::with_capacity(max_len); let mut carry:bool = false; // the carry bit - for (i, val) in (&self.data).into_iter().enumerate() { + for i in 0..max_len { // compute next digit and carry + let lhs_val = if i < self.data.len() { self.data[i] } else { 0 }; let rhs_val = if i < rhs.data.len() { rhs.data[i] } else { 0 }; - let (sum, new_carry) = overflowing_add(*val, rhs_val, carry); + let (sum, new_carry) = overflowing_add(lhs_val, rhs_val, carry); // store them result_vec.push(sum); carry = new_carry; @@ -180,8 +182,8 @@ impl<'a, 'b> ops::Add<&'a BigInt> for &'b BigInt { result_vec.push(1); } // We know that the invariant holds: overflowing_add would only return (0, false) if - // the arguments are (0, 0, false), but we know that in the last iteration, `val` is the - // last digit of `self` and hence not 0. + // the arguments are (0, 0, false), but we know that in the last iteration, one od the two digits + // is the last of its number and hence not 0. BigInt { data: result_vec } } } @@ -225,6 +227,14 @@ mod tests { assert_eq!(overflowing_add(1 << 63, (1 << 63) -1 , true), (0, true)); } + #[test] + fn test_add() { + let b1 = BigInt::new(1 << 32); + let b2 = BigInt::from_vec(vec![0, 1]); + + assert_eq!(&b1 + &b2, BigInt::from_vec(vec![1 << 32, 1])); + } + #[test] fn test_inc1() { let mut b = BigInt::new(0); diff --git a/src/main.rs b/src/main.rs index cf0cd87..abf286e 100644 --- a/src/main.rs +++ b/src/main.rs @@ -75,6 +75,7 @@ // * [Part 05: Clone](part05.html) // * [Part 06: Copy, Lifetimes](part06.html) // * [Part 07: Operator Overloading, Tests, Formating](part07.html) +// * [Part 08: Associated Types, Modules](part08.html) // * (to be continued) #![allow(dead_code, unused_imports, unused_variables, unused_mut)] mod part00; @@ -86,7 +87,7 @@ mod part05; mod part06; mod part07; mod part08; -mod part09; +//mod part09; // To actually run the code of some part (after filling in the blanks, if necessary), simply edit the `main` // function. diff --git a/src/part00.rs b/src/part00.rs index cd1e7cc..6469907 100644 --- a/src/part00.rs +++ b/src/part00.rs @@ -82,8 +82,7 @@ fn read_vec() -> Vec { vec![18,5,7,1,9,27] /*@*/ } -// Finally, let's call our functions and run the code! -// But, wait, we would like to actually see something, so we need to print the result. +// Of course, we would also like to actually see the result of the computation, so we need to print the result. //@ Of course Rust can print numbers, but after calling `vec_min`, we have a `NumberOrNothing`. //@ So let's write a small helper function that prints such values. @@ -104,8 +103,9 @@ pub fn main() { print_number_or_nothing(min); } -// You can now use `cargo build` to compile your code. If all goes well, try `cargo run` on the -// console to run it. +//@ You can now use `cargo build` to compile your *crate*. That's Rust's name for a *compilation unit*, which in +//@ the case of Rust means an application or a library.
+// Finally, try `cargo run` on the console to run it. //@ Yay, it said "1"! That's actually the right answer. Okay, we could have //@ computed that ourselves, but that's besides the point. More importantly: diff --git a/src/part02.rs b/src/part02.rs index 41bb3bc..bd8abf0 100644 --- a/src/part02.rs +++ b/src/part02.rs @@ -62,7 +62,7 @@ fn call_constructor(x: i32) -> SomethingOrNothing { //@ So, as a first step towards a generic `vec_min`, we define a `Minimum` trait. //@ For now, just ignore the `Copy`, we will come back to this point later. //@ A `trait` is a lot like interfaces in Java: You define a bunch of functions -//@ you want to have implemented, and their argument and return types.
+//@ you want to have implemented, and their argument and return types.
//@ The function `min` takes to arguments of the same type, but I made the //@ first argument the special `self` argument. I could, alternatively, have //@ made `min` a static function as follows: `fn min(a: Self, b: Self) -> Self`. @@ -79,7 +79,7 @@ pub trait Minimum : Copy { //@ //@ There is a crucial difference to templates in C++: We actually have to declare which traits //@ we want the type to satisfy. If we left away the `Minimum`, Rust would have complained that -//@ we cannot call `min`. Just try it!
+//@ we cannot call `min`. Just try it!
//@ This is in strong contrast to C++, where the compiler only checks such details when the //@ function is actually used. pub fn vec_min(v: Vec) -> SomethingOrNothing { diff --git a/src/part05.rs b/src/part05.rs index 72c787d..3992fb1 100644 --- a/src/part05.rs +++ b/src/part05.rs @@ -10,7 +10,7 @@ //@ to use a vector "digits" of the number. This is like "1337" being a vector of four digits (1, 3, 3, 7), //@ except that we will use `u64` as type of our digits, meaning we have 2^64 individual digits. Now we just //@ have to decide the order in which we store numbers. I decided that we will store the least significant -//@ digit first. This means that "1337" would actually become (7, 3, 3, 1).
+//@ digit first. This means that "1337" would actually become (7, 3, 3, 1).
//@ Finally, we declare that there must not be any trailing zeros (corresponding to //@ useless leading zeros in our usual way of writing numbers). This is to ensure that //@ the same number can only be stored in one way. diff --git a/src/part06.rs b/src/part06.rs index 35cd5a9..b39a441 100644 --- a/src/part06.rs +++ b/src/part06.rs @@ -49,7 +49,7 @@ fn vec_min(v: &Vec) -> Option { //@ `e` is a `&BigInt`. Assigning `min = Some(*e)` works just like a function call: Ownership of the //@ underlying data is transferred from where `e` borrows from to `min`. But that's not allowed, since //@ we just borrowed `e`, so we cannot empty it! We can, however, call `clone()` on it. Then we own -//@ the copy that was created, and hence we can store it in `min`.
+//@ the copy that was created, and hence we can store it in `min`.
//@ Of course, making such a full copy is expensive, so we'd like to avoid it. We'll some to that in the next part. // ## `Copy` types @@ -78,7 +78,7 @@ impl Copy for SomethingOrNothing {} //@ ## An operational perspective //@ Instead of looking at what happens "at the surface" (i.e., visible in Rust), one can also explain -//@ ownership passing and how `Copy` and `Clone` fit in by looking at what happens on the machine.
+//@ ownership passing and how `Copy` and `Clone` fit in by looking at what happens on the machine.
//@ When Rust code is executed, passing a value (like `i32` or `Vec`) to a function will always //@ result in a shallow copy being performed: Rust just copies the bytes representing that value, and //@ considers itself done. That's just like the default copy constructor in C++. Rust, however, will diff --git a/src/part07.rs b/src/part07.rs index 6544995..618eb22 100644 --- a/src/part07.rs +++ b/src/part07.rs @@ -27,7 +27,7 @@ pub fn vec_min(v: &Vec) -> Option<&T> { //@ Notice that the return type `Option<&T>` is technically (leaving the borrowing story aside) a //@ pointer to a `T`, that could optionally be invalid. In other words, it's just like a pointer in //@ C(++) or Java that can be `NULL`! However, thanks to `Option` being an `enum`, we cannot forget -//@ to check the pointer for validity, avoiding the safety issues of C(++).
+//@ to check the pointer for validity, avoiding the safety issues of C(++).
//@ Also, if you are worried about wasting space, notice that Rust knows that `&T` can never be //@ `NULL`, and hence optimizes `Option<&T>` to be no larger than `&T`. The `None` case is represented //@ as `NULL`. This is another great example of a zero-cost abstraction: `Option<&T>` is exactly like @@ -147,4 +147,4 @@ fn test_vec_min() { // of course, need a `Display` bound on `T`.) Then you should be able to use them with `println!` just like you do // with numbers, and get rid of the inherent functions to print `SomethingOrNothing` and `SomethingOrNothing`. -//@ [index](main.html) | [previous](part06.html) | [next](main.html) +//@ [index](main.html) | [previous](part06.html) | [next](part08.html) diff --git a/src/part08.rs b/src/part08.rs index 90c35f6..e01a35b 100644 --- a/src/part08.rs +++ b/src/part08.rs @@ -1,21 +1,41 @@ -// Rust-101, Part 08: Associated Types, Modules (WIP) -// ================================================== +// Rust-101, Part 08: Associated Types, Modules +// ============================================ -use std::cmp; -use std::ops; -use std::fmt; +use std::{cmp,ops}; use part05::BigInt; -// Add with carry, returning the sum and the carry +//@ As our next goal, let us implement addition for our `BigInt`. The main issue here will be dealing with the overflow. +//@ First of all, we will have to detect when an overflow happens. This is stored in a so-called *carry* bit, and we have to carry this +//@ information on to the next pair of digits we add. The core primitive of addition therefore is to add two digits *and* a +//@ carry, and to return the sum digit and the next carry. + +// So, let us write a function to "add with carry", and give it the appropriate type. Notice Rust's native support for pairs. fn overflowing_add(a: u64, b: u64, carry: bool) -> (u64, bool) { + //@ Rust's stanza on integer overflows may be a bit surprising: In general, when we write `a + b`, an overflow is + //@ considered an *error*. If you compile your program in debug mode, Rust will actually check for that error and panic + //@ the program in case of overflows. For performance reasons, no such checks are currently inserted for release builds. + //@ The reason for this is that many serious security vulnerabilities have been caused by integer overflows, so just assuming + //@ "per default" that they are intended is dangerous.
+ //@ If you explicitly *do* want an overflow to happen, you can call the `wrapping_add` + //@ function (see [the documentation](http://doc.rust-lang.org/stable/std/primitive.u64.html#method.wrapping_add), + //@ there are similar functions for other arithmetic operations). There are also similar functions + //@ `checked_add` etc. to enforce the overflow check. let sum = u64::wrapping_add(a, b); - if sum >= a { // first addition did not overflow - unimplemented!() - } else { // first addition *did* overflow + // If an overflow happened, then the sum will be smaller than *both* summands. Without an overflow, of course, it will be + // at least as large as both of them. So, let's just pick one and check. + if sum >= a { + // The addition did not overflow.
+ // **Exercise 08.1**: Write the code to handle adding the carry in this case. unimplemented!() + } else { + // The addition *did* overflow. It is impossible for the addition of the carry + // to overflow again, as we are just adding 0 or 1. + (sum + if carry { 1 } else { 0 }, true) /*@*/ } } +// `overflow_add` is a sufficiently intricate function that a test case is justified. +// This should also help you to check your solution of the exercise. /*#[test]*/ fn test_overflowing_add() { assert_eq!(overflowing_add(10, 100, false), (110, false)); @@ -25,12 +45,106 @@ fn test_overflowing_add() { assert_eq!(overflowing_add(1 << 63, (1 << 63) -1 , true), (0, true)); } -impl ops::Add for BigInt { +// ## Associated Types +//@ Now we are equipped to write the addition function for `BigInt`. As you may have guessed, the `+` operator +//@ is tied to a trait (`std::ops::Add`), which we are now going to implement for `BigInt`. +//@ +//@ In general, addition need not be homogeneous: For example, we could add a vector (in 3-dimensional +//@ space, say) to a point. So when implementing `Add` for a type, one has to specify the type of +//@ the other operand. In this case, it will also be `BigInt` (and we could have left it away, since that's the default). +impl ops::Add for BigInt { + //@ Besides static functions and methods, traits can contain *associated types*: This is a type + //@ chosen by every particular implementation of the trait. The methods of the trait can then + //@ refer to that type. In the case of addition, it is used to give the type of the result. + //@ (Also see the [documentation of `Add`](http://doc.rust-lang.org/stable/std/ops/trait.Add.html).) + //@ + //@ In general, you can consider the two `BigInt` given above (in the `impl` line) *input* types of trait search: When + //@ `a + b` is invoked with `a` having type `T` and `b` having type `U`, Rust tries to find an implementation of `Add` for + //@ `T` where the right-hand type is `U`. The associated types, on the other hand, are *output* types: For every combination + //@ of input types, there's a particular result type chosen by the corresponding implementation of `Add`. + + // Here, we choose the result type to be again `BigInt`. type Output = BigInt; + + // Now we can write the actual function performing the addition. fn add(self, rhs: BigInt) -> Self::Output { - let mut result_vec:Vec = Vec::with_capacity(cmp::max(self.data.len(), rhs.data.len())); + // We know that the result will be *at least* as long as the longer of the two operands, + // so we can create a vector with sufficient capacity to avoid expensive reallocations. + let max_len = cmp::max(self.data.len(), rhs.data.len()); + let mut result_vec:Vec = Vec::with_capacity(max_len); + let mut carry = false; /* the current carry bit */ + for i in 0..max_len { + // Compute next digit and carry. Store the digit for the result, and the carry for later. + let lhs_val = if i < self.data.len() { self.data[i] } else { 0 }; + let rhs_val = if i < rhs.data.len() { rhs.data[i] } else { 0 }; + let (sum, new_carry) = overflowing_add(lhs_val, rhs_val, carry); /*@*/ + result_vec.push(sum); /*@*/ + carry = new_carry; /*@*/ + } + // **Exercise 08.2**: Handle the final `carry`, and return the sum. unimplemented!() } } -// [index](main.html) | [previous](part07.html) | [next](main.html) +// ## Traits and borrowed types +//@ If you inspect the addition function above closely, you will notice that it actually requires +//@ *ownership* of its arguments: Both operands are consumed to produce the result. This is, of +//@ course, in general not what we want. We'd rather like to be able to add two `&BigInt`. + +// Writing this out becomes a bit tedious, because trait implementations (unlike functions) require full explicit annotation +// of lifetimes. Make sure you understand exactly what the following definition says. +impl<'a, 'b> ops::Add<&'a BigInt> for &'b BigInt { + type Output = BigInt; + fn add(self, rhs: &'a BigInt) -> Self::Output { + // **Exercise 08.3**: Implement this function. + unimplemented!() + } +} + +// ## Modules +//@ As you learned, tests can be written right in the middle of your development in Rust. However, it is +//@ considered good style to bundle all tests together. This is particularly useful in cases where +//@ you wrote utility functions for the tests, that no other code should use. + +// Rust calls a bunch of definitions that are grouped together a *module*. You can put definitions in a submodule as follows. +mod my_mod { + type MyType = i32; + fn my_fun() -> MyType { 42 } +} +//@ As already mentioned, outside of the module, only those items declared public with `pub` may be used. Submodules can access +//@ everything defined in their parents. Modules themselves are also hidden from the outside per default, and can be made public +//@ with `pub`. When you use an identifier (or, more general, a *path* like `mod1::submod::name`), it is interpreted as being +//@ relative to the current module. So, for example, to access `overflowing_add` from within `my_mod`, you would have to give a more +//@ explicit path by writing `super::overflowing_add`, which tells Rust to look in the parent module. +//@ +//@ You can make names from other modules available locally with `use`. Per default, `use` works globally, so e.g. +//@ `use std;` imports the *global* name `std`. By adding `super::` or `self::` to the beginning of the path, you make it relative +//@ to the parent or current module, respectively. (You can also explicitly construct an absolute path by starting it with `::`, +//@ e.g., `::std::cmp::min`). You can say `pub use path;` to simultaneously *import* names and make them publicly available to others. +//@ Finally, you can import all public items of a module at once with `use module::*;`. +//@ +//@ Modules can be put into separate files with the syntax `mod name;`. To explain this, let me take a small detour through +//@ the Rust compilation process. Cargo starts by invoking`rustc` on the file `src/lib.rs` or `src/main.rs`, depending on whether +//@ you compile an application or a library. When `rustc` encounters a `mod name;`, it looks for the files `name.rs` and +//@ `name/mod.rs` and goes on compiling there. (It is an error for both of them to exist). You can think of the contents of the +//@ file being embedded at this place. However, only the file where compilation started, and files `name/mod.rs` can load modules +//@ from other files. This ensures that the directory structure mirrors the structure of the modules, with `mod.rs`, `lib.rs` +//@ and `main.rs` representing a directory or crate itself (similar to, e.g., `__init__.py` in Python). + +// For the purpose of testing, one typically introduces a module called `tests` and tells the compiler +// (by means of the `cfg` attribute) to only compile this module for tests. +#[cfg(test)] +mod tests { + //@ If we added some functions here that are useful for testing, Rust would not bother compiling + //@ them when you just build your program for normal use. Other than that, tests work as usually. + #[test] + fn test_add() { + let b1 = BigInt::new(1 << 32); + let b2 = BigInt::from_vec(vec![0, 1]); + + assert_eq!(&b1 + &b2, BigInt::from_vec(vec![1 << 32, 1])); + // **Exercise 08.4**: Add some more testcases. + } +} + +//@ [index](main.html) | [previous](part07.html) | [next](main.html) diff --git a/src/part09.rs b/src/part09.rs index dc329bc..0045c7a 100644 --- a/src/part09.rs +++ b/src/part09.rs @@ -1,4 +1,4 @@ // Rust-101, Part 09: Iterators (WIP) -// ================================= +// ================================== -// [index](main.html) | [previous](part08.html) | [next](main.html) +//@ [index](main.html) | [previous](part08.html) | [next](main.html) diff --git a/workspace/src/main.rs b/workspace/src/main.rs index 5dd1592..09954a0 100644 --- a/workspace/src/main.rs +++ b/workspace/src/main.rs @@ -9,6 +9,7 @@ mod part04; mod part05; mod part06; mod part07; +mod part08; // This decides which part is actually run. fn main() { diff --git a/workspace/src/part00.rs b/workspace/src/part00.rs index aad3f21..49e89eb 100644 --- a/workspace/src/part00.rs +++ b/workspace/src/part00.rs @@ -58,8 +58,7 @@ fn read_vec() -> Vec { unimplemented!() } -// Finally, let's call our functions and run the code! -// But, wait, we would like to actually see something, so we need to print the result. +// Of course, we would also like to actually see the result of the computation, so we need to print the result. fn print_number_or_nothing(n: NumberOrNothing) { unimplemented!() @@ -72,7 +71,6 @@ pub fn main() { print_number_or_nothing(min); } -// You can now use `cargo build` to compile your code. If all goes well, try `cargo run` on the -// console to run it. +// Finally, try `cargo run` on the console to run it. diff --git a/workspace/src/part08.rs b/workspace/src/part08.rs index 90c35f6..7e2ba3b 100644 --- a/workspace/src/part08.rs +++ b/workspace/src/part08.rs @@ -1,21 +1,28 @@ -// Rust-101, Part 08: Associated Types, Modules (WIP) -// ================================================== +// Rust-101, Part 08: Associated Types, Modules +// ============================================ -use std::cmp; -use std::ops; -use std::fmt; +use std::{cmp,ops}; use part05::BigInt; -// Add with carry, returning the sum and the carry + +// So, let us write a function to "add with carry", and give it the appropriate type. Notice Rust's native support for pairs. fn overflowing_add(a: u64, b: u64, carry: bool) -> (u64, bool) { let sum = u64::wrapping_add(a, b); - if sum >= a { // first addition did not overflow + // If an overflow happened, then the sum will be smaller than *both* summands. Without an overflow, of course, it will be + // at least as large as both of them. So, let's just pick one and check. + if sum >= a { + // The addition did not overflow.
+ // **Exercise 08.1**: Write the code to handle adding the carry in this case. unimplemented!() - } else { // first addition *did* overflow + } else { + // The addition *did* overflow. It is impossible for the addition of the carry + // to overflow again, as we are just adding 0 or 1. unimplemented!() } } +// `overflow_add` is a sufficiently intricate function that a test case is justified. +// This should also help you to check your solution of the exercise. /*#[test]*/ fn test_overflowing_add() { assert_eq!(overflowing_add(10, 100, false), (110, false)); @@ -25,12 +32,61 @@ fn test_overflowing_add() { assert_eq!(overflowing_add(1 << 63, (1 << 63) -1 , true), (0, true)); } -impl ops::Add for BigInt { +// ## Associated Types +impl ops::Add for BigInt { + + // Here, we choose the result type to be again `BigInt`. type Output = BigInt; + + // Now we can write the actual function performing the addition. fn add(self, rhs: BigInt) -> Self::Output { - let mut result_vec:Vec = Vec::with_capacity(cmp::max(self.data.len(), rhs.data.len())); + // We know that the result will be *at least* as long as the longer of the two operands, + // so we can create a vector with sufficient capacity to avoid expensive reallocations. + let max_len = cmp::max(self.data.len(), rhs.data.len()); + let mut result_vec:Vec = Vec::with_capacity(max_len); + let mut carry = false; /* the current carry bit */ + for i in 0..max_len { + // Compute next digit and carry. Store the digit for the result, and the carry for later. + let lhs_val = if i < self.data.len() { self.data[i] } else { 0 }; + let rhs_val = if i < rhs.data.len() { rhs.data[i] } else { 0 }; + unimplemented!() + } + // **Exercise 08.2**: Handle the final `carry`, and return the sum. + unimplemented!() + } +} + +// ## Traits and borrowed types + +// Writing this out becomes a bit tedious, because trait implementations (unlike functions) require full explicit annotation +// of lifetimes. Make sure you understand exactly what the following definition says. +impl<'a, 'b> ops::Add<&'a BigInt> for &'b BigInt { + type Output = BigInt; + fn add(self, rhs: &'a BigInt) -> Self::Output { + // **Exercise 08.3**: Implement this function. unimplemented!() } } -// [index](main.html) | [previous](part07.html) | [next](main.html) +// ## Modules + +// Rust calls a bunch of definitions that are grouped together a *module*. You can put definitions in a submodule as follows. +mod my_mod { + type MyType = i32; + fn my_fun() -> MyType { 42 } +} + +// For the purpose of testing, one typically introduces a module called `tests` and tells the compiler +// (by means of the `cfg` attribute) to only compile this module for tests. +#[cfg(test)] +mod tests { + #[test] + fn test_add() { + let b1 = BigInt::new(1 << 32); + let b2 = BigInt::from_vec(vec![0, 1]); + + assert_eq!(&b1 + &b2, BigInt::from_vec(vec![1 << 32, 1])); + // **Exercise 08.4**: Add some more testcases. + } +} + diff --git a/workspace/src/part09.rs b/workspace/src/part09.rs index dc329bc..8e82f03 100644 --- a/workspace/src/part09.rs +++ b/workspace/src/part09.rs @@ -1,4 +1,3 @@ // Rust-101, Part 09: Iterators (WIP) -// ================================= +// ================================== -// [index](main.html) | [previous](part08.html) | [next](main.html)