+
diff --git a/community.md b/community.md
index d38288dbb..b6100c9aa 100644
--- a/community.md
+++ b/community.md
@@ -1,9 +1,9 @@
---
layout: default
-title: Rust Community · The Rust Programming Language
+title: The Rust Community · The Rust Programming Language
---
-# Rust Community
+# The Rust Community
Rust is an amazing programming language, but its greatest strength
is its kind and inclusive community.
@@ -129,6 +129,7 @@ socialize with other people with a similar interest. Meetings are
usually held monthly and very informal. Meetings are open to everyone.
There is a global [calendar][calendar] for keeping up with Rust events.
+Contact the [community team][community_team] to add your own.
[user_group]: ./user_groups.html
[calendar]: https://www.google.com/calendar/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com
@@ -179,12 +180,11 @@ help get you started.
[community_team]: https://www.rust-lang.org/team.html#Community
[mod_team]: https://www.rust-lang.org/team.html#Moderation
+
## Rust Development
Rust has had over [1,200 different contributors][authors], a number that grows
-every single week. We'd love for you to join that list! If you aren't sure what
-to work on or how to get started, take a look at our
-[how to contribute][contribute] page.
+every single week. [We'd love for you to join that list][contribute]!
As mentioned above, the [Rust Internals Forum][internals_forum] is dedicated to
discussing the design and implementation of Rust. A lot of discussion also
@@ -203,7 +203,7 @@ team business, including the progression of proposals through the RFC and
implementation process.
[authors]: https://github.com/rust-lang/rust/blob/master/AUTHORS.txt
-[contribute]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
+[contribute]: contribute.html
[github]: https://github.com/rust-lang/rust
[rfcs]: https://github.com/rust-lang/rfcs
[team_reports]: https://github.com/rust-lang/subteams
diff --git a/contribute-bugs.md b/contribute-bugs.md
new file mode 100644
index 000000000..b9b79a0ac
--- /dev/null
+++ b/contribute-bugs.md
@@ -0,0 +1,63 @@
+---
+layout: default
+title: Contributing to Rust — finding, triaging and fixing issues · The Rust Programming Language
+---
+
+# Contributing to Rust — finding, triaging and fixing issues
+
+The day-to-day maintenance of the project revolves around Rust's
+[issue tracker] and [pull requests][PR], and more help is always
+needed. The most basic way to get started contributing to Rust is to
+look for the [E-easy] or [E-mentor] labels. These are meant to be
+approachable for new Rust programmers.
+
+On `E-mentor` issues an experienced Rust developer has volunteered in
+the comments to mentor you through solving the issue and [submitting
+the fix via GitHub pull request][pull]. Contact them about the issue,
+on the issue tracker by [@mentioning] their name in a comment, on IRC,
+or through email. Note that Rust developers get a lot of notifications
+and it is easy to miss some; don't hesitate to hunt them down by
+whatever means necessary!
+
+Other projects in Rust maintain similar entry-level tasks, including
+the web browser [Servo], the HTTP library [hyper], the
+source-formatter [rustfmt], and the lint collection [clippy].
+
+While Rust has an [extensive test suite][test] there is always more to
+test. The [E-needstest] label indicates issues that are thought to be
+fixed but don't have tests. Writing test cases is a great way to
+understand a new project and get started contributing.
+
+Rust is always in need of people to [triage] issues: reproduce bugs,
+minimize test cases, apply labels, close resolved issues. Note that
+you'll need elevated GitHub permissions to apply labels, but this is
+easy to obtain for somebody with a bit of experience in the
+project. Ask a [team member][team].
+
+Once you've found your way around the project and have created a few
+pull requests in a particular area, consider reviewing others' pull
+requests: good reviewership is a rare skill and always appreciated. No
+prior permission is needed — just start constructively and politely
+commenting on pull requests that interest you. If you want training
+on conducting good code reviews [read this guide][reviews].
+
+
+
+[@mentioning]: https://github.com/blog/821
+[E-easy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
+[E-mentor]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
+[E-needstest]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-needstest
+[PR]: https://github.com/rust-lang/rust/pulls
+[Servo]: https://github.com/servo/servo
+[clippy]: https://github.com/Manishearth/rust-clippy
+[hyper]: https://github.com/hyperium/hyper
+[issue tracker]: https://github.com/rust-lang/rust/issues
+[pull]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#pull-requests
+[reviews]: http://blog.originate.com/blog/2014/09/29/effective-code-reviews/
+[rustfmt]: https://github.com/nrc/rustfmt
+[team]: team.html
+[test]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md
+[triage]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#issue-triage
diff --git a/contribute-community.md b/contribute-community.md
new file mode 100644
index 000000000..e4c38ec55
--- /dev/null
+++ b/contribute-community.md
@@ -0,0 +1,84 @@
+---
+layout: default
+title: Contributing to Rust — community building · The Rust Programming Language
+---
+
+# Contributing to Rust — community building
+
+Help newbies, spread the word, meet interesting people. Make Rust the
+shining example of open source development that we all want it to be.
+
+Keep an eye on the [#rust-beginners] channel. This is where we direct
+new Rust programmers to ask for help, and it is vital when they do
+that they receive prompt, accurate, and courteous responses. Likewise,
+[Stack Overflow], [users.rust-lang.org], and [/r/rust], are all forums
+where Rust programers commonly look for assistance. If you want
+training on answering programmers' questions [read this
+guide][helpful].
+
+If you are already experienced in some area of the project, please
+look out for potential [E-easy] bugs. When you see an
+easy issue on the bug tracker that you know how to fix, write up a
+description of the fix and tag it with E-easy. Note that what is
+obvious to you is not obvious to a new Rust contributor, and its
+important to describe the problem and the solution clearly. It is
+thus also helpful to triage E-easy bugs for poor descrptions and
+improve them.
+
+Experienced developers who are patient and communicate clearly should
+consider [mentoring new contributors][mentor]. Tag easy issues with
+[E-mentor] and mention in a comment that you will mentor. Expect people
+to contact you about the issue, and attempt to respond promptly.
+
+Maintaining entry-level tasks is good not only for The Rust Project
+itself but all projects. If your project has a consistent supply of
+entry-level tasks you might institute such a program
+yourself. ***Curating entry-level tasks is one of the most effective
+methods of bringing new programmers into the project***. If you want
+training on mentoring new contributors [read this
+guide][mentor-guide].
+
+Talk about what you are working on in the weekly "what's everyone
+working on this week" threads on [/r/rust] and [users.rust-lang.org],
+and indicate what you need help with. These are great starting points
+for collaboration.
+
+Advocate Rust in your own local community. Rust [user groups] and [events]
+are a unique and exciting part of the Rust experience: there are so
+many, and they are everywhere! If you haven't been yet, go and enjoy
+new experiences. If there is nothing Rusty going on near you then
+consider organizing something. You can poll for interest and announce
+events on [/r/rust] or [users.rust-lang.org]. Contact the [community
+team] to put events on the calendar, and thus be announced on [This
+Week in Rust].
+
+Remember as you are advocating Rust though to be considerate of
+others' views — not everybody is going to be receptive to Rust, and
+that's just fine.
+
+Meet other Rust community builders in [#rust-community].
+
+
+
+[#rust-beginners]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-beginners
+[#rust-community]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-community
+[/r/rust]: https://reddit.com/r/rust
+[E-easy]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy
+[E-mentor]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AE-easy+label%3AE-mentor
+[Stack Overflow]: http://stackoverflow.com/questions/tagged/rust
+[This Week in Rust]: http://www.this-week-in-rust.org
+[community team]: https://www.rust-lang.org/team.html#Community
+[events]: https://www.google.com/calendar/embed?src=apd9vmbc22egenmtu5l6c5jbfc@group.calendar.google.com
+[helpful]: http://blogs.msmvps.com/jonskeet/2009/02/17/answering-technical-questions-helpfully/
+[mentor]: https://users.rust-lang.org/t/mentoring-newcomers-to-the-rust-ecosystem/3088
+[mentor-guide]: http://manishearth.github.io/blog/2016/01/03/making-your-open-source-project-newcomer-friendly/
+[user groups]: user_groups.html
+[users.rust-lang.org]: https://users.rust-lang.org
diff --git a/contribute-compiler.md b/contribute-compiler.md
new file mode 100644
index 000000000..775ccd698
--- /dev/null
+++ b/contribute-compiler.md
@@ -0,0 +1,109 @@
+---
+layout: default
+title: Contributing to Rust — language, compiler, and the standard library · The Rust Programming Language
+---
+
+# Contributing to Rust — language, compiler, and the standard library
+
+
+The source code to the compiler and standard library are in the main
+repository, and as their maintenance is the primary objective of that
+repository, many labels on the issue tracker relate to it. Some of
+the more fruitful labels include [A-codegen], for translation of
+Rust to LLVM IR; [A-debuginfo], generation of metadata used by debuggers;
+[A-diagnostics], the feedback the compiler provides on errors; [A-libs],
+issues with the standard library; [A-macros] and [A-syntaxext], both
+related to syntax extensions; and [A-typesystem], on the topic of types.
+
+There is no well-maintained guide to the architecture of the compiler,
+but [there is a small overview in-tree][rustc-guide]. The [API
+documentation for the crates that make up the
+compiler][internals-docs] can help with navigating the code, as can
+the source code browser [Rust DXR]. The [guide to the Rust test
+suite][testsuite] will teach you how to exercise the Rust build system
+effectively, as will running [`make tips`][tips] at the command line.
+
+For the foreseable future, one of the major thrusts of Rust compiler
+development is converting its internals from operating directly off
+the AST to working with an [intermediate representation called
+MIR][mir]. This work is expected to open up many new possibilities by
+simplifying the compiler and help is needed to e.g. create a MIR-based
+translation pass, add MIR-based optimizations, and implement
+incremental compilation. There is yet no single source for information
+on work needed here, but ask on [internals.rust-lang.org] or
+[#rust-internals] for guidance.
+
+[It's embarrasing when our compiler crashes][ice] — the
+dreaded 'internal compiler error' (ICE). The [I-ICE] label
+tracks these, and they are often plentiful. These are usually
+good bugs to start with because it's easy to know when you've fixed
+them, and they're often relatively self-contained.
+
+The performance of Rust code is one of its great advantages; and the
+performance of the Rust compiler one of its great weaknesses. Any
+improvements to either runtime or — especially — compiletime performance
+are widely celebrated. The [I-slow] and [A-optimization] labels deal
+with runtime performance, and [I-compiletime] with compiletime. We have
+a [site that tracks compiletime performance][rustc-perf] on a number
+of workloads. The `-Z time-passes` compiler flag can help debug
+compiler performance, and Rust code can be profiled with standard
+profilers like `perf` on Linux.
+
+Major new features go through a [Request for Comments (RFC)][rfc]
+process, by which the design is agreed upon. Though it is open to all,
+it is a social process between developers who already have various
+amounts of experience working together, and it is recommended to get
+involved slowly — submitting a hasty RFC without understanding
+the historical, technical, or social context is an easy way
+to make a poor impression and come away disappointed. Read the
+aforelinkd readme file to understand best how it all works. Many
+ideas have been debated in Rust's history, some rejected, some
+postponed until the future, and the RFC [issue tracker][rfc-issues]
+catalogs some wishlist ideas that have yet to make headway into the
+language. Shortly before an RFC is accepted for implementation it
+enters 'final commemnt period', indicated by the [final-comment-period
+label on the rust-lang/rfcs repository][rfc-fcp]. Likewise, before a
+feature is enabled in the stable compiler (called 'ungating') it
+enters [final-comment-period in the rust-lang/rust
+repository][issue-fcp]. Both FCPs are critical moments to get involved
+and express opinions on the direction of the language, and are
+advertised in the weekly subteam reports on [internals.rust-lang.org].
+
+Meet other Rust compiler engineers in [#rustc], language
+designers in [#rust-lang], and library designers in [#rust-libs].
+
+
+
+
+[#rust-internals]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals
+[#rust-lang]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-lang
+[#rust-libs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-libs
+[#rustc]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc
+[A-codegen]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-codegen
+[A-debuginfo]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-debuginfo
+[A-diagnostics]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-diagnostics
+[A-libs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-libs
+[A-macros]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-macros
+[A-optimization]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-optimization
+[A-syntaxext]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-syntaxext
+[A-typesystem]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-typesystem
+[I-ICE]: https://github.com/rust-lang/rust/labels/I-ICE
+[I-compiletime]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-compiletime
+[I-slow]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AI-slow
+[Rust DXR]: https://dxr.mozilla.org/rust/source/src
+[ice]: https://users.rust-lang.org/t/glacier-a-big-ol-pile-of-ice/3380
+[internals-docs]: http://manishearth.github.com/rust-internals-docs
+[internals.rust-lang.org]: https://internals.rust-lang.org/
+[issue-fcp]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AB-unstable+label%3Afinal-comment-period
+[mir]: https://github.com/rust-lang/rust/issues/27840
+[rfc-fcp]: https://github.com/rust-lang/rfcs/pulls?q=is%3Aopen+is%3Apr+label%3Afinal-comment-period
+[rfc-issues]: https://github.com/rust-lang/rfcs/issues
+[rfc]: https://github.com/rust-lang/rfcs#table-of-contents
+[rustc-guide]: https://github.com/rust-lang/rust/blob/master/src/librustc/README.md
+[rustc-perf]: http://ncameron.org/perf-rustc/
+[testsuite]: https://github.com/rust-lang/rust-wiki-backup/blob/master/Note-testsuite.md
+[tips]: https://github.com/rust-lang/rust/blob/3d1f3c9d389d46607ae28c51cc94c1f43d65f3f9/Makefile.in#L48
diff --git a/contribute-docs.md b/contribute-docs.md
new file mode 100644
index 000000000..7a6b8ef24
--- /dev/null
+++ b/contribute-docs.md
@@ -0,0 +1,67 @@
+---
+layout: default
+title: Contributing to Rust — documentation · The Rust Programming Language
+---
+
+# Contributing to Rust — documentation
+
+Documentation is never good enough and there's never enough of it.
+Many aspects of Rust's documentation don't require deep knowledge to
+improve, and writing, reviewing, and editing documentation are great
+ways to learn Rust. Furthermore, improvements to documentation are
+easy to identify and limitless. Don't like the way something reads?
+Discover some information that wasn't documented? Your pull request
+will be gleefully embraced.
+
+***The most impactful documentation you can write is [for the crates
+that make up the Rust ecosystem][crate_docs]***. While the in-tree
+documentation is relatively complete, the same is not yet true for
+[many of the popular crates and tools][awesome-rust] that Rust
+programmers interact with every day. Contributing API documentation to
+a popular Rust project will earn you the enduring love of its maintainer.
+
+[The Book] is the primary documentation for Rust, maintained in the
+main repository. It has its own issue label, [A-book] and
+is continually being refined. Other documentation in the main
+repository include [The Rust Reference], the [standard library API
+documentation][std], [The Rustonomicon] (a guide to using `unsafe`
+correctly). The [Rust Style Guidelines] are so incomplete they are not
+linked prominently; an ambitious contributor can make much headway
+there. The [error index][err] provides extended explanations of the
+errors produced by the compiler. As new errors are added this
+documentation [must be maintained][err-issue], so there always
+errors not reflected in the index to be added. Most in-tree
+documentation lives in the [src/doc] directory. To contribute simply
+edit it and submit a pull request. These are all covered by the
+[A-docs] label on the issue tracker.
+
+A great deal of important Rust documentation does not live in the main
+repository, or is not maintained by the project, but is still
+critically important to Rust's success. Examples of excellent Rust
+documentation that is actively developed and in need of contributors
+include [Rust By Example], [Rust Design Patterns], and [rust-rosetta].
+For other existing documentation projects to contribute to see [rust-learning].
+
+Meet other Rust documentarians in [#rust-docs].
+
+
+
+[#rust-docs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-docs
+[A-book]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-book
+[A-docs]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-docs
+[Rust By Example]: https://github.com/rust-lang/rust-by-example
+[Rust Design Patterns]: https://github.com/nrc/patterns
+[Rust Style Guidelines]: http://doc.rust-lang.org/style/index.html
+[The Book]: http://doc.rust-lang.org/book/index.html
+[The Rust Reference]: http://doc.rust-lang.org/reference.html
+[The Rustonomicon]: http://doc.rust-lang.org/nomicon/index.html
+[awesome-rust]: https://github.com/kud1ing/awesome-rust
+[crate_docs]: https://users.rust-lang.org/t/lets-talk-about-ecosystem-documentation/2791
+[err-issue]: https://github.com/rust-lang/rust/issues/24407
+[err]: http://doc.rust-lang.org/error-index.html
+[rust-learning]: https://github.com/ctjhoa/rust-learning
+[rust-rosetta]: https://github.com/Hoverbear/rust-rosetta
+[src/doc]: https://github.com/rust-lang/rust/tree/master/src/doc
+[std]: http://doc.rust-lang.org/std/index.html
diff --git a/contribute-libs.md b/contribute-libs.md
new file mode 100644
index 000000000..ebeaa6f66
--- /dev/null
+++ b/contribute-libs.md
@@ -0,0 +1,66 @@
+---
+layout: default
+title: Contributing to Rust — libraries · The Rust Programming Language
+---
+
+# Contributing to Rust — libraries
+
+If you want to contribute to Rust by writing volumes of Rust code,
+then libraries are where it's at: since Rust is a young language,
+there are many types of libraries that either do not exist yet
+or are incomplete and in need of improvement or competition.
+
+Deciding what to write that will have impact and be fun is a common
+difficulty. Here are some ideas:
+
+* Read and participate in the weekly "what's everyone working on
+ this week" threads on [/r/rust] and [users.rust-lang.org]. These are
+ packed with exciting announcements from other Rust programmers in
+ need of collaborators.
+* Familiarize yourself with the best Rust libraries through
+ [awesome-rust] and [libs.rs].
+* Some larger projects, including the web browser [Servo], the HTTP
+ library [hyper], the source-formatter [rustfmt], and the lint
+ collection [clippy], tag issues with 'easy' labels for new
+ contributors.
+* Get involved with one of the active Rust-oriented GitHub
+ organizations, such as [PistonDevelopers], [servo], [redox-os],
+ [iron], [contain-rs], [hyperium]. It's often easier to find a place
+ to fit in with these subcommunities, they are in greater need of
+ help than rust-lang itself, and they are filled with experienced
+ Rust developers to guide you.
+* Help guide libraries from [rust-lang-nursery] into rust-lang proper.
+ Unfortunately there is not much documentation on what needs to be
+ done here; ask on [#rust-libs].
+* Inspect the RFC issue tracker for a [requested community
+ library][requested] and build it.
+* Watch [Github Trending][trending] for currently active Rust projects.
+
+As a library author you will want to be aware of the [best practices
+for Rust libraries][lib-prac].
+
+Meet other Rust library designers in [#rust-libs].
+
+
+
+[#rust-libs]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-libs
+[/r/rust]: https://reddit.com/r/rust
+[PistonDevelopers]: https://github.com/PistonDevelopers
+[Servo]: https://github.com/servo/servo
+[Servo]: https://github.com/servo/servo
+[awesome-rust]: https://github.com/kud1ing/awesome-rust
+[clippy]: https://github.com/Manishearth/rust-clippy
+[contain-rs]: https://github.com/contain-rs
+[hyper]: https://github.com/hyperium/hyper
+[hyperium]: https://github.com/hyperium
+[iron]: https://github.com/iron
+[lib-prac]: https://pascalhertleif.de/artikel/good-practices-for-writing-rust-libraries/
+[libs.rs]: http://www.libs.rs
+[redox-os]: https://github.com/redox-os
+[requested]: https://github.com/rust-lang/rfcs/labels/A-community-library
+[rust-lang-nursery]: https://github.com/rust-lang-nursery
+[rustfmt]: https://github.com/nrc/rustfmt
+[trending]: https://github.com/trending?l=rust
+[users.rust-lang.org]: https://users.rust-lang.org
diff --git a/contribute-tools.md b/contribute-tools.md
new file mode 100644
index 000000000..911c532ec
--- /dev/null
+++ b/contribute-tools.md
@@ -0,0 +1,40 @@
+---
+layout: default
+title: Contributing to Rust — tooling, IDEs and infrastructure · The Rust Programming Language
+---
+
+# Contributing to Rust — tooling, IDEs and infrastructure
+
+Tools play a huge part in the success of a language, and there is a
+great deal left to implement. ***A major focus of Rust development now
+is [improving the IDE experience][ides]***. This involves work
+throughout the Rust stack, from the compiler itself through your
+favorite IDE. Follow the link for more information.
+
+Both Cargo, the Rust package manager, and rustdoc,
+the Rust documentation generator, while full-featured and functional,
+suffer from a lack of developers. Rustdoc has many open issues, under
+the main repository's [A-rustdoc] label. They are mostly bugs and
+contributing is a matter of fixing the bug and submitting a pull
+request. Cargo has [its own repository and issues][Cargo], and those
+interested in contributing might want to introduce themselves in
+[#cargo].
+
+Although Rust can be run under both the gdb and lldb debuggers with
+limited success, there are still many cases where debugging does not
+work as expected. The [A-debuginfo] issue tracks these.
+
+For ideas for more tooling projects to contributo to see
+[awesome-rust].
+
+There are often other tooling projects of interest just waiting for
+the right people to come along and implement them. Discuss with other
+Rust tooling enthusiasts in [#rust-tools].
+
+[#cargo]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rustc
+[#rust-tools]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-tools
+[A-debuginfo]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-debuginfo
+[A-rustdoc]: https://github.com/rust-lang/rust/issues?q=is%3Aopen+is%3Aissue+label%3AA-rustdoc
+[Cargo]: https://github.com/rust-lang/cargo/issues
+[awesome-rust]: https://github.com/kud1ing/awesome-rust
+[ides]: ides.html
diff --git a/contribute.md b/contribute.md
new file mode 100644
index 000000000..71f5725e9
--- /dev/null
+++ b/contribute.md
@@ -0,0 +1,63 @@
+---
+layout: default
+title: Contributing to Rust · The Rust Programming Language
+---
+
+# Contributing to Rust
+
+You've started learning Rust. You love it, and you want to be a part
+of it. If you're not sure how to get involved, then this page
+will help.
+
+**Found a bug and need to report it?** [Follow the bug reporting
+guide][bugs]. Thanks in advance!
+
+Rust is an expansive system of projects, the most prominent of which
+are maintained by [The Rust Project Developers][devs] in [the
+rust-lang organization on GitHub][rust-lang]. Newcomers may be
+interested in the project's [CONTRIBUTING.md] file, which explains the
+mechanics of contributing to [rust-lang/rust].
+
+There are many ways to contribute to the success of Rust.
+This guide focuses on a few avenues for the new contributor:
+
+* [**Finding, triaging and fixing issues**](contribute-bugs.html). The
+ basic work of maintaining a large and active project like Rust.
+* [**Documentation**](contribute-docs.html). Not just official
+ documentation, but also for crates, blog posts, and other unofficial
+ sources.
+* [**Community building**](contribute-community.html). Helping your fellow
+ Rustacean, and expanding the reach of Rust.
+* [**Tooling, IDEs and infrastructure**](contribute-tools.html). The
+ important pieces that make using a language practical and painless.
+* [**Libraries**](contribute-libs.html). Rust's suitability for any
+ particular task is mostly dependent on availability of quality
+ libraries.
+* [**Language, compiler and the standard
+ library**](contribute-compiler.html). Language design, feature
+ implementation, performance improvement.
+
+If you need additional guidance ask on [#rust-internals] or
+[internals.rust-lang.org].
+
+We pride ourselves on maintaining civilized discourse, and to that end
+contributors are expected to follow our [Code of Conduct][coc]. If you
+have questions about this please inquire with the [community team].
+
+
+
+[#rust-internals]: https://client00.chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust-internals
+[CONTRIBUTING.md]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md
+[bugs]: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports
+[coc]: https://www.rust-lang.org/conduct.html
+[community team]: https://www.rust-lang.org/team.html#Community
+[dev_proc]: community.html#rust-development
+[devs]: https://github.com/rust-lang/rust/graphs/contributors
+[internals.rust-lang.org]: https://internals.rust-lang.org/
+[rust-lang/rust]: https://github.com/rust-lang/rust
+[rust-lang]: https://github.com/rust-lang
diff --git a/css/style.css b/css/style.css
index 62ded7ef5..6ac30ef95 100644
--- a/css/style.css
+++ b/css/style.css
@@ -60,10 +60,15 @@ ul.menu li {
margin-top: 0em;
margin-bottom: 0em;
}
+ul.menu li.menu {
+ margin-top: 3em;
+}
ul.menu h2 {
- font-size: 15.4px;
+ font-size: 20px;
font-weight: 500;
- margin: .8em 0;
+ margin: 1em;
+ display: inline;
+ line-height: 1.5em;
}
ul.menu li>ul {
margin-top: .5em;
@@ -123,11 +128,6 @@ div.install {
margin-top: 2.5em;
margin-bottom: 1.5em;
}
-@media (min-width: 662px) {
- div.install {
- margin-top: 5em;
- }
-}
.table-installers {
border-spacing: 4px;
@@ -175,7 +175,7 @@ p.pitch {
@media (min-width: 992px) {
p.pitch {
font-size: 25px;
- margin-top: 2.7em;
+ margin-top: 1.5em;
margin-bottom: 1em;
margin-right: 1em;
text-align: left;
@@ -190,7 +190,7 @@ p.pitch a {
color: #777;
text-align: right;
font-size: 130%;
- margin-top: 2em;
+ margin-top: 0.8em;
}
.version-rec-box-inner {
@@ -202,6 +202,7 @@ p.pitch a {
hr {
margin-top: 2em;
margin-bottom: 3em;
+ border-top: 2px solid #dedede;
}
.asterisk {
@@ -383,3 +384,110 @@ ul.laundry-list {
text-align: right;
margin: 5px 10px 0 0;
}
+
+.content {
+ border-top: 2px solid #dedede;
+ margin-top: 2em;
+ margin-bottom: 8em;
+ padding-top: 2em;
+}
+
+.content p,
+.content ul,
+.content ol,
+.content blockquote,
+.content pre {
+ margin: 0 0 1rem;
+}
+
+.content h1 {
+ font-size: 2.5em;
+ line-height: 1.5em;
+ margin-top: 0;
+ margin-bottom: 1rem;
+ font-weight: 400;
+ position: relative;
+}
+
+.content h2 {
+ font-size: 2em;
+ line-height: 1.5em;
+ margin: 3rem 0 1rem;
+ font-weight: 400;
+ border-top: 2px solid #dedede;
+ padding-top: 1rem;
+}
+
+.content h3 {
+ font-size: 1em;
+ line-height: 1.5em;
+ font-weight: 500;
+ margin: 2rem 0 .5rem;
+}
+
+@media screen and (min-width: 820px) {
+ .faq {
+ /*padding-right: 6em;*/
+ }
+
+ .faq p,
+ .faq ul,
+ .faq ol,
+ .faq blockquote,
+ .faq pre,
+ .faq table {
+ margin-left: 8rem;
+ }
+}
+
+.faq .faq-intro {
+ margin-left: 0rem;
+}
+
+.faq blockquote {
+ border-left: .25em solid #dedede;
+ padding-left: 2rem;
+}
+
+.faq blockquote p {
+ margin: 0;
+}
+
+.faq pre {
+ margin-top: 2rem;
+ margin-bottom: 2rem;
+}
+
+.faq code {
+ display: inline-block;
+ padding: .1em .2em 0;
+ font-size: 0.95em;
+ line-height: 1em;
+ background-color: #f7f7f7;
+ border-radius: 2px;
+ font-weight: 400;
+ font-family: Consolas, "Andale Mono WT", "Andale Mono", "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", Monaco, "Courier New", Courier, monospace;
+}
+
+.faq pre code {
+ font-size: 1em;
+ line-height: 1.5em;
+}
+
+.faq h3 > a {
+ color: black;
+}
+
+#toc h2 {
+ border: 0;
+ font-size: 2rem;
+ line-height: 1.5em;
+}
+
+#toc ol {
+ margin: 0 0 0 2rem;
+ padding: 0;
+ -webkit-columns: 150px 3;
+ -moz-columns: 150px 3;
+ columns: 150px 3;
+}
diff --git a/documentation.md b/documentation.md
new file mode 100644
index 000000000..ed159ac20
--- /dev/null
+++ b/documentation.md
@@ -0,0 +1,92 @@
+---
+layout: default
+title: Rust Documentation · The Rust Programming Language
+---
+
+# Rust Documentation
+
+If you haven't seen Rust at all yet, the first thing you should read
+is the introduction to the book, [**The Rust Programming
+Language**][book]. It will give you a good idea of what Rust is like,
+show you how to install it, and explain its syntax and concepts. Upon
+completing the book, you'll be an intermediate Rust developer, and
+will have a good grasp of the fundamental ideas behind Rust.
+
+## Learning Rust
+
+[**The Rust Programming Language**][book]. Also known as "The Book",
+The Rust Programming Language is the most comprehensive resource for
+all topics related to Rust, and is the primary official document of
+the language.
+
+[**Rust by Example**][rbe]. A collection of self-contained Rust
+examples on a variety of topics, executable in-browser.
+
+[**Frequently asked questions**][faq].
+
+[**The Rustonomicon**][nomicon]. An entire book dedicated to
+explaining how to write unsafe Rust code. It is for advanced Rust
+programmers.
+
+[**rust-learning**]. A community-maintained collection of resources
+for learning Rust.
+
+[book]: https://doc.rust-lang.org/book/
+[rbe]: http://rust-by-example.com
+[faq]: faq.html
+[nomicon]: https://doc.rust-lang.org/nomicon/
+[**rust-learning**]: https://github.com/ctjhoa/rust-learning
+
+## References
+
+[**Standard Library API Reference**][api]. Documentation for the
+standard library.
+
+[**The Rust Reference**][ref]. While Rust does not have a
+specification, the reference tries to describe its working in
+detail. It tends to be out of date.
+
+[**Syntax Index**][syn]. This appendix from The Book contains examples
+of all syntax in Rust cross-referenced with the section of The Book
+that describes it.
+
+[**The Cargo Guide**][cargo]. The documentation for Cargo,
+Rust's package manager.
+
+[**Compiler Error Index**][err]. Extended explanations of
+the errors produced by the Rust compiler.
+
+[api]: https://doc.rust-lang.org/std/
+[syn]: https://doc.rust-lang.org/book/syntax-index.html
+[ref]: https://doc.rust-lang.org/reference.html
+[cargo]: http://doc.crates.io/guide.html
+[err]: https://doc.rust-lang.org/error-index.html
+
+## Project policies
+
+[**Rust security policy**][security]. The project's policies for
+reporting, fixing and disclosing security-related bugs.
+
+[**Rust copyright and trademark policies**][legal]. The Rust
+copyrights are owned by The Rust Project Developers, and its
+trademarks are owned by Mozilla. Appropriate usage of Rust's
+trademarks are described here.
+
+[security]: security.html
+[legal]: legal.html
+
+## Nightly and beta documentation
+
+Much of the official Rust documentation is also available for the
+[nightly] and [beta] releases in addition to the stable documentation
+linked above.
+
+[nightly]: http://doc.rust-lang.org/nightly/
+[beta]: http://doc.rust-lang.org/beta/
+
+## Non-english resources
+
+For resources in languages other than English, see the
+[locale-specific links in rust-learning][locale].
+
+[locale]: https://github.com/ctjhoa/rust-learning#locale-links
diff --git a/downloads.html b/downloads.html
index c63d40373..f895cb48b 100644
--- a/downloads.html
+++ b/downloads.html
@@ -1,5 +1,5 @@
---
-layout: default
+layout: basic
title: Downloads · The Rust Programming Language
---
diff --git a/faq.md b/faq.md
new file mode 100644
index 000000000..72c80b4d6
--- /dev/null
+++ b/faq.md
@@ -0,0 +1,1463 @@
+---
+layout: faq
+title: Frequently Asked Questions · The Rust Programming Language
+---
+
+# Frequently Asked Questions
+
+
+This page exists to answer common questions about the Rust programming language. It is not a complete guide to the language, nor is it a tool for teaching the language. It is a reference to answer oft-repeated questions people in the Rust community encounter, and to clarify the reasoning behind some of Rust's design decisions.
+
+
+
+If there is some common or important question you feel is wrongly left unanswered here, feel free to help us fix it.
+
+
+To design and implement a safe, concurrent, practical systems language.
+
+Rust exists because other languages at this level of abstraction and efficiency are unsatisfactory. In particular:
+
+1. There is too little attention paid to safety.
+2. They have poor concurrency support.
+3. There is a lack of practical affordances.
+4. They offer limited control over resources.
+
+Rust exists as an alternative that provides both efficient code and a comfortable level of abstraction, while improving on all four of these points.
+
+
+
+No. Rust started as Graydon Hoare's part-time side project in 2006 and remained so for over 3 years. Mozilla got involved in 2009 once the language was mature enough to run basic tests and demonstrate its core concepts. Though it remains sponsored by Mozilla, Rust is developed by a diverse community of enthusiasts from many different places around the world. The [Rust Team](https://www.rust-lang.org/team.html) is composed of both Mozilla and non-Mozilla members, and `rustc` (Rust's compiler) has had over [1,000 unique contributors](https://github.com/rust-lang/rust/) so far.
+
+As far as [project governance](https://github.com/rust-lang/rfcs/blob/master/text/1068-rust-governance.md) goes, Rust is managed by a core team that sets the vision and priorities for the project,
+guiding it from a global perspective. There are also subteams to guide and foster development of particular areas of interest, including the core language, the compiler, Rust libraries, Rust tools, and moderation of the official Rust communities. Designs in each these areas are advanced through an [RFC process](https://github.com/rust-lang/rfcs). For changes which do not require an RFC, decisions are made through pull requests on the [`rustc` repository](https://github.com/rust-lang/rust).
+
+
+
+1. We do not employ any particularly cutting-edge technologies. Old, established techniques are better.
+2. We do not prize expressiveness, minimalism or elegance above other goals. These are desirable but subordinate goals.
+3. We do not intend to cover the complete feature-set of C++, or any other language. Rust should provide majority-case features.
+4. We do not intend to be 100% static, 100% safe, 100% reflective, or too dogmatic in any other sense. Trade-offs exist.
+5. We do not demand that Rust run on "every possible platform". It must eventually work without unnecessary compromises on widely-used hardware and software platforms.
+
+
+
+The main project is [Servo](https://github.com/servo/servo), an experimental browser engine Mozilla is working on. They are also working to [integrate Rust components](https://bugzilla.mozilla.org/show_bug.cgi?id=1135640) into Firefox.
+
+
+
+The two biggest open source Rust projects right now are [Servo](https://github.com/servo/servo) and the [Rust compiler](https://github.com/rust-lang/rust) itself.
+
+
+
+
+
+The easiest way to try Rust is through the [playpen](https://play.rust-lang.org/), an online app for writing and running Rust code. If you want to try Rust on your system, [install it](https://www.rust-lang.org/install.html) and go through the ["Learn Rust"](https://doc.rust-lang.org/stable/book/learn-rust.html) section of the book.
+
+
+
+There are several ways. You can:
+
+- Post in [users.rust-lang.org](https://users.rust-lang.org/), the official Rust users forum
+- Ask in the official [Rust IRC channel](https://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) (#rust on irc.mozilla.org)
+- Ask on [StackOverflow](http://stackoverflow.com/questions/tagged/rust) with the "rust" tag
+- Post in [/r/rust](https://www.reddit.com/r/rust), the official Rust subreddit
+
+
+
+Rust started with a goal of creating a safe but usable systems programming language. In pursuit of this goal it explored a lot of ideas, some of which it kept (lifetimes, traits) while others were discarded (the typestate system, green threading). Also, in the run up to 1.0 a lot of the standard library was rewritten as early designs were updated to best use Rust's features and provide quality, consistent cross-platform APIs.
+
+
+
+Rust's language versioning follows [SemVer](http://semver.org/), with backwards incompatible changes of stable APIs only allowed in minor versions if those changes fix compiler bugs, patch safety holes, or change dispatch or type inference to require additional annotation. More detailed guidelines for minor version changes are available as approved RFCs for both the [language](https://github.com/rust-lang/rfcs/blob/master/text/1122-language-semver.md) and [standard library](https://github.com/rust-lang/rfcs/blob/master/text/1105-api-evolution.md).
+
+Rust maintains three "release channels": stable, beta, and nightly. Stable and beta are updated every six weeks, with the current nightly becoming the new beta, and the current beta becoming the new stable. Language and standard library features marked unstable or hidden behind feature gates may only be used on the nightly channel. New features land as unstable, and are "ungated" once approved by the core team and relevant subteams. This approach allows for experimentation while providing strong backwards-compatibility guarantees for the stable channel.
+
+For additional details, read the Rust blog post ["Stability as a Deliverable."](http://blog.rust-lang.org/2014/10/30/Stability.html)
+
+
+
+No, you cannot. Rust works hard to provide strong guarantees about the stability of the features provided on the beta and stable channels. When something is unstable, it means that we can't provide those guarantees for it yet, and don't want people relying on it staying the same. This gives us the opportunity to try changes in the wild on the nightly channel, while still maintaining strong guarantees for people seeking stability.
+
+Things stabilize all the time, and the beta and stable channels update every six weeks. If you're waiting for a feature to be available without using the nightly channel, you can locate its tracking issue by checking the [`B-unstable`](https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+tracking+label%3AB-unstable) tag on the issue tracker.
+
+
+
+The Apache license includes important protection against patent aggression, but it is not compatible with the GPL, version 2. To avoid problems using Rust with GPL2, it is alternately MIT licensed.
+
+
+
+This is partly due to preference of the original developer (Graydon), and partly due to the fact that languages tend to have a wider audience and more diverse set of possible embeddings and end-uses than products such as web browsers. We'd like to appeal to as many of those potential contributors as possible.
+
+
+
+Fast! Rust is already competitive with idiomatic C and C++ in a number of benchmarks (like the [Benchmarks Game](http://benchmarksgame.alioth.debian.org/u64q/compare.php?lang=rust&lang2=gpp) and [others](https://github.com/kostya/benchmarks)).
+
+Like C++, Rust takes [zero-cost abstractions](http://blog.rust-lang.org/2015/05/11/traits.html) as one of its core principles: none of Rusts abstractions impose a global performance penalty, nor is there overhead from any runtime system.
+
+Given that Rust is built on LLVM and strives to resemble Clang from LLVM's perspective, any LLVM performance improvements also help Rust. In the long run, the richer information in Rust's type system should also enable optimizations that are difficult or impossible for C/C++ code.
+
+
+
+No. One of Rust's key innovations is guaranteeing memory safety (no segfaults) *without* requiring garbage collection.
+
+By avoiding GC, Rust can offer numerous benefits: predictable cleanup of resources, lower overhead for memory management, and essentially no runtime system. All of these traits make Rust lean and easy to embed into arbitrary contexts, and make it much easier to [integrate Rust code with languages that have a GC](http://calculist.org/blog/2015/12/23/neon-node-rust/).
+
+Rust avoids the need for GC through its system of ownership and borrowing, but that same system helps with a host of other problems, including
+[resource management in general](http://blog.skylight.io/rust-means-never-having-to-close-a-socket/) and [concurrency](http://blog.rust-lang.org/2015/04/10/Fearless-Concurrency.html).
+
+In practice, instead of GC Rust programs rely on reference counting through the
+standard library's
+[`Rc`](http://doc.rust-lang.org/std/rc/struct.Rc.html) and
+[`Arc`](http://doc.rust-lang.org/std/sync/struct.Arc.html) types.
+
+We are however investigating *optional* garbage collection as a future
+extension. The goal is to enable smooth integration with
+garbage-collected runtimes, such as those offered by the
+[Spidermonkey](https://developer.mozilla.org/en-US/docs/Mozilla/Projects/SpiderMonkey)
+and [V8](https://developers.google.com/v8/?hl=en) JavaScript engines.
+Finally, some people have investigated implementing
+[pure Rust garbage collectors](http://manishearth.github.io/blog/2015/09/01/designing-a-gc-in-rust/)
+without compiler support.
+
+
+
+The Rust compiler doesn't compile with optimizations unless asked to, [as optimizations slow down compilation and are usually undesirable during development](https://users.rust-lang.org/t/why-does-cargo-build-not-optimise-by-default/4150/3).
+
+If you compile with `cargo`, use the `--release` flag. If you compile with `rustc` directly, use the `-O` flag. Either of these will turn on optimizations.
+
+
+
+Code translation and optimizations. Rust provides high level abstractions that compile down into efficient machine code, and those translations take time to run, especially when optimizing.
+
+But Rust's compilation time is not as bad as it may seem, and there is reason to believe it will improve. When comparing projects of similar size between C++ and Rust, compilation time of the entire project is generally believed to be comparable. The common perception that Rust compilation is slow is in large part due to the differences in the *compilation model* between C++ and Rust: C++'s compilation unit is the file, while Rust's is the crate, composed of many files. Thus, during development, modifying a single C++ file can result in much less recompilation than in Rust. There is a major effort underway to refactor the compiler to introduce [incremental compilation](https://github.com/rust-lang/rfcs/blob/master/text/1298-incremental-compilation.md), which will provide Rust the compile time benefits of C++'s model.
+
+Aside from the compilation model, there are several other aspects of Rust's language design and compiler implementation that affect compile-time performance.
+
+First, Rust has a moderately-complex type system, and must spend a non-negligible amount of compile time enforcing the constraints that make Rust safe at runtime.
+
+Secondly, the Rust compiler suffers from long-standing technical debt, and notably generates poor-quality LLVM IR which LLVM must spend time "fixing". There is hope that future [MIR-based](https://github.com/rust-lang/rfcs/blob/master/text/1211-mir.md) optimization and translation passes will ease the burden the Rust compiler places on LLVM.
+
+Thirdly, Rust's use of LLVM for code generation is a double-edged sword: while it enables Rust to have world-class runtime performance, LLVM is a large framework that is not focused on compile-time performance, particularly when working with poor-quality inputs.
+
+Finally, while Rust's preferred strategy of monomorphising generics (ala C++) produces fast code, it demands that significantly more code be generated than other translation strategies. Rust programmers can use trait objects to trade away this code bloat by using dynamic dispatch instead.
+
+
+
+By default, Rust's [`HashMap`][HashMap] uses the [SipHash](https://131002.net/siphash/) hashing algorithm, which is designed to prevent [hash table collision attacks](http://programmingisterrible.com/post/40620375793/hash-table-denial-of-service-attacks-revisited) while providing [reasonable performance on a variety of workloads](https://www.reddit.com/r/rust/comments/3hw9zf/rust_hasher_comparisons/cub4oh6).
+
+While SipHash [demonstrates competitive performance](http://cglab.ca/%7Eabeinges/blah/hash-rs/) in many cases, one case where it is notably slower than other hashing algorithms is with short keys, such as integers. This is why Rust programmers often observe slow performance with [`HashMap`][HashMap]. The [FNV hasher](https://crates.io/crates/fnv) is frequently recommended for these cases, but be aware that it does not have the same collision-resistance properties as SipHash.
+
+
+
+There is, but it's only available on the nightly channel. We ultimately plan to build a pluggable system for integrated benchmarks, but in the meantime, the current system is [considered unstable](https://github.com/rust-lang/rust/issues/29553).
+
+
+
+Not generally, no. Tail-call optimization may be done in [limited circumstances](http://llvm.org/docs/CodeGenerator.html#sibling-call-optimization), but is [not guaranteed](https://mail.mozilla.org/pipermail/rust-dev/2013-April/003557.html). As the feature has always been desired, Rust has a keyword (`become`) reserved, though it is not clear yet whether it is technically possible, nor whether it will be implemented. There was a [proposed extension](https://github.com/rust-lang/rfcs/pull/81) that would allow tail-call elimination in certain contexts, but it is currently postponed.
+
+
+
+Not in the typical sense used by languages such as Java, but parts of the Rust standard library can be considered a "runtime", providing a heap, backtraces, unwinding, and stack guards. There is a [small amount of initialization code](https://github.com/rust-lang/rust/blob/33916307780495fe311fe9c080b330d266f35bfb/src/libstd/rt.rs#L43) that runs before the user's `main` function. The Rust standard library additionally links to the the C standard library, which does similar [runtime initialization](http://www.embecosm.com/appnotes/ean9/html/ch05s02.html). Rust code can be compiled without the standard library, in which case the runtime is roughly equivalent to C's.
+
+
+
+Use of curly braces to denote blocks is a common design choice in a variety of programming languages, and Rust's consistency is useful for people already familiar with the style.
+
+Curly braces also allow for more flexible syntax for the programmer, a simpler parser in the compiler, and help reduce the possibility of logic mistakes caused by incorrect indentation, like Apple's [goto fail](https://gotofail.com/) bug.
+
+
+
+Whereas C requires mandatory parentheses for `if`-statement conditionals but leaves brackets optional, Rust makes the opposite choice for its `if`-expressions. This keeps the conditional clearly separate from the body and avoids the hazard of optional brackets, which can lead to easy-to-miss errors during refactoring.
+
+
+
+Rust's overall design preference is for limiting the size of the *language* while enabling powerful *libraries*. While Rust does provide initialization syntax for arrays and string literals, these are the only collection types built into the language. Other library-defined types, including the ubiquitous [`Vec`][Vec] collection type, use macros for initialization like the [`vec!`][VecMacro] macro.
+
+This design choice of using Rust's macro facilities to initialize collections will likely be extended generically to other collections in the future, enabling simple initialization of not only [`HashMap`][HashMap] and [`Vec`][Vec], but also other collection types such as [`BTreeMap`][BTreeMap]. In the meantime, if you want a more convenient syntax for initializing collections, you can [create your own macro](http://stackoverflow.com/questions/27582739/how-do-i-create-a-hashmap-literal) to provide it.
+
+
+
+Rust is a very expression-oriented language, and "implicit returns" are part of that design. Constructs like `if`s, `match`es, and normal blocks are all expressions in Rust. For example, the following code checks if an [`i64`][i64] is odd, returning the result by simply yielding it as a value:
+
+```rust
+fn is_odd(x: i64) -> bool {
+ if x % 2 != 0 { true } else { false }
+}
+```
+
+Although it can be simplified even further like so:
+
+```rust
+fn is_odd(x: i64) -> bool {
+ x % 2 != 0
+}
+```
+
+In each example, the last line of the function is the return value of that function. It is important to note that if a function ends in a semicolon, its return type will be `()`, indicating no returned value. Implicit returns must omit the semicolon to work.
+
+Explicit returns are only used if an implicit return is impossible because you are returning before the end of the function's body. While each of the above functions could have been written with a `return` keyword and semicolon, doing so would be unnecessarily verbose, and inconsistent with the conventions of Rust code.
+
+
+
+In Rust, declarations tend to come with explicit types, while actual code has its types inferred. There are several reasons for this design:
+
+- Mandatory declaration signatures help enforce interface stability at both the module and crate level.
+- Signatures improve code comprehension for the programmer, eliminating the need for an IDE running an inference algorithm across an entire crate to be able to guess at a function's argument types; it's always explicit and nearby.
+- Mechanically, it simplifies the inference algorithm, as inference only requires looking at one function at a time.
+
+
+
+To aid in refactoring and clarity.
+
+First, if every possibility is covered by the `match`, adding variants to the `enum` in the future will cause a compilation failure, rather than an error at runtime. This type of compiler assistance makes fearless refactoring possible in Rust.
+
+Second, exhaustive checking makes the semantics of the default case explicit: in general, the only safe way to have a non-exhaustive `match` would be to panic the thread if nothing is matched. Early versions of Rust did not require `match` cases to be exhaustive and it was found to be a great source of bugs.
+
+It is easy to ignore all unspecified cases by using the `_` wildcard:
+
+```rust
+match val.do_something() {
+ Cat(a) => { /* ... */ }
+ _ => { /* ... */ }
+}
+```
+
+
+
+The choice of which to use is dependent on the purpose of the program.
+
+If you are interested in the greatest degree of precision with your floating point numbers, then prefer [`f64`][f64]. If you are more interested in keeping the size of the value small or being maximally efficient, and are not concerned about the associated inaccuracy of having fewer bits per value, then [`f32`][f32] is better. Operations on [`f32`][f32] are usually faster, even on 64-bit hardware. As a common example, graphics programming typically uses [`f32`][f32] because it requires high performance, and 32-bit floats are sufficient for representing pixels on the screen.
+
+If in doubt, choose [`f64`][f64] for the greater precision.
+
+
+
+Floats can be compared with the `==`, `!=`, `<`, `<=`, `>`, and `>=` operators, and with the `partial_cmp()` function. `==` and `!=` are part of the [`PartialEq`][PartialEq] trait, while `<`, `<=`, `>`, `>=`, and `partial_cmp()` are part of the [`PartialOrd`][PartialOrd] trait.
+
+Floats cannot be compared with the `cmp()` function, which is part of the [`Ord`][Ord] trait, as there is no total ordering for floats. Furthermore, there is no total equality relation for floats, and so they also do not implement the [`Eq`][Eq] trait.
+
+There is no total ordering or equality on floats because the floating-point value [`NaN`](https://en.wikipedia.org/wiki/NaN) is not less than, greater than, or equal to any other floating-point value or itself.
+
+Because floats do not implement [`Eq`][Eq] or [`Ord`][Ord], they may not be used in types whose trait bounds require those traits, such as [`BTreeMap`][BTreeMap] or [`HashMap`][HashMap]. This is important because these types *assume* their keys provide a total ordering or total equality relation, and will malfunction otherwise.
+
+There [is a crate](https://crates.io/crates/ordered-float) that wraps [`f32`][f32] and [`f64`][f64] to provide [`Ord`][Ord] and [`Eq`][Eq] implementations, which may be useful in certain cases.
+
+
+
+There are two ways: the `as` keyword, which does simple casting for primitive types, and the [`Into`][Into] and [`From`][From] traits, which are implemented for a number of type conversions (and which you can implement for your own types). The [`Into`][Into] and [`From`][From] traits are only implemented in cases where conversions are lossless, so for example, `f64::from(0f32)` will compile while `f32:from(0f64)` will not. On the other hand, `as` will convert between any two primitive types, truncating values as necessary.
+
+
+
+Usually, you can pass a reference to a `String` or `Vec` wherever a slice is expected.
+Using [Deref coercions](https://doc.rust-lang.org/stable/book/deref-coercions.html), [`String`s][String] and [`Vec`s][Vec] will automatically coerce to their respective slices when passed by reference with `&` or `& mut`.
+
+In some cases, such as generic code, it's necessary to convert manually. Manual conversions can be achieved using the slicing operator, like so: `&my_vec[..]`.
+
+
+
+The [`to_owned()`][to_owned] method converts from a [`&str`][str] into a [`String`][String], and [`String`s][String] are automatically converted into [`&str`][str] when you borrow a reference to them. Both are demonstrated in the following example:
+
+```rust
+fn main() {
+ let s = "Jane Doe".to_owned();
+ say_hello(&s);
+}
+
+fn say_hello(name: &str) {
+ println!("Hello {}!", name);
+}
+```
+
+
+
+[`String`][String] is an owned buffer of UTF-8 bytes allocated on the heap. Mutable [`String`s][String] can be modified, growing their capacity as needed. [`&str`][str] is a fixed-capacity "view" into a [`String`][String] allocated elsewhere, commonly on the heap, in the case of slices dereferenced from [`String`s][String], or in static memory, in the case of string literals.
+
+[`&str`][str] is a primitive type implemented by the Rust language, while [`String`][String] is implemented in the standard library.
+
+
+
+You cannot. At least not without a firm understanding of what you mean by "character", and preprocessing the string to find the index of the desired character.
+
+Rust strings are UTF-8 encoded. A single visual character in UTF-8 is not necessarily a single byte as it would be in an ASCII-encoded string. Each byte is called a "code unit" (in UTF-16, code units are 2 bytes; in UTF-32 they are 4 bytes). "Code points" are composed of one or more code units, and combine in "grapheme clusters" which most closely approximate characters.
+
+Thus, even though you may index on bytes in a UTF-8 string, you can't access the `i`th code point or grapheme cluster in constant time. However, if you know at which byte that desired code point or grapheme cluster begins, then you _can_ access it in constant time. Functions including [`str::find()`][str__find] and regex matches return byte indices, facilitating this sort of access.
+
+
+
+The [`str`][str] type is UTF-8 because we observe more text in the wild in this encoding – particularly in network transmissions, which are endian-agnostic – and we think it's best that the default treatment of I/O not involve having to recode codepoints in each direction.
+
+This does mean that locating a particular Unicode codepoint inside a string is an O(n) operation, although if the starting byte index is already known then they can be accessed in O(1) as expected. On the one hand, this is clearly undesirable; on the other hand, this problem is full of trade-offs and we'd like to point out a few important qualifications:
+
+Scanning a [`str`][str] for ASCII-range codepoints can still be done safely byte-at-a-time. If you use [`.as_bytes()`][str__as_bytes], pulling out a [`u8`][u8] costs only `O(1)` and produces a value that can be cast and compared to an ASCII-range [`char`][char]. So if you're (say) line-breaking on `'\n'`, byte-based treatment still works. UTF-8 was well-designed this way.
+
+Most "character oriented" operations on text only work under very restricted language assumptions such as "ASCII-range codepoints only". Outside ASCII-range, you tend to have to use a complex (non-constant-time) algorithm for determining linguistic-unit (glyph, word, paragraph) boundaries anyway. We recommend using an "honest" linguistically-aware, Unicode-approved algorithm.
+
+The [`char`][char] type is UTF-32. If you are sure you need to do a codepoint-at-a-time algorithm, it's trivial to write a `type wstr = [char]`, and unpack a [`str`][str] into it in a single pass, then work with the `wstr`. In other words: the fact that the language is not "decoding to UTF32 by default" shouldn't stop you from decoding (or re-encoding any other way) if you need to work with that encoding.
+
+For a more in-depth explanation of why UTF-8 is usually preferable over UTF-16 or UTF-32, read the [UTF-8 Everywhere manifesto](http://utf8everywhere.org/).
+
+
+
+If your reason for implementing these data structures is to use them for other programs, there's no need, as efficient implementations of these data structures are provided by the standard library.
+
+If, however, [your reason is simply to learn](http://cglab.ca/~abeinges/blah/too-many-lists/book/), then you will likely need to dip into unsafe code. While these data structures _can_ be implemented entirely in safe Rust, the performance is likely to be worse than it would be with the use of unsafe code. The simple reason for this is that data structures like vectors and linked lists rely on pointer and memory operations that are disallowed in safe Rust.
+
+For example, a doubly-linked list requires that there be two mutable references to each node, but this violates Rust's mutable reference aliasing rules. You can solve this using [`Weak`][Weak], but the performance will be poorer than you likely want. With unsafe code you can bypass the mutable reference aliasing rule restriction, but must manually verify that your code introduces no memory safety violations.
+
+
+
+The easiest way is by using the collection's [`IntoIterator`][IntoIterator] implementation. Here is an example for [`&Vec`][Vec]:
+
+```rust
+let v = vec![1,2,3,4,5];
+for item in &v {
+ print!("{} ", item);
+}
+println!("\nLength: {}", v.len());
+```
+
+Rust `for` loops call `into_iter()` (defined on the [`IntoIterator`][IntoIterator] trait) for whatever they're iterating over. Anything implementing the [`IntoIterator`][IntoIterator] trait may be looped over with a `for` loop. [`IntoIterator`][IntoIterator] is implemented for [`&Vec`][Vec] and [`&mut Vec`][Vec], causing the iterator from `into_iter()` to borrow the contents of the collection, rather than moving/consuming them. The same is true for other standard collections as well.
+
+If a moving/consuming iterator is desired, write the `for` loop without `&` or `&mut` in the iteration.
+
+If you need direct access to a borrowing iterator, you can usually get it by calling the `iter()` method.
+
+
+
+You don't necessarily have to. If you're declaring an array directly, the size is inferred based on the number of elements. But if you're declaring a function that takes a fixed-size array, the compiler has to know how big that array will be.
+
+One thing to note is that currently Rust doesn't offer generics over arrays of different size. If you'd like to accept a contiguous container of a variable number of values, use a [`Vec`][Vec] or slice (depending on whether you need ownership).
+
+
+
+There are at least four options (discussed at length in [Too Many Linked Lists](http://cglab.ca/~abeinges/blah/too-many-lists/book/):
+
+- You can implement it using [`Rc`][Rc] and [`Weak`][Weak] to allow shared ownership of nodes,
+although this approach pays the cost of memory management.
+- You can implement it using `unsafe` code using raw pointers. This will be
+more efficient, but bypasses Rust's safety guarantees.
+- Using vectors and indices into those vectors. There are [several](http://smallcultfollowing.com/babysteps/blog/2015/04/06/modeling-graphs-in-rust-using-vector-indices/) [available](http://featherweightmusings.blogspot.com/2015/04/graphs-in-rust.html) examples and explanations of this approach.
+- Using borrowed references with [`UnsafeCell`][UnsafeCell]. There are [explanations and code](https://github.com/nrc/r4cppp/blob/master/graphs/README.md#node-and-unsafecell) available for this approach.
+
+
+
+These are different terms for the same thing. In all cases, it means the value has been moved to another owner, and moved out of the possession of the original owner, who can no longer use it.
+
+
+
+If a type implements the [`Copy`][Copy] trait, then it will be copied when passed to a function. All numeric types in Rust implement [`Copy`][Copy], but struct types do not implement [`Copy`][Copy] by default, so they are moved instead. This means that the struct can no longer be used elsewhere, unless it is moved back out of the function via the return.
+
+
+
+This error means that the value you're trying to use has been moved to a new owner. The first thing to check is whether the move in question was necessary: if it moved into a function, it may be possible to rewrite the function to use a reference, rather than moving. Otherwise if the type being moved implements [`Clone`][Clone], then calling `clone()` on it before moving will move a copy of it, leaving the original still available for further use. Note though that cloning a value should typically be the last resort since cloning can be expensive, causing further allocations.
+
+If the moved value is of your own custom type, consider implementing [`Copy`][Copy] (for implicit copying, rather than moving) or [`Clone`][Clone] (explicit copying). [`Copy`][Copy] is most commonly implemented with `#[derive(Copy, Clone)]` ([`Copy`][Copy] requires [`Clone`][Clone]), and [`Clone`][Clone] with `#[derive(Clone)]`.
+
+If none of these are possible, you may want to modify the function that acquired ownership to return ownership of the value when the function exits.
+
+
+
+- Use `self` when a function needs to consume the value
+- Use `&self` when a function only needs a read-only reference to the value
+- Use `&mut self` when a function needs to mutate the value without consuming it
+
+
+
+The borrow checker applies only a few rules, which can be found in the Rust book's [section on borrowing](https://doc.rust-lang.org/stable/book/references-and-borrowing.html#the-rules), when evaluating Rust code. These rules are:
+
+> First, any borrow must last for a scope no greater than that of the owner. Second, you may have one or the other of these two kinds of borrows, but not both at the same time:
+>
+> - one or more references (&T) to a resource.
+> - exactly one mutable reference (&mut T)
+
+While the rules themselves are simple, following them consistently is not, particularly for those unaccustomed to reasoning about lifetimes and ownership.
+
+The first step in understanding the borrow checker is reading the errors it produces. A lot of work has been put into making sure the borrow checker provides quality assistance in resolving the issues it identifies. When you encounter a borrow checker problem, the first step is to slowly and carefully read the error reported, and to only approach the code after you understand the error being described.
+
+The second step is to become familiar with the ownership and mutability-related container types provided by the Rust standard library, including [`Cell`][Cell], [`RefCell`][RefCell], and [`Cow`][Cow]. These are useful and necessary tools for expressing certain ownership and mutability sutations, and have been written to be of minimal performance cost.
+
+The single most important part of understanding the borrow checker is practice. Rust's strong static analyses guarantees are strict and quite different from what many programmers have worked with before. It will take some time to become completely comfortable with everything.
+
+If you find yourself struggling with the borrow checker, or running out of patience, always feel free to reach out to the [Rust community](community.html) for help.
+
+
+
+This is covered in the official documentation for [`Rc`][Rc], Rust's non-atomically reference-counted pointer type. In short, [`Rc`][Rc] and its thread-safe cousin [`Arc`][Arc] are useful to express shared ownership, and have the system automatically deallocate the associated memory when no one has access to it.
+
+
+
+To return a closure from a function, it must be a "move closure", meaning that the closure is declared with the `move` keyword. As [explained in the Rust book](https://doc.rust-lang.org/book/closures.html#move-closures), this gives the closure its own copy of the captured variables, independent of its parent stack frame. Otherwise, returning a closure would be unsafe, as it would allow access to variables that are no longer valid; put another way: it would allow reading potentially invalid memory. The closure must also be wrapped in a [`Box`][Box], so that it is allocated on the heap. Read more about this [in the book](https://doc.rust-lang.org/book/closures.html#returning-closures).
+
+
+
+A [deref coercion](https://doc.rust-lang.org/book/deref-coercions.html) is a handy coercion
+that automatically converts references to pointers (e.g., `&Rc` or `&Box`) into references
+to their contents (e.g., `&T`). Deref coercions exist to make using Rust more ergonomic, and are implemented via the [`Deref`][Deref] trait.
+
+A Deref implementation indicates that the implementing type may be converted into a target by a call to the `deref` method, which takes an immutable reference to the calling type and returns a reference (of the same lifetime) to the target type. The `*` prefix operator is shorthand for the `deref` method.
+
+They're called "coercions" because of the following rule, quoted here [from the Rust book](https://doc.rust-lang.org/stable/book/deref-coercions.html):
+
+> If you have a type `U`, and it implements `Deref`, values of `&U` will automatically coerce to a `&T`.
+
+For example, if you have a `&Rc`, it will coerce via this rule into a `&String`, which then coerces to a `&str` in the same way. So if a function takes a `&str` parameter, you can pass in a `&Rc` directly, with all coercions handled automatically via the `Deref` trait.
+
+The most common sorts of deref coercions are:
+
+- `&Rc` to `&T`
+- `&Box` to `&T`
+- `&Arc` to `&T`
+- `&Vec` to `&[T]`
+- `&String` to `&str`
+
+
+
+Lifetimes are Rust's answer to the question of memory safety. They allow Rust to ensure memory safety without the performance costs of garbage collection. They are based on a variety of academic work, which can be found in the [Rust book](https://doc.rust-lang.org/stable/book/academic-research.html#type-system).
+
+
+
+The `'a` syntax comes from the ML family of programming languages, where `'a` is used to indicate a generic type parameter. For Rust, the syntax had to be something that was unambiguous, noticeable, and fit nicely in a type declaration right alongside traits and references. Alternative syntaxes have been discussed, but no alternative syntax has been demonstrated to be clearly better.
+
+
+
+You need to ensure that the borrowed item will outlive the function. This can be done by binding the output lifetime to some input lifetime like so:
+
+```rust
+type Pool = TypedArena;
+
+// (the lifetime below is only written explicitly for
+// expository purposes; it can be omitted via the
+// elision rules described in a later FAQ entry)
+fn create_borrowed<'a>(pool: &'a Pool,
+ x: i32,
+ y: i32) -> &'a Thing {
+ pool.alloc(Thing { x: x, y: y })
+}
+```
+
+An alternative is to eliminate the references entirely by returning an owning type like [`String`][String]:
+
+```rust
+fn happy_birthday(name: &str, age: i64) -> String {
+ format!("Hello {}! You're {} years old!", name, age)
+}
+```
+
+This approach is simpler, but often results in unnecessary allocations.
+
+
+
+In fact, *all* reference types have a lifetime, but most of the time you do not have to write
+it explicitly. The rules are as follows:
+
+1. Within a function body, you never have to write a lifetime explicitly; the correct value
+ should always be inferred.
+2. Within a function *signature* (for example, in the types of its
+ arguments, or its return type), you *may* have to write a lifetime
+ explicitly. Lifetimes there use a simple defaulting scheme called
+ ["lifetime elision"](https://doc.rust-lang.org/book/lifetimes.html#lifetime-elision),
+ which consists of the following three rules:
+
+ - Each elided lifetime in a function’s arguments becomes a distinct lifetime parameter.
+ - If there is exactly one input lifetime, elided or not, that
+ lifetime is assigned to all elided lifetimes in the return values
+ of that function.
+ - If there are multiple input lifetimes, but one of them is &self
+ or &mut self, the lifetime of self is assigned to all elided
+ output lifetimes.
+3. Finally, in a `struct` or `enum` definition, all lifetimes must be explicitly declared.
+
+If these rules result in compilation errors, the Rust compiler will provide an error message indicating the error caused, and suggesting a potential solution based on which step of the inference process caused the error.
+
+
+
+The only way to construct a value of type `&Foo` or `&mut Foo` is to specify an existing value of type `Foo` that the reference points to. The reference "borrows" the original value for a given region of code (the lifetime of the reference), and the value being borrowed from cannot be moved or destroyed for the duration of the borrow.
+
+
+
+You can do that with the [`Option`][Option] type, which can either be `Some(T)` or `None`. `Some(T)` indicates that a value of type `T` is contained within, while `None` indicates the absence of a value.
+
+
+
+Monomorphisation specializes each use of a generic function (or structure) with specific instance,
+based on the parameter types of calls to that function (or uses of the structure).
+
+During monomorphisisation a new copy of the generic function is translated for each unique set of types the function is instantiated with. This is the same strategy used by C++. It results in fast code that is specialized for every call-site and statically dispatched, with the tradeoff that functions instantiated with many different types can cause "code bloat", where multiple function instances result in larger binaries than would be created with other translation strategies.
+
+Functions that accept [trait objects](http://doc.rust-lang.org/book/trait-objects.html) instead of type parameters do not undergo monomorphisation. Instead, methods on the trait objects are dispatched dynamically at runtime.
+
+
+
+Functions and closures are operationally equivalent, but have different runtime representations due to their differing implementations.
+
+Functions are a built-in primitive of the language, while closures are essentially syntactic sugar for one of three traits: [`Fn`][Fn], [`FnMut`][FnMut], and [`FnOnce`][FnOnce]. When you make a closure, the Rust compiler automatically creates a struct implementing the appropriate trait of those three and containing the captured environment variables as members, and makes it so the struct can be called as a function. Bare functions can not capture an environment.
+
+The big difference between these traits is how they take the `self` parameter. [`Fn`][Fn] takes `&self`, [`FnMut`][FnMut] takes `&mut self`, and [`FnOnce`][FnOnce] takes `self`.
+
+Even if a closure does not capture any environment variables, it is represeted at runtime as two pointers, the same as any other closure.
+
+
+
+Higher-kinded types are types with unfilled parameters. Type constructors, like [`Vec`][Vec], [`Result`][Result], and [`HashMap`][HashMap] are all examples of higher-kinded types: each requires some additional type parameters in order to actually denote a specific type, like `Vec`. Support for higher-kinded types means these "incomplete" types may be used anywhere "complete" types can be used, including as generics for functions.
+
+Any complete type, like [`i32`][i32], [`bool`][bool], or [`char`][char] is of kind `*`. A type with one parameter, like [`Vec`][Vec] is of kind `* -> *`, meaning that [`Vec`][Vec] takes in a complete type like [`i32`][i32] and returns a complete type `Vec`. A type which three parameters, like [`HashMap`][HashMap] is of kind `* -> * -> * -> *`, and takes in three complete types (like [`i32`][i32], [`String`][String], and [`RandomState`][RandomState]) to produce a new complete type `HashMap`.
+
+In addition to these examples, type constructors can take *lifetime* arguments, which we'll denote as `Lt`. For example, `slice::Iter` has kind `Lt -> * -> *`, because it must be instantiated like `Iter<'a, u32>`.
+
+The lack of support for higher-kinded types makes it difficult to write certain kinds of generic code. It's particularly problematic for abstracting over concepts like iterators, since iterators are often parameterized over a lifetime at least. That in turn has prevented the creation of traits abstracting over Rust's collections.
+
+Another common example is concepts like functors or monads, both of which are type constructors, rather than single types.
+
+Rust doesn't currently have support for higher-kinded types because it hasn't been a priority compared to other improvements we want to make. Since the design is a major, cross-cutting change, we also want to approach it carefully. But there's no inherent reason for the current lack of support.
+
+
+
+These are called [associated types](https://doc.rust-lang.org/stable/book/associated-types.html), and they allow for the expression of trait bounds that can't be expressed with a `where` clause. For example, a generic bound `X: Bar` means "`X` must implement the trait `Bar`, and in that implementation of `Bar`, `X` must choose `Foo` for `Bar`'s associated type, `T`." Examples of where such a constraint cannot be expressed via a `where` clause include trait objects like `Box>`.
+
+Associated types exist because generics often involve families of types, where one type determines all of the others in a family. For example, a trait for graphs might have as its `Self` type the graph itself, and have associated types for nodes and for edges. Each graph type uniquely determines the associated types. Using associated types makes it much more concise to work with these families of types, and also provides better type inference in many cases.
+
+
+
+There are some types in Rust whose values are only partially ordered, or have only partial equality. Partial ordering means that there may be values of the given type that are neither less than nor greater than each other. Partial equality means that there may be values of the given type that are not equal to themselves.
+
+Floating point types ([`f32`][f32] and [`f64`][f64]) are good examples of each. Any floating point type may have the value `NaN` (meaning "not a number"). `NaN` is not equal to itself (`NaN == Nan` is false), and not less than or greater than any other floating point value. As such, both [`f32`][f32] and [`f64`][f64] implement [`PartialOrd`][PartialOrd] and [`PartialEq`][PartialEq] but not [`Ord`][Ord] and not [`Eq`][Eq].
+
+As explained in [the earlier question on floats](#why-cant-i-compare-floats), these distinctions are important because some collections rely on total orderings/equality in order to give correct results.
+
+
+
+Using the [`read_to_string()`][read__read_to_string] method, which is defined on the [`Read`][Read] trait in [`std::io`][std-io].
+
+```rust
+fn read_file(path: &str) -> Result {
+ let mut f = try!(File::open(path));
+ let mut s = String::new();
+ try!(f.read_to_string(&mut s)); // `s` contains the contents of "foo.txt"
+ s
+}
+
+fn main() {
+ match read_file("foo.txt") {
+ Ok(_) => println!("Got file contents!"),
+ Err(err) => println!("Getting file contents failed with error: {}", err)
+ };
+}
+```
+
+
+
+The [`File`][File] type implements the [`Read`][Read] trait, which has a variety of functions for reading and writing data, including [`read()`][read__read], [`read_to_end()`][read__read_to_end], [`bytes()`][read__bytes], [`chars()`][read__chars], and [`take()`][read__take]. Each of these functions reads a certain amount of input from a given file. [`read()`][read__read] reads as much input as the underlying system will provide in a single call. [`read_to_end()`][read__read_to_end] reads the entire buffer into a vector, allocating as much space as is needed. [`bytes()`][read__bytes] and [`chars()`][read__chars] allow you to iterate over the bytes and characters of the file, respectively. Finally, [`take()`][read__take] allows you to read up to an arbitrary number of bytes from the file. Collectively, these should allow you to efficiently read in any data you need.
+
+For buffered reads, use the [`BufReader`][BufReader] struct, which helps to reduce the number of system calls when reading.
+
+
+
+The easiest way is to use [`Args`][Args], which provides an iterator over the input arguments.
+
+If you're looking for something more powerful, there are a [number of options on crates.io](https://crates.io/keywords/argument).
+
+
+
+Exceptions complicate understanding of control-flow, they express validity/invalidity outside of the type system, and they interoperate poorly with multithreaded code (a major focus of Rust).
+
+Rust prefers a type-based approach to error handling, which is [covered at length in the book](https://doc.rust-lang.org/stable/book/error-handling.html). This fits more nicely with Rust's control flow, concurrency, and everything else.
+
+
+
+`unwrap()` is a function that extracts the value inside an [`Option`][Option] or [`Result`][Result] and panics if no value is present.
+
+`unwrap()` shouldn't be your default way to handle errors you expect to arise, such as incorrect user input. In production code, it should be treated like an assertion that the value is non-empty, which will crash the program if violated.
+
+It's also useful for quick prototypes where you don't want to handle an error yet, or blog posts where error handling would distract from the main point.
+
+
+
+It's probably an issue with the function's return type. The [`try!`][TryMacro] macro either extracts the value from a [`Result`][Result], or returns early with the error [`Result`][Result] is carrying. This means that [`try`][TryMacro] only works for functions that return [`Result`][Result] themselves, where the `Err`-constructed type implements `From::from(err)`. In particular, this means that the [`try!`][TryMacro] macro cannot work inside the `main` function.
+
+
+
+If you're looking for a way to avoid handling [`Result`s][Result] in other people's code, there's always [`unwrap()`][unwrap], but it's probably not what you want. [`Result`][Result] is an indicator that some computation may or may not complete successfully. Requiring you to handle these failures explicitly is one of the ways that Rust encourages robustness. Rust provides tools like the [`try!` macro][TryMacro] to make handling failures ergonomic.
+
+If you really don't want to handle an error, use [`unwrap()`][unwrap], but know that doing so means that the code panic on failure, which usually results in a shutting down the process.
+
+
+
+Mutation is safe if it's synchronized. Mutating a static [`Mutex`][Mutex] (lazily initialized via the [lazy-static](https://crates.io/crates/lazy_static/) crate) does not require an `unsafe` block, nor does mutating a static [`AtomicUsize`][AtomicUsize] (which can be initialized without lazy_static).
+
+More generally, if a type implements [`Sync`][Sync] and does not implement [`Drop`][Drop], it [can be used in a `static`](https://doc.rust-lang.org/book/const-and-static.html#static).
+
+
+
+Not currently. Rust macros are ["hygienic macros"](https://en.wikipedia.org/wiki/Hygienic_macro), which intentionally avoid capturing or creating identifiers that may cause unexpected collisions with other identifiers. Their capabilities are significantly different than the style of macros commonly associated with the C preprocessor. Macro invocations can only appear in places where they are explicitly supported: items, method declarations, statements, expressions, and patterns. Here, "method declarations" means a blank space where a method can be put. They can't be used to complete a partial method declaration. By the same logic, they can't be used to complete a partial variable declaration.
+
+
+
+Rust programs can be debugged using [gdb](http://sourceware.org/gdb/current/onlinedocs/gdb/) or [lldb](http://lldb.llvm.org/tutorial.html), the same as C and C++. In fact, every Rust installation comes with one or both of rust-gdb and rust-lldb (depending on platform support). These are wrappers over gdb and lldb with Rust pretty-printing enabled.
+
+
+
+This error is usually caused by [`unwrap()`ing][unwrap] a `None` or `Err` in client code. Enabling backtraces by setting the environment variable `RUST_BACKTRACE=1` helps with getting more information. Compiling in debug mode (the default for `cargo build`) is also helpful. Using a debugger like the provided `rust-gdb` or `rust-lldb` is also helpful.
+
+
+
+There are a number of options for development environment with Rust, all of which are detailed on the official [IDE support page](https://www.rust-lang.org/ides.html).
+
+
+
+`rustfmt` is [right here](https://github.com/rust-lang-nursery/rustfmt), and is being actively developed to make reading Rust code as easy and predictable as possible.
+
+
+
+If you want to clone an existing slice safely, you can use [`clone_from_slice`][clone_from_slice]. This function is currently unstable, but [should be stabilized soon](https://internals.rust-lang.org/t/stabilizing-basic-functions-on-arrays-and-slices/2868).
+
+To copy potentially overlapping bytes, use [`copy`][copy]. To copy nonoverlapping bytes, use [`cpy_nonoverlapping`][copy_nonoverlapping]. Both of these functions are `unsafe`, as both can be used to subvert the language's safety guarantees. Take care when using them.
+
+
+
+Absolutely. Rust programs can be set to not load the standard library using the `#![no_std]` attribute. With this attribute set, you can continue to use the Rust core library, which is nothing but the platform-agnostic primitives. As such, it doesn't include IO, concurrency, heap allocation, etc.
+
+
+
+Not by default. In the general case, `enum` and `struct` layouts are undefined. This allows the compiler to potentially do optimizations like re-using padding for the discriminant, compacting variants of nested `enum`s, reordering fields to remove padding, etc. `enums` which carry no data ("C-like") are eligible to have a defined representation. Such `enums` are easily distinguished in that they are simply a list of names that carry no data:
+
+```rust
+enum CLike {
+ A,
+ B = 32,
+ C = 34,
+ D
+}
+```
+
+The `#[repr(C)]` attribute can be applied to such `enums` to give them the same representation they would have in equivalent C code. This allows using Rust `enum`s in FFI code where C `enum`s are also used, for most use cases. The attribute can also be applied to `struct`s to get the same layout as a C `struct` would.
+
+
+
+Platform-specific behavior can be expressed using [conditional compilation attributes](https://doc.rust-lang.org/reference.html#conditional-compilation) such as `target_os`, `target_family`, `target_endian`, etc.
+
+
+
+Yes it can! There are already examples of using Rust for both [Android](https://github.com/tomaka/android-rs-glue) and [iOS](https://www.bignerdranch.com/blog/building-an-ios-app-in-rust-part-1/). It does require a bit of work to set up, but Rust functions fine on both platforms.
+
+
+
+Cross compilation is possible in Rust, but it requires [a bit of work](https://github.com/japaric/ruststrap/blob/master/1-how-to-cross-compile.md) to set up. Every Rust compiler is a cross-compiler, but libraries need to be cross-compiled for the target platform.
+
+Rust does distribute [copies of the standard library](http://static.rust-lang.org/dist/) for each of the supported platforms, which are contained in the `rust-std-*` files for each of the build directories found on the distribution page, but there are not yet automated ways to install them.
+
+
+
+- A crate is a compilation unit, which is the smallest amount of code that the Rust compiler can operate on.
+- A module is a (possibly nested) unit of code organization inside a crate.
+- A crate contains an implicit, un-named top-level module.
+- Recursive definitions can span modules, but not crates.
+- Using another crate binds the root of its namespace into the user's namespace.
+
+
+
+There are a number of possible answers, but a common mistake is not realizing that `use` declarations are relative to the crate root. Try rewriting your declarations to use the paths they would use if defined in the root file of your project and see if that fixes the problem.
+
+There are also `self` and `super`, which disambiguate `use` paths as being relative to the current module or parent module, respectively.
+
+For complete information on `use`ing libraries, read the Rust book's chapter ["Crates and Modules"](https://doc.rust-lang.org/stable/book/crates-and-modules.html).
+
+
+
+There are two ways to declare modules in Rust, inline or in another file. Here is an example of each:
+
+```rust
+// In main.rs
+mod hello {
+ pub fn f() {
+ println!("hello!");
+ }
+}
+
+fn main() {
+ hello::f();
+}
+```
+
+```rust
+// In main.rs
+mod hello;
+
+fn main() {
+ hello::f();
+}
+
+// In hello.rs
+pub fn f() {
+ println!("hello!");
+}
+```
+
+In the first example, the module is defined in the same file it's used. In the second example, the module declaration in the main file tells the compiler to look for either `hello.rs` or `hello/mod.rs`, and to load that file.
+
+Note the difference between `mod` and `use`: `mod` declares that a module exists, whereas `use` references a module declared elsewhere, bringing its contents into scope within the current module.
+
+
+
+As explained on the Cargo [configuration documentation](http://doc.crates.io/config.html), you can set Cargo to use a proxy by setting the "proxy" variable under `[http]` in the configuration file.
+
+
+
+For methods defined on a trait, you have to explicitly import the trait declaration. This means it's not enough to import a module where a struct implements the trait, you must also import the trait itself.
+
+
+
+It probably could, but you also don't want it to. While in many cases it is likely that the compiler could determine the correct module to import by simply looking for where a given identifier is defined, this may not be the case in general. Any decision rule in `rustc` for choosing between competing options would likely cause surprise and confusion in some cases, and Rust prefers to be explicit about where names are coming from.
+
+For example, the compiler could say that in the case of competing identifier definitions the definition from the earliest imported module is chosen. So if both module `foo` and module `bar` define the identifier `baz`, but `foo` is the first registered module, the compiler would insert `use foo::baz;`.
+
+```rust
+mod foo;
+mod bar;
+
+// use foo::baz // to be inserted by the compiler.
+
+fn main() {
+ baz();
+}
+```
+
+If you know this is going to happen, perhaps it saves a small number of keystrokes, but it also greatly increases the possibility for surprising error messages when you actually meant for `baz()` to be `bar::baz()`, and it decreases the readability of the code by making the meaning of a function call dependent on module declaration. These are not tradeoffs we are willing to make.
+
+However, in the future, an IDE could help manage declarations, which gives you the best of both worlds: machine assistance for pulling in names, but explicit declarations about where those names are coming from.
+
+
+
+
+
+Import dynamic libraries in Rust with [libloading](https://crates.io/crates/libloading), which provides a cross-platform system for dynamic linking.
+
+
+
+Quoting the [official explanation](https://internals.rust-lang.org/t/crates-io-package-policies/1041) of [http://crates.io](http://crates.io)'s design:
+
+> In the first month with crates.io, a number of people have asked us about the possibility of introducing [namespaced packages](https://github.com/rust-lang/crates.io/issues/58).
+>
+> While namespaced packages allow multiple authors to use a single, generic name, they add complexity to how packages are referenced in Rust code and in human communication about packages. At first glance, they allow multiple authors to claim names like `http`, but that simply means that people will need to refer to those packages as `wycats' http` or `reem's http`, offering little benefit over package names like `wycats-http` or `reem-http`.
+>
+> When we looked at package ecosystems without namespacing, we found that people tended to go with more creative names (like `nokogiri` instead of "tenderlove's libxml2"). These creative names tend to be short and memorable, in part because of the lack of any hierarchy. They make it easier to communicate concisely and unambiguously about packages. They create exciting brands. And we've seen the success of several 10,000+ package ecosystems like NPM and RubyGems whose communities are prospering within a single namespace.
+>
+> In short, we don't think the Cargo ecosystem would be better off if Piston chose a name like `bvssvni/game-engine` (allowing other users to choose `wycats/game-engine`) instead of simply `piston`.
+>
+> Because namespaces are strictly more complicated in a number of ways,and because they can be added compatibly in the future should they become necessary, we're going to stick with a single shared namespace.
+
+
+
+The standard library does not include an implementation of HTTP, so you will want to use an external crate. [Hyper](https://github.com/hyperium/hyper) is the most popular, but there are [a number of others as well](https://crates.io/keywords/http).
+
+
+
+There are a variety of ways to write GUI applications in Rust. Just check out [this list of GUI frameworks](https://github.com/kud1ing/awesome-rust#gui).
+
+
+
+[Serde](https://github.com/serde-rs/serde) is the recommended library for serialization and deserialization of Rust data to and from a number of different formats.
+
+
+
+[Glium](https://github.com/tomaka/glium) is the major library for OpenGL programming in Rust. [GLFW](https://github.com/bjz/glfw-rs) is also a solid option.
+
+
+
+Yes you can! The major game programming library for Rust is [Piston](http://www.piston.rs/), and there's both a [subreddit for game programming in Rust](https://www.reddit.com/r/rust_gamedev/) and an IRC channel (`#rust-gamedev` on [Mozilla IRC](https://wiki.mozilla.org/IRC)) as well.
+
+
+
+It is multi-paradigm. Many things you can do in OO languages you can do in Rust, but not everything, and not always using the same abstraction you're accustomed to.
+
+
+
+That depends. There _are_ ways of translating object-oriented concepts like [multiple inheritance](https://www.reddit.com/r/rust/comments/2sryuw/ideaquestion_about_multiple_inheritence/) to Rust, but as Rust is not object-oriented the result of the translation may look substantially different from its appearance in an OO language.
+
+
+
+The easiest way is to use the [`Option`][Option] type in whatever function you're using to construct instances of the struct (usually `new()`). Another way is to use the [builder pattern](https://aturon.github.io/ownership/builders.html), where only certain functions instantiating member variables must be called before the construction of the built type.
+
+
+
+Globals in Rust can be done using `const` declarations for compile-time computed global constants, while `static` can be used for mutable globals. Note that modifying a `static mut` variable requires the use of `unsafe`, as it allows for data races, one of the things guaranteed not to happen in safe Rust. One important distinction between `const` and `static` values is that you can take references to `static` values, but not references to `const` values, which don't have a specified memory location. For more information on `const` vs. `static`, read [the Rust book](https://doc.rust-lang.org/book/const-and-static.html).
+
+
+
+Rust currently has limited support for compile time constants. You can define primitives using `const` declarations (similar to `static`, but immutable and without a specified location in memory) as well as define `const` functions and inherent methods.
+
+To define procedural constants that can't be defined via these mechanisms, use the [`lazy-static`](https://github.com/rust-lang-nursery/lazy-static.rs) crate, which emulates compile-time evaluation by automatically evaluating the constant at first use.
+
+
+
+Rust has no concept of "life before `main`". The closest you'll see can be done through the [`lazy-static`](https://github.com/Kimundi/lazy-static.rs) crate, which simulates a "before main" by lazily initializing static variables at their first usage.
+
+
+
+
+
+No. Globals cannot have a non-constant-expression constructor and cannot have a destructor at all. Static constructors are undesirable because portably ensuring a static initialization order is difficult. Life before main is often considered a misfeature, so Rust does not allow it.
+
+See the [C++ FQA](http://yosefk.com/c++fqa/ctors.html#fqa-10.12) about the "static initialization order fiasco", and [Eric Lippert's blog](http://ericlippert.com/2013/02/06/static-constructors-part-one/) for the challenges in C#, which also has this feature.
+
+You can approximate non-constant-expression globals with the [lazy-static](https://crates.io/crates/lazy_static/) crate.
+
+
+
+Rust does not have `static` fields as shown in the code snippet above. Instead, you can declare a `static` variable in a given module, which is kept private to that module.
+
+
+
+Converting a C-style enum to an integer can be done with an `as` expression, like `e as i64` (where `e` is some enum).
+
+Converting in the other direction can be done with a `match` statement, which maps different numeric values to different potential values for the enum.
+
+
+
+Committing to an ABI is a big decision that can limit potentially advantageous language changes in the future. Given that Rust only hit 1.0 in May of 2015, it is still too early to make a commitment as big as a stable ABI. This does not mean that one won't happen in the future, though. (Though C++ has managed to go for many years without specifying a stable ABI.)
+
+The `extern` keyword allows Rust to use specific ABI's, such as the well-defined C ABI, for interop with other languages.
+
+
+
+Yes. The Rust code has to be exposed via an `extern` declaration, which makes it C-ABI compatible. Such a function can be passed to C code as a function pointer or, if given the `#[no_mangle]` attribute to disable symbol mangling, can be called directly from C code.
+
+
+
+Modern C++ includes many features that make writing safe and correct code less error-prone, but it's not perfect, and it's still easy to introduce unsafety. This is something the C++ core developers are working to overcome, but C++ is limited by a long history that predates a lot of the ideas they are now trying to implement.
+
+Rust was designed from day one to be a safe systems programming language, which means it's not limited by historic design decisions that make getting safety right in C++ so complicated. In C++, safety is achieved by careful personal discipline, and is very easy to get wrong. In Rust, safety is the default. It gives you the ability to work in a team that includes people less perfect than you are, without having to spend your time double-checking their code for safety bugs.
+
+
+
+Rust doesn't currently have an exact equivalent to template specialization, but it is [being worked on](https://github.com/rust-lang/rfcs/pull/1210) and will hopefully be added soon. However, similar effects can be achieved via [associated types](https://doc.rust-lang.org/stable/book/associated-types.html).
+
+
+
+The underlying concepts are similar, but the two systems work very
+differently in practice. In both systems, "moving" a value is a way to
+transfer ownership of its underlying resources. For example, moving a
+string would transfer the string's buffer rather than copying it.
+
+In Rust, ownership transfer is the default behavior. For example, if I
+write a function that takes a `String` as argument, this function will
+take ownership of the `String` value supplied by its caller:
+
+```rust
+fn process(s: String) { }
+
+fn caller() {
+ let s = String::from("Hello, world!");
+ process(s); // Transfers ownership of `s` to `process`
+ process(s); // Error! ownership already transferred.
+}
+```
+
+As you can see in the snippet above, in the function `caller`, the
+first call to `process` transfers ownership of the variable `s`. The
+compiler tracks ownership, so the second call to `process` results in
+an error, because it is illegal to give away ownership of the same
+value twice. Rust will also prevent you from moving a value if there
+is an outstanding reference into that value.
+
+C++ takes a different approach. In C++, the default is to copy a value
+(to invoke the copy constructor, more specifically). However, callees
+can declare their arguments using an "rvalue reference", like
+`string&&`, to indicate that they will take ownership of some of the
+resources owned by that argument (in this case, the string's internal
+buffer). The caller then must either pass a temporary expression or
+make an explicit move using `std::move`. The rough equivalent to the
+function `process` above, then, would be:
+
+```
+void process(string&& s) { }
+
+void caller() {
+ string s("Hello, world!");
+ process(std::move(s));
+ process(std::move(s));
+}
+```
+
+C++ compilers are not obligated to track moves. For example, the code
+above compiles without a warning or error, at least using the default
+settings on clang. Moreover, in C++ ownership of the string `s` itself
+(if not its internal buffer) remains with `caller`, and so the
+destructor for `s` will run when `caller` returns, even though it has
+been moved (in Rust, in contrast, moved values are dropped only by
+their new owners).
+
+
+
+Rust and C++ can interoperate through C. Both Rust and C++ provide a [foreign function interface](https://doc.rust-lang.org/book/ffi.html) for C, and can use that to communicate between each other. If writing C bindings is too tedious, you can always use [rust-bindgen](https://github.com/crabtw/rust-bindgen) to help automatically generate workable C bindings.
+
+
+
+No. Functions serve the same purpose as constructors without adding language complexity. The usual name for the constructor-equivalent function in Rust is `new()`, although this is just a convention rather than a language rule. The `new()` function in fact is just like any other function. An example of it looks like so:
+
+```rust
+struct Foo {
+ a: i32,
+ b: f64,
+ c: bool,
+}
+
+impl Foo {
+ fn new() -> Foo {
+ Foo {
+ a: 0,
+ b: 0.0,
+ c: false,
+ }
+ }
+}
+```
+
+
+
+Not exactly. Types which implement `Copy` will do a standard C-like "shallow copy" with no extra work (similar to "plain old data" in C++). It is impossible to implement `Copy` types that require custom copy behavior. Instead, in Rust "copy constructors" are created by implementing the `Clone` trait, and explicitly calling the `clone` method. Making user-defined copy operators explicit surfaces the underlying complexity, making it easier for the developer to identify potentially expensive operations.
+
+
+
+No. Values of all types are moved via `memcpy`. This makes writing generic unsafe code much simpler since assignment, passing and returning are known to never have a side effect like unwinding.
+
+
+
+Rust and Go have substantially different design goals. The following differences are not the only ones (which are too numerous to list), but are a few of the more important ones:
+
+- Rust is lower level than Go. For example, Rust does not require a garbage collector, whereas Go does. In general, Rust affords a level of control that is comparable to C or C++.
+- Rust's focus is on ensuring safety and efficiency while also providing high-level affordances, while Go's is on being a small, simple language which compiles quickly and can work nicely with a variety of tools.
+- Rust has strong support for generics, which Go does not.
+- Rust has strong influences from the world of functional programming, including a type system which draws from Haskell's typeclasses. Go has a simpler type system, using interfaces for basic generic programming.
+
+
+
+Rust traits are similar to Haskell typeclasses, but are currently not as powerful, as Rust cannot express higher-kinded types. Rust's associated types are equivalent to Haskell type families.
+
+Some specific difference between Haskell typeclasses and Rust traits include:
+
+- Rust traits have an implicit first parameter called `Self`. `trait Bar` in Rust corresponds to `class Bar self` in Haskell, and `trait Bar` in Rust corresponds to `class Boo foo self` in Haskell.
+- "Supertraits" or "superclass constraints" in Rust are written `trait Sub: Super`, compared to `class Super self => Sub self` in Haskell.
+- Rust forbids orphan instances, resulting in different coherence rules in Rust compared to Haskell.
+- Rust's `impl` resolution considers the relevant `where` clauses and trait bounds when deciding whether two `impl`s overlap, or choosing between potential `impl`s. Haskell only considers the constraints in the `instance` declaration, disregarding any constraints provided elsewhere.
+- A subset of Rust's traits (the ["object safe"](https://github.com/rust-lang/rfcs/blob/master/text/0255-object-safety.md) ones) can be used for dynamic dispatch via trait objects. The same feature is available in Haskell via GHC's `ExistentialQuantification`.
+
+
+
+The Rust language has been around for a number of years, and only reached version 1.0 in May of 2015. In the time before then the language changed significantly, and a number of StackOverflow answers were given at the time of older versions of the language.
+
+Over time more and more answers will be offered for the current version, thus improving this issue as the proportion of out-of-date answers is reduced.
+
+
+
+You can report issues in the Rust documentation on the Rust compiler [issue tracker](https://github.com/rust-lang/rust/issues). Make sure to read the [contributing guidelines](https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#writing-documentation) first.
+
+
+
+ 
+