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<u64> = 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<u64> = 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;
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 }
}
}
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);
// * [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;
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.
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.
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. <br/>
+// 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:
//@ 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.<br/>
+//@ you want to have implemented, and their argument and return types. <br/>
//@ 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`.
//@
//@ 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!<br/>
+//@ we cannot call `min`. Just try it! <br/>
//@ This is in strong contrast to C++, where the compiler only checks such details when the
//@ function is actually used.
pub fn vec_min<T: Minimum>(v: Vec<T>) -> SomethingOrNothing<T> {
//@ 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).<br/>
+//@ digit first. This means that "1337" would actually become (7, 3, 3, 1). <br/>
//@ 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.
//@ `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`.<br/>
+//@ the copy that was created, and hence we can store it in `min`. <br/>
//@ 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
//@ ## 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.<br/>
+//@ ownership passing and how `Copy` and `Clone` fit in by looking at what happens on the machine. <br/>
//@ When Rust code is executed, passing a value (like `i32` or `Vec<i32>`) 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
//@ 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(++).<br/>
+//@ to check the pointer for validity, avoiding the safety issues of C(++). <br/>
//@ 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
// 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<i32>` and `SomethingOrNothing<f32>`.
-//@ [index](main.html) | [previous](part06.html) | [next](main.html)
+//@ [index](main.html) | [previous](part06.html) | [next](part08.html)
-// 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. <br/>
+ //@ 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. <br/>
+ // **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));
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<BigInt> 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<u64> = 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<u64> = 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)
// Rust-101, Part 09: Iterators (WIP)
-// =================================
+// ==================================
-// [index](main.html) | [previous](part08.html) | [next](main.html)
+//@ [index](main.html) | [previous](part08.html) | [next](main.html)
mod part05;
mod part06;
mod part07;
+mod part08;
// This decides which part is actually run.
fn main() {
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!()
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.
-// 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. <br/>
+ // **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));
assert_eq!(overflowing_add(1 << 63, (1 << 63) -1 , true), (0, true));
}
-impl ops::Add for BigInt {
+// ## Associated Types
+impl ops::Add<BigInt> 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<u64> = 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<u64> = 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.
+ }
+}
+
// Rust-101, Part 09: Iterators (WIP)
-// =================================
+// ==================================
-// [index](main.html) | [previous](part08.html) | [next](main.html)
projects / rust-101.git / commitdiff