src/doc/complement-cheatsheet.md

   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 ~~~
  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 ~~~
  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 the `format!` syntax extension.
  26
  27 ~~~
  28 let x: int = 42;
  29 let y: ~str = format!("{:t}", x);   // binary
  30 let y: ~str = format!("{:o}", x);   // octal
  31 let y: ~str = format!("{:x}", x);   // lowercase hexadecimal
  32 let y: ~str = format!("{:X}", x);   // uppercase hexidecimal
  33 ~~~
  34
  35 **String to int, in non-base-10**
  36
  37 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).
  38
  39 ~~~
  40 use std::num;
  41
  42 let x: Option<i64> = num::from_str_radix("deadbeef", 16);
  43 let y: i64 = x.unwrap();
  44 ~~~
  45
  46 **Vector of Bytes to String**
  47
  48 To return a Borrowed String Slice (&str) use the str helper function [`from_utf8`](http://static.rust-lang.org/doc/master/std/str/fn.from_utf8.html).
  49
  50 ~~~
  51 use std::str;
  52
  53 let bytes = ~[104u8,105u8];
  54 let x: Option<&str> = str::from_utf8(bytes);
  55 let y: &str = x.unwrap();
  56 ~~~
  57
  58 To return an Owned String (~str) use the str helper function [`from_utf8_owned`](http://static.rust-lang.org/doc/master/std/str/fn.from_utf8_owned.html).
  59
  60 ~~~
  61 use std::str;
  62
  63 let x: Option<~str> = str::from_utf8_owned(~[104u8,105u8]);
  64 let y: ~str = x.unwrap();
  65 ~~~~
  66
  67 To return a [`MaybeOwned`](http://static.rust-lang.org/doc/master/std/str/enum.MaybeOwned.html) use the str helper function [`from_utf8_lossy`](http://static.rust-lang.org/doc/master/std/str/fn.from_utf8_owned.html).  This function also replaces non-valid utf-8 sequences with U+FFFD replacement character.
  68
  69 ~~~
  70 use std::str;
  71
  72 let x = bytes!(72u8,"ello ",0xF0,0x90,0x80,"World!");
  73 let y = str::from_utf8_lossy(x);
  74 ~~~~
  75
  76 # File operations
  77
  78 ## How do I read from a file?
  79
  80 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.
  81
  82 ~~~ {.ignore}
  83 use std::path::Path;
  84 use std::io::fs::File;
  85
  86 let path : Path   = Path::new("Doc-FAQ-Cheatsheet.md");
  87 let on_error      = || fail!("open of {:?} failed", path);
  88 let reader : File = File::open(&path).unwrap_or_else(on_error);
  89 ~~~
  90
  91 ## How do I iterate over the lines in a file?
  92
  93 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).
  94
  95 ~~~
  96 use std::io::BufferedReader;
  97 # use std::io::MemReader;
  98
  99 # let reader = MemReader::new(vec!());
 100
 101 let mut reader = BufferedReader::new(reader);
 102 for line in reader.lines() {
 103     print!("line: {}", line);
 104 }
 105 ~~~
 106
 107 # String operations
 108
 109 ## How do I search for a substring?
 110
 111 Use the [`find_str`](http://static.rust-lang.org/doc/master/std/str/trait.StrSlice.html#tymethod.find_str) method.
 112
 113 ~~~
 114 let str = "Hello, this is some random string";
 115 let index: Option<uint> = str.find_str("rand");
 116 ~~~
 117
 118 # Containers
 119
 120 ## How do I get the length of a vector?
 121
 122 The [`Container`](http://static.rust-lang.org/doc/master/std/container/trait.Container.html) trait provides the `len` method.
 123
 124 ~~~
 125 let u: ~[u32] = ~[0, 1, 2];
 126 let v: &[u32] = &[0, 1, 2, 3];
 127 let w: [u32, .. 5] = [0, 1, 2, 3, 4];
 128
 129 println!("u: {}, v: {}, w: {}", u.len(), v.len(), w.len()); // 3, 4, 5
 130 ~~~
 131
 132 ## How do I iterate over a vector?
 133
 134 Use the [`iter`](http://static.rust-lang.org/doc/master/std/vec/trait.ImmutableVector.html#tymethod.iter) method.
 135
 136 ~~~
 137 let values: ~[int] = ~[1, 2, 3, 4, 5];
 138 for value in values.iter() {  // value: &int
 139     println!("{}", *value);
 140 }
 141 ~~~
 142
 143 (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.)
 144
 145 # Type system
 146
 147 ## How do I store a function in a struct?
 148
 149 ~~~
 150 struct Foo {
 151     myfunc: fn(int, uint) -> i32
 152 }
 153
 154 struct FooClosure<'a> {
 155     myfunc: |int, uint|: 'a -> i32
 156 }
 157
 158 fn a(a: int, b: uint) -> i32 {
 159     (a as uint + b) as i32
 160 }
 161
 162 fn main() {
 163     let f = Foo { myfunc: a };
 164     let g = FooClosure { myfunc: |a, b|  { (a - b as int) as i32 } };
 165     println!("{}", (f.myfunc)(1, 2));
 166     println!("{}", (g.myfunc)(3, 4));
 167 }
 168 ~~~
 169
 170 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.
 171
 172 ## How do I express phantom types?
 173
 174 [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:
 175
 176 ~~~
 177 enum Open {}
 178 enum Closed {}
 179 ~~~
 180
 181 Phantom types are useful for enforcing state at compile time. For example:
 182
 183 ~~~
 184 struct Door<State>(~str);
 185
 186 struct Open;
 187 struct Closed;
 188
 189 fn close(Door(name): Door<Open>) -> Door<Closed> {
 190     Door::<Closed>(name)
 191 }
 192
 193 fn open(Door(name): Door<Closed>) -> Door<Open> {
 194     Door::<Open>(name)
 195 }
 196
 197 let _ = close(Door::<Open>(~"front"));
 198 ~~~
 199
 200 Attempting to close a closed door is prevented statically:
 201
 202 ~~~ {.ignore}
 203 let _ = close(Door::<Closed>(~"front")); // error: mismatched types: expected `main::Door<main::Open>` but found `main::Door<main::Closed>`
 204 ~~~
 205
 206 # FFI (Foreign Function Interface)
 207
 208 ## C function signature conversions
 209
 210 Description            C signature                                    Equivalent Rust signature
 211 ---------------------- ---------------------------------------------- ------------------------------------------
 212 no parameters          `void foo(void);`                              `fn foo();`
 213 return value           `int foo(void);`                               `fn foo() -> c_int;`
 214 function parameters    `void foo(int x, int y);`                      `fn foo(x: c_int, y: c_int);`
 215 in-out pointers        `void foo(const int* in_ptr, int* out_ptr);`   `fn foo(in_ptr: *c_int, out_ptr: *mut c_int);`
 216
 217 Note: The Rust signatures should be wrapped in an `extern "ABI" { ... }` block.
 218
 219 ### Representing opaque handles
 220
 221 You might see things like this in C APIs:
 222
 223 ~~~ {.notrust}
 224 typedef struct Window Window;
 225 Window* createWindow(int width, int height);
 226 ~~~
 227
 228 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:
 229
 230 ~~~ {.ignore}
 231 enum Window {}
 232 extern "C" {
 233     fn createWindow(width: c_int, height: c_int) -> *Window;
 234 }
 235 ~~~
 236
 237 Using a phantom type ensures that the handles cannot be (safely) constructed in client code.
 238
 239 # Contributing to this page
 240
 241 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.
 242
 243 Similar documents for other programming languages:
 244
 245   * [http://pleac.sourceforge.net/](http://pleac.sourceforge.net)