% The Rust Guide
-<div style="border: 2px solid red; padding:5px;">
-This guide is a work in progress. Until it is ready, we highly recommend that
-you read the <a href="tutorial.html">Tutorial</a> instead. This work-in-progress Guide is being
-displayed here in line with Rust's open development policy. Please open any
-issues you find as usual.
-</div>
-
-# Welcome!
-
Hey there! Welcome to the Rust guide. This is the place to be if you'd like to
learn how to program in Rust. Rust is a systems programming language with a
focus on "high-level, bare-metal programming": the lowest level control a
(If you're concerned about `curl | sudo sh`, please keep reading. Disclaimer
below.)
-If you're on Windows, please [download this .exe and run
-it](https://static.rust-lang.org/dist/rust-nightly-install.exe).
+If you're on Windows, please download either the [32-bit
+installer](https://static.rust-lang.org/dist/rust-nightly-i686-w64-mingw32.exe)
+or the [64-bit
+installer](https://static.rust-lang.org/dist/rust-nightly-x86_64-w64-mingw32.exe)
+and run it.
If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay.
Not every programming language is great for everyone. Just pass an argument to
to make a `projects` directory in my home directory, and keep all my projects
there. Rust does not care where your code lives.
-This actually leads to one other concern we should address: this tutorial will
+This actually leads to one other concern we should address: this guide will
assume that you have basic familiarity with the command line. Rust does not
require that you know a whole ton about the command line, but until the
language is in a more finished state, IDE support is spotty. Rust makes no
Now that you've got your file open, type this in:
-```
+```{rust}
fn main() {
println!("Hello, world!");
}
```{bash}
$ rustc main.rs
-$ ./hello_world # or hello_world.exe on Windows
+$ ./main # or main.exe on Windows
Hello, world!
```
Success! Let's go over what just happened in detail.
-```
+```{rust}
fn main() {
}
```
-These two lines define a **function** in Rust. The `main` function is special:
+These lines define a **function** in Rust. The `main` function is special:
it's the beginning of every Rust program. The first line says "I'm declaring a
function named `main`, which takes no arguments and returns nothing." If there
were arguments, they would go inside the parentheses (`(` and `)`), and because
Next up is this line:
-```
+```{rust}
println!("Hello, world!");
```
This line does all of the work in our little program. There are a number of
details that are important here. The first is that it's indented with four
spaces, not tabs. Please configure your editor of choice to insert four spaces
-with the tab key. We provide some sample configurations for various editors
-[here](https://github.com/rust-lang/rust/tree/master/src/etc).
+with the tab key. We provide some [sample configurations for various
+editors](https://github.com/rust-lang/rust/tree/master/src/etc).
The second point is the `println!()` part. This is calling a Rust **macro**,
which is how metaprogramming is done in Rust. If it were a function instead, it
oriented** language, which means that most things are expressions. The `;` is
used to indicate that this expression is over, and the next one is ready to
begin. Most lines of Rust code end with a `;`. We will cover this in-depth
-later in the tutorial.
+later in the guide.
Finally, actually **compiling** and **running** our program. We can compile
with our compiler, `rustc`, by passing it the name of our source file:
```
There are now two files: our source code, with the `.rs` extension, and the
-executable (`hello_world.exe` on Windows, `hello_world` everywhere else)
+executable (`main.exe` on Windows, `main` everywhere else)
```{bash}
-$ ./hello_world # or hello_world.exe on Windows
+$ ./main # or main.exe on Windows
```
This prints out our `Hello, world!` text to our terminal.
Rust is a statically typed language, which means that we specify our types up
front. So why does our first example compile? Well, Rust has this thing called
-"[Hindley-Milner type
-inference](http://en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type_system)",
-named after some really smart type theorists. If you clicked that link, don't
-be scared: what this means for you is that Rust will attempt to infer the types
-in your program, and it's pretty good at it. If it can infer the type, Rust
+"type inference." If it can figure out what the type of something is, Rust
doesn't require you to actually type it out.
-We can add the type if we want to. Types come after a colon (`:`):
+We can add the type if we want to, though. Types come after a colon (`:`):
```{rust}
let x: int = 5;
If you want something to happen in the `false` case, use an `else`:
-```
+```{rust}
let x = 5i;
if x == 5i {
This is all pretty standard. However, you can also do this:
-```
+
+```{rust}
let x = 5i;
let y = if x == 5i {
Which we can (and probably should) write like this:
-```
+```{rust}
let x = 5i;
let y = if x == 5i { 10i } else { 15i };
What is this exception that makes us say 'almost?' You saw it already, in this
code:
-```
+```{rust}
let x = 5i;
let y: int = if x == 5i { 10i } else { 15i };
The values in structs are immutable, like other bindings in Rust. However, you
can use `mut` to make them mutable:
-```rust
+```{rust}
struct Point {
x: int,
y: int,
don't:
-```
+```{rust}
struct Color(int, int, int);
struct Point(int, int, int);
```
It is almost always better to use a struct than a tuple struct. We would write
`Color` and `Point` like this instead:
-```rust
+```{rust}
struct Color {
red: int,
blue: int,
tuple struct with only one element. We call this a 'newtype,' because it lets
you create a new type that's a synonym for another one:
-```
+```{rust}
struct Inches(int);
let length = Inches(10);
Rust has a keyword, `match`, that allows you to replace complicated `if`/`else`
groupings with something more powerful. Check it out:
-```rust
+```{rust}
let x = 5i;
match x {
The `for` loop is used to loop a particular number of times. Rust's `for` loops
work a bit differently than in other systems languages, however. Rust's `for`
-loop doesn't look like this C `for` loop:
+loop doesn't look like this "C style" `for` loop:
-```{ignore,c}
+```{c}
for (x = 0; x < 10; x++) {
printf( "%d\n", x );
}
```
-It looks like this:
+Instead, it looks like this:
```{rust}
for x in range(0i, 10i) {
the iterator, and we loop another time. When there are no more values, the
`for` loop is over.
-In our example, the `range` function is a function, provided by Rust, that
-takes a start and an end position, and gives an iterator over those values. The
-upper bound is exclusive, though, so our loop will print `0` through `9`, not
-`10`.
+In our example, `range` is a function that takes a start and an end position,
+and gives an iterator over those values. The upper bound is exclusive, though,
+so our loop will print `0` through `9`, not `10`.
Rust does not have the "C style" `for` loop on purpose. Manually controlling
each element of the loop is complicated and error prone, even for experienced C
-developers.
+developers.
We'll talk more about `for` when we cover **iterator**s, later in the Guide.
`continue` is similar, but instead of ending the loop, goes to the next
iteration: This will only print the odd numbers:
-```
+```{rust}
for x in range(0i, 10i) {
if x % 2 == 0 { continue; }
and then prints it back out:
```{rust,ignore}
-use std::io;
-
fn main() {
println!("Type something!");
## Comparing guesses
-If you remember, earlier in the tutorial, we made a `cmp` function that compared
+If you remember, earlier in the guide, we made a `cmp` function that compared
two numbers. Let's add that in, along with a `match` statement to compare the
guess to the secret guess:
Here's how it works:
-```
+```{rust}
struct Circle {
x: f64,
y: f64,
You can also define methods that do not take a `self` parameter. Here's a
pattern that's very common in Rust code:
-```
+```{rust}
struct Circle {
x: f64,
y: f64,
know that we're safe.
There's another detail here that's not 100% clear because of how `println!`
-works. `num` is actually of type `&int`, that is, it's a reference to an `int`,
+works. `num` is actually of type `&int`. That is, it's a reference to an `int`,
not an `int` itself. `println!` handles the dereferencing for us, so we don't
see it. This code works fine too:
projects / rust.git / blobdiff