3 # How do I convert *X* to *Y*?
7 Use [`ToStr`](std/to_str/trait.ToStr.html).
11 let y: String = x.to_str().to_string();
16 Use [`FromStr`](std/from_str/trait.FromStr.html), and its helper function,
17 [`from_str`](std/from_str/fn.from_str.html).
20 let x: Option<int> = from_str("42");
21 let y: int = x.unwrap();
24 **Int to string, in non-base-10**
26 Use the `format!` syntax extension.
30 let y: String = format!("{:t}", x); // binary
31 let y: String = format!("{:o}", x); // octal
32 let y: String = format!("{:x}", x); // lowercase hexadecimal
33 let y: String = format!("{:X}", x); // uppercase hexadecimal
36 **String to int, in non-base-10**
38 Use [`FromStrRadix`](std/num/trait.FromStrRadix.html), and its helper
39 function, [`from_str_radix`](std/num/fn.from_str_radix.html).
44 let x: Option<i64> = num::from_str_radix("deadbeef", 16);
45 let y: i64 = x.unwrap();
48 **Vector of Bytes to String**
50 To return a Borrowed String Slice (&str) use the str helper function
51 [`from_utf8`](std/str/fn.from_utf8.html).
56 let bytes = &[104u8,105u8];
57 let x: &str = str::from_utf8(bytes).unwrap();
60 To return an Owned String use the str helper function
61 [`from_utf8_owned`](std/str/fn.from_utf8_owned.html).
66 let x: Option<String> =
67 str::from_utf8([ 104u8, 105u8 ]).map(|x| x.to_string());
68 let y: String = x.unwrap();
71 To return a [`MaybeOwned`](std/str/type.MaybeOwned.html) use the str helper
72 function [`from_utf8_lossy`](std/str/fn.from_utf8_owned.html).
73 This function also replaces non-valid utf-8 sequences with U+FFFD replacement
79 let x = bytes!(72u8,"ello ",0xF0,0x90,0x80,"World!");
80 let y = str::from_utf8_lossy(x);
85 ## How do I read from a file?
88 [`File::open`](std/io/fs/struct.File.html#method.open)
90 [`File`](std/io/fs/struct.File.html)
91 struct, which implements the
92 [`Reader`](std/io/trait.Reader.html)
97 use std::io::fs::File;
99 let path : Path = Path::new("Doc-FAQ-Cheatsheet.md");
100 let on_error = || fail!("open of {:?} failed", path);
101 let reader : File = File::open(&path).unwrap_or_else(on_error);
104 ## How do I iterate over the lines in a file?
106 Use the [`lines`](std/io/trait.Buffer.html#method.lines) method on a
107 [`BufferedReader`](std/io/struct.BufferedReader.html).
110 use std::io::BufferedReader;
111 # use std::io::MemReader;
113 # let reader = MemReader::new(vec!());
115 let mut reader = BufferedReader::new(reader);
116 for line in reader.lines() {
117 print!("line: {}", line);
123 ## How do I search for a substring?
125 Use the [`find_str`](std/str/trait.StrSlice.html#tymethod.find_str) method.
128 let str = "Hello, this is some random string";
129 let index: Option<uint> = str.find_str("rand");
134 ## How do I get the length of a vector?
136 The [`Container`](std/container/trait.Container.html) trait provides the `len` method.
139 let u: Vec<u32> = vec![0, 1, 2];
140 let v: &[u32] = &[0, 1, 2, 3];
141 let w: [u32, .. 5] = [0, 1, 2, 3, 4];
143 println!("u: {}, v: {}, w: {}", u.len(), v.len(), w.len()); // 3, 4, 5
146 ## How do I iterate over a vector?
148 Use the [`iter`](std/slice/trait.ImmutableVector.html#tymethod.iter) method.
151 let values: Vec<int> = vec![1, 2, 3, 4, 5];
152 for value in values.iter() { // value: &int
153 println!("{}", *value);
157 (See also [`mut_iter`](std/slice/trait.MutableVector.html#tymethod.mut_iter)
158 which yields `&mut int` and
159 [`move_iter`](std/slice/trait.OwnedVector.html#tymethod.move_iter) which yields
160 `int` while consuming the `values` vector.)
164 ## How do I store a function in a struct?
168 myfunc: fn(int, uint) -> i32
171 struct FooClosure<'a> {
172 myfunc: |int, uint|: 'a -> i32
175 fn a(a: int, b: uint) -> i32 {
176 (a as uint + b) as i32
180 let f = Foo { myfunc: a };
181 let g = FooClosure { myfunc: |a, b| { (a - b as int) as i32 } };
182 println!("{}", (f.myfunc)(1, 2));
183 println!("{}", (g.myfunc)(3, 4));
187 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.
189 ## How do I express phantom types?
191 [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:
198 Phantom types are useful for enforcing state at compile time. For example:
201 struct Door<State>(String);
206 fn close(Door(name): Door<Open>) -> Door<Closed> {
210 fn open(Door(name): Door<Closed>) -> Door<Open> {
214 let _ = close(Door::<Open>("front".to_string()));
217 Attempting to close a closed door is prevented statically:
220 let _ = close(Door::<Closed>("front".to_string())); // error: mismatched types: expected `main::Door<main::Open>` but found `main::Door<main::Closed>`
223 # FFI (Foreign Function Interface)
225 ## C function signature conversions
227 | Description | C signature | Equivalent Rust signature |
228 |---------------------|-----------------------------------------------|------------------------------------------------|
229 | no parameters | `void foo(void);` | `fn foo();` |
230 | return value | `int foo(void);` | `fn foo() -> c_int;` |
231 | function parameters | `void foo(int x, int y);` | `fn foo(x: c_int, y: c_int);` |
232 | in-out pointers | `void foo(const int* in_ptr, int* out_ptr);` | `fn foo(in_ptr: *c_int, out_ptr: *mut c_int);` |
234 Note: The Rust signatures should be wrapped in an `extern "ABI" { ... }` block.
236 ### Representing opaque handles
238 You might see things like this in C APIs:
241 typedef struct Window Window;
242 Window* createWindow(int width, int height);
245 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:
250 fn createWindow(width: c_int, height: c_int) -> *Window;
254 Using a phantom type ensures that the handles cannot be (safely) constructed in client code.
256 # Contributing to this page
258 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.
260 Similar documents for other programming languages:
262 * [http://pleac.sourceforge.net/](http://pleac.sourceforge.net)