aml3 / rusttutorial Goto Github PK

Update the example code snippets to work with rust 1.0 stable release

Any pointer or reference in Rust, be it to an int or a complicated struct will be a pointer to a box.

That's partially wrong; a reference (&) is just pointing to a chunk of memory; which if unboxed will be itself unboxed.

So, for example, &int is not a pointer to a box.

(Side note: it would be cool to have the text compiled from Markdown source or something like it; I use pandoc in my project).

The Rust/Java tabs are broken on github.io, but they seem to work locally.

Hi, sorry to kind of dump a big blob on you, but I did some proofreading and have several comments:

An Exercise in Matching:

form, and run "rustc "

These angle-brackets need escaping.

Starting to Corrode:

it requires some effort to understand, but provide the big advantage of providing both explicit control and safety.

"it requires" refers to "Rust", "way", or "memory references", but then there is no clear antecedent for "provide".
"provide"/"providing" is a bit awkward.
Consider "and which requires some effort to understand, but provides the big advantages of both explicit control and safety."

Boxes:

Because Rust is designed to emphasize safety, any allocated memory in Rust is boxed, and thus any box can be thought of as simply a chunk of memory.

This sentence is confusing to me. I don't feel it's explained how emphasis on safety is achieved through boxing all allocated memory, and this seems an awkward way to state that "a box is a chunk of memory". Maybe something like "Because Rust is designed to emphasize safety, it must enforce safe usage of allocated memory. This is achieved by considering each allocated chunk a 'box' and enforcing certain rules regarding references to the box." could be said.

As of Rust 0.9, this syntax is deprecated, however it is planned to be reintroduced in future releases. These added a deal of simplicity to pointer management, however other pointer types could be used with more efficency.

@-pointer syntax is not planned to be reinstated; the more verbose syntax like Gc is intended to encourage using more efficient ownership schemes when possible. Additionally, it was decided to be bad practice to special-case one sort of shared ownership syntactically when refcounting and other deallocation schemes are tools which should be similarly ergonomic. The ubiquity of unique ownership is the reason ~T merits a sigil shorthand rather than being Uniq.

Ownership:

Programmers do not have to explicitly allocated and deallocate storage.

"allocated" -> "allocate"

Owned Boxes:

So the following code will assign y to a new owned pointer pointing to a new copy of the value "10".

The code sample shows y as the destination, not the source, of the assignment.

Borrowed References:

"This most commonly used to pass in a pointer reference to a method."

+"is"

Lifetimes:
It's weird to use a double-indirection (&~int) here. I would write the code like this:

    let mut reference: ∫
    {
        let val: ~int = ~10;
        reference = &*val;
    } //val deallocated here
    println!("{:d}", *reference); //Referencing something that's gone!

It might also be good to point out that since the compiler never allows a reference to point to a deallocated box, the println! line is not necessary--the mere act of "reference" holding a reference that is invalid after the block is enough to set off rustc, and indeed that's where the error message points.

Strings:

Rust supposrts a scdoe string edoc type which is a vector of characters.

Typos! Additionally, this isn't true: vectors of characters look like ~[char] and can be mutated internally, while strings are internally immutable and take O(n) time to index by characters or slice by characters due to UTF-8 being a variable-length encoding.

Each character is a UTF-8 sequence, represented by the u8 type in Rust.

Terminology is really important when talking about strings in Rust, because they're specified to be valid Unicode and Unicode relies conceptually on some fairly subtle distinctions. Since Rust is safe, these distinctions are enforced by the language and lend shape to a lot of the string API, so it's important that learners of the language also understand them, or at least aren't misled.
In this case, "character" should probably not be used to refer to the portion of a Rust string encoding that character, because Rust has its own char type which is a 4-byte UCS-32 (also Unicode) codepoint. It would be better to say "A Rust string is a chunk of text encoded in UTF-8, represented internally as a vector of bytes (the u8 type)."

These slice methods work on any vector, but string manipulation is the most common use of slices.

Please note that string slicing counts bytes, but vector slicing counts elements. For ASCII text, each character is represented in a single byte, but languages other than English tend to use characters which take up multiple bytes in UTF-8, and text from the Internet often contains things like curly quotes which are also multi-byte sequences in UTF-8.

Files:

edoc Option type

This seems to be marked-up incorrectly.

"enumerable types"

"enumerated types" or just "enums"

this returns an Option objects

"object"

a function succeds

"succeeds"

Splitter:
This is all style nitpicks, so feel free to ignore it wholesale. But do consider teaching iterators here:
I would have let args' type be inferred.
Path::new can take an &str, so .to_slice() fname instead of cloning it.
xor can be written idiomatically as:

    fn xor(a: &[u8], b: &[u8]) -> ~[u8] {
        a.iter().zip(b.iter()).map(|(&x,&y)| x^y).collect()
    }

split can be written idiomatically as:

fn split(msg_bytes: &[u8], mut share1: File, mut share2: File) {
    let mut random_bytes = std::rand::task_rng().gen_vec(msg_bytes.len());

    let encrypted_bytes = xor(msg_bytes, random_bytes);
    share1.write(random_bytes);
    share2.write(encrypted_bytes);
}

It may make preprocessing easier. Or, we could run the preprocessor from each folder using a makefile.