I took a shot at learning Go recently and I found its simplicity to be refreshing. Rust is a similar language from Mozilla which I’ve been interested in for a while now.

My main resources are the tutorial and manual, but there are many more. As usual, oftentimes some things will be directly from the source, with my commentary surrounding it. There is also a more basic Rust by Example which is similar to the go tour.

Types

There are no implicit type conversions. Instead, the as keyword is used to perform explicit type conversions. The type keyword can be used to create type aliases.

The Box<T> type represents a boxed value allocated on the heap. The Vec<T> type represents a growable vector. The String type represents a growable UTF-8 encoded buffer.

Nearly every statement in Rust is an expression that yields a value, but this can be suppressed by adding a trailing semicolon ;, which makes the result be unit ().

The Result<T, E> type is similar to Haskell’s Either, containing either Ok or Err. The try! macro makes it easier to work with Result, expanding to a match expression that returns the contained error or evaluates to the. This reminds me of the Either monad.

Types are categorized into kinds based on various properties of the components of the type.

• Send is for types that can be safely sent between tasks. Includes scalars, owning pointers, owned closures, and structural types containing only other owned types. All Send types are 'static
• Share for types that are thread-safe
• Copy is for types that consist of Plain Old Data. Includes scalars, immutable references, and structural types containing other Copy types
• 'static is for types that don’t contain any references except those with static lifetime
• Drop is for types that need to be cleaned up by a destructor. Only Send types can implement Drop
• Default is for types with destructors, closure environments, or other non-first-class types which aren’t copyable at all and are only accessible through pointers

Variables

Variables are immutable by default and are defined using the let keyword, though one can be made mutable by providing the mut keyword after let.

let x     = 3; // immutable
let mut y = 4; // mutable

Constants represent a value, not a memory address, and can be declared using the const keyword. Constants can be declared in any scope, can’t be shadowed, and are considered rvalues. Constants are essentially inlined wherever they are used, like #define constants in C.

const age: int = value;

Global variables represent a memory address and can be declared using the static keyword. Static variables can be created using the static keyword and always have a single address. If the static doesn’t contain an UnsafeCell then it may be placed in read-only memory.

static LANGUAGE: &'static str = "Rust";
static THRESHOLD: int = 10;

It’s also possible to define mutable statics, though using these is considered unsafe as it can introduce race conditions. Because of this, mutable static can only be read or written to within unsafe blocks, and can’t be placed in read-only memory.

static mut LEVELS: uint = 0;

unsafe fn bump_levels_unsafe1() -> uint {
  let ret = LEVELS;
  LEVELS += 1;
  return ret;
}

Modules

The content of all source code that the compiler directly had to compile in order to end up with a particular binary is collectively called a crate. A crate is a unit of independent compilation in Rust. Using an already compiled library in code doesn’t make it part of a crate.

There exists a hierarchy of modules where the root is referred to as crate root. Global paths begin with the root path ::, all other paths are local paths, similar to the distinction between absolute /-prefixed paths and relative paths in a POSIX file system.

Everything in Rust is private by default with a single exception. If an enumeration is declared public, then its variants are public as well by default, though this may be overridden with the priv keyword.

Visibility restrictions are only applicable at module boundaries, so that private items are available within the same module and its descendants. Descendants still have to bring the parent items into view using use, however—this simply means that they have permission view private items.

Source files and modules are not the same thing. The only file that’s relevant when compiling is the one that contains the body of the crate root. Declaring a module without a body prompts the compiler to look for a file named after that module or for a file named mod.rs in a folder named after that module, and use its contents as the module’s body.

The path attribute may be used to manually specify a module’s path.

#[path = "manual.rs"]
mod aliased;

mod plants;
mod animals {
  mod fish;
  mod mammals {
    mod humans;
  }
}

// looks for:

// src/manual.rs

// src/plants.rs
// src/plants/mod.rs

// src/animals/fish.rs
// src/animals/fish/mod.rs

// src/animals/mammals/humans.rs
// src/animals/mammals/humans/mod.rs

The use statement can be used to bring in a module’s contents into the current block by providing a global path without the :: prefix. It’s possible to prefix with super:: to start the path in the parent module, and self:: to start the path in the current module.

use super::some_parent_item;
use self::some_child_module::some_item;

Imported items are shadowed by local definitions. To make this fact more explicit, use statements must go before any declaration, including mod declarations. This looks awkward when importing items from a module that follows:

use farm::cow;

mod farm {
  pub fn cow() {
    println!("moo")
  }
}

fn main() {
  cow()
}

This is even more awkward when using a mod statement that looks in a separate file for the contents:

use b::foo;
mod b;

fn main() { foo(); }

These restrictions have been removed by RFC #385, so that it’s now possible to use any order:

mod b;
use b::foo;

It’s possible to import by wildcard or selectively, similar to Scala. It’s also possible to rename an imported item:

use farm::{chicken, cow};

#[feature(globs)]
use farm::*;

use farm::chicken as egg_layer;

It’s possible to make a module available through another module by using pub mod. This allows the exposed module’s public items to be accessible using path-notation.

// secondmod.rs
pub fn hi() { println!("hi"); };

// firstmod.rs
pub mod secondmod;

// main.rs
firstmod::secondmod::hi();

Likewise, it’s possible to re-export specific items to make them appear to be part of the module in which they’re exposed, using pub use.

// firstmod.rs
pub use secondmod::hi;
mod secondmod;

// main.rs
firstmod::hi();

It’s common to use existing libraries, which in rust are simply referred to as crates. The extern crate declaration is used to reference other crates, similar to extern in C.

Items imported via extern crate can be shadowed by local declarations and by items imported by use, so they must go before both. Crates declared in an extern crate declaration are looked for in the library search path, which can be expanded with the -L switch.

extern crate num;

use farm::dog;
use num::rational::Ratio;

mod farm {
  pub fn dog() { println!("woof") }
}

fn main() {
  farm::dog();
  let one_half = ::num::rational::Ratio::new(1, 2);
}

Crates can contain metadata used for the resultant libraries:

#![crate_name = "farm"];

#![desc = "Farm"]
#![license = "BSD"]
#![comment = "Farm library"]

// specify that it's a library
#![crate_type = "lib"];

This information can be used to select the crate from the extern crate declaration:

extern crate farm = "farm";

For example, here’s an example library, its compilation, and usage:

#[crate_name = "world"];
#[crate_type = "lib"];

pub fn explore() -> &'static str { "world" }

extern crate world;
fn main() {
  println!("hello {}", world::explore());
}

$ rustc world.rs     # compiles libworld-<HASH>-0.42.so
$ rustc main.rs -L . # include local dir in library search path
$ ./main
"hello world"

Many predefined items such as range and Option<T> come from the standard library’s prelude, similar to Haskell’s. The rust compiler automatically inserts the following into the crate root:

extern crate std;

// to prevent: in crate root
#[no_std];

As well as the following into every module body:

use std::prelude::*;

// to prevent: in any module
#[no_implicit_prelude];

Attributes can be used to specify conditional compilation of code, crate names, disabling or enabling compiler features, and so on. The cfg attribute can test for configuration values passed by the rust compiler either implicitly or explicitly with the --cfg flag.

// crate-wide attribute
#![crate_attribute]

// module-wide attribute
#[module_attribute]

#[cfg(target_os = "linux")]
fn on_linux() {
  println!("on linux")
}

#[cfg(not(target_os = "linux"))]
fn not_on_linux() {
  println!("not on linux")
}

Ownership

An object’s lifetime is determined by its owner, either a variable or a task-local garbage collector. Ownership is recursive so that mutability is inherited recursively and a destructor destroys the contained tree of owned objects. Variables are owners and destroy the contained object when they go out of scope.

struct Foo { x: int, y: box int }

{
  // `a` is owner of struct and its fields
  let a = Foo { x: 5, y: box 10 };
}
// `a` goes out of scope, destructor for y's `box int` is called

// `b` is mutable, so the objects it owns are also mutable
let mut b = Foo { x: 5, y: box 10 };
b.x = 10

Notice that a structure may contain a mutable reference, so that even if the structure is immutable, the pointed-to value can be mutated. Naturally, the reference itself can’t be changed since the structure is immutable.

struct S1 {
  b: int
}

struct S2<'a> {
  a: &'a mut S1
}

let mut s1 = S1 { b: 56 };
let s2 = S2 { a: &mut s1 };

s2.a.b = 45;    // legal
s2.a = &mut s1; // illegal

Boxes

Values are allocated on the stack by default, but they can also be boxed, i.e. allocated on the heap. Values are boxed with the box keyword and result in a value of type Box<T>. Box values can be dereferenced using the * operator, or they can be destructured by using the box keyword on the LHS.

enum List {
  Cons(u32, Box<List>),
  Nil
}

let list = Cons(1, box Cons(2, box Cons(3, box Nil)));

The list represents an owned tree of values.

It’s not necessary to worry about manually boxing large return values or arguments, they are essentially passed by reference if they are larger than the size of the machine’s register. To quote the tutorial:

A large value is returned via a hidden output parameter, and the decision on where to place the return value should be left to the caller

What this essentially means is that if for example function foo() returns BigStruct, the compiler will pass foo() a pointer to an uninitialized BigStruct in the local scope, something like:

let x: BigStruct; // uninitialized
foo(&x); // as if type: foo(_ret: &mut BigStruct)

This allows the caller to decide where to place the return value, for example:

fn foo() -> (u64, u64, u64, u64, u64, u64) {
  (5, 5, 5, 5, 5, 5)
}

// allocates result in a box and writes u64's directly to it
let x = box foo();

Managed Boxes

There are other ownership strategies that can be employed, such as task-local garbage collected and reference counted. Reference counted ownership ¹ is possible through std::rc::Rc:

use std::rc::Rc;

let x = Rc::new([1, 2, 3]);
let y = x.clone(); // a new owner
let z = x; // moves x into z

assert_eq!(*z.borrow(), [1, 2, 3]);

let mut a = Rc::new([1, 2]);
a = z; // variable is mutable, not its contents

Cells

Mutability can’t be inherited when shared ownership is involved, since the contained values may be multiply-aliased, so boxes are always immutable and the contained values can only be borrowed as shared references, not mutable references.

However, dynamic mutability is possible via types like Cell and RefCell where freezing is handled via dynamic checks which can fail at run-time. Specifically, Cell is for types that implement Copy, and RefCell is for all others.

Rc and Gc types are not sendable, so they can’t be used to share memory between tasks. This is instead possible via the extra::arc module.

let shared_map: Rc<RefCell<_>> = Rc::new(RefCell::new(HashMap::new()));
shared_map.borrow_mut().insert("africa", 92388i);
shared_map.borrow_mut().insert("kyoto", 11837i);
shared_map.borrow_mut().insert("piccadilly", 11826i);

A Cell may also be used to hide mutability for operations that appear to be immutable. A good example of this is Rc whose clone() method must increment the reference count, but clone is not expected to change the source value, which is why it takes &self and not &mut self. This can be reconciled by storing the reference count in a Cell.

struct Rc<T> { ptr: *mut RcBox<T> }
struct RcBox<T> { value: T, refcount: Cell<uint> }

impl<T> Clone for Rc<T> {
  fn clone(&self) -> Rc<T> {
    unsafe {
      (*self.ptr).refcount.set((*self.ptr).refcount.get() + 1);
      Rc { ptr: self.ptr }
    }
  }
}

Moving

Moving in Rust is similar to C++11 move semantics, where the “move” refers to moving ownership. Rust performs a shallow copy for parameter passing, assignment, and returning from functions. Performing such a shallow copy is treated by Rust as “moving ownership” of the value, so that the original source location can no longer be used unless it is reinitialized. A move can be avoided by cloning:

let mut xs = Nil;
let ys = xs;

// error if attempt to use `xs`

xs = Nil; // xs can be used again

let x = box 5;
let y = x.clone(); // y is a newly allocated box
let z = x; // no new memory alloc'd, x can no longer be used

Mutability can be changed by moving it to a new owner:

let r = box 13;
let mut s = r; // box becomes mutable
*s += 1;
let t = s; // box becomes immutable

Borrowing

References don’t imply ownership, they’re “borrowed.” Reference parameters are often used to allow functions to work with all manner of different allocated types.

fn distance(p1: &Point, p2: &Point) -> f64 {
  let x = p1.x - p2.x;
  let y = p1.y - p2.y;
  sqrt(x * x + y * y)
}

This can be used on stack-allocated variables by using the address-of operator & to borrow the local variable, to create an alias for it, i.e. another route to the same data. Managed and owned boxes, on the other hand, are automatically converted to references, in which case the “borrowed” metaphor is more like “lent out”.

If the contents of a variable are lent out then the variable can’t be sent to another task. Also, no actions can be taken that may cause the borrowed value to be freed or to change its type. It’s necessary to wait for the borrowed value to be returned, i.e. reference to go out of scope, before making full use of it again.

Furthermore, the act of lending immutable pointers to variables freezes the objects they point to and prevents their mutation until the reference is destroyed (i.e. out of scope):

let mut x = 5;
{
  let y = &x; // x is frozen
}
// x is unfrozen

Pointers and boxes are uniformly dereferenced with *. The pointer borrowed can be read as taking the reference of the mutable value, that is, the mut is part of the name. Note that the precedence levels of * and . are similar to those in C/C++, making for the awkward parenthesized dereferencing syntax. Unlike C/C++, there is no -> shortcut. Instead, there is automatic pointer dereferencing through * and [], which applies to any number of levels of indirection:

let mut owned = box 20;
let mut value = 30;
let borrowed = &mut value;

*owned = *borrowed + 100;
*borrowed = 1000;

let point = box Point { x: 10.0, y: 20.0 };
println!("{:f}", point.x);

References

The & symbol has multiple context-dependent meanings in Rust, as in C++ ². Remembering that expressions are for constructing and patterns for destructuring, a & in a pattern dereferences the expression being destructured. This can be useful to avoid having to manually dereference the variable within the body using *.

For example, the fold function takes a folding operation in the form of a closure that is passed the accumulator and a reference &T to the current element, which means that within the body it would have to be manually dereferenced with *, and we can avoid that by specifying the & in the pattern.

let manual  = v.iter().fold(0, |a, b| a + *b);
let pattern = v.iter().fold(0, |a, &b| a + b);

It’s also necessary when attempting to match on borrowed values. In this case, it reads as dereference the variable then see if it matches the pattern.

let x = Some(5);
let y = (&x, 2);

match y {
  (&Some(a), b) => a + b,
  (_, a) => a
}

A & in a function signature means that the parameter accepts a reference. Owned pointers box and types that implement the Deref trait are automatically converted to references when passed to such functions. Variables on the stack, on the other hand, can yield a reference manually using &, which is the address-of operator in that context.

fn eq(xs: &int, ys: &int) -> bool { ... }

let xs = box 34;
let ys = 34;
assert!(eq(xs, &ys));

A & that’s applied to an rvalue is a shorthand for creating a temporary and taking its address.

let explicit = Point { x: 3.0, y: 4.0 };
reference_taking_func(&explicit);

let shorthand = &Point { x: 3.0, y: 4.0 };
reference_taking_func(shorthand);

A mutable reference &mut is one through which the pointed-to variable can be modified, provided the pointed-to variable is also mutable. When a mutable reference exists to an object, no other reference can exist to the same object, regardless of whether it’s mutable or not. Compare this with a regular, immutable reference of which many can exist to the same variable, since the variable cannot be modified through it.

There is also the ref keyword that can be used in a pattern. In this context, it is similar to C++’s ref-qualifier, which means bind by reference. This is required when matching on something that can’t or we don’t want to be taken by value. It can be used with box and mut as well.

For example, we want to get a reference to the Foo in &Option<Foo>. Taking it by value would require moving ownership, but since the Option is borrowed we don’t have ownership to begin with. Instead we bind the foo by reference which does away with the need to take ownership.

let some = Some(foo);
let borrowed = &some;

match borrowed {
  &Some(ref foo) => *foo
}

let mut tuple (box 5u, 3u);
{
  let (box ref mut i, _) = tuple;
  *i = 3;
}

Another example is the Option type’s as_mut method which converts an Option<T> to Option<&mut T>. It essentially provides a mutable reference to the contained value to facilitate its mutation.

In order to avoid moving the reference out of the Option and thereby invalidating it later on, it’s necessary to bind it by reference with ref.

However, this would yield a & &mut uint, and since it’s not a mutable reference it would prevent us from mutating the value, otherwise it would essentially break the rule of not allowing more than one mutable reference to any one thing.

For this reason, it’s necessary to bind it by mutable reference with ref mut, yielding a &mut &mut uint, allowing us to mutate the value by doing **v = 1;. To avoid having to dereference twice, we would include the dereference operator & in the pattern position, to finally arrive at &ref mut v.

let mut x = Some(2u);
match x.as_mut() {
  Some(&ref mut v) => *v = 42,
  None => {},
}

assert_eq!(x, Some(42u));

There’s also a language inconsistency where "str" is of type &str, but to get a type of &&str it doesn’t suffice to simply do &"str", because that too is treated as &str, so two are needed: &&str.

In the following example, contains_key takes a value of type &K where K is the key type. The key type is &str, so &K is &&str. Because of the language inconsistency noted above, two &’s must prefix the string literal in order to yield a &&str to pass to contains_key. Alternatively, a single & can be used if the string literal is surrounded in parentheses.

Issue #10105 is a proposal to fix this. I’ve also read that DST will fix this as a consequence of its implementation.

use collections::Hashmap;

// type inferred as HashMap<&str, &str>
let mut items = HashMap::new();

items.insert("key1", "value1");
items.insert("key2", "value2");

if !items.contains_key(& &"key1") {
  println!("not present");
}

// or
if !items.contains_key(&("key1")) {
  println!("not present");
}

Lifetimes

Objects have lifetimes which aid the borrow checker in enforcing valid borrowing. The compiler automatically sets the lifetimes. In the following example, the compiler may give integer lifetime 'i and ref_to_int lifetime 'r with type &'i int denoting that it’s a reference type that points to an int of lifetime 'i.

let integer: int = 5
let ref_to_int: &int = &integer;

It’s possible to give a lifetime a name in order to explicitly specify the lifetime of a returned reference. In the following case, the named lifetime 'r is associated with the parameter p: &Point, this named lifetime is then also mentioned in the return type. What this means is that the returned reference will have the same lifetime as the passed in pointer parameter p. In effect, this means that the returned reference will remain valid as long as p itself remains valid.

This is necessary because, generally it’s only possible to return references derived from a parameter to the function, and named lifetimes explicitly specify which parameter that is. The lifetime is something that’s implicitly passed in from the caller’s context, just like the parameter.

struct Point { x: f64, y: f64 }

fn get_x<'r>(p: &'r Point) -> &'r f64 {
  &p.x
}

Named lifetimes allow grouping of parameters by lifetime. The following means that all of the parameters are assigned the same named lifetime r, so that in the caller the lifetime r will be the intersection of the lifetime of the three region parameters.

fn select<'r, T>(shape: &'r Shape, threshold: f64, a: &'r T, b: &'r T) -> &'r T {
  if compute_area(shape) > threshold {
    a
  } else {
    b
  }
}

For example, if select() were called by the following function it would produce an error. The reason is that the lifetime of the first parameter to select() is the function body of select_unit(). The second two parameters to select() share a lifetime in select_unit(), so there are actually two lifetimes. The intersection between these two lifetimes would be the Shape’s lifetime which is the function body, so the return value of the select() call will be the function body of select_unit().

This would lead to a compilation error, because select_unit() is supposed to return a value with a lifetime of r, which is the lifetime of a and b, not the lifetime of the local Circle.

fn select_unit<'r, T>(threshold: f64, a: &'r T, b: &'r T) -> &'r T {
  let shape = Circle(Point { x: 0., y: 0. }, 1.);
  select(&shape, threshold, a, b);
}

This can be resolved by creating another lifetime, 'tmp in select() and assign it to the shape parameter, in order to distinguish it from the lifetime of the last two parameters. However, since we wouldn’t be using the 'tmp lifetime and the compiler is guaranteed to generate a unique lifetime for ever parameter, it’s simpler to simply omit it altogether:

fn select<'r, T>(shape: Shape, threshold: f64, a: &'r T, b: &'r T) -> &'r T {
  if compute_area(shape) > threshold {
    a
  } else {
    b
  }
}

It’s also necessary to specify explicit lifetimes in structures that contain references.

struct Pair<'a, 'b> {
  one: &'a mut int,
  two: &'b mut int,
}

It’s also possible to use named lifetime notation to label control structures, allowing for breaking and continuing to specific locations.

'h: for i in range(0,10) {
  'g: loop {
    if i % 2 == 0 { continue 'h; }
    if i == 9 { break 'h; }
    break 'g;
  }
}

Elision

RFC #141 proposed expanded lifetime elision rules. The practical effect of this is that a lot of omitted, or elided, lifetime annotations can be inferred by the compiler.

To facilitate this, the compiler has notions of input or output. For functions, inputs are the lifetimes on arguments and outputs are the lifetimes on result types; this doesn’t include lifetimes that appear in the method’s impl or trait header. For implementations, inputs are the lifetimes on the type receiving the implementation, and the outputs are the lifetimes on the trait.

// elided one input and two outputs
fn foo(s: &str) -> (&str, &str)

// input:  'a, 'c
// output: 'b, 'c
impl<'a, 'b, 'c> Trait<'b, 'c> for Type<'a, 'c>

Given this distinction between lifetime parameters, the rules are simple:

1. each elided lifetime in input position becomes a distinct lifetime parameter, as was already the case

   fn print(s: &str);
   fn print<'a>(s: &'a str);
   
   impl Reader for (&str, &str) { ... }
   impl<'a, 'b> Reader for (&'a str, &'b str) { ... }
   

2. if there’s only one input lifetime position, its lifetime is assigned to all elided output lifetimes

   fn substr(s: &str, until: uint) -> &str;
   fn substr<'a>(s: &'a str, until: uint) -> &'a str;
   
   impl StrSlice for &str { ... }
   impl<'a> StrSlice<'a> for &'a str { ... }
   

3. if there are multiple input lifetime positions and one of them is &self or &mut self, the lifetime of self is assigned to all elided output lifetimes

   fn args<T: ToCStr>(&mut self, args: &[T]) -> &mut Command
   fn args<'a, 'b, T: ToCStr>(&'a mut self, args: &'b [T]) -> &'a mut Command
   

4. otherwise, it’s an error to elide an output lifetime

   fn get_str() -> &str;
   fn frob(s: &str, t: &str) -> &str;
   

Lifetime elision with implementations is a bit trickier. Elision inference occurs at two levels: the implementation header line and its methods. Expansion can occur in trait methods since they’re treated as any other function.

trait Bar<'a> {
  fn bound(&'a self) -> &int { ... }
  fn fresh(&self) -> &int { ... }
}

// fresh expands like any other function
trait Bar<'a> {
  fn bound(&'a self) -> &'a int { ... }
  fn fresh<'b>(&'b self) -> &'b int { ... }
}

In general, the elided signatures of the impl should match those of the trait so that the impl expansion matches the trait and thus will compile. Failing to do this might break the relationship between an impl header-level lifetime and a method’s lifetime.

Consider the following example where the impl header-level was expanded, and then the bound method expanded separately with a distinct lifetime (as per rule #1) even though they’re supposed to be the same as specified in the trait.

impl Bar for &str {
  fn bound(&self) -> &int { ... }
}

// bound's lifetime should've been 'a
impl<'a> Bar<'a> for &'a str {
  fn bound<'b>(&'b self) -> &'b int { ... }
}

If the signatures are used exactly as in the trait, with the same lifetime elisions, the impl expansion will most likely expand to match the trait’s expansion.

impl<'a> Bar<'a> for &'a str {
  fn bound(&'a self) -> &'a int { ... }
  fn fresh(&self) -> &int { ... }
}

// fresh method expands correctly
impl<'a> Bar<'a> for &'a str {
  fn bound(&'a self) -> &'a int { ... }
  fn fresh<'b>(&'b self) -> &'b int { ... }
}

Dropping

Destructors are functions responsible for cleaning up resources used by an object that is no longer accessible. Objects are never accessible after their destructor has been called, so it’s not possible to fail from accessing freed resources. Further, when a task fails, destructors of all objects in the task are called.

The box keyword represents a unique handle for a memory allocation on the heap:

{
  let y = box 10; // allocated on the heap
}
// destructor frees heap memory as soon as `y` goes out of scope

Collections

Arrays

Fixed-size vectors are unboxed blocks of memory that owns the elements it contains.

let fixed_size: [1, 2, 3];
let five_zeroes: [int, ..5] = [0, ..5];

Slices

Slices point into blocks of memory and don’t have ownership over the elements. Other vector types coerce to slices. An unadorned string literal is an immutable string slice:

let xs = &[1, 2, 3];
let ys: &[int] = xs;

let three = [1, 2, 3];
let zs: &[int] = three;

let string = "foobar";
let view: &str = string.slice(0, 3);

Mutable slices exist, but none for strings, since strings are a multi-byte encoding of Unicode code points, meaning they can’t be freely mutated without the ability to alter the length, something that can’t be done via slices, which simply provide a window.

let mut xs = [1, 2, 3];
let view = xs.mut_slice(0, 2);
view[0] = 5;

let ys: &mut [int] = &mut [1, 2, 3];

RFC #198 adds overloaded slice notation via the Slice and SliceMut traits.

let xs = &[1, 2, 3, 4, 5];

assert_eq!(xs[], xs.as_slice());
assert_eq!(xs[n..m], xs.slice(n, m));
assert_eq!(xs[n..], xs.slice_from(n));
assert_eq!(xs[..m], xs.slice_to(m));

assert_eq!(xs[mut], xs.as_mut_slice());
assert_eq!(xs[mut n..m], xs.slice_mut(n, m));
assert_eq!(xs[mut n..], xs.slice_from_mut(n));
assert_eq!(xs[mut ..m], xs.slice_to_mut(m));

Vectors

Vectors are dynamically-sized and have a destructor that cleans up the allocated memory on the heap. Vectors own the elements they contain. They are represented with 3 words: a pointer to the data, its length, and its capacity representing how much memory is reserved for the vector.

let mut numbers = vec![1, 2, 3];
numbers.push(4);

let more_numbers: Vec<int> = numbers;

Strings

Strings are represented as vectors of u8 with a guarantee of containing a valid UTF-8 sequence. The String type represents a non-null terminated, growable string, while the &str type represents fixed-size one.

String is represented as a vector of bytes Vec<u8> that is guaranteed to always be a valid UTF-8 sequence. The &str type is a slice &[u8] that always points to a valid UTF-8 sequence and can be used as a view into String, as &[T] is a view into Vec<T>.

String literals are stored in the static region of the program’s memory, and so Rust treats static strings as slices which serve as views into the region of memory pertaining to the string: &'static str.

let mut string = String::from_str("fo");
string.push_char('o');

// trimmed strings are slices into original string
// no new allocation required
let trimmed: &str = string.as_slice().trim_chars(&[',', ' ']);
println!("Unused characters: {}", trimmed);

let literal: &'static str = "testing";

Raw string literals are possible by surrounding the string with zero or more hashes # as needed to disambiguate from the string contents, and prefixed by an r.

let pattern = r#"\d+"#;

Byte string literals are possible by prefixing the string with a b and are stored as &'static [u8]. A byte literal is a single ASCII character surrounded by single quotes and prefixed by b.

Byte literals can have raw bodies by appending the b prefix with the r for raw string literals.

let letter: u8 = b'A'; // 65u8
let name: &'static [u8] = b"john";

let raw_bytes = br#"test"#;

Pattern Matching

Pattern matching takes the place of regular switch statements. Pattern matches don’t fall through. The pipe operator | can be used to combine multiple patterns into one arm. As in Haskell, matches must be exhaustive. Every case is separated by commas, unless block expressions are used. As in Haskell, pattern matching can be used to bind values. Pattern guards are added using if expressions:

match number {
  0     => println("zero"),
  1 | 2 => println("one or two"),
  3..10 => println("three to ten"),
  _     => println("something else")
}

The underscore _ is a placeholder and two dots .. acts as a wildcard pattern for matching the rest of the fields.

match x {
  Cons(_, box Nil) => panic!("singleton list"),
  Cons(..)         => return,
  Nil              => panic!("empty list")
}

Patterns can also be bound to variables as in Haskell and Scala:

match age {
  a @ 0..20 => println!("{} years old", a),
  _         => println!("older than 21")
}

Pattern matching on structures can use the field name which creates a local varaible with that name ³.

struct Test {
  age: int,
  apples: int
}

let Test { age, apples } = b;

RFC #160 added support for if-let pattern matching as in Swift, where the condition succeeds if the pattern matches.

if let Some(x) = optional {
  doSomething(x);
}

Similarly, RFC #214 added support for while-let. It works in a similar manner to the above if-let, essentially continuing the loop so long as the pattern matches. This is useful for iterators.

while let Some(value) = iter.next() {
  // ...
}

With the advanced_slice_patterns feature gate, it’s possible to use more advanced pattern matching on slices. With these patterns, .. can be used to match any number of elements, which can also be bound to a name.

match slice {
  [first, second, rest..] => blah,
}

Control Structures

The for loop is in the form of for-in; there is no explicit increment looping via for loops. The loop keyword denotes an infinite loop.

Structures

Structures are laid out in memory the same as as they are in C. Structures are constructed similar to Go structures. Structures have inherited mutability. Structures can be pattern matched on to destructure their fields.

struct Point {
  x: f64,
  y: f64
}

match mypoint {
  Point { x, .. } => { println(x.to_str()) }
}

Structures can define methods by providing implementations.

impl Point {
  fn static() {
    // static method
  }

  fn something(&self) {
    // method
  }
}

Functional updates can be performed by terminating the structure expression syntax with .. followed by another value of the same type as the structure being defined. This is similar to what is commonly done in Haskell.

let base = Point3d { x: 1, y: 2, z: 3 };
Point3d { y: 0, z: 10, ..base }

Enumerations

Enumerations in Rust feel similar to algebraic datatypes in Haskell. Enumerations can be C-like, in which case they can optionally be given specific values. The specific values can be converted to an int using the cast operator as. Enumerations can define methods with the impl keyword as with structures. Enumerations variants can be structs as well:

enum Shape {
  Circle(Point, f64)
  Rectangle(Point, Point)
}

enum Direction {
  Left,
  Right
}

enum Color {
  Red = 0xff0000,
  Green = 0x00ff00,
  Blue = 0x0000ff
}

#[feature(struct_variant)]
enum Shape {
  Circle { center: Point, radius: f64 },
  Rectangle { top_left: Point, bottom_right: Point }
}

Tuples

Tuples are available and are most similar to Haskell’s. Tuple structs behave like both structs and tuples. They’re like tuples with names. Tuple structs with a single field are similar to Haskell newtypes and are often called the same thing in Rust. These provide a distinct type from the type they wrap. Newtypes’ wrapped values can be extracted using the dereference operator *:

let mytup: (int, int, f64) = (10, 20, 30.0)

struct MyTup(int, int, f64);
let mytup: MyTup = MyTup(10, 20, 30.0)

struct GizmoId(int);
let my_gizmo_id: GizmoId = GizmoId(10);
let id_int: int = *my_gizmo_id;

RFC #184 adds tuple accessor syntax which applies to tuples and tuple structs. Only one level is possible since more than one would be considered a float.

let mut tpl = (0, 1);
tpl.1 = 2;

struct Foo(int, int);
let mut foo = Foo(3, -15);
foo.0 = 5;

Functions

Function definitions are similar to Scala’s, with the type following the name of the parameter. The return type follows the parameter list as in Scala, but more like C++11’s alternative function syntax. If the top-level block of the function produces an expression, the return statement may be omitted. Functions that return nothing return nil (), which can be omitted from the function declaration. However, ending the function with a semicolon is also equivalent to returning (). Function arguments can be destructured, but the patterns must be irrefutable:

fn line(a: int, b: int, x: int) -> int { a * x + b }

fn do_nothing_the_hard_way() -> () { return (); }
fn do_nothing_the_easy_way() { }
fn do_nothing_another_way(a: int) -> () { a; }

fn first((value, _): (int, f64)) -> int { value }

In short, blocks such as { expr1; expr2 } are considered a single expression and evaluate to the result of the last expression if it’s not followed by a semicolon, otherwise the block evaluates to ().

A diverging function is one that never returns a value to the caller. Every control path must end in panic!() or another diverging function. This is informs the compiler that execution will never return to the original context, allowing things to type-check where they wouldn’t otherwise.

In the following example, my_err can be used even though it’s not of type int because it’s a diverging function.

fn my_err(s: &str) -> ! {
  println!("{}", s);
  panic!();
}

fn f(i: int) -> int {
  if i == 42 {
    return 42;
  } else {
    my_err("Bad number!");
  }
}

Parameters can be marked as to be moved into the function. They can also be borrowed immutably, or mutably which allows the variable to be mutated. Finally, a parameter can also be moved into the function and marked as mutable, so that once moved into the function it can be mutated within the scope of the function.

fn m(x: T);      // move
fn m(mut x: T);  // move and mark mutable
fn m(x: &T);     // immutably borrow
fn m(x: &mut T); // mutably borrow

Methods

Methods are functions that take self as the first argument, which is of the same type as the method’s receiver. Implementations are used to define methods on specific types, such as structs and enums.

struct Point {
  x: f64,
  y: f64
}

enum Shape {
  Circle(Point, f64),
  Rectangle(Point, Point)
}

impl Shape {
  fn draw(&self) {
    match *self {
      Circle(p, f)      => draw_circle(p, f),
      Rectangle(p1, p2) => draw_rectangle(p1, p2)
    }
  }
}

let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);
s.draw();

It’s also possible to define static methods by omitting the self parameter. This is usually how constructors are defined:

use std::f64::consts::PI;

struct Circle { radius: f64 }

impl Circle {
  fn new(area: f64) -> Circle {
    Circle { radius: (area / PI).sqrt() }
  }
}

let c = Circle::new(42.5);

Universal Function Call Syntax

RFC #132 specifies a universal function call syntax (UFCS) which provides a way to completely disambiguate a particular method call, which is particularly useful when a type implements more than one trait that contains the same method.

Given a particular call syntax, different behavior occurs:

• Trait::method(): the same behavior occurs as it does now.

• T::method() where T is a path that resolves to a type: it is rewritten internally to <T>::method().

• <T>::method(): if type T implements only one trait in the scope that provides method(), then that method is called. Otherwise, the call must be disambiguated using the syntax <T as DesiredTrait>::method().

A nice consequence of UFCS is that static methods on traits can be called through the implementing type now, instead of having to be called on the trait itself.

#[deriving(Default)]
struct S;

S::default();
Default::default();

In fact, UFCS completely erases the distinction between static methods and regular methods, so that t.a(b) is also equivalent to T::a(t, b). This means that methods can be called like functions:

struct Foo;

impl Foo {
  fn bar(&self) {
    // ...
  }
}

let x = Foo;

x.bar();
Foo::bar(&x);

Closures

Regular, named functions don’t close over their environment, but closures do.

fn call_closure_with_ten(b: |int|) { b(10); }

let captured_var = 20;
let closure = |arg| println!("captured_var={}, arg={}", captured_var, arg);

call_closure_with_ten(closure);

Stack closures are a specific kind of closure that directly accesses local variables in the enclosing scope, making them very efficient. To ensure that they don’t outlive the current scope, they aren’t first class, so they can’t be assigned to values or returned from functions.

let mut max = 0;
[1, 2, 3].map(|x| if *x > max { max = *x })

Owned closures are written with proc, e.g. proc(arg: int), and they own values that can be sent safely between processes. As a result, they can only be called once. The values they close over are copied, and they become owned by the closure. These are particularly used in concurrent scenarios, particularly for spawning tasks.

Despite there being different types of closures, functions that expect a || closure can accept any kind of closure provided they have the same arguments and return types. For this reason, higher-order functions should usually define their closure types as || so that callers can pass any kind of closure.

Unboxed Closures

RFC #114 proposed unboxed closure traits Fn, FnMut, and FnOnce, along with new closure syntax which was refined by RFC #231. These traits are defined in std::ops, which is a module that defines traits for overloading operators. In effect, implementing these traits is equivalent to overloading the function call operator () in C++.

As in C++, unboxed closures essentially expand to an anonymous structure which contains the captured variables—known as upvars—as well as an implementation of one of these traits, which has the effect of overloading the function call operator ().

In this context, the receiving parameter self refers to the instance of the generated structure, so that the type of self determines whether the upvars can be moved or mutated. This is exactly the difference between the three unboxed closure traits.

The RFC defines two types of closures: escaping and non-escaping closures. Escaping closures are closures that will escape the stack frame that created them—such as task bodies—and are created using the move || syntax. Non-escaping closures are the most common and therefore use the default || syntax.

Both escaping and non-escaping closures can implement any of the closure traits, depending on how the upvars are used within the closure.

1. FnOnce if any upvars are moved out of the closure
2. FnMut if any upvars are mutably borrowed within the closure
3. otherwise: Fn

Notice that moving an upvar out of the closure essentially means to move it out of the closure’s environment, that is, its implementing anonymous structure.

The trait above is inferred, but inference of these traits is not completely implemented yet. As a result, there exists syntax sugar to explicitly declare which trait to choose.

A simple way to remember this sugar is to imagine that the self keyword precedes the colon :, which makes it obvious that this sugar is designating the type of the self parameter, which corresponds to the appropriate trait.

Capture modes determine the manner in which upvars are captured. With escaping closures, all upvars are moved into the closure. For non-escaping closures, there are three different capture modes that are applied depending on three different situations which are checked in-order:

1. if an upvar is mutably borrowed within the closure, it is mutably borrowed into the closure
2. if an upvar is moved within the closure and doesn’t implement Copy, it is moved into the closure
3. otherwise: the upvar is immutably borrowed

Notice that regular non-escaping closures can end up moving all of the upvars only if they’re moved within the closure. This is why the separate escaping closure syntax move || is necessary, for cases where the closure escapes the stack frame, in order to ensure that all upvars are moved into the closure regardless of how they’re used within.

There exists sugar for denoting unboxed closure traits at the type level.

fn foo<F>() where F: FnMut(int, int) -> int {
  // ...
}

Generics

Types can be parameterized similar to C++ class templates:

enum List<T> {
  Const(T, Box<List<T>>),
  Nil
}

fn prepend<T>(xs: List<T>, value: T) -> List<T> {
  Cons(value, box xs)
}

The compiler can infer the type of a list like this:

let mut xs = Nil;
xs = prepend(xs, 10);
xs = prepend(xs, 20);
xs = prepend(xs, 30);

However, it’s also possible to explicitly annotate the types:

let mut xs: List<int> = Nil::<int>;
xs = prepend::<int>(xs, 10);
xs = prepend::<int>(xs, 20);
xs = prepend::<int>(xs, 30);

The list equality function can be updated for this generic list by adding a trait bound of Eq on the element type and adding ref annotations to avoid moving out the element types. In fact, we might as well implement the Eq trait for this generic list already:

impl<T: Eq> Eq for List<T> {
  fn eq(&self, ys: &List<T>) -> bool {
    match (self, ys) {
      (&Nil, &Nil) => true,
      (&Cons(ref x, box ref next_xs), &Cons(ref y, box ref next_ys))
        if x == y => next_xs == next_ys,
      _ => false
    }
  }
}

Generic functions in Rust have similar performance characteristics as templates in C++ because it performs monomorphization which generates a separate copy of each generic function at each call site, which is specialized to the argument types, optimized specifically for them. This is similar to C++ template instantiation.

fn map<T, U>(vector: &[T], function: |v: &T| -> U) -> Vec<U> {
  let mut accumulator = Vec::new();
  for element in vector.iter() {
    accumulator.push(function(element));
  }
  return accumulator;
}

Type parameters can also be used to define generic types, structs, and enums.

use std::hashmap::HashMap;
type Set<T> = HashMap<T, ()>;
// Set<int>

struct Stack<T> {
  elements: Vec<T>
}
// Stack<int>

enum Option<T> {
  Some(T),
  None
}
// Option<int>

Where Clauses

RFC #135 adds support for where clauses similar to those in Swift which allow type bounds to be specified for the type parameters in a generic declaration. Where clauses can be added to anything that can be parameterized with type or lifetime parameters, except for trait method definitions. This includes impl, fn, trait, struct, as well as associated types.

Multiple bounds declarations are separated by commas, and multiple bounds for a given type parameter can be written separately or in a compound form using +.

impl<K: Hash + Eq, V> HashMap<K, V> {
  // ...
}

impl<K, V> HashMap<K, V>
  where K: Hash + Eq {
  // ...
}

With associated types, a trait like Iterator might no longer have type parameters, since it’ll be an associated type. As a result, a bound can’t be provided for the type parameter using regular syntax. Instead, where clauses can be used to express the bound.

// Iterator has no type parameter, so this doesn't work
fn sum<I: Iterator<int>>(i: I) -> int {
  // ...
}

// the where clause can express a bound
// on the Iterator's associated type `E`
fn sum<I: Iterator>(i: I) -> int
  where I::E == int {
  // ...
}

Traits

Traits are similar to type classes in Haskell. They allow the expression of bounded polymorphism which limits the possible types a type parameter could refer to. For example, the clone method which allows the copying of a type, isn’t defined on all types because it can’t be safely performed on all types, due to user-defined destructors for example. Traits allow to bound the polymorphism of a generic function by specifying that a type parameter must implement the Clone trait in this case to limit the types on which the function can work:

fn head<T: Clone>(v: &[T]) -> T {
  v[0].clone()
}

Traits contain zero or more method signatures. In the following trait, it is said that Printable provides a print method with the given signature:

trait Printable {
  fn print(&self);
}

impl Printable for int {
  fn print(&self) { println!("{:?}", *self) }
}

impl Printable for String {
  fn print(&self) { println(*self) }
}

It’s also possible to define default method implementations which can later be overridden on a case-by-case basis:

trait Printable {
  fn print(&self) { println!("{:?}", *self) }
}

// these use default implementation
impl Printable for int {}
impl Printable for bool {}
impl Printable for f32 {}

// overrides default implementation
impl Printable for String {
  fn print(&self) { println(*self) }
}