|
| 1 | +% Rust Cheatsheet |
| 2 | + |
| 3 | +# How do I convert *X* to *Y*? |
| 4 | + |
| 5 | +**Int to string** |
| 6 | + |
| 7 | +Use [`ToStr`](http://static.rust-lang.org/doc/master/std/to_str/trait.ToStr.html). |
| 8 | + |
| 9 | +```rust |
| 10 | +let x: int = 42; |
| 11 | +let y: ~str = x.to_str(); |
| 12 | +``` |
| 13 | + |
| 14 | +**String to int** |
| 15 | + |
| 16 | +Use [`FromStr`](http://static.rust-lang.org/doc/master/std/from_str/trait.FromStr.html), and its helper function, [`from_str`](http://static.rust-lang.org/doc/master/std/from_str/fn.from_str.html). |
| 17 | + |
| 18 | +```rust |
| 19 | +let x: Option<int> = from_str("42"); |
| 20 | +let y: int = x.unwrap(); |
| 21 | +``` |
| 22 | + |
| 23 | +**Int to string, in non-base-10** |
| 24 | + |
| 25 | +Use [`ToStrRadix`](http://static.rust-lang.org/doc/master/std/num/trait.ToStrRadix.html). |
| 26 | + |
| 27 | +```rust |
| 28 | +use std::num::ToStrRadix; |
| 29 | + |
| 30 | +let x: int = 42; |
| 31 | +let y: ~str = x.to_str_radix(16); |
| 32 | +``` |
| 33 | + |
| 34 | +**String to int, in non-base-10** |
| 35 | + |
| 36 | +Use [`FromStrRadix`](http://static.rust-lang.org/doc/master/std/num/trait.FromStrRadix.html), and its helper function, [`from_str_radix`](http://static.rust-lang.org/doc/master/std/num/fn.from_str_radix.html). |
| 37 | + |
| 38 | +```rust |
| 39 | +use std::num::from_str_radix; |
| 40 | + |
| 41 | +let x: Option<int> = from_str_radix("deadbeef", 16); |
| 42 | +let y: int = x.unwrap(); |
| 43 | +``` |
| 44 | + |
| 45 | +# File operations |
| 46 | + |
| 47 | +## How do I read from a file? |
| 48 | + |
| 49 | +Use [`File::open`](http://static.rust-lang.org/doc/master/std/io/fs/struct.File.html#method.open) to create a [`File`](http://static.rust-lang.org/doc/master/std/io/fs/struct.File.html) struct, which implements the [`Reader`](http://static.rust-lang.org/doc/master/std/io/trait.Reader.html) trait. |
| 50 | + |
| 51 | +```rust |
| 52 | +use std::path::Path; |
| 53 | +use std::io::fs::File; |
| 54 | + |
| 55 | +let path : Path = Path::new("Doc-FAQ-Cheatsheet.md"); |
| 56 | +let on_error = || fail!("open of {:?} failed", path); |
| 57 | +let reader : File = File::open(&path).unwrap_or_else(on_error); |
| 58 | +``` |
| 59 | + |
| 60 | +## How do I iterate over the lines in a file? |
| 61 | + |
| 62 | +Use the [`lines`](http://static.rust-lang.org/doc/master/std/io/trait.Buffer.html#method.lines) method on a [`BufferedReader`](http://static.rust-lang.org/doc/master/std/io/buffered/struct.BufferedReader.html). |
| 63 | + |
| 64 | +```rust |
| 65 | +use std::io::buffered::BufferedReader; |
| 66 | + |
| 67 | +let mut reader = BufferedReader::new(reader); |
| 68 | +for line in reader.lines() { |
| 69 | + print!("line: {}", line); |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +# String operations |
| 74 | + |
| 75 | +## How do I search for a substring? |
| 76 | + |
| 77 | +Use the [`find_str`](http://static.rust-lang.org/doc/master/std/str/trait.StrSlice.html#tymethod.find_str) method. |
| 78 | + |
| 79 | +```rust |
| 80 | +let str = "Hello, this is some random string"; |
| 81 | +let index: Option<uint> = str.find_str("rand"); |
| 82 | +``` |
| 83 | + |
| 84 | +# Containers |
| 85 | + |
| 86 | +## How do I get the length of a vector? |
| 87 | + |
| 88 | +The [`Container`](http://static.rust-lang.org/doc/master/std/container/trait.Container.html) trait provides the `len` method. |
| 89 | + |
| 90 | +```rust |
| 91 | +let u: ~[u32] = ~[0, 1, 2]; |
| 92 | +let v: &[u32] = &[0, 1, 2, 3]; |
| 93 | +let w: [u32, .. 5] = [0, 1, 2, 3, 4]; |
| 94 | + |
| 95 | +println!("u: {}, v: {}, w: {}", u.len(), v.len(), w.len()); // 3, 4, 5 |
| 96 | +``` |
| 97 | + |
| 98 | +## How do I iterate over a vector? |
| 99 | + |
| 100 | +Use the [`iter`](http://static.rust-lang.org/doc/master/std/vec/trait.ImmutableVector.html#tymethod.iter) method. |
| 101 | + |
| 102 | +```rust |
| 103 | +let values: ~[int] = ~[1, 2, 3, 4, 5]; |
| 104 | +for value in values.iter() { // value: &int |
| 105 | + println!("{}", *value); |
| 106 | +} |
| 107 | +``` |
| 108 | + |
| 109 | +(See also [`mut_iter`](http://static.rust-lang.org/doc/master/std/vec/trait.MutableVector.html#tymethod.mut_iter) which yields `&mut int` and [`move_iter`](http://static.rust-lang.org/doc/master/std/vec/trait.OwnedVector.html#tymethod.move_iter) which yields `int` while consuming the `values` vector.) |
| 110 | + |
| 111 | +# Type system |
| 112 | + |
| 113 | +## How do I store a function in a struct? |
| 114 | + |
| 115 | +```rust |
| 116 | +struct Foo { |
| 117 | + myfunc: fn(int, uint) -> i32 |
| 118 | +} |
| 119 | + |
| 120 | +struct FooClosure<'a> { |
| 121 | + myfunc: 'a |int, uint| -> i32 |
| 122 | +} |
| 123 | + |
| 124 | +fn a(a: int, b: uint) -> i32 { |
| 125 | + (a as uint + b) as i32 |
| 126 | +} |
| 127 | + |
| 128 | +fn main() { |
| 129 | + let f = Foo { myfunc: a }; |
| 130 | + let g = FooClosure { myfunc: |a, b| { (a - b as int) as i32 } }; |
| 131 | + println!("{}", (f.myfunc)(1, 2)); |
| 132 | + println!("{}", (g.myfunc)(3, 4)); |
| 133 | +} |
| 134 | +``` |
| 135 | + |
| 136 | +Note that the parenthesis surrounding `f.myfunc` are necessary: they are how Rust disambiguates field lookup and method call. The `'a` on `FooClosure` is the lifetime of the closure's environment pointer. |
| 137 | + |
| 138 | +## How do I express phantom types? |
| 139 | + |
| 140 | +[Phantom types](http://www.haskell.org/haskellwiki/Phantom_type) are those that cannot be constructed at compile time. To express these in Rust, zero-variant `enum`s can be used: |
| 141 | + |
| 142 | +```rust |
| 143 | +enum Open {} |
| 144 | +enum Closed {} |
| 145 | +``` |
| 146 | + |
| 147 | +Phantom types are useful for enforcing state at compile time. For example: |
| 148 | + |
| 149 | +```rust |
| 150 | +struct Door<State>(~str); |
| 151 | + |
| 152 | +fn close(Door(name): Door<Open>) -> Door<Closed> { |
| 153 | + Door::<Closed>(name) |
| 154 | +} |
| 155 | + |
| 156 | +fn open(Door(name): Door<Closed>) -> Door<Open> { |
| 157 | + Door::<Open>(name) |
| 158 | +} |
| 159 | + |
| 160 | +let _ = close(Door::<Open>(~"front")); // ok |
| 161 | +let _ = close(Door::<Closed>(~"front")); // error: mismatched types: expected `main::Door<main::Open>` but found `main::Door<main::Closed>` |
| 162 | +``` |
| 163 | + |
| 164 | +# FFI (Foreign Function Interface) |
| 165 | + |
| 166 | +## C function signature conversions |
| 167 | + |
| 168 | +Description | C signature | Equivalent Rust signature |
| 169 | +----------------------|----------------------------------------------|------------------------------------------ |
| 170 | +no parameters | `void foo(void);` | `fn foo();` |
| 171 | +return value | `int foo(void);` | `fn foo() -> c_int;` |
| 172 | +function parameters | `void foo(int x, int y);` | `fn foo(x: int, y: int);` |
| 173 | +in-out pointers | `void foo(const int* in_ptr, int* out_ptr);` | `fn foo(in_ptr: *c_int, out_ptr: *mut c_int);` |
| 174 | + |
| 175 | +Note: The Rust signatures should be wrapped in an `extern "ABI" { ... }` block. |
| 176 | + |
| 177 | +### Representing opaque handles |
| 178 | + |
| 179 | +You might see things like this in C APIs: |
| 180 | + |
| 181 | +```c |
| 182 | +typedef struct Window Window; |
| 183 | +Window* createWindow(int width, int height); |
| 184 | +``` |
| 185 | +
|
| 186 | +You can use a zero-element `enum` ([phantom type](#how-do-i-express-phantom-types)) to represent the opaque object handle. The FFI would look like this: |
| 187 | +
|
| 188 | +```rust |
| 189 | +enum Window {} |
| 190 | +extern "C" { |
| 191 | + fn createWindow(width: c_int, height: c_int) -> *Window; |
| 192 | +} |
| 193 | +``` |
| 194 | + |
| 195 | +Using a phantom type ensures that the handles cannot be (safely) constructed in client code. |
| 196 | + |
| 197 | +# Contributing to this page |
| 198 | + |
| 199 | +For small examples, have full type annotations, as much as is reasonable, to keep it clear what, exactly, everything is doing. Try to link to the API docs, as well. |
| 200 | + |
| 201 | +Similar documents for other programming languages: |
| 202 | + |
| 203 | + * [http://pleac.sourceforge.net/](http://pleac.sourceforge.net) |
0 commit comments