Newcomer to Rust: my experience

[steveklabnik]

A longer reply, to give you answers, in case you’re still wondering:

(this is in the spirit of letting you know the answers to the questions, not saying that it’s not a weakness of the docs.

Pointers

This section explains why we should use &T in preference to Box<T>, before introducing Box<T>.

In general, this is meant to assume that you have knowledge of Rust already. But most of this is going away in the re-organization, so it should be less confusing anyway.

It doesn’t say why you can’t lend an mutable reference and another reference to the same value at the same time. (I remember hearing a rationale for this, involving enums, that seems irrelevant to why one can’t double-borrow simpler types like i32, but regardless of what the rationale is, it should be provided.)

It’s just that this causes a data race.

We are told “References to Strings will automatically coerce into &strs”, but it doesn’t say why or how.

It’s true, this is ‘deref coercions’. There’s a whole section in the new TOC abou tit.

[quote=“qwertie, post:52, topic:1816”] It also doesn’t explain very clearly what the difference between str and String is. [/quote]

That’s a bummer, as it’s a major part of this section

str is a primitive type that’s not sized. String is a library type, that’s an owned, heap-allocated string.

It doesn’t say why there is a true in for l in s.graphemes(true).

As the documentation for graphemes says: http://doc.rust-lang.org/nightly/unicode/str/trait.UnicodeStr.html#tymethod.graphemes … it doesn’t anymore. It used to. You basically always pass true as far as I’m concerned

What does the first line mean? let graph = MyGraph; // MyGraph is the name of a struct let obj = Box::new(graph) as Box<Graph>; It makes exactly as much sense to me as let foo = i32; would. I also wonder why each of the structs do not have { bodies }.

Empty structs don’t need bodies. I basically just left

struct MyGraph;

out of the example, maybe it’d be more clear with it there. I was trying to say that it works for any struct, rather than unit structs only.

“Anonymous functions that have an associated environment are called ‘closures’, because they close over an environment.” Although I know what a closure is, the phrase “close over an environment” isn’t meaningful to me. Must be a math thing.

I think recent drafts have extra text here, unsure.

I think rationales should be stated more explicitly. Instead of saying we don’t need to write the types of closure arguments because “they don’t cause the kinds of error-at-a-distance that inferring named function types can,” restate the fact that "Rust supports type inference, but doesn’t allow it on top-level functions because [blah blah blah]

That is the blah blah blah. Errors at a distance.

The subsection on “move closures” is confusing because the previous example showed that variables are already moved into the closure without the move keyword, whereas the book says that the initial example with move gets a copy of num.

Yeah, this is because numbers are Copy, which are copied on move. Maybe shouldn’t use a Copy type.

The syntax Fn(A, B) -> C is different than for all other traits.

yeah, this is basically sugar.

Moreover it seems impossible to express closures with the normal Trait<Params> syntax, because type Output is an associated type, not a type parameter, i.e. we can write Fn<(A, B)>, but there’s nowhere to put the return type C.

The associated type is named Output.

C++ programmers will recognize extern “rust-call” as a calling convention. But isn’t this redundant? Wouldn’t all trait functions be rust-call by default? I think if the book includes extern “rust-call” it needs to explain what it’s doing there.

Yeah, I left this in for accuracy, but didn’t want to get into calling conventions.

Saying that for i in 0…nums.len() is “strictly worse than using an actual iterator” seems an exaggeration. Because if you use an index variable your loop will know which index of the vector it is looking at, while for num in &nums won’t. It’s a tradeoff.

You can use enumerate() if you also need an index, so this case isn’t actually an advantage.

The statement “Why does &nums give us references? Firstly, because we explicitly asked it to with &” is strange. There is no obvious connection between &nums and “&(nums[i]) for each possible i”. It is unclear why for num in &nums was later changed to for num in nums.iter().

I’ll review the copy-editing in this section. They’re equivlanet forms.

Why doesn’t for i in (1…100).filter(|&x| x % 2 == 0) say *x % 2?

Because it’s not a pointer: &x pattern matches a pointer, and x is a value.

A missed opportunity to give a rationale. The section ends by discussing “error: binary operation == cannot be applied to type T”. C++ programmers will note that C++ does not give an error like that unless the template is instantiated with a T that actually has no == operator. The opportunity here is to explain that if a generic function compiles at all, then it will work correctly for all Ts that meet the constraints in the function signature. Hmm… this does mean that you’d have to have to introduce a constraint that includes == before the traits section. But that’s okay, there’s no need to know what a trait is before revealing T: Float.

Wait, in C++, if a template compiles, it still may not work? that sounds… terrible. This is just me not being familliar with C++ details, and assuming things work as they should

PartialEq is a strange name. How is it “partial”?

Partial equality as opposed to total equality.

The VTable “example” is very confusing, firstly because it appears to be Rust code but on closer inspection seems to be a kind of pseudocode,

it is.

[quote=“qwertie, post:52, topic:1816”] secondly because it uses notations that were never introduced before, like x as *const u8, [/quote]

that’s a cast, which has its own section in the new TOC

thirdly because call_method_on_u8 calls byte.method() somehow, even though call_method_on_u8 does not mention Foo nor FooVtable,

Right, the intention here is to show the underlying structure which the compiler uses.

[quote=“qwertie, post:52, topic:1816”] and fourthly because there’s no apparent reason why the parameter x points to () instead of the type to which x is immediately cast. Finally, it seems to me that next to the pseudo-Rust we should be shown some normal Rust that the pseudo-Rust is supposed to represent. Since Rust is a systems language, isn’t it possible to write some code that is actually compiles & runs and is equivalent to what the normal Rust code does? [/quote]

The problem here is the clash with the builtin types…

I’m confused about this “vec” macro. It was shown with the syntax vec![1,2,3] but the square brackets are nowhere to be seen in the macro_rules.

all macros can be invoked with (), {}, or [].

The problem with Mutex is fixed by introducing Arc, but you didn’t explain the fact that let data = data.lock().unwrap(); was orginally outside the closure and then was moved inside.

I guess that closures capturing things they referred to was known.

You mention that data.lock() may fail to acquire the mutex, but why would it fail?

of the top of my head, no idea.

[quote=“qwertie, post:52, topic:1816”]Doesn’t lock() wait for the shared resource to become available? At the same location you do something that will baffle many programmers, let mut data = data.lock().unwrap();, in which the left and right hand side of = both refer to data [/quote]

This is called ‘shadowing’ and is pretty pervasive in Rust code, I’ll make sure it’s in the bindings section.

You seem to be suggesting that channels are somehow an alternative to using a timer to wait 50ms for threads to complete (even though you already introduced thread::scoped). I think it would be more appropriate to introduce join() at this point.

Not at all, it’s just to show a program that does something.

“try! makes use of FromError” links to a page that does not mention FromError.

Yeah, this type got removed RIGHT BEFORE beta, so links break I’ll update it.

[steveklabnik]

Thank you for the detailed notes!

[tbu]

Partial equality as opposed to total equality.

I don’t know what total equality is, but Eq also guarantees that x == x, which PartialEq doesn’t.

[mdinger]

I don’t know what total equality is, but Eq also guarantees that x == x, which PartialEq doesn’t.

This was an attempt to address the cryptic differences between PartialOrd and Ord which is probably similar to the differences between PartialEq and Eq (the bug is probably a little out of date though now). The fact that I attempted to give a simpler example 3-4 times and had to be corrected each every time should be an indicator that it’s kinda complicated and should be simplified/clarified.

If you have any concrete suggestion on how this could be explained better, do state your ideas. It would be good if these concepts were explained better.

[tomjakubowski]

It’s just that this causes a data race.

To clarify: it’s dangerous even in the single-threaded case. Consider some C++ like:

void foo(std::vector<std::string> xs)
{
    for (const auto &x : xs) {
        // ... 
        if (some_condition) xs.push("whoops"); // causes UB
    }
}

This kind of error is impressively common in real C++ codebases, and is particularly insidious because it might only be apparent under unusual circumstances (like if the vector’s capacity needs to grow + relocate during the iteration). Ensuring that a pointer through which mutation can occur has unique access to its referent, as with Rust’s &mut T, prevents this class of errors entirely. Anecdotally, I’ve noticed an example like this is far more likely to catch the attention of a seasoned C++ programmer than others.

[petrochenkov]

Anecdotally, I’ve noticed an example like this is far more likely to catch the attention of a seasoned C++ programmer than others.

Yeah, it’s a good example and I’ve seen some C++ programmers reacting very negatively on it! I’ve seen Rust described as “a language where you can’t insert/remove elements in the loop” several times. C++ gives much more fine grained guarantees for such things, than just “UB happens” (see here for example) and people don’t like to trade this freedom and control for safety.

[comex]

If the new size() is greater than capacity() then all iterators and references (including the past-the-end iterator) are invalidated. Otherwise only the past-the-end iterator is invalidated.

vector::push_back probably isn’t the best example, since you can only keep using any pointers or iterators if you actually checked capacity, which isn’t a common pattern from what I’ve seen. Of course, there are common situations where C++ programmers can and do keep relying on pointers, like removing elements from a vector, modifying elements in place, modifying lists, etc.

I think the best answer to such complaints is to say that you don’t have to feel bad about using vector indices everywhere if necessary - yea, even if it reminds you of heathen languages that don’t have pointers.

[iopq]

This, I know that everything wants you to install it first before you play with it, but it would help so much if the tutorial was just clicking play embedded in the page and getting the result instantly back.

[OZ_]

Rust is meant for low level programmers, not web developers.

As a developer which coming to Rust from dynamic languages for language with static typing (I like static typing), and a web developer, I very dislike such phrases. I hope this person have nothing to do with Rust core team. Otherwise, if he/she is right, and Rust is not for web developers, please point this on the rust-lang.org explicitly.

[lambda]

I can assure you that Rust is not just for low-level programmers, and there are many people working on libraries and frameworks to make it suitable for web development. @sinistersnare is not on the core team (nor am I, or most people in this thread), his comments represent only his own opinion.

[sinistersnare]

I am also a web developer coming to Rust from dynamic languages with a history of strong (not static) typing. I am no OS developer (though I would like to be), and I think you misinterpreted me.

I view Rust as a language to use when you need fast code (because everything should be safe), with minimal footprint. Usually, in web sites, the bottleneck is with the database, and not the application code, so there is not really a need for Rust when you have safe languages like Python, Java, or Haskell.

However, if you, for example, only have an instance where you have 10 megabytes of RAM, like if you dont want to spend tons of money on hundreds of megs of ram on DigitalOcean or AWS for a hefty runtime like a JVM, then the minimal footprint of Rust is perfect.

The average web dev does not need Rust, it is not an insult, its a personal opinion held by me. I do not appreciate your comment, but I am not going to assume malice (done that too much before), and I want to say that I am sorry if i offended you.

---

Thanks, @lambda for the defense. <3

I am also +1 for the book to be light on Cargo, I think it would be good to be able to run all non-cargo specific examples on play.rust-lang.org (although im pretty sure that is the case, just wanted to reiterate).

Personally, when I am reading a book about clojure, I don’t care about leiningen, same thing with Python and Pip, I want to learn the language, not the infrastructure.

[OZ_]

Usually, in web sites, the bottleneck is with the database, and not the application code, so there is not really a need for Rust when you have safe languages like Python

Since when Python is a safe language? Look at Ruby performance and you will realize that code performance matters too (although not so much). In web sites, memory footprint per connection is a bottleneck too - for scaling (even when you have 32Gb of RAM per instance), so languages like Go and Rust are very attractive for web development. Also, what is attractive personally for me is static (exactly static) typing and explicit errors handling, so you can catch a lot of errors on the compilation step, so you can save huge amount of time in debugging step.

The average web dev does not need Rust

And second time you write message which can be read by some web developer as “you are not welcomed in Rust, go away”. Let web devs decide what they need, especially when nobody asks you.

[JoeHazzers]

I’ve also just come to Rust as a newcomer, and I have to agree with the general comments left initially by @terpstra.

Sparing you from the backstory of how I came across Rust and my own personal background, I found the book to be a little directionless at times, and often not backing up or expanding upon claims it makes.

There’s at least one area where the book mentions that doing something in some way is “considered poor style” (I believe this was referring to explicit use of the return keyword, but never goes on to discuss idiomatic Rust or what is considered “good style” (and why).

Also, I can basically confirm @qwertie’s general points, especially his point regarding iterators:

Saying that for i in 0…nums.len() is “strictly worse than using an actual iterator” seems an exaggeration. Because if you use an index variable your loop will know which index of the vector it is looking at, while for num in &nums won’t. It’s a tradeoff.

I saw the “strictly worse” comment and asked myself “why? what makes it worse? what should I be doing to access indexes?”. Of course, @steveklabnik’s answer:

You can use enumerate() if you also need an index, so this case isn’t actually an advantage.

answers my question, and this should probably be in the book.

I can appreciate that the language is fast-moving and the documentation sometimes suffers from this pace, but I found the book to be “Much Ado About Nothing” for the most part. Some of Rust’s most interesting aspects (it’s ownership model and lifetimes) were under-explained to the point I knew they existed, but I had no idea how to use them or how they even worked.

I found the book useful as a basic syntax guide and telling me about a few gotchas and getting me oriented with the syntax, but I believe that the book definitely needs some work for people who come looking for in-depth explanations of Rust’s features and the reasoning behind them.

Thanks @steveklabnik for your efforts, and I hope that the book can be improved to help people like me in the future

[sinistersnare]

I generally find a good coding style for Rust can be found in Python, as they share a lot of syntactic and semantic similarities. The reason I say this is because I find that Raymond Hettinger’s video “Transforming Code into Beautiful, Idiomatic Python,” is actually quite effective at showcasing good Rust code too , for example, the video contains a great explanation at why enumerate is recommended over length based iteration.

I also find myself consulting the zen and pep8 for good practices in general coding.

Thats usually what I say to people who seem unguided by the Rust documentation, hope it helps!

@OZ_ please stop being offended, this is the internet, things are communicated badly, just relax and do not assume malice. Thats all im going to say, you are going way off topic.

[steveklabnik]

@OZ_ please stop being offended, this is the internet,

I really want to stop having this converstion, but this is not an opinion shared by me. While it’s true that you should try to assume something charitable, ‘it’s just the internet’ is not an acceptable response for bad behavior, generally speaking.

Now, as I said above, let’s move past this. It’s not a big deal.

[steveklabnik]

answers my question, and this should probably be in the book.

Hey @JoeHazzers, thanks You’re possibly right in this case. The thing is: it depends. I’m not sure I’ve ever actually used enumerate in my own code, just like I rarely ever used each_with_index in the Ruby I wrote. It’s very hard to write a general-purpose doc, as differnet people do different things in different styles. if you go on at length about every detail, you get the above complaints about Cargo, for example: covering stuff that is ‘boring’.

It’s impossible to generally please everyone, which is why I can’t wait until some other people start writing more long-form documentation and tutorials. There’s a few blog series that are shaping up, but we need more!

I believe that the book definitely needs some work for people who come looking for in-depth explanations of Rust’s features and the reasoning behind them.

This is absolutely true. A significant amount of this has been in flux, historically, which is why the book sticks to the basics. You have to cover everything, so you cover easy things, and things that are unlikely to change. Now that things are settling down, it’s easier to do so, but there’s a lot, even for the basics: last I checked, the book was already 50,000 words, which is the size of a small novel. And when I re-did the TOC, I found a feature or two I still hadn’t even gotten the basics covered with yet.

So, I guess what I’m saying is, you’re right, but you also have to be patient. (which you are, I mean the general ‘you’)

[iopq]

It depends actually. I would say that you want to spend the most time optimizing your front page, because that’s what 90% of visitors will be seeing. This means you want to avoid having DB queries on the front page. Even if you pull data from the DB, you should still use a caching layer so that you’re getting very low response times.

If your page loads slowly, a greater percentage of people will turn back instead of waiting for it to load.

So yes, your website might have enough RAM to run Ruby on Rails, but if it takes a few hundred milliseconds more to render the page you’re still losing customers.

[leshow]

Personally, when I am reading a book about clojure, I don’t care about leiningen, same thing with Python and Pip, I want to learn the language, not the infrastructure

But when you read a book about writing Javascript in Node, you likely want to hear about npm don’t you? This is a more suitable example of the connection between Rust & Cargo IMO

[sinistersnare]

Personally, I have no good feelings about JavaScript, or its ecosystem, so I don’t use it as an example because of my lack of experience.

It could be, but I am not sure. I also personally thing that, like I said, Id rather learn about the language and then its infrastructure, not both at once.

[MTRust]

From what I’ve seen in most Ruby and Node books, they glance over the package management stuff and simply assume that you pretty much know how to use the tools. In this respect, I view the inclusion of cargo as a first-class topic in the Rust book quite refreshing and beneficial . It’s true that at first I didn’t care much about cargo as such, but it was good knowing that it is there if/when I will need it and at least I knew how to fetch external dependencies - then I simply skipped the rest until cargo became an integral part of my workflow and then I knew where to go back for more information on its usage.

So in my view, yes - you don’t need cargo right out of the gate, but you can always just skip the irrelevant sections and come back later, that said I do agree that perhaps it could be moved to the end as a sort of appendix.