Added Frequently Asked Questions Page

[alilleybrinker]

This commit is the first draft of a new Frequently Asked Questions (FAQ) page for the Rust website. It provides answers for all but 4 of the 130 questions asked by the community, which can be found on the tracking issue #181.

The answers could use some review, as could the design and organization. I've tried to provide clear, concise answers that more often than not point people to the relevant portion of the Rust book.

Thoughts? Changes?

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @brson (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[brson]

\o/ Woah! So much web site. Thanks.

[Diggsey]

Some thoughts while reading through it:

• Why does "very small and limited runtime" link to lazy_static?
• "Can I use globals across threads without unsafe" - You can use them as long as they're Sync and don't implement Drop, you just can't mutate them.
• "there is no total ordering for floating point numbers" - Technically, the spec does define several possible total orderings for floating point numbers, at least one of which is implemented by an external crate - maybe link to it?
• "How do I return a borrow to something I created from a function?" - Maybe suggest returning an owning type like String instead, and possibly mention Cow.
• "How can I define a struct that contains a pointer to one of its own fields?" - I think you can actually do this, but it's useless as the struct becomes permanently borrowed (by itself), and so cannot ever be moved.
• "What is the difference between consuming and moving/taking ownership?" - They're actually the same thing. When you call a method which consumes self, there's no requirement that self is dropped, it's simply moved into the method.
• "Using Deref coercions! Strings and Vecs will automatically coerce to their respective slices when referenced" - The term "referenced" is very ambiguous here, maybe make it clear that you mean using &var.
• "How do I do O(1) character access in a String?" - You can: str implements both Index and IndexMut, and so indexing is available via both String and &str. The caveats you mentioned still apply, but rather than getting out nonsense data, indexing will panic if it's not a valid UTF8 boundary.
• "The char type is UCS4" - Actually, it's UTF32, which is subtly different because it disallows values outside the range 0-0x10FFFF, or within the range reserved for UTF16 surrogates. This is necessary to ensure that it can only contain valid unicode characters.
• "Modules and Crates" - Maybe mention that use declarations are always relative to the crate root, rather than the current module, which is different from how name resolution works for everything else. This is one of the most confusing things when first using rust's module system.
• "What is "monomorphisation" - C++ programmers will know this as template instantiation. In rust however, it's an implementation detail rather than a language feature.
• "How does Rust's ownership system related to move semantics in C++?" - Maybe note that unlike in rust, in C++ destructors are still called after a value has been moved, ie. it's a destructive copy rather than an actual move.
• "Does Rust have C++-style constructors?" - Mention that methods which construct value are typically named "new".

[alilleybrinker]

Wonderful! This is exactly the input I'm looking for:

Why does "very small and limited runtime" link to lazy_static?

Ah, mistake during editing. Fixing now.

"Can I use globals across threads without unsafe" - You can use them as long as they're Sync and don't implement Drop, you just can't mutate them.

Good to know. I've updated my answer accordingly.

"there is no total ordering for floating point numbers" - Technically, the spec does define several possible total orderings for floating point numbers, at least one of which is implemented by an external crate - maybe link to it?

Do you know which crate?

"How do I return a borrow to something I created from a function?" - Maybe suggest returning an owning type like String instead, and possibly mention Cow.

Good point. Updated.

"How can I define a struct that contains a pointer to one of its own fields?" - I think you can actually do this, but it's useless as the struct becomes permanently borrowed (by itself), and so cannot ever be moved.

Do you have some example code that does this? I'd like to provide an example if I can.

"What is the difference between consuming and moving/taking ownership?" - They're actually the same thing. When you call a method which consumes self, there's no requirement that self is dropped, it's simply moved into the method.

You're right. Fixed.

"Using Deref coercions! Strings and Vecs will automatically coerce to their respective slices when referenced" - The term "referenced" is very ambiguous here, maybe make it clear that you mean using &var.

I agree. I've clarified the language.

"How do I do O(1) character access in a String?" - You can: str implements both Index and IndexMut, and so indexing is available via both String and &str. The caveats you mentioned still apply, but rather than getting out nonsense data, indexing will panic if it's not a valid UTF8 boundary.

Good point. I've updated the answer.

"The char type is UCS4" - Actually, it's UTF32, which is subtly different because it disallows values outside the range 0-0x10FFFF, or within the range reserved for UTF16 surrogates. This is necessary to ensure that it can only contain valid unicode characters.

Yup. I copied this answer verbatim from a much older FAQ on the Rust website. It may have been true at one point (I don't know), but you're right that it isn't now.

"Modules and Crates" - Maybe mention that use declarations are always relative to the crate root, rather than the current module, which is different from how name resolution works for everything else. This is one of the most confusing things when first using rust's module system.

I've added an answer addressing this.

"What is "monomorphisation" - C++ programmers will know this as template instantiation. In rust however, it's an implementation detail rather than a language feature.

Good idea. Added.

"How does Rust's ownership system related to move semantics in C++?" - Maybe note that unlike in rust, in C++ destructors are still called after a value has been moved, ie. it's a destructive copy rather than an actual move.

Yup. Added.

"Does Rust have C++-style constructors?" - Mention that methods which construct value are typically named "new".

Added, along with a small example of such a function.

[alilleybrinker]

Before anything gets merged I do want to note that four questions remain unanswered and commented out in the source code. This does not necessarily need to block merging, but if someone can answer any of these questions before we merge that would be much appreciated. If not, then afterward works.

[Diggsey]

Do you know which crate?

https://crates.io/crates/ordered-float

Do you have some example code that does this? I'd like to provide an example if I can.

http://is.gd/MDSXVA

[alilleybrinker]

Okay, I've updated it with that information.

[alilleybrinker]

I think this is ready to merge, unless there are concerns about the specialized styling for the page.

[brson]

Here's how the page looks deployed.

[steveklabnik]

😍

[GuillaumeGomez]

"also helps" instead of "also help" I think.

[brson]

"C++" -> "idiomatic C++" I think.

[nagisa]

I’d say “at least as fast”. “as fast as” implies equality.

[tshepang]

@brson why is it important to mention "idiomatic"? Is it because on some benchmarks, people use non-idiomatic C++ to win?

[brson]

That's right. Pedants can easily write horrible C++ code that beats safe
Rust as a counter-argument to performance claims, so we typically qualify
them with 'idiomatic C++'.

On the other hand though, in many cases safe Rust can trounce even
horribly-unsafe C++, and its our prerogative to make strong claims to sell
Rust (I don't mind ruffling feathers a bit). I'll think about it.

On Wed, Nov 18, 2015 at 4:53 AM, Tshepang Lekhonkhobe <
notifications@github.com> wrote:

In faq.md
#202 (comment):

•    <li><a href="#cross-platform">Cross-Platform</a></li>
  

•    <li><a href="#design-patterns">Design Patterns</a></li>
  

•    <li><a href="#macros">Macros</a></li>
  

•    <li><a href="#other-languages">Other Languages</a></li>
  

•    <li><a href="#licensing">Licensing</a></li>
  

•    <li><a href="#naming">Naming</a></li>
  

+
+
+## Performance
+
+#### How fast is Rust?
+
+As always, this question is difficult to answer. There's still a lot of work to do on speed, and depending on what you're benchmarking, Rust has variable performance.
+
+That said, it is an explicit goal of Rust to be as fast as C++ for most things. Language decisions are made with performance in mind, and we want Rust to be as fast as possible. Given that Rust is built on top of LLVM, any performance improvements in it also help Rust become faster.

@brson https://github.com/brson why is it important to mention
"idiomatic"? Is it because on some benchmarks, people use non-idiomatic C++
to win?

—
Reply to this email directly or view it on GitHub
https://github.com/rust-lang/rust-www/pull/202/files#r45194937.

[brson]

Can we not use a custom layout for this? Is the only customization here the copyright disclaimer? If so I feel ok, for now at least, assuming that the copyright declaration on the www repo itself is sufficient.

This is an interesting choice though, and we should consider whether something like it should be done for the entire site.

[alilleybrinker]

The custom layout is actually for an interesting reason. Markdown doesn't allow having Markdown embedded in HTML tags, and the <div class="faq"> is used for some custom styling (which may be undesirable, and definitely needs a bit of fine-tuning for mobile). I prefer to write in Markdown, although the file could of course be transitioned to entirely HTML if the extra layout is undesirable.

[aturon]

cc me. We need to advertise this PR very widely, get the whole community's eyes on it.

[edunham]

Could this be formatted so each question has an anchor, and I can link to a specific section? I imagine needing to link particular questions to new users quite frequently, and it'd be better to include the section in the URL than to tell them "click here and scrolll"

[brson]

This para explains why this page 'exists' twice (first sentence and third). It's not bad but feels like it could be tightened up. No suggestions offhand.

[brson]

"As always" are filler words, can be removed.

[brson]

Before demurring about performance we might want to say 'Rust is fast'. It is. We can rightfully make some strong claims.

Could even link to sources to back up those claims.

[alilleybrinker]

Absolutely. Are there particular sources or benchmarks which would be preferred targets for links? I know some people have expressed problems with the benchmarks like the Benchmarks Game in the past.

[nikomatsakis]

It feels like there are more concurrency questions that should be listed here. For example, I frequently hear people express surprise that Rust supports mutexes, since early versions of the language supported only message passing. Perhaps a question explaining this would make sense.

[alilleybrinker]

I am happy to add some more concurrency questions and answers. The included answers right now are a combination of topics covered in previous FAQs (updated, of course) and questions suggested after soliciting input from the community. It may simply be that a second round of question seeking may be in order, with particular focus on concurrency and any other sections currently under-covered by the FAQ.

[nagisa]

Heading level jump from 2 to 4.

[brson]

If we're going to claim that GC is possible seems like we should link to something to back that up.

"should not be a requirement" - "should" feels too weak since it's just a fact there's no GC in Rust. Maybe 'Rust provides the tools..., but does not include a garbage collector in the language or its standard libraries'.

[sfackler]

I would not say that goto fail is the primary motivation here. A bigger point is that parsing becomes ambiguous or at least confusing when both the parens around the condition and the braces around the block are omitted:

if foo == baz && bar.thingy() < 10 buz = 100;

[Toby-S]

Also means no dangling else.

[vadimcn]

Exactly. The "safety" justification is dubious anyways: if someone was paying so little attention to pasted code, he could have pasted the second goto after the closing bracket to the same effect. If anything this bug argues in favor of indentation-sensitive syntax.
Ability to drop brackets on conditionals in control structures is a much better justification, IMO.

[mbrubeck]

This should mention SliceConcatExt::concat and join.

[nikomatsakis]

Indices and vectors work well too. Here are two blog posts covering this topic:

• http://featherweightmusings.blogspot.com/2015/04/graphs-in-rust.html
• http://smallcultfollowing.com/babysteps/blog/2015/04/06/modeling-graphs-in-rust-using-vector-indices/

[sfackler]

read does not read until the buffer is full, but rather as much as the underlying system is willing to provide in a single call. read_exact does, which is unstable right now but will probably stabilize for 1.6.

[nagisa]

You probably want to note BufReader and its associated trait.

[brson]

No need to mention C/C++ here, just that --release makes things fast.

[Toby-S]

The heading here reads a bit unnaturally for me... perhaps "Why are programs compiled with cargo build slow?" or the more general "Why is my program slow?"?

[alilleybrinker]

Obviously things aren't quite done yet. I have some more direct feedback to go over, and I need to address @brson's previous points. But I just want to say that this has been a really great process, and I can't wait to get this thing polished and merged. Thanks for all the help and feedback, everyone.

Oh, and no problem @steveklabnik. It's been my pleasure.

[pnkfelix]

You mean "without & or &mut in the iteration", right?

(Not "collection", that is)

[alilleybrinker]

Yup. Thanks. I've fixed it.

[pnkfelix]

(great job incorporating feedback @AndrewBrinker ; I was especially impressed by the places where I said "oh man this is wrong but I don't know how to fix it" (and I threw up my hands) and you subsequently found a solution, quite quickly!)

[alilleybrinker]

Thanks @pnkfelix! I'm glad you like what I've done. It wouldn't have been possible without all the great feedback from everyone. The current version is much much better than my first draft. It'll be interesting to see how the document evolves over time, and to see what sort of feedback we get once it's up on the site.

@brson, I know you have some style changes you'd like made, and that your plan is to wrap this up yourself (I'm guessing squash down all the commits in this PR). Should I incorporate the style changes here, or is that something you'd like to do?

Also, I am still working on your big list of thoughts. The deref coercion and higher-kinded types answers have been updated, but the rest still need to be addressed properly.

[alilleybrinker]

Also, I started adding a bunch of missing links to the API docs at @steveklabnik's suggestion, but I'm not finished yet.

[solson]

I think an explanation of Rust's expression-oriented syntax and value flow would be good for this question. Implicit returns follow naturally from the normal evaluation rules, and mentioning only block expressions doesn't tell the whole story since the final expression might be, say, an if expression which new users might not be aware is an expression at all. Maybe we could link to a place in the book that describes this.

On the style guideline side, you could note the benefit of using return only for early returns, so you know normal control and value flow is being interrupted wherever you see it.

[tshepang]

Yeah, implicit returns are not mere style. They are a strong convention.

[tshepang]

@AndrewBrinker rocks!

[solson]

Mutation is safe if it's synchronized (e.g. Mutex<T> or AtomicUsize in a static is fine). Currently you need something like the lazy_static crate to initialize a Mutex<T> in a static, but AtomicUsize statics can be created and mutated in stable Rust with just libstd.

[solson]

A static variable can't be modified even with unsafe - you need static mut, which probably isn't something that should be recommended (particularly to beginners).

The next paragraph is misleading as well since you can't put a RefCell in a static at all currently (static requires Sync). However, one can have memory- and thread-safe mutable globals using the lazy_static crate and Mutex<T> or in simpler cases with a plain static atomic.

[solson]

This answer should mention the lazy_static crate as a workaround.

[solson]

This is shaping up to be quite excellent! Thanks to everyone who's been working so hard on this. 😄

[alilleybrinker]

Okay, I've now made changes addressing all but the following points of @brson's:

• The exceptions answer still needs a rewrite
• We still don't have an answer on Rust's name (I'm actually not sure what the real explanation is here)
• The "Concurrency," "Macros," and "Debugging" sections are still small (I think this is fine for now. They will almost certainly grow in future revisions based on community feedback).

I am also still going through the entire document adding links to the API docs.

[alilleybrinker]

Okay, I've finished adding the links to the API docs, and I've made the correction suggested by @tsion.

[brson]

@brson, I know you have some style changes you'd like made, and that your plan is to wrap this up yourself (I'm guessing squash down all the commits in this PR). Should I incorporate the style changes here, or is that something you'd like to do?

I'll take care of merging the styles. I am going to open one PR that contains all pending website changes.

[brson]

My previous points have been addressed to my satisfaction (for the most part, see below), and I'm intending to merge this with the other open PRs and my style changes into one fresh PR for landing.

The only remaining big concerns I have about the FAQ are: HKT section, while better, in the first section makes it sound like Rust has HKT by saying that type constructors that exist are KHTs; there's still no Q&A for 'What does "Rust" mean'.

I'm happy to address those in follow ups though.

[brson]

Here's the combined PR.

Thank you everybody for the amazing reviews and @AndrewBrinker for putting it all together. We're almost done.