diff options
Diffstat (limited to 'src/doc')
43 files changed, 20734 insertions, 0 deletions
diff --git a/src/doc/README.md b/src/doc/README.md new file mode 100644 index 00000000000..9135650c31b --- /dev/null +++ b/src/doc/README.md @@ -0,0 +1,86 @@ +# Dependencies + +[Pandoc](http://johnmacfarlane.net/pandoc/installing.html), a universal +document converter, is required to generate docs as HTML from Rust's +source code. + +[Node.js](http://nodejs.org/) is also required for generating HTML from +the Markdown docs (reference manual, tutorials, etc.) distributed with +this git repository. + +[po4a](http://po4a.alioth.debian.org/) is required for generating translated +docs from the master (English) docs. + +[GNU gettext](http://www.gnu.org/software/gettext/) is required for managing +the translation data. + +# Building + +To generate all the docs, just run `make docs` from the root of the repository. +This will convert the distributed Markdown docs to HTML and generate HTML doc +for the 'std' and 'extra' libraries. + +To generate HTML documentation from one source file/crate, do something like: + +~~~~ +rustdoc --output-dir html-doc/ --output-format html ../src/libstd/path.rs +~~~~ + +(This, of course, requires a working build of the `rustdoc` tool.) + +# Additional notes + +To generate an HTML version of a doc from Markdown without having Node.js +installed, you can do something like: + +~~~~ +pandoc --from=markdown --to=html5 --number-sections -o rust.html rust.md +~~~~ + +(rust.md being the Rust Reference Manual.) + +The syntax for pandoc flavored markdown can be found at: +http://johnmacfarlane.net/pandoc/README.html#pandocs-markdown + +A nice quick reference (for non-pandoc markdown) is at: +http://kramdown.rubyforge.org/quickref.html + +# Notes for translators + +Notice: The procedure described below is a work in progress. We are working on +translation system but the procedure contains some manual operations for now. + +To start the translation for a new language, see po4a.conf at first. + +To generate .pot and .po files, do something like: + +~~~~ +po4a --copyright-holder="The Rust Project Developers" \ + --package-name="Rust" \ + --package-version="0.10-pre" \ + -M UTF-8 -L UTF-8 \ + po4a.conf +~~~~ + +(the version number must be changed if it is not 0.10-pre now.) + +Now you can translate documents with .po files, commonly used with gettext. If +you are not familiar with gettext-based translation, please read the online +manual linked from http://www.gnu.org/software/gettext/ . We use UTF-8 as the +file encoding of .po files. + +When you want to make a commit, do the command below before staging your +change: + +~~~~ +for f in doc/po/**/*.po; do + msgattrib --translated $f -o $f.strip + if [ -e $f.strip ]; then + mv $f.strip $f + else + rm $f + fi +done +~~~~ + +This removes untranslated entries from .po files to save disk space. diff --git a/src/doc/complement-bugreport.md b/src/doc/complement-bugreport.md new file mode 100644 index 00000000000..d84d720871d --- /dev/null +++ b/src/doc/complement-bugreport.md @@ -0,0 +1,46 @@ +% How to submit a Rust bug report + +# I think I found a bug in the compiler! + +If you see this message: `error: internal compiler error: unexpected failure`, +then you have definitely found a bug in the compiler. It's also possible that +your code is not well-typed, but if you saw this message, it's still a bug in +error reporting. + +If you see a message about an LLVM assertion failure, then you have also +definitely found a bug in the compiler. In both of these cases, it's not your +fault and you should report a bug! + +If you see a compiler error message that you think is meant for users to see, +but it confuses you, *that's a bug too*. If it wasn't clear to you, then it's +an error message we want to improve, so please report it so that we can try +to make it better. + +# How do I know the bug I found isn't a bug that already exists in the issue tracker? + +If you don't have enough time for a search, then don't worry about that. Just submit +the bug. If it's a duplicate, somebody will notice that and close it during triage. + +If you have the time for it, it would be useful to type the text of the error +message you got [into the issue tracker search box](https://github.com/mozilla/rust/issues) +to see if there's an existing bug that resembles your problem. If there is, +and it's an open bug, you can comment on that issue and say you are also affected. +This will encourage the devs to fix it. But again, don't let this stop you from +submitting a bug. We'd rather have to do the work of closing duplicates than +miss out on valid bug reports. + +# What information should I include in a bug report? + +It generally helps our diagnosis to include your specific OS (for example: Mac OS X 10.8.3, +Windows 7, Ubuntu 12.04) and your hardware architecture (for example: i686, x86_64). +It's also helpful to copy/paste the output of re-running the erroneous rustc +command with the `-v` flag. Finally, if you can run the offending command under gdb, +pasting a stack trace can be useful; to do so, you will need to set a breakpoint on `rust_fail`. + +# I submitted a bug, but nobody has commented on it! + +This is sad, but does happen sometimes, since we're short-staffed. If you +submit a bug and you haven't received a comment on it within 3 business days, +it's entirely reasonable to either ask on the #rust IRC channel, +or post on the [rust-dev mailing list](https://mail.mozilla.org/listinfo/rust-dev) +to ask what the status of the bug is. diff --git a/src/doc/complement-cheatsheet.md b/src/doc/complement-cheatsheet.md new file mode 100644 index 00000000000..a92980d5e70 --- /dev/null +++ b/src/doc/complement-cheatsheet.md @@ -0,0 +1,214 @@ +% Rust Cheatsheet + +# How do I convert *X* to *Y*? + +**Int to string** + +Use [`ToStr`](http://static.rust-lang.org/doc/master/std/to_str/trait.ToStr.html). + +~~~ +let x: int = 42; +let y: ~str = x.to_str(); +~~~ + +**String to int** + +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). + +~~~ +let x: Option<int> = from_str("42"); +let y: int = x.unwrap(); +~~~ + +**Int to string, in non-base-10** + +Use [`ToStrRadix`](http://static.rust-lang.org/doc/master/std/num/trait.ToStrRadix.html). + +~~~ +use std::num::ToStrRadix; + +let x: int = 42; +let y: ~str = x.to_str_radix(16); +~~~ + +**String to int, in non-base-10** + +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). + +~~~ +use std::num::from_str_radix; + +let x: Option<i64> = from_str_radix("deadbeef", 16); +let y: i64 = x.unwrap(); +~~~ + +# File operations + +## How do I read from a file? + +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. + +~~~ {.ignore} +use std::path::Path; +use std::io::fs::File; + +let path : Path = Path::new("Doc-FAQ-Cheatsheet.md"); +let on_error = || fail!("open of {:?} failed", path); +let reader : File = File::open(&path).unwrap_or_else(on_error); +~~~ + +## How do I iterate over the lines in a file? + +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). + +~~~ +use std::io::BufferedReader; +# use std::io::MemReader; + +# let reader = MemReader::new(~[]); + +let mut reader = BufferedReader::new(reader); +for line in reader.lines() { + print!("line: {}", line); +} +~~~ + +# String operations + +## How do I search for a substring? + +Use the [`find_str`](http://static.rust-lang.org/doc/master/std/str/trait.StrSlice.html#tymethod.find_str) method. + +~~~ +let str = "Hello, this is some random string"; +let index: Option<uint> = str.find_str("rand"); +~~~ + +# Containers + +## How do I get the length of a vector? + +The [`Container`](http://static.rust-lang.org/doc/master/std/container/trait.Container.html) trait provides the `len` method. + +~~~ +let u: ~[u32] = ~[0, 1, 2]; +let v: &[u32] = &[0, 1, 2, 3]; +let w: [u32, .. 5] = [0, 1, 2, 3, 4]; + +println!("u: {}, v: {}, w: {}", u.len(), v.len(), w.len()); // 3, 4, 5 +~~~ + +## How do I iterate over a vector? + +Use the [`iter`](http://static.rust-lang.org/doc/master/std/vec/trait.ImmutableVector.html#tymethod.iter) method. + +~~~ +let values: ~[int] = ~[1, 2, 3, 4, 5]; +for value in values.iter() { // value: &int + println!("{}", *value); +} +~~~ + +(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.) + +# Type system + +## How do I store a function in a struct? + +~~~ +struct Foo { + myfunc: fn(int, uint) -> i32 +} + +struct FooClosure<'a> { + myfunc: 'a |int, uint| -> i32 +} + +fn a(a: int, b: uint) -> i32 { + (a as uint + b) as i32 +} + +fn main() { + let f = Foo { myfunc: a }; + let g = FooClosure { myfunc: |a, b| { (a - b as int) as i32 } }; + println!("{}", (f.myfunc)(1, 2)); + println!("{}", (g.myfunc)(3, 4)); +} +~~~ + +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. + +## How do I express phantom types? + +[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: + +~~~ +enum Open {} +enum Closed {} +~~~ + +Phantom types are useful for enforcing state at compile time. For example: + +~~~ +struct Door<State>(~str); + +struct Open; +struct Closed; + +fn close(Door(name): Door<Open>) -> Door<Closed> { + Door::<Closed>(name) +} + +fn open(Door(name): Door<Closed>) -> Door<Open> { + Door::<Open>(name) +} + +let _ = close(Door::<Open>(~"front")); +~~~ + +Attempting to close a closed door is prevented statically: + +~~~ {.ignore} +let _ = close(Door::<Closed>(~"front")); // error: mismatched types: expected `main::Door<main::Open>` but found `main::Door<main::Closed>` +~~~ + +# FFI (Foreign Function Interface) + +## C function signature conversions + +Description C signature Equivalent Rust signature +---------------------- ---------------------------------------------- ------------------------------------------ +no parameters `void foo(void);` `fn foo();` +return value `int foo(void);` `fn foo() -> c_int;` +function parameters `void foo(int x, int y);` `fn foo(x: int, y: int);` +in-out pointers `void foo(const int* in_ptr, int* out_ptr);` `fn foo(in_ptr: *c_int, out_ptr: *mut c_int);` + +Note: The Rust signatures should be wrapped in an `extern "ABI" { ... }` block. + +### Representing opaque handles + +You might see things like this in C APIs: + +~~~ {.notrust} +typedef struct Window Window; +Window* createWindow(int width, int height); +~~~ + +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: + +~~~ {.ignore} +enum Window {} +extern "C" { + fn createWindow(width: c_int, height: c_int) -> *Window; +} +~~~ + +Using a phantom type ensures that the handles cannot be (safely) constructed in client code. + +# Contributing to this page + +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. + +Similar documents for other programming languages: + + * [http://pleac.sourceforge.net/](http://pleac.sourceforge.net) diff --git a/src/doc/complement-lang-faq.md b/src/doc/complement-lang-faq.md new file mode 100644 index 00000000000..3572a411e0a --- /dev/null +++ b/src/doc/complement-lang-faq.md @@ -0,0 +1,247 @@ +% Language FAQ + +# General language issues + +## Safety oriented + +* Memory safe: no null pointers, dangling pointers, use-before-initialize or use-after-move +* Expressive mutability control. Immutable by default, statically verified freezing for Owned types +* No shared mutable state across tasks +* Dynamic execution safety: task failure / unwinding, trapping, RAII / dtors +* Safe interior pointer types with lifetime analysis + +## Concurrency and efficiency oriented + +* Lightweight tasks (coroutines) with expanding stacks +* Fast asynchronous, copyless message passing +* Optional garbage collected pointers +* All types may be explicitly allocated on the stack or interior to other types +* Static, native compilation using LLVM +* Direct and simple interface to C code + +## Practicality oriented + +* Multi-paradigm: pure-functional, concurrent-actor, imperative-procedural, OO + * First-class functions, cheap non-escaping closures + * Algebraic data types (called enums) with pattern matching + * Method implementations on any type + * Traits, which share aspects of type classes and interfaces +* Multi-platform. Developed on Windows, Linux, OS X +* UTF-8 strings, assortment of machine-level types +* Works with existing native toolchains, GDB, Valgrind, Instruments, etc +* Rule-breaking is allowed if explicit about where and how + +## What does it look like? + +The syntax is still evolving, but here's a snippet from the hash map in core::hashmap. + +~~~ +struct LinearMap<K,V> { + k0: u64, + k1: u64, + resize_at: uint, + size: uint, + buckets: ~[Option<Bucket<K,V>>], +} + +enum SearchResult { + FoundEntry(uint), FoundHole(uint), TableFull +} + +fn linear_map_with_capacity<K:Eq + Hash,V>(capacity: uint) -> LinearMap<K,V> { + let r = rand::Rng(); + linear_map_with_capacity_and_keys(r.gen_u64(), r.gen_u64(), capacity) +} + +impl<K:Hash + IterBytes + Eq, V> LinearMap<K,V> { + + fn contains_key(&self, k: &K) -> bool { + match self.bucket_for_key(self.buckets, k) { + FoundEntry(_) => true, + TableFull | FoundHole(_) => false + } + } + + fn clear(&mut self) { + for bkt in self.buckets.mut_iter() { + *bkt = None; + } + self.size = 0; + } + +... +} +~~~ + +## Are there any big programs written in it yet? I want to read big samples. + +There aren't many large programs yet. The Rust [compiler][rustc], 60,000+ lines at the time of writing, is written in Rust. As the oldest body of Rust code it has gone through many iterations of the language, and some parts are nicer to look at than others. It may not be the best code to learn from, but [borrowck] and [resolve] were written recently. + +[rustc]: https://github.com/mozilla/rust/tree/master/src/librustc +[resolve]: https://github.com/mozilla/rust/blob/master/src/librustc/middle/resolve.rs +[borrowck]: https://github.com/mozilla/rust/blob/master/src/librustc/middle/borrowck/ + +A research browser engine called [Servo][servo], currently 30,000+ lines across more than a dozen crates, will be exercising a lot of Rust's distinctive type-system and concurrency features, and integrating many native libraries. + +[servo]: https://github.com/mozilla/servo + +Some examples that demonstrate different aspects of the language: + +* [sprocketnes], an NES emulator with no GC, using modern Rust conventions +* The language's general-purpose [hash] function, SipHash-2-4. Bit twiddling, OO, macros +* The standard library's [HashMap], a sendable hash map in an OO style +* The extra library's [json] module. Enums and pattern matching + +[sprocketnes]: https://github.com/pcwalton/sprocketnes +[hash]: https://github.com/mozilla/rust/blob/master/src/libstd/hash.rs +[HashMap]: https://github.com/mozilla/rust/blob/master/src/libstd/hashmap.rs +[json]: https://github.com/mozilla/rust/blob/master/src/libextra/json.rs + +You may also be interested in browsing [GitHub's Rust][github-rust] page. + +[github-rust]: https://github.com/languages/Rust + +## Does it run on Windows? + +Yes. All development happens in lock-step on all 3 target platforms. Using MinGW, not Cygwin. Note that the windows implementation currently has some limitations: in particular tasks [cannot unwind on windows][unwind], and all Rust executables [require a MinGW installation at runtime][libgcc]. + +[unwind]: https://github.com/mozilla/rust/issues/908 +[libgcc]: https://github.com/mozilla/rust/issues/1603 + +## Have you seen this Google language, Go? How does Rust compare? + +Rust and Go have similar syntax and task models, but they have very different type systems. Rust is distinguished by greater type safety and memory safety guarantees, more control over memory layout, and robust generics. + +Rust has several key features that aren't shared by Go: + +* No shared mutable state - Shared mutable state allows data races, a large class of bad bugs. In Rust there is no sharing of mutable data, but ownership of data can be efficiently transferred between tasks. +* Minimal GC impact - By not having shared mutable data, Rust can avoid global GC, hence Rust never stops the world to collect garbage. With multiple allocation options, individual tasks can completely avoid GC. +* No null pointers - Accidentally dereferencing null pointers is a big bummer, so Rust doesn't have them. +* Type parametric code - Generics prove useful time and again, though they are inevitably complex to greater or lesser degrees. + +Some of Rust's advantages come at the cost of a more intricate type system than Go's. + +Go has its own strengths and in particular has a great user experience that Rust still lacks. + +## I like the language but it really needs _$somefeature_. + +At this point we are focusing on removing and stabilizing features rather than adding them. File a bug if you think it's important in terms of meeting the existing goals or making the language passably usable. Reductions are more interesting than additions, though. + +# Specific language issues + +## Is it OO? How do I do this thing I normally do in an OO language? + +It is multi-paradigm. Not everything is shoe-horned into a single abstraction. Many things you can do in OO languages you can do in Rust, but not everything, and not always using the same abstraction you're accustomed to. + +## How do you get away with "no null pointers"? + +Data values in the language can only be constructed through a fixed set of initializer forms. Each of those forms requires that its inputs already be initialized. A liveness analysis ensures that local variables are initialized before use. + +## What is the relationship between a module and a crate? + +* A crate is a top-level compilation unit that corresponds to a single loadable object. +* A module is a (possibly nested) unit of name-management inside a crate. +* A crate contains an implicit, un-named top-level module. +* Recursive definitions can span modules, but not crates. +* Crates do not have global names, only a set of non-unique metadata tags. +* There is no global inter-crate namespace; all name management occurs within a crate. + * Using another crate binds the root of _its_ namespace into the user's namespace. + +## Why is failure unwinding non-recoverable within a task? Why not try to "catch exceptions"? + +In short, because too few guarantees could be made about the dynamic environment of the catch block, as well as invariants holding in the unwound heap, to be able to safely resume; we believe that other methods of signalling and logging errors are more appropriate, with tasks playing the role of a "hard" isolation boundary between separate heaps. + +Rust provides, instead, three predictable and well-defined options for handling any combination of the three main categories of "catch" logic: + +* Failure _logging_ is done by the integrated logging subsystem. +* _Recovery_ after a failure is done by trapping a task failure from _outside_ the task, where other tasks are known to be unaffected. +* _Cleanup_ of resources is done by RAII-style objects with destructors. + +Cleanup through RAII-style destructors is more likely to work than in catch blocks anyways, since it will be better tested (part of the non-error control paths, so executed all the time). + +## Why aren't modules type-parametric? + +We want to maintain the option to parametrize at runtime. We may make eventually change this limitation, but initially this is how type parameters were implemented. + +## Why aren't values type-parametric? Why only items? + +Doing so would make type inference much more complex, and require the implementation strategy of runtime parametrization. + +## Why are enumerations nominal and closed? + +We don't know if there's an obvious, easy, efficient, stock-textbook way of supporting open or structural disjoint unions. We prefer to stick to language features that have an obvious and well-explored semantics. + +## Why aren't channels synchronous? + +There's a lot of debate on this topic; it's easy to find a proponent of default-sync or default-async communication, and there are good reasons for either. Our choice rests on the following arguments: + +* Part of the point of isolating tasks is to decouple tasks from one another, such that assumptions in one task do not cause undue constraints (or bugs, if violated!) in another. Temporal coupling is as real as any other kind; async-by-default relaxes the default case to only _causal_ coupling. +* Default-async supports buffering and batching communication, reducing the frequency and severity of task-switching and inter-task / inter-domain synchronization. +* Default-async with transmittable channels is the lowest-level building block on which more-complex synchronization topologies and strategies can be built; it is not clear to us that the majority of cases fit the 2-party full-synchronization pattern rather than some more complex multi-party or multi-stage scenario. We did not want to force all programs to pay for wiring the former assumption into all communications. + +## Why are channels half-duplex (one-way)? + +Similar to the reasoning about default-sync: it wires fewer assumptions into the implementation, that would have to be paid by all use-cases even if they actually require a more complex communication topology. + +## Why are strings UTF-8 by default? Why not UCS2 or UCS4? + +The `str` type is UTF-8 because we observe more text in the wild in this encoding -- particularly in network transmissions, which are endian-agnostic -- and we think it's best that the default treatment of I/O not involve having to recode codepoints in each direction. + +This does mean that indexed access to a Unicode codepoint inside a `str` value is an O(n) operation. On the one hand, this is clearly undesirable; on the other hand, this problem is full of trade-offs and we'd like to point a few important qualifications: + +* Scanning a `str` for ASCII-range codepoints can still be done safely octet-at-a-time, with each indexing operation pulling out a `u8` costing only O(1) and producing a value that can be cast and compared to an ASCII-range `char`. So if you're (say) line-breaking on `'\n'`, octet-based treatment still works. UTF8 was well-designed this way. +* Most "character oriented" operations on text only work under very restricted language assumptions sets such as "ASCII-range codepoints only". Outside ASCII-range, you tend to have to use a complex (non-constant-time) algorithm for determining linguistic-unit (glyph, word, paragraph) boundaries anyways. We recommend using an "honest" linguistically-aware, Unicode-approved algorithm. +* The `char` type is UCS4. If you honestly need to do a codepoint-at-a-time algorithm, it's trivial to write a `type wstr = [char]`, and unpack a `str` into it in a single pass, then work with the `wstr`. In other words: the fact that the language is not "decoding to UCS4 by default" shouldn't stop you from decoding (or re-encoding any other way) if you need to work with that encoding. + +## Why are strings, vectors etc. built-in types rather than (say) special kinds of trait/impl? + +In each case there is one or more operator, literal constructor, overloaded use or integration with a built-in control structure that makes us think it would be awkward to phrase the type in terms of more-general type constructors. Same as, say, with numbers! But this is partly an aesthetic call, and we'd be willing to look at a worked-out proposal for eliminating or rephrasing these special cases. + +## Can Rust code call C code? + +Yes. Since C code typically expects a larger stack than Rust code does, the stack may grow before the call. The Rust domain owning the task that makes the call will block for the duration of the call, so if the call is likely to be long-lasting, you should consider putting the task in its own domain (thread or process). + +## Can C code call Rust code? + +Yes. The Rust code has to be exposed via an `extern` declaration, which makes it C-ABI compatible. Its address can then be taken and passed to C code. When C calls Rust back, the callback occurs in very restricted circumstances. + +## How do Rust's task stacks work? + +They start small (ideally in the hundreds of bytes) and expand dynamically by calling through special frames that allocate new stack segments. This is known as the "spaghetti stack" approach. + +## What is the difference between a managed box pointer (`@`) and an owned box pointer (`~`)? + +* Managed boxes live in the garbage collected task-local heap +* Owned boxes live in the global exchange heap +* Managed boxes may be referred to by multiple managed box references +* Owned boxes have unique ownership and there may only be a single unique pointer to a unique box at a time +* Managed boxes may not be shared between tasks +* Owned boxes may be transferred (moved) between tasks + +## What is the difference between a reference (`&`) and managed and owned boxes? + +* References point to the interior of a stack _or_ heap allocation +* References can only be formed when it will provably be outlived by the referent +* References to managed box pointers keep the managed boxes alive +* References to owned boxes prevent their ownership from being transferred +* References employ region-based alias analysis to ensure correctness + +## Why aren't function signatures inferred? Why only local slots? + +* Mechanically, it simplifies the inference algorithm; inference only requires looking at one function at a time. +* The same simplification goes double for human readers. A reader does not need an IDE running an inference algorithm across an entire crate to be able to guess at a function's argument types; it's always explicit and nearby. +* Parameters in Rust can be passed by reference or by value. We can't automatically infer which one the programmer means. + +## Why does a type parameter need explicit trait bounds to invoke methods on it, when C++ templates do not? + +* Requiring explicit bounds means that the compiler can type-check the code at the point where the type-parametric item is *defined*, rather than delaying to when its type parameters are instantiated. You know that *any* set of type parameters fulfilling the bounds listed in the API will compile. It's an enforced minimal level of documentation, and results in very clean error messages. + +* Scoping of methods is also a problem. C++ needs [Koenig (argument dependent) lookup](http://en.wikipedia.org/wiki/Argument-dependent_name_lookup), which comes with its own host of problems. Explicit bounds avoid this issue: traits are explicitly imported and then used as bounds on type parameters, so there is a clear mapping from the method to its implementation (via the trait and the instantiated type). + + * Related to the above point: since a parameter explicitly names its trait bounds, a single type is able to implement traits whose sets of method names overlap, cleanly and unambiguously. + +* There is further discussion on [this thread on the Rust mailing list](https://mail.mozilla.org/pipermail/rust-dev/2013-September/005603.html). + +## Will Rust implement automatic semicolon insertion, like in Go? + +For simplicity, we do not plan to do so. Implementing automatic semicolon insertion for Rust would be tricky because the absence of a trailing semicolon means "return a value". diff --git a/src/doc/complement-project-faq.md b/src/doc/complement-project-faq.md new file mode 100644 index 00000000000..8665644c1f1 --- /dev/null +++ b/src/doc/complement-project-faq.md @@ -0,0 +1,68 @@ +% Project FAQ + +# What is this project's goal, in one sentence? + +To design and implement a safe, concurrent, practical, static systems language. + +# Why are you doing this? + +Existing languages at this level of abstraction and efficiency are unsatisfactory. In particular: + +* Too little attention paid to safety. +* Poor concurrency support. +* Lack of practical affordances, too dogmatic about paradigm. + +# What are some non-goals? + +* To employ any particularly cutting-edge technologies. Old, established techniques are better. +* To prize expressiveness, minimalism or elegance above other goals. These are desirable but subordinate goals. +* To cover the "systems language" part all the way down to "writing an OS kernel". +* To cover the complete feature-set of C++, or any other language. It should provide majority-case features. +* To be 100% static, 100% safe, 100% reflective, or too dogmatic in any other sense. Trade-offs exist. +* To run on "every possible platform". It must eventually work without unnecessary compromises on widely-used hardware and software platforms. + +# Is any part of this thing production-ready? + +No. Feel free to play around, but don't expect completeness or stability yet. Expect incompleteness and breakage. + +What exists presently is: + +* A self-hosted (written in Rust) compiler, which uses LLVM as a backend. +* A runtime library. +* An evolving standard library. +* Documentation for the language and libraries. +* Incomplete tools for packaging and documentation. +* A test suite covering the compiler and libraries. + +# Is this a completely Mozilla-planned and orchestrated thing? + +No. It started as a part-time side project in 2006 and remained so for over 3 years. Mozilla got involved in 2009 once the language was mature enough to run some basic tests and demonstrate the idea. + +# Why did you do so much work in private? + +* A certain amount of shyness. Language work is somewhat political and flame-inducing. +* Languages designed by committee have a poor track record. Design coherence is important. There were a lot of details to work out and the initial developer (Graydon) had this full time job thing eating up most days. + +# Why publish it now? + +* The design is stable enough. All the major pieces have reached non-imaginary, initial implementation status. It seems to hold together ok. +* Languages solely implemented and supported by one person _also_ have a poor track record. To survive it'll need help. + +# What will Mozilla use Rust for? + +Mozilla intends to use Rust as a platform for prototyping experimental browser architectures. Specifically, the hope is to develop a browser that is more amenable to parallelization than existing ones, while also being less prone to common C++ coding errors. The name of that project is _[Servo](http://github.com/mozilla/servo)_. + +# Are you going to use this to suddenly rewrite the browser and change everything? Is the Mozilla Corporation trying to force the community to use a new language? + +No. This is a research project. The point is to explore ideas. There is no plan to incorporate any Rust-based technology into Firefox. + +# Why GitHub rather than the normal Mozilla setup (Mercurial / Bugzilla / Tinderbox)? + +* This is a fresh codebase and has no existing ties to Mozilla infrastructure; there is no particular advantage to (re)using any of the above infrastructure, it would all have to be upgraded and adapted to our needs. +* Git has been progressing rapidly in the years since Mozilla picked Mercurial for its main development needs, and appears to be both more widely known and more accessible at this point. +* This reduces the administrative requirements for contributing to merely establishing a paper trail via a contributor agreement. There is no need for vouching, granting commit access to Mozilla facilities, or setting up Mozilla user accounts. + +# Why a BSD-style license rather than MPL or tri-license? + +* Partly due to preference of the original developer (Graydon). +* Partly due to the fact that languages tend to have a wider audience and more diverse set of possible embeddings and end-uses than focused, coherent products such as web browsers. We'd like to appeal to as many of those potential contributors as possible. diff --git a/src/doc/complement-usage-faq.md b/src/doc/complement-usage-faq.md new file mode 100644 index 00000000000..aca7d833849 --- /dev/null +++ b/src/doc/complement-usage-faq.md @@ -0,0 +1,31 @@ +% Usage FAQ + +# How do I get my program to display the output of `log` statements? + +**Short answer** set the RUST_LOG environment variable to the name of your source file, sans extension. + +```sh +rustc hello.rs +export RUST_LOG=hello +./hello +``` + +**Long answer** RUST_LOG takes a 'logging spec' that consists of a comma-separated list of paths, where a path consists of the crate name and sequence of module names, each separated by double-colons. For standalone .rs files the crate is implicitly named after the source file, so in the above example we were setting RUST_LOG to the name of the hello crate. Multiple paths can be combined to control the exact logging you want to see. For example, when debugging linking in the compiler you might set `RUST_LOG=rustc::metadata::creader,rustc::util::filesearch,rustc::back::rpath` + +If you aren't sure which paths you need, try setting RUST_LOG to `::help` and running your program. This will print a list of paths available for logging. For a full description see [the language reference][1]. + +[1]:http://doc.rust-lang.org/doc/master/rust.html#logging-system + +# How do I get my program to display the output of `debug!` statements? + +This is much like the answer for `log` statements, except that you also need to compile your program in debug mode (that is, pass `--cfg debug` to `rustc`). Note that if you want to see the instrumentation of the `debug!` statements within `rustc` itself, you need a debug version of `rustc`; you can get one by invoking `configure` with the `--enable-debug` option. + +# What does it mean when a program exits with `leaked memory`? + +The error looks like this: `leaked memory in rust main loop (2 objects)' failed, rt/memory_region.cpp:99 2 objects`. + +This message indicates a memory leak, and is mostly likely to happen on rarely exercised failure paths. Note that failure unwinding is not yet implemented on windows so this is expected. If you see this on Linux or Mac it's a compiler bug; please report it. + +# Why did my build create a bunch of zero-length files in my lib directory? + +This is a normal part of the Rust build process. The build system uses these zero-length files for dependency tracking, as the actual names of the Rust libraries contain hashes that can't be guessed easily by the Makefiles. diff --git a/src/doc/favicon.inc b/src/doc/favicon.inc new file mode 100644 index 00000000000..8dd05620e48 --- /dev/null +++ b/src/doc/favicon.inc @@ -0,0 +1 @@ +<link rel="shortcut icon" href="http://www.rust-lang.org/favicon.ico" /> \ No newline at end of file diff --git a/src/doc/full-toc.inc b/src/doc/full-toc.inc new file mode 100644 index 00000000000..35681f1796d --- /dev/null +++ b/src/doc/full-toc.inc @@ -0,0 +1,10 @@ +<style> + /* Display the full TOC */ + #TOC ul ul { + display: block; + padding-left: 2em; + } + #influences blockquote p:last-child { + color: #999; + } +</style> diff --git a/src/doc/guide-conditions.md b/src/doc/guide-conditions.md new file mode 100644 index 00000000000..d97de779902 --- /dev/null +++ b/src/doc/guide-conditions.md @@ -0,0 +1,844 @@ +% The Rust Condition and Error-handling Guide + +# Introduction + +Rust does not provide exception handling[^why-no-exceptions] +in the form most commonly seen in other programming languages such as C++ or Java. +Instead, it provides four mechanisms that work together to handle errors or other rare events. +The four mechanisms are: + + - Options + - Results + - Failure + - Conditions + +This guide will lead you through use of these mechanisms +in order to understand the trade-offs of each and relationships between them. + +# Example program + +This guide will be based around an example program +that attempts to read lines from a file +consisting of pairs of numbers, +and then print them back out with slightly different formatting. +The input to the program might look like this: + +~~~~ {.notrust} +$ cat numbers.txt +1 2 +34 56 +789 123 +45 67 +~~~~ + +For which the intended output looks like this: + +~~~~ {.notrust} +$ ./example numbers.txt +0001, 0002 +0034, 0056 +0789, 0123 +0045, 0067 +~~~~ + +An example program that does this task reads like this: + +~~~~ +# #[allow(unused_imports)]; +use std::io::{BufferedReader, File}; +# mod BufferedReader { +# use std::io::File; +# use std::io::MemReader; +# use std::io::BufferedReader; +# static s : &'static [u8] = bytes!("1 2\n\ +# 34 56\n\ +# 789 123\n\ +# 45 67\n\ +# "); +# pub fn new(_inner: Option<File>) -> BufferedReader<MemReader> { +# BufferedReader::new(MemReader::new(s.to_owned())) +# } +# } + +fn main() { + let pairs = read_int_pairs(); + for &(a,b) in pairs.iter() { + println!("{:4.4d}, {:4.4d}", a, b); + } +} + +fn read_int_pairs() -> ~[(int,int)] { + let mut pairs = ~[]; + + // Path takes a generic by-value, rather than by reference +# let _g = std::io::ignore_io_error(); + let path = Path::new(&"foo.txt"); + let mut reader = BufferedReader::new(File::open(&path)); + + // 1. Iterate over the lines of our file. + for line in reader.lines() { + // 2. Split the line into fields ("words"). + let fields = line.words().to_owned_vec(); + // 3. Match the vector of fields against a vector pattern. + match fields { + + // 4. When the line had two fields: + [a, b] => { + // 5. Try parsing both fields as ints. + match (from_str::<int>(a), from_str::<int>(b)) { + + // 6. If parsing succeeded for both, push both. + (Some(a), Some(b)) => pairs.push((a,b)), + // 7. Ignore non-int fields. + _ => () + } + } + // 8. Ignore lines that don't have 2 fields. + _ => () + } + } + pairs +} +~~~~ + +This example shows the use of `Option`, +along with some other forms of error-handling (and non-handling). +We will look at these mechanisms +and then modify parts of the example to perform "better" error handling. + +# Options + +The simplest and most lightweight mechanism in Rust for indicating an error is the type `std::option::Option<T>`. +This type is a general purpose `enum` +for conveying a value of type `T`, represented as `Some(T)` +_or_ the sentinel `None`, to indicate the absence of a `T` value. +For simple APIs, it may be sufficient to encode errors as `Option<T>`, +returning `Some(T)` on success and `None` on error. +In the example program, the call to `from_str::<int>` returns `Option<int>` +with the understanding that "all parse errors" result in `None`. +The resulting `Option<int>` values are matched against the pattern `(Some(a), Some(b))` +in steps 5 and 6 in the example program, +to handle the case in which both fields were parsed successfully. + +Using `Option` as in this API has some advantages: + + - Simple API, users can read it and guess how it works. + - Very efficient, only an extra `enum` tag on return values. + - Caller has flexibility in handling or propagating errors. + - Caller is forced to acknowledge existence of possible-error before using value. + +However, it has serious disadvantages too: + + - Verbose, requires matching results or calling `Option::unwrap` everywhere. + - Infects caller: if caller doesn't know how to handle the error, must propagate (or force). + - Temptation to do just that: force the `Some(T)` case by blindly calling `unwrap`, + which hides the error from the API without providing any way to make the program robust against the error. + - Collapses all errors into one: + - Caller can't handle different errors differently. + - Caller can't even report a very precise error message + +Note that in order to keep the example code reasonably compact, +several unwanted cases are silently ignored: +lines that do not contain two fields, as well as fields that do not parse as ints. +To propagate these cases to the caller using `Option` would require even more verbose code. + +# Results + +Before getting into _trapping_ the error, +we will look at a slight refinement on the `Option` type above. +This second mechanism for indicating an error is called a `Result`. +The type `std::result::Result<T,E>` is another simple `enum` type with two forms, `Ok(T)` and `Err(E)`. +The `Result` type is not substantially different from the `Option` type in terms of its ergonomics. +Its main advantage is that the error constructor `Err(E)` can convey _more detail_ about the error. +For example, the `from_str` API could be reformed +to return a `Result` carrying an informative description of a parse error, +like this: + +~~~~ {.ignore} +enum IntParseErr { + EmptyInput, + Overflow, + BadChar(char) +} + +fn from_str(&str) -> Result<int,IntParseErr> { + // ... +} +~~~~ + +This would give the caller more information for both handling and reporting the error, +but would otherwise retain the verbosity problems of using `Option`. +In particular, it would still be necessary for the caller to return a further `Result` to _its_ caller if it did not want to handle the error. +Manually propagating result values this way can be attractive in certain circumstances +— for example when processing must halt on the very first error, or backtrack — +but as we will see later, many cases have simpler options available. + +# Failure + +The third and arguably easiest mechanism for handling errors is called "failure". +In fact it was hinted at earlier by suggesting that one can choose to propagate `Option` or `Result` types _or "force" them_. +"Forcing" them, in this case, means calling a method like `Option<T>::unwrap`, +which contains the following code: + +~~~~ {.ignore} +pub fn unwrap(self) -> T { + match self { + Some(x) => return x, + None => fail!("option::unwrap `None`") + } +} +~~~~ + +That is, it returns `T` when `self` is `Some(T)`, and _fails_ when `self` is `None`. + +Every Rust task can _fail_, either indirectly due to a kill signal or other asynchronous event, +or directly by failing an `assert!` or calling the `fail!` macro. +Failure is an _unrecoverable event_ at the task level: +it causes the task to halt normal execution and unwind its control stack, +freeing all task-local resources (the local heap as well as any task-owned values from the global heap) +and running destructors (the `drop` method of the `Drop` trait) +as frames are unwound and heap values destroyed. +A failing task is not permitted to "catch" the unwinding during failure and recover, +it is only allowed to clean up and exit. + +Failure has advantages: + + - Simple and non-verbose. Suitable for programs that can't reasonably continue past an error anyways. + - _All_ errors (except memory-safety errors) can be uniformly trapped in a supervisory task outside the failing task. + For a large program to be robust against a variety of errors, + often some form of task-level partitioning to contain pervasive errors (arithmetic overflow, division by zero, + logic bugs) is necessary anyways. + +As well as obvious disadvantages: + + - A blunt instrument, terminates the containing task entirely. + +Recall that in the first two approaches to error handling, +the example program was only handling success cases, and ignoring error cases. +That is, if the input is changed to contain a malformed line: + +~~~~ {.notrust} +$ cat bad.txt +1 2 +34 56 +ostrich +789 123 +45 67 +~~~~ + +Then the program would give the same output as if there was no error: + +~~~~ {.notrust} +$ ./example bad.txt +0001, 0002 +0034, 0056 +0789, 0123 +0045, 0067 +~~~~ + +If the example is rewritten to use failure, these error cases can be trapped. +In this rewriting, failures are trapped by placing the I/O logic in a sub-task, +and trapping its exit status using `task::try`: + +~~~~ +# #[allow(unused_imports)]; +use std::io::{BufferedReader, File}; +use std::task; +# mod BufferedReader { +# use std::io::File; +# use std::io::MemReader; +# use std::io::BufferedReader; +# static s : &'static [u8] = bytes!("1 2\n\ +# 34 56\n\ +# 789 123\n\ +# 45 67\n\ +# "); +# pub fn new(_inner: Option<File>) -> BufferedReader<MemReader> { +# BufferedReader::new(MemReader::new(s.to_owned())) +# } +# } + +fn main() { + + // Isolate failure within a subtask. + let result = task::try(proc() { + + // The protected logic. + let pairs = read_int_pairs(); + for &(a,b) in pairs.iter() { + println!("{:4.4d}, {:4.4d}", a, b); + } + + }); + if result.is_err() { + println!("parsing failed"); + } +} + +fn read_int_pairs() -> ~[(int,int)] { + let mut pairs = ~[]; +# let _g = std::io::ignore_io_error(); + let path = Path::new(&"foo.txt"); + + let mut reader = BufferedReader::new(File::open(&path)); + for line in reader.lines() { + match line.words().to_owned_vec() { + [a, b] => pairs.push((from_str::<int>(a).unwrap(), + from_str::<int>(b).unwrap())), + + // Explicitly fail on malformed lines. + _ => fail!() + } + } + pairs +} +~~~~ + +With these changes in place, running the program on malformed input gives a different answer: + +~~~~ {.notrust} +$ ./example bad.txt +rust: task failed at 'explicit failure', ./example.rs:44 +parsing failed +~~~~ + +Note that while failure unwinds the sub-task performing I/O in `read_int_pairs`, +control returns to `main` and can easily continue uninterrupted. +In this case, control simply prints out `parsing failed` and then exits `main` (successfully). +Failure of a (sub-)task is analogous to calling `exit(1)` or `abort()` in a unix C program: +all the state of a sub-task is cleanly discarded on exit, +and a supervisor task can take appropriate action +without worrying about its own state having been corrupted. + +# Conditions + +The final mechanism for handling errors is called a "condition". +Conditions are less blunt than failure, and less cumbersome than the `Option` or `Result` types; +indeed they are designed to strike just the right balance between the two. +Conditions require some care to use effectively, but give maximum flexibility with minimum verbosity. +While conditions use exception-like terminology ("trap", "raise") they are significantly different: + + - Like exceptions and failure, conditions separate the site at which the error is raised from the site where it is trapped. + - Unlike exceptions and unlike failure, when a condition is raised and trapped, _no unwinding occurs_. + - A successfully trapped condition causes execution to continue _at the site of the error_, as though no error occurred. + +Conditions are declared with the `condition!` macro. +Each condition has a name, an input type and an output type, much like a function. +In fact, conditions are implemented as dynamically-scoped functions held in task local storage. + +The `condition!` macro declares a module with the name of the condition; +the module contains a single static value called `cond`, of type `std::condition::Condition`. +The `cond` value within the module is the rendezvous point +between the site of error and the site that handles the error. +It has two methods of interest: `raise` and `trap`. + +The `raise` method maps a value of the condition's input type to its output type. +The input type should therefore convey all relevant information to the condition handler. +The output type should convey all relevant information _for continuing execution at the site of error_. +When the error site raises a condition handler, +the `Condition::raise` method searches for the innermost installed task-local condition _handler_, +and if any such handler is found, calls it with the provided input value. +If no handler is found, `Condition::raise` will fail the task with an appropriate error message. + +Rewriting the example to use a condition in place of ignoring malformed lines makes it slightly longer, +but similarly clear as the version that used `fail!` in the logic where the error occurs: + +~~~~ +# #[allow(unused_imports)]; +use std::io::{BufferedReader, File}; +# mod BufferedReader { +# use std::io::File; +# use std::io::MemReader; +# use std::io::BufferedReader; +# static s : &'static [u8] = bytes!("1 2\n\ +# 34 56\n\ +# 789 123\n\ +# 45 67\n\ +# "); +# pub fn new(_inner: Option<File>) -> BufferedReader<MemReader> { +# BufferedReader::new(MemReader::new(s.to_owned())) +# } +# } + +// Introduce a new condition. +condition! { + pub malformed_line : ~str -> (int,int); +} + +fn main() { + let pairs = read_int_pairs(); + for &(a,b) in pairs.iter() { + println!("{:4.4d}, {:4.4d}", a, b); + } +} + +fn read_int_pairs() -> ~[(int,int)] { + let mut pairs = ~[]; +# let _g = std::io::ignore_io_error(); + let path = Path::new(&"foo.txt"); + + let mut reader = BufferedReader::new(File::open(&path)); + for line in reader.lines() { + match line.words().to_owned_vec() { + [a, b] => pairs.push((from_str::<int>(a).unwrap(), + from_str::<int>(b).unwrap())), + // On malformed lines, call the condition handler and + // push whatever the condition handler returns. + _ => pairs.push(malformed_line::cond.raise(line.clone())) + } + } + pairs +} +~~~~ + +When this is run on malformed input, it still fails, +but with a slightly different failure message than before: + +~~~~ {.notrust} +$ ./example bad.txt +rust: task failed at 'Unhandled condition: malformed_line: ~"ostrich"', .../libstd/condition.rs:43 +~~~~ + +While this superficially resembles the trapped `fail!` call before, +it is only because the example did not install a handler for the condition. +The different failure message is indicating, among other things, +that the condition-handling system is being invoked and failing +only due to the absence of a _handler_ that traps the condition. + +# Trapping a condition + +To trap a condition, use `Condition::trap` in some caller of the site that calls `Condition::raise`. +For example, this version of the program traps the `malformed_line` condition +and replaces bad input lines with the pair `(-1,-1)`: + +~~~~ +# #[allow(unused_imports)]; +use std::io::{BufferedReader, File}; +# mod BufferedReader { +# use std::io::File; +# use std::io::MemReader; +# use std::io::BufferedReader; +# static s : &'static [u8] = bytes!("1 2\n\ +# 34 56\n\ +# 789 123\n\ +# 45 67\n\ +# "); +# pub fn new(_inner: Option<File>) -> BufferedReader<MemReader> { +# BufferedReader::new(MemReader::new(s.to_owned())) +# } +# } + +condition! { + pub malformed_line : ~str -> (int,int); +} + +fn main() { + // Trap the condition: + malformed_line::cond.trap(|_| (-1,-1)).inside(|| { + + // The protected logic. + let pairs = read_int_pairs(); + for &(a,b) in pairs.iter() { + println!("{:4.4d}, {:4.4d}", a, b); + } + + }) +} + +fn read_int_pairs() -> ~[(int,int)] { + let mut pairs = ~[]; +# let _g = std::io::ignore_io_error(); + let path = Path::new(&"foo.txt"); + + let mut reader = BufferedReader::new(File::open(&path)); + for line in reader.lines() { + match line.words().to_owned_vec() { + [a, b] => pairs.push((from_str::<int>(a).unwrap(), + from_str::<int>(b).unwrap())), + _ => pairs.push(malformed_line::cond.raise(line.clone())) + } + } + pairs +} +~~~~ + +Note that the remainder of the program is _unchanged_ with this trap in place; +only the caller that installs the trap changed. +Yet when the condition-trapping variant runs on the malformed input, +it continues execution past the malformed line, substituting the handler's return value. + +~~~~ {.notrust} +$ ./example bad.txt +0001, 0002 +0034, 0056 +-0001, -0001 +0789, 0123 +0045, 0067 +~~~~ + +# Refining a condition + +As you work with a condition, you may find that the original set of options you present for recovery is insufficient. +This is no different than any other issue of API design: +a condition handler is an API for recovering from the condition, and sometimes APIs need to be enriched. +In the example program, the first form of the `malformed_line` API implicitly assumes that recovery involves a substitute value. +This assumption may not be correct; some callers may wish to skip malformed lines, for example. +Changing the condition's return type from `(int,int)` to `Option<(int,int)>` will suffice to support this type of recovery: + +~~~~ +# #[allow(unused_imports)]; +use std::io::{BufferedReader, File}; +# mod BufferedReader { +# use std::io::File; +# use std::io::MemReader; +# use std::io::BufferedReader; +# static s : &'static [u8] = bytes!("1 2\n\ +# 34 56\n\ +# 789 123\n\ +# 45 67\n\ +# "); +# pub fn new(_inner: Option<File>) -> BufferedReader<MemReader> { +# BufferedReader::new(MemReader::new(s.to_owned())) +# } +# } + +// Modify the condition signature to return an Option. +condition! { + pub malformed_line : ~str -> Option<(int,int)>; +} + +fn main() { + // Trap the condition and return `None` + malformed_line::cond.trap(|_| None).inside(|| { + + // The protected logic. + let pairs = read_int_pairs(); + for &(a,b) in pairs.iter() { + println!("{:4.4d}, {:4.4d}", a, b); + } + + }) +} + +fn read_int_pairs() -> ~[(int,int)] { + let mut pairs = ~[]; +# let _g = std::io::ignore_io_error(); + let path = Path::new(&"foo.txt"); + + let mut reader = BufferedReader::new(File::open(&path)); + for line in reader.lines() { + match line.words().to_owned_vec() { + [a, b] => pairs.push((from_str::<int>(a).unwrap(), + from_str::<int>(b).unwrap())), + + // On malformed lines, call the condition handler and + // either ignore the line (if the handler returns `None`) + // or push any `Some(pair)` value returned instead. + _ => { + match malformed_line::cond.raise(line.clone()) { + Some(pair) => pairs.push(pair), + None => () + } + } + } + } + pairs +} +~~~~ + +Again, note that the remainder of the program is _unchanged_, +in particular the signature of `read_int_pairs` is unchanged, +even though the innermost part of its reading-loop has a new way of handling a malformed line. +When the example is run with the `None` trap in place, +the line is ignored as it was in the first example, +but the choice of whether to ignore or use a substitute value has been moved to some caller, +possibly a distant caller. + +~~~~ {.notrust} +$ ./example bad.txt +0001, 0002 +0034, 0056 +0789, 0123 +0045, 0067 +~~~~ + +# Further refining a condition + +Like with any API, the process of refining argument and return types of a condition will continue, +until all relevant combinations encountered in practice are encoded. +In the example, suppose a third possible recovery form arose: reusing the previous value read. +This can be encoded in the handler API by introducing a helper type: `enum MalformedLineFix`. + +~~~~ +# #[allow(unused_imports)]; +use std::io::{BufferedReader, File}; +# mod BufferedReader { +# use std::io::File; +# use std::io::MemReader; +# use std::io::BufferedReader; +# static s : &'static [u8] = bytes!("1 2\n\ +# 34 56\n\ +# 789 123\n\ +# 45 67\n\ +# "); +# pub fn new(_inner: Option<File>) -> BufferedReader<MemReader> { +# BufferedReader::new(MemReader::new(s.to_owned())) +# } +# } + +// Introduce a new enum to convey condition-handling strategy to error site. +pub enum MalformedLineFix { + UsePair(int,int), + IgnoreLine, + UsePreviousLine +} + +// Modify the condition signature to return the new enum. +// Note: a condition introduces a new module, so the enum must be +// named with the `super::` prefix to access it. +condition! { + pub malformed_line : ~str -> super::MalformedLineFix; +} + +fn main() { + // Trap the condition and return `UsePreviousLine` + malformed_line::cond.trap(|_| UsePreviousLine).inside(|| { + + // The protected logic. + let pairs = read_int_pairs(); + for &(a,b) in pairs.iter() { + println!("{:4.4d}, {:4.4d}", a, b); + } + + }) +} + +fn read_int_pairs() -> ~[(int,int)] { + let mut pairs = ~[]; +# let _g = std::io::ignore_io_error(); + let path = Path::new(&"foo.txt"); + + let mut reader = BufferedReader::new(File::open(&path)); + for line in reader.lines() { + match line.words().to_owned_vec() { + [a, b] => pairs.push((from_str::<int>(a).unwrap(), + from_str::<int>(b).unwrap())), + + // On malformed lines, call the condition handler and + // take action appropriate to the enum value returned. + _ => { + match malformed_line::cond.raise(line.clone()) { + UsePair(a,b) => pairs.push((a,b)), + IgnoreLine => (), + UsePreviousLine => { + let prev = pairs[pairs.len() - 1]; + pairs.push(prev) + } + } + } + } + } + pairs +} +~~~~ + +Running the example with `UsePreviousLine` as the fix code returned from the handler +gives the expected result: + +~~~~ {.notrust} +$ ./example bad.txt +0001, 0002 +0034, 0056 +0034, 0056 +0789, 0123 +0045, 0067 +~~~~ + +At this point the example has a rich variety of recovery options, +none of which is visible to casual users of the `read_int_pairs` function. +This is intentional: part of the purpose of using a condition +is to free intermediate callers from the burden of having to write repetitive error-propagation logic, +and/or having to change function call and return types as error-handling strategies are refined. + +# Multiple conditions, intermediate callers + +So far the function trapping the condition and the function raising it have been immediately adjacent in the call stack. +That is, the caller traps and its immediate callee raises. +In most programs, the function that traps may be separated by very many function calls from the function that raises. +Again, this is part of the point of using conditions: +to support that separation without having to thread multiple error values and recovery strategies all the way through the program's main logic. + +Careful readers will notice that there is a remaining failure mode in the example program: the call to `.unwrap()` when parsing each integer. +For example, when presented with a file that has the correct number of fields on a line, +but a non-numeric value in one of them, such as this: + +~~~~ {.notrust} +$ cat bad.txt +1 2 +34 56 +7 marmot +789 123 +45 67 +~~~~ + + +Then the program fails once more: + +~~~~ {.notrust} +$ ./example bad.txt +task <unnamed> failed at 'called `Option::unwrap()` on a `None` value', .../libstd/option.rs:314 +~~~~ + +To make the program robust — or at least flexible — in the face of this potential failure, +a second condition and a helper function will suffice: + +~~~~ +# #[allow(unused_imports)]; +use std::io::{BufferedReader, File}; +# mod BufferedReader { +# use std::io::File; +# use std::io::MemReader; +# use std::io::BufferedReader; +# static s : &'static [u8] = bytes!("1 2\n\ +# 34 56\n\ +# 789 123\n\ +# 45 67\n\ +# "); +# pub fn new(_inner: Option<File>) -> BufferedReader<MemReader> { +# BufferedReader::new(MemReader::new(s.to_owned())) +# } +# } + +pub enum MalformedLineFix { + UsePair(int,int), + IgnoreLine, + UsePreviousLine +} + +condition! { + pub malformed_line : ~str -> ::MalformedLineFix; +} + +// Introduce a second condition. +condition! { + pub malformed_int : ~str -> int; +} + +fn main() { + // Trap the `malformed_int` condition and return -1 + malformed_int::cond.trap(|_| -1).inside(|| { + + // Trap the `malformed_line` condition and return `UsePreviousLine` + malformed_line::cond.trap(|_| UsePreviousLine).inside(|| { + + // The protected logic. + let pairs = read_int_pairs(); + for &(a,b) in pairs.iter() { + println!("{:4.4d}, {:4.4d}", a, b); + } + + }) + }) +} + +// Parse an int; if parsing fails, call the condition handler and +// return whatever it returns. +fn parse_int(x: &str) -> int { + match from_str::<int>(x) { + Some(v) => v, + None => malformed_int::cond.raise(x.to_owned()) + } +} + +fn read_int_pairs() -> ~[(int,int)] { + let mut pairs = ~[]; +# let _g = std::io::ignore_io_error(); + let path = Path::new(&"foo.txt"); + + let mut reader = BufferedReader::new(File::open(&path)); + for line in reader.lines() { + match line.words().to_owned_vec() { + // Delegate parsing ints to helper function that will + // handle parse errors by calling `malformed_int`. + [a, b] => pairs.push((parse_int(a), parse_int(b))), + + _ => { + match malformed_line::cond.raise(line.clone()) { + UsePair(a,b) => pairs.push((a,b)), + IgnoreLine => (), + UsePreviousLine => { + let prev = pairs[pairs.len() - 1]; + pairs.push(prev) + } + } + } + } + } + pairs +} +~~~~ + +Again, note that `read_int_pairs` has not changed signature, +nor has any of the machinery for trapping or raising `malformed_line`, +but now the program can handle the "right number of fields, non-integral field" form of bad input: + +~~~~ {.notrust} +$ ./example bad.txt +0001, 0002 +0034, 0056 +0007, -0001 +0789, 0123 +0045, 0067 +~~~~ + +There are three other things to note in this variant of the example program: + + - It traps multiple conditions simultaneously, + nesting the protected logic of one `trap` call inside the other. + + - There is a function in between the `trap` site and `raise` site for the `malformed_int` condition. + There could be any number of calls between them: + so long as the `raise` occurs within a callee (of any depth) of the logic protected by the `trap` call, + it will invoke the handler. + + - This variant insulates callers from a design choice in the library: + the `from_str` function was designed to return an `Option<int>`, + but this program insulates callers from that choice, + routing all `None` values that arise from parsing integers in this file into the condition. + + +# When to use which technique + +This guide explored several techniques for handling errors. +Each is appropriate to different circumstances: + + - If an error may be extremely frequent, expected, and very likely dealt with by an immediate caller, + then returning an `Option` or `Result` type is best. These types force the caller to handle the error, + and incur the lowest speed overhead, usually only returning one extra word to tag the return value. + Between `Option` and `Result`: use an `Option` when there is only one kind of error, + otherwise make an `enum FooErr` to represent the possible error codes and use `Result<T,FooErr>`. + + - If an error can reasonably be handled at the site it occurs by one of a few strategies — possibly including failure — + and it is not clear which strategy a caller would want to use, a condition is best. + For many errors, the only reasonable "non-stop" recovery strategies are to retry some number of times, + create or substitute an empty or sentinel value, ignore the error, or fail. + + - If an error cannot reasonably be handled at the site it occurs, + and the only reasonable response is to abandon a large set of operations in progress, + then directly failing is best. + +Note that an unhandled condition will cause failure (along with a more-informative-than-usual message), +so if there is any possibility that a caller might wish to "ignore and keep going", +it is usually harmless to use a condition in place of a direct call to `fail!()`. + + +[^why-no-exceptions]: Exceptions in languages like C++ and Java permit unwinding, like Rust's failure system, +but with the option to halt unwinding partway through the process and continue execution. +This behavior unfortunately means that the _heap_ may be left in an inconsistent but accessible state, +if an exception is thrown part way through the process of initializing or modifying memory. +To compensate for this risk, correct C++ and Java code must program in an extremely elaborate and difficult "exception-safe" style +— effectively transactional style against heap structures — +or else risk introducing silent and very difficult-to-debug errors due to control resuming in a corrupted heap after a caught exception. +These errors are frequently memory-safety errors, which Rust strives to eliminate, +and so Rust unwinding is unrecoverable within a single task: +once unwinding starts, the entire local heap of a task is destroyed and the task is terminated. diff --git a/src/doc/guide-container.md b/src/doc/guide-container.md new file mode 100644 index 00000000000..1c79be1eb82 --- /dev/null +++ b/src/doc/guide-container.md @@ -0,0 +1,410 @@ +% The Rust Containers and Iterators Guide + +# Containers + +The container traits are defined in the `std::container` module. + +## Unique vectors + +Vectors have `O(1)` indexing, push (to the end) and pop (from the end). Vectors +are the most common container in Rust, and are flexible enough to fit many use +cases. + +Vectors can also be sorted and used as efficient lookup tables with the +`bsearch()` method, if all the elements are inserted at one time and +deletions are unnecessary. + +## Maps and sets + +Maps are collections of unique keys with corresponding values, and sets are +just unique keys without a corresponding value. The `Map` and `Set` traits in +`std::container` define the basic interface. + +The standard library provides three owned map/set types: + +* `std::hashmap::HashMap` and `std::hashmap::HashSet`, requiring the keys to + implement `Eq` and `Hash` +* `std::trie::TrieMap` and `std::trie::TrieSet`, requiring the keys to be `uint` +* `extra::treemap::TreeMap` and `extra::treemap::TreeSet`, requiring the keys + to implement `TotalOrd` + +These maps do not use managed pointers so they can be sent between tasks as +long as the key and value types are sendable. Neither the key or value type has +to be copyable. + +The `TrieMap` and `TreeMap` maps are ordered, while `HashMap` uses an arbitrary +order. + +Each `HashMap` instance has a random 128-bit key to use with a keyed hash, +making the order of a set of keys in a given hash table randomized. Rust +provides a [SipHash](https://131002.net/siphash/) implementation for any type +implementing the `IterBytes` trait. + +## Double-ended queues + +The `extra::ringbuf` module implements a double-ended queue with `O(1)` +amortized inserts and removals from both ends of the container. It also has +`O(1)` indexing like a vector. The contained elements are not required to be +copyable, and the queue will be sendable if the contained type is sendable. +Its interface `Deque` is defined in `extra::collections`. + +The `extra::dlist` module implements a double-ended linked list, also +implementing the `Deque` trait, with `O(1)` removals and inserts at either end, +and `O(1)` concatenation. + +## Priority queues + +The `extra::priority_queue` module implements a queue ordered by a key. The +contained elements are not required to be copyable, and the queue will be +sendable if the contained type is sendable. + +Insertions have `O(log n)` time complexity and checking or popping the largest +element is `O(1)`. Converting a vector to a priority queue can be done +in-place, and has `O(n)` complexity. A priority queue can also be converted to +a sorted vector in-place, allowing it to be used for an `O(n log n)` in-place +heapsort. + +# Iterators + +## Iteration protocol + +The iteration protocol is defined by the `Iterator` trait in the +`std::iter` module. The minimal implementation of the trait is a `next` +method, yielding the next element from an iterator object: + +~~~ +/// An infinite stream of zeroes +struct ZeroStream; + +impl Iterator<int> for ZeroStream { + fn next(&mut self) -> Option<int> { + Some(0) + } +} +~~~~ + +Reaching the end of the iterator is signalled by returning `None` instead of +`Some(item)`: + +~~~ +# fn main() {} +/// A stream of N zeroes +struct ZeroStream { + remaining: uint +} + +impl ZeroStream { + fn new(n: uint) -> ZeroStream { + ZeroStream { remaining: n } + } +} + +impl Iterator<int> for ZeroStream { + fn next(&mut self) -> Option<int> { + if self.remaining == 0 { + None + } else { + self.remaining -= 1; + Some(0) + } + } +} +~~~ + +In general, you cannot rely on the behavior of the `next()` method after it has +returned `None`. Some iterators may return `None` forever. Others may behave +differently. + +## Container iterators + +Containers implement iteration over the contained elements by returning an +iterator object. For example, vector slices several iterators available: + +* `iter()` and `rev_iter()`, for immutable references to the elements +* `mut_iter()` and `mut_rev_iter()`, for mutable references to the elements +* `move_iter()` and `move_rev_iter()`, to move the elements out by-value + +A typical mutable container will implement at least `iter()`, `mut_iter()` and +`move_iter()` along with the reverse variants if it maintains an order. + +### Freezing + +Unlike most other languages with external iterators, Rust has no *iterator +invalidation*. As long as an iterator is still in scope, the compiler will prevent +modification of the container through another handle. + +~~~ +let mut xs = [1, 2, 3]; +{ + let _it = xs.iter(); + + // the vector is frozen for this scope, the compiler will statically + // prevent modification +} +// the vector becomes unfrozen again at the end of the scope +~~~ + +These semantics are due to most container iterators being implemented with `&` +and `&mut`. + +## Iterator adaptors + +The `Iterator` trait provides many common algorithms as default methods. For +example, the `fold` method will accumulate the items yielded by an `Iterator` +into a single value: + +~~~ +let xs = [1, 9, 2, 3, 14, 12]; +let result = xs.iter().fold(0, |accumulator, item| accumulator - *item); +assert_eq!(result, -41); +~~~ + +Most adaptors return an adaptor object implementing the `Iterator` trait itself: + +~~~ +let xs = [1, 9, 2, 3, 14, 12]; +let ys = [5, 2, 1, 8]; +let sum = xs.iter().chain(ys.iter()).fold(0, |a, b| a + *b); +assert_eq!(sum, 57); +~~~ + +Some iterator adaptors may return `None` before exhausting the underlying +iterator. Additionally, if these iterator adaptors are called again after +returning `None`, they may call their underlying iterator again even if the +adaptor will continue to return `None` forever. This may not be desired if the +underlying iterator has side-effects. + +In order to provide a guarantee about behavior once `None` has been returned, an +iterator adaptor named `fuse()` is provided. This returns an iterator that will +never call its underlying iterator again once `None` has been returned: + +~~~ +let xs = [1,2,3,4,5]; +let mut calls = 0; +let it = xs.iter().scan((), |_, x| { + calls += 1; + if *x < 3 { Some(x) } else { None }}); +// the iterator will only yield 1 and 2 before returning None +// If we were to call it 5 times, calls would end up as 5, despite only 2 values +// being yielded (and therefore 3 unique calls being made). The fuse() adaptor +// can fix this. +let mut it = it.fuse(); +it.next(); +it.next(); +it.next(); +it.next(); +it.next(); +assert_eq!(calls, 3); +~~~ + +## For loops + +The function `range` (or `range_inclusive`) allows to simply iterate through a given range: + +~~~ +for i in range(0, 5) { + print!("{} ", i) // prints "0 1 2 3 4" +} + +for i in std::iter::range_inclusive(0, 5) { // needs explicit import + print!("{} ", i) // prints "0 1 2 3 4 5" +} +~~~ + +The `for` keyword can be used as sugar for iterating through any iterator: + +~~~ +let xs = [2u, 3, 5, 7, 11, 13, 17]; + +// print out all the elements in the vector +for x in xs.iter() { + println!("{}", *x) +} + +// print out all but the first 3 elements in the vector +for x in xs.iter().skip(3) { + println!("{}", *x) +} +~~~ + +For loops are *often* used with a temporary iterator object, as above. They can +also advance the state of an iterator in a mutable location: + +~~~ +let xs = [1, 2, 3, 4, 5]; +let ys = ["foo", "bar", "baz", "foobar"]; + +// create an iterator yielding tuples of elements from both vectors +let mut it = xs.iter().zip(ys.iter()); + +// print out the pairs of elements up to (&3, &"baz") +for (x, y) in it { + println!("{} {}", *x, *y); + + if *x == 3 { + break; + } +} + +// yield and print the last pair from the iterator +println!("last: {:?}", it.next()); + +// the iterator is now fully consumed +assert!(it.next().is_none()); +~~~ + +## Conversion + +Iterators offer generic conversion to containers with the `collect` adaptor: + +~~~ +let xs = [0, 1, 1, 2, 3, 5, 8]; +let ys = xs.rev_iter().skip(1).map(|&x| x * 2).collect::<~[int]>(); +assert_eq!(ys, ~[10, 6, 4, 2, 2, 0]); +~~~ + +The method requires a type hint for the container type, if the surrounding code +does not provide sufficient information. + +Containers can provide conversion from iterators through `collect` by +implementing the `FromIterator` trait. For example, the implementation for +vectors is as follows: + +~~~ {.ignore} +impl<A> FromIterator<A> for ~[A] { + pub fn from_iterator<T: Iterator<A>>(iterator: &mut T) -> ~[A] { + let (lower, _) = iterator.size_hint(); + let mut xs = with_capacity(lower); + for x in iterator { + xs.push(x); + } + xs + } +} +~~~ + +### Size hints + +The `Iterator` trait provides a `size_hint` default method, returning a lower +bound and optionally on upper bound on the length of the iterator: + +~~~ {.ignore} +fn size_hint(&self) -> (uint, Option<uint>) { (0, None) } +~~~ + +The vector implementation of `FromIterator` from above uses the lower bound +to pre-allocate enough space to hold the minimum number of elements the +iterator will yield. + +The default implementation is always correct, but it should be overridden if +the iterator can provide better information. + +The `ZeroStream` from earlier can provide an exact lower and upper bound: + +~~~ +# fn main() {} +/// A stream of N zeroes +struct ZeroStream { + remaining: uint +} + +impl ZeroStream { + fn new(n: uint) -> ZeroStream { + ZeroStream { remaining: n } + } + + fn size_hint(&self) -> (uint, Option<uint>) { + (self.remaining, Some(self.remaining)) + } +} + +impl Iterator<int> for ZeroStream { + fn next(&mut self) -> Option<int> { + if self.remaining == 0 { + None + } else { + self.remaining -= 1; + Some(0) + } + } +} +~~~ + +## Double-ended iterators + +The `DoubleEndedIterator` trait represents an iterator able to yield elements +from either end of a range. It inherits from the `Iterator` trait and extends +it with the `next_back` function. + +A `DoubleEndedIterator` can have its direction changed with the `rev` adaptor, +returning another `DoubleEndedIterator` with `next` and `next_back` exchanged. + +~~~ +let xs = [1, 2, 3, 4, 5, 6]; +let mut it = xs.iter(); +println!("{:?}", it.next()); // prints `Some(&1)` +println!("{:?}", it.next()); // prints `Some(&2)` +println!("{:?}", it.next_back()); // prints `Some(&6)` + +// prints `5`, `4` and `3` +for &x in it.rev() { + println!("{}", x) +} +~~~ + +The `rev_iter` and `mut_rev_iter` methods on vectors just return an inverted +version of the standard immutable and mutable vector iterators. + +The `chain`, `map`, `filter`, `filter_map` and `inspect` adaptors are +`DoubleEndedIterator` implementations if the underlying iterators are. + +~~~ +let xs = [1, 2, 3, 4]; +let ys = [5, 6, 7, 8]; +let mut it = xs.iter().chain(ys.iter()).map(|&x| x * 2); + +println!("{:?}", it.next()); // prints `Some(2)` + +// prints `16`, `14`, `12`, `10`, `8`, `6`, `4` +for x in it.rev() { + println!("{}", x); +} +~~~ + +The `reverse_` method is also available for any double-ended iterator yielding +mutable references. It can be used to reverse a container in-place. Note that +the trailing underscore is a workaround for issue #5898 and will be removed. + +~~~ +let mut ys = [1, 2, 3, 4, 5]; +ys.mut_iter().reverse_(); +assert_eq!(ys, [5, 4, 3, 2, 1]); +~~~ + +## Random-access iterators + +The `RandomAccessIterator` trait represents an iterator offering random access +to the whole range. The `indexable` method retrieves the number of elements +accessible with the `idx` method. + +The `chain` adaptor is an implementation of `RandomAccessIterator` if the +underlying iterators are. + +~~~ +let xs = [1, 2, 3, 4, 5]; +let ys = ~[7, 9, 11]; +let mut it = xs.iter().chain(ys.iter()); +println!("{:?}", it.idx(0)); // prints `Some(&1)` +println!("{:?}", it.idx(5)); // prints `Some(&7)` +println!("{:?}", it.idx(7)); // prints `Some(&11)` +println!("{:?}", it.idx(8)); // prints `None` + +// yield two elements from the beginning, and one from the end +it.next(); +it.next(); +it.next_back(); + +println!("{:?}", it.idx(0)); // prints `Some(&3)` +println!("{:?}", it.idx(4)); // prints `Some(&9)` +println!("{:?}", it.idx(6)); // prints `None` +~~~ diff --git a/src/doc/guide-ffi.md b/src/doc/guide-ffi.md new file mode 100644 index 00000000000..c892c06902a --- /dev/null +++ b/src/doc/guide-ffi.md @@ -0,0 +1,567 @@ +% The Rust Foreign Function Interface Guide + +# Introduction + +This guide will use the [snappy](https://code.google.com/p/snappy/) +compression/decompression library as an introduction to writing bindings for +foreign code. Rust is currently unable to call directly into a C++ library, but +snappy includes a C interface (documented in +[`snappy-c.h`](https://code.google.com/p/snappy/source/browse/trunk/snappy-c.h)). + +The following is a minimal example of calling a foreign function which will +compile if snappy is installed: + +~~~~ {.ignore} +use std::libc::size_t; + +#[link(name = "snappy")] +extern { + fn snappy_max_compressed_length(source_length: size_t) -> size_t; +} + +fn main() { + let x = unsafe { snappy_max_compressed_length(100) }; + println!("max compressed length of a 100 byte buffer: {}", x); +} +~~~~ + +The `extern` block is a list of function signatures in a foreign library, in +this case with the platform's C ABI. The `#[link(...)]` attribute is used to +instruct the linker to link against the snappy library so the symbols are +resolved. + +Foreign functions are assumed to be unsafe so calls to them need to be wrapped +with `unsafe {}` as a promise to the compiler that everything contained within +truly is safe. C libraries often expose interfaces that aren't thread-safe, and +almost any function that takes a pointer argument isn't valid for all possible +inputs since the pointer could be dangling, and raw pointers fall outside of +Rust's safe memory model. + +When declaring the argument types to a foreign function, the Rust compiler can +not check if the declaration is correct, so specifying it correctly is part of +keeping the binding correct at runtime. + +The `extern` block can be extended to cover the entire snappy API: + +~~~~ {.ignore} +use std::libc::{c_int, size_t}; + +#[link(name = "snappy")] +extern { + fn snappy_compress(input: *u8, + input_length: size_t, + compressed: *mut u8, + compressed_length: *mut size_t) -> c_int; + fn snappy_uncompress(compressed: *u8, + compressed_length: size_t, + uncompressed: *mut u8, + uncompressed_length: *mut size_t) -> c_int; + fn snappy_max_compressed_length(source_length: size_t) -> size_t; + fn snappy_uncompressed_length(compressed: *u8, + compressed_length: size_t, + result: *mut size_t) -> c_int; + fn snappy_validate_compressed_buffer(compressed: *u8, + compressed_length: size_t) -> c_int; +} +~~~~ + +# Creating a safe interface + +The raw C API needs to be wrapped to provide memory safety and make use of higher-level concepts +like vectors. A library can choose to expose only the safe, high-level interface and hide the unsafe +internal details. + +Wrapping the functions which expect buffers involves using the `vec::raw` module to manipulate Rust +vectors as pointers to memory. Rust's vectors are guaranteed to be a contiguous block of memory. The +length is number of elements currently contained, and the capacity is the total size in elements of +the allocated memory. The length is less than or equal to the capacity. + +~~~~ {.ignore} +pub fn validate_compressed_buffer(src: &[u8]) -> bool { + unsafe { + snappy_validate_compressed_buffer(src.as_ptr(), src.len() as size_t) == 0 + } +} +~~~~ + +The `validate_compressed_buffer` wrapper above makes use of an `unsafe` block, but it makes the +guarantee that calling it is safe for all inputs by leaving off `unsafe` from the function +signature. + +The `snappy_compress` and `snappy_uncompress` functions are more complex, since a buffer has to be +allocated to hold the output too. + +The `snappy_max_compressed_length` function can be used to allocate a vector with the maximum +required capacity to hold the compressed output. The vector can then be passed to the +`snappy_compress` function as an output parameter. An output parameter is also passed to retrieve +the true length after compression for setting the length. + +~~~~ {.ignore} +pub fn compress(src: &[u8]) -> ~[u8] { + unsafe { + let srclen = src.len() as size_t; + let psrc = src.as_ptr(); + + let mut dstlen = snappy_max_compressed_length(srclen); + let mut dst = vec::with_capacity(dstlen as uint); + let pdst = dst.as_mut_ptr(); + + snappy_compress(psrc, srclen, pdst, &mut dstlen); + dst.set_len(dstlen as uint); + dst + } +} +~~~~ + +Decompression is similar, because snappy stores the uncompressed size as part of the compression +format and `snappy_uncompressed_length` will retrieve the exact buffer size required. + +~~~~ {.ignore} +pub fn uncompress(src: &[u8]) -> Option<~[u8]> { + unsafe { + let srclen = src.len() as size_t; + let psrc = src.as_ptr(); + + let mut dstlen: size_t = 0; + snappy_uncompressed_length(psrc, srclen, &mut dstlen); + + let mut dst = vec::with_capacity(dstlen as uint); + let pdst = dst.as_mut_ptr(); + + if snappy_uncompress(psrc, srclen, pdst, &mut dstlen) == 0 { + dst.set_len(dstlen as uint); + Some(dst) + } else { + None // SNAPPY_INVALID_INPUT + } + } +} +~~~~ + +For reference, the examples used here are also available as an [library on +GitHub](https://github.com/thestinger/rust-snappy). + +# Stack management + +Rust tasks by default run on a "large stack". This is actually implemented as a +reserving a large segment of the address space and then lazily mapping in pages +as they are needed. When calling an external C function, the code is invoked on +the same stack as the rust stack. This means that there is no extra +stack-switching mechanism in place because it is assumed that the large stack +for the rust task is plenty for the C function to have. + +A planned future improvement (net yet implemented at the time of this writing) +is to have a guard page at the end of every rust stack. No rust function will +hit this guard page (due to Rust's usage of LLVM's `__morestack`). The intention +for this unmapped page is to prevent infinite recursion in C from overflowing +onto other rust stacks. If the guard page is hit, then the process will be +terminated with a message saying that the guard page was hit. + +For normal external function usage, this all means that there shouldn't be any +need for any extra effort on a user's perspective. The C stack naturally +interleaves with the rust stack, and it's "large enough" for both to +interoperate. If, however, it is determined that a larger stack is necessary, +there are appropriate functions in the task spawning API to control the size of +the stack of the task which is spawned. + +# Destructors + +Foreign libraries often hand off ownership of resources to the calling code. +When this occurs, we must use Rust's destructors to provide safety and guarantee +the release of these resources (especially in the case of failure). + +As an example, we give a reimplementation of owned boxes by wrapping `malloc` +and `free`: + +~~~~ +use std::cast; +use std::libc::{c_void, size_t, malloc, free}; +use std::ptr; +use std::unstable::intrinsics; + +// Define a wrapper around the handle returned by the foreign code. +// Unique<T> has the same semantics as ~T +pub struct Unique<T> { + // It contains a single raw, mutable pointer to the object in question. + priv ptr: *mut T +} + +// Implement methods for creating and using the values in the box. +// NB: For simplicity and correctness, we require that T has kind Send +// (owned boxes relax this restriction, and can contain managed (GC) boxes). +// This is because, as implemented, the garbage collector would not know +// about any shared boxes stored in the malloc'd region of memory. +impl<T: Send> Unique<T> { + pub fn new(value: T) -> Unique<T> { + unsafe { + let ptr = malloc(std::mem::size_of::<T>() as size_t) as *mut T; + assert!(!ptr::is_null(ptr)); + // `*ptr` is uninitialized, and `*ptr = value` would attempt to destroy it + // move_val_init moves a value into this memory without + // attempting to drop the original value. + intrinsics::move_val_init(&mut *ptr, value); + Unique{ptr: ptr} + } + } + + // the 'r lifetime results in the same semantics as `&*x` with ~T + pub fn borrow<'r>(&'r self) -> &'r T { + unsafe { cast::copy_lifetime(self, &*self.ptr) } + } + + // the 'r lifetime results in the same semantics as `&mut *x` with ~T + pub fn borrow_mut<'r>(&'r mut self) -> &'r mut T { + unsafe { cast::copy_mut_lifetime(self, &mut *self.ptr) } + } +} + +// The key ingredient for safety, we associate a destructor with +// Unique<T>, making the struct manage the raw pointer: when the +// struct goes out of scope, it will automatically free the raw pointer. +// NB: This is an unsafe destructor, because rustc will not normally +// allow destructors to be associated with parametrized types, due to +// bad interaction with managed boxes. (With the Send restriction, +// we don't have this problem.) +#[unsafe_destructor] +impl<T: Send> Drop for Unique<T> { + fn drop(&mut self) { + unsafe { + let x = intrinsics::uninit(); // dummy value to swap in + // We need to move the object out of the box, so that + // the destructor is called (at the end of this scope.) + ptr::replace_ptr(self.ptr, x); + free(self.ptr as *mut c_void) + } + } +} + +// A comparison between the built-in ~ and this reimplementation +fn main() { + { + let mut x = ~5; + *x = 10; + } // `x` is freed here + + { + let mut y = Unique::new(5); + *y.borrow_mut() = 10; + } // `y` is freed here +} +~~~~ + +# Callbacks from C code to Rust functions + +Some external libraries require the usage of callbacks to report back their +current state or intermediate data to the caller. +It is possible to pass functions defined in Rust to an external library. +The requirement for this is that the callback function is marked as `extern` +with the correct calling convention to make it callable from C code. + +The callback function that can then be sent to through a registration call +to the C library and afterwards be invoked from there. + +A basic example is: + +Rust code: +~~~~ {.ignore} +extern fn callback(a:i32) { + println!("I'm called from C with value {0}", a); +} + +#[link(name = "extlib")] +extern { + fn register_callback(cb: extern "C" fn(i32)) -> i32; + fn trigger_callback(); +} + +fn main() { + unsafe { + register_callback(callback); + trigger_callback(); // Triggers the callback + } +} +~~~~ + +C code: +~~~~ {.ignore} +typedef void (*rust_callback)(int32_t); +rust_callback cb; + +int32_t register_callback(rust_callback callback) { + cb = callback; + return 1; +} + +void trigger_callback() { + cb(7); // Will call callback(7) in Rust +} +~~~~ + +In this example will Rust's `main()` will call `do_callback()` in C, +which would call back to `callback()` in Rust. + + +## Targetting callbacks to Rust objects + +The former example showed how a global function can be called from C code. +However it is often desired that the callback is targetted to a special +Rust object. This could be the object that represents the wrapper for the +respective C object. + +This can be achieved by passing an unsafe pointer to the object down to the +C library. The C library can then include the pointer to the Rust object in +the notification. This will allow the callback to unsafely access the +referenced Rust object. + +Rust code: +~~~~ {.ignore} + +struct RustObject { + a: i32, + // other members +} + +extern fn callback(target: *RustObject, a:i32) { + println!("I'm called from C with value {0}", a); + (*target).a = a; // Update the value in RustObject with the value received from the callback +} + +#[link(name = "extlib")] +extern { + fn register_callback(target: *RustObject, cb: extern "C" fn(*RustObject, i32)) -> i32; + fn trigger_callback(); +} + +fn main() { + // Create the object that will be referenced in the callback + let rust_object = ~RustObject{a: 5, ...}; + + unsafe { + // Gets a raw pointer to the object + let target_addr:*RustObject = ptr::to_unsafe_ptr(rust_object); + register_callback(target_addr, callback); + trigger_callback(); // Triggers the callback + } +} +~~~~ + +C code: +~~~~ {.ignore} +typedef void (*rust_callback)(int32_t); +void* cb_target; +rust_callback cb; + +int32_t register_callback(void* callback_target, rust_callback callback) { + cb_target = callback_target; + cb = callback; + return 1; +} + +void trigger_callback() { + cb(cb_target, 7); // Will call callback(&rustObject, 7) in Rust +} +~~~~ + +## Asynchronous callbacks + +In the previously given examples the callbacks are invoked as a direct reaction +to a function call to the external C library. +The control over the current thread is switched from Rust to C to Rust for the +execution of the callback, but in the end the callback is executed on the +same thread (and Rust task) that lead called the function which triggered +the callback. + +Things get more complicated when the external library spawns its own threads +and invokes callbacks from there. +In these cases access to Rust data structures inside the callbacks is +especially unsafe and proper synchronization mechanisms must be used. +Besides classical synchronization mechanisms like mutexes, one possibility in +Rust is to use channels (in `std::comm`) to forward data from the C thread +that invoked the callback into a Rust task. + +If an asychronous callback targets a special object in the Rust address space +it is also absolutely necessary that no more callbacks are performed by the +C library after the respective Rust object gets destroyed. +This can be achieved by unregistering the callback in the object's +destructor and designing the library in a way that guarantees that no +callback will be performed after unregistration. + +# Linking + +The `link` attribute on `extern` blocks provides the basic building block for +instructing rustc how it will link to native libraries. There are two accepted +forms of the link attribute today: + +* `#[link(name = "foo")]` +* `#[link(name = "foo", kind = "bar")]` + +In both of these cases, `foo` is the name of the native library that we're +linking to, and in the second case `bar` is the type of native library that the +compiler is linking to. There are currently three known types of native +libraries: + +* Dynamic - `#[link(name = "readline")] +* Static - `#[link(name = "my_build_dependency", kind = "static")] +* Frameworks - `#[link(name = "CoreFoundation", kind = "framework")] + +Note that frameworks are only available on OSX targets. + +The different `kind` values are meant to differentiate how the native library +participates in linkage. From a linkage perspective, the rust compiler creates +two flavors of artifacts: partial (rlib/staticlib) and final (dylib/binary). +Native dynamic libraries and frameworks are propagated to the final artifact +boundary, while static libraries are not propagated at all. + +A few examples of how this model can be used are: + +* A native build dependency. Sometimes some C/C++ glue is needed when writing + some rust code, but distribution of the C/C++ code in a library format is just + a burden. In this case, the code will be archived into `libfoo.a` and then the + rust crate would declare a dependency via `#[link(name = "foo", kind = + "static")]`. + + Regardless of the flavor of output for the crate, the native static library + will be included in the output, meaning that distribution of the native static + library is not necessary. + +* A normal dynamic dependency. Common system libraries (like `readline`) are + available on a large number of systems, and often a static copy of these + libraries cannot be found. When this dependency is included in a rust crate, + partial targets (like rlibs) will not link to the library, but when the rlib + is included in a final target (like a binary), the native library will be + linked in. + +On OSX, frameworks behave with the same semantics as a dynamic library. + +## The `link_args` attribute + +There is one other way to tell rustc how to customize linking, and that is via +the `link_args` attribute. This attribute is applied to `extern` blocks and +specifies raw flags which need to get passed to the linker when producing an +artifact. An example usage would be: + +~~~ {.ignore} +#[link_args = "-foo -bar -baz"] +extern {} +~~~ + +Note that this feature is currently hidden behind the `feature(link_args)` gate +because this is not a sanctioned way of performing linking. Right now rustc +shells out to the system linker, so it makes sense to provide extra command line +arguments, but this will not always be the case. In the future rustc may use +LLVM directly to link native libraries in which case `link_args` will have no +meaning. + +It is highly recommended to *not* use this attribute, and rather use the more +formal `#[link(...)]` attribute on `extern` blocks instead. + +# Unsafe blocks + +Some operations, like dereferencing unsafe pointers or calling functions that have been marked +unsafe are only allowed inside unsafe blocks. Unsafe blocks isolate unsafety and are a promise to +the compiler that the unsafety does not leak out of the block. + +Unsafe functions, on the other hand, advertise it to the world. An unsafe function is written like +this: + +~~~~ +unsafe fn kaboom(ptr: *int) -> int { *ptr } +~~~~ + +This function can only be called from an `unsafe` block or another `unsafe` function. + +# Accessing foreign globals + +Foreign APIs often export a global variable which could do something like track +global state. In order to access these variables, you declare them in `extern` +blocks with the `static` keyword: + +~~~{.ignore} +use std::libc; + +#[link(name = "readline")] +extern { + static rl_readline_version: libc::c_int; +} + +fn main() { + println!("You have readline version {} installed.", + rl_readline_version as int); +} +~~~ + +Alternatively, you may need to alter global state provided by a foreign +interface. To do this, statics can be declared with `mut` so rust can mutate +them. + +~~~{.ignore} +use std::libc; +use std::ptr; + +#[link(name = "readline")] +extern { + static mut rl_prompt: *libc::c_char; +} + +fn main() { + do "[my-awesome-shell] $".as_c_str |buf| { + unsafe { rl_prompt = buf; } + // get a line, process it + unsafe { rl_prompt = ptr::null(); } + } +} +~~~ + +# Foreign calling conventions + +Most foreign code exposes a C ABI, and Rust uses the platform's C calling convention by default when +calling foreign functions. Some foreign functions, most notably the Windows API, use other calling +conventions. Rust provides a way to tell the compiler which convention to use: + +~~~~ +#[cfg(target_os = "win32", target_arch = "x86")] +#[link_name = "kernel32"] +extern "stdcall" { + fn SetEnvironmentVariableA(n: *u8, v: *u8) -> std::libc::c_int; +} +~~~~ + +This applies to the entire `extern` block. The list of supported ABI constraints +are: + +* `stdcall` +* `aapcs` +* `cdecl` +* `fastcall` +* `Rust` +* `rust-intrinsic` +* `system` +* `C` + +Most of the abis in this list are self-explanatory, but the `system` abi may +seem a little odd. This constraint selects whatever the appropriate ABI is for +interoperating with the target's libraries. For example, on win32 with a x86 +architecture, this means that the abi used would be `stdcall`. On x86_64, +however, windows uses the `C` calling convention, so `C` would be used. This +means that in our previous example, we could have used `extern "system" { ... }` +to define a block for all windows systems, not just x86 ones. + +# Interoperability with foreign code + +Rust guarantees that the layout of a `struct` is compatible with the platform's representation in C. +A `#[packed]` attribute is available, which will lay out the struct members without padding. +However, there are currently no guarantees about the layout of an `enum`. + +Rust's owned and managed boxes use non-nullable pointers as handles which point to the contained +object. However, they should not be manually created because they are managed by internal +allocators. References can safely be assumed to be non-nullable pointers directly to the +type. However, breaking the borrow checking or mutability rules is not guaranteed to be safe, so +prefer using raw pointers (`*`) if that's needed because the compiler can't make as many assumptions +about them. + +Vectors and strings share the same basic memory layout, and utilities are available in the `vec` and +`str` modules for working with C APIs. However, strings are not terminated with `\0`. If you need a +NUL-terminated string for interoperability with C, you should use the `c_str::to_c_str` function. + +The standard library includes type aliases and function definitions for the C standard library in +the `libc` module, and Rust links against `libc` and `libm` by default. diff --git a/src/doc/guide-lifetimes.md b/src/doc/guide-lifetimes.md new file mode 100644 index 00000000000..d31b0eed849 --- /dev/null +++ b/src/doc/guide-lifetimes.md @@ -0,0 +1,663 @@ +% The Rust References and Lifetimes Guide + +# Introduction + +References are one of the more flexible and powerful tools available in +Rust. A reference can point anywhere: into the managed or exchange +heap, into the stack, and even into the interior of another data structure. A +reference is as flexible as a C pointer or C++ reference. However, +unlike C and C++ compilers, the Rust compiler includes special static checks +that ensure that programs use references safely. Another advantage of +references is that they are invisible to the garbage collector, so +working with references helps reduce the overhead of automatic memory +management. + +Despite their complete safety, a reference's representation at runtime +is the same as that of an ordinary pointer in a C program. They introduce zero +overhead. The compiler does all safety checks at compile time. + +Although references have rather elaborate theoretical +underpinnings (region pointers), the core concepts will be familiar to +anyone who has worked with C or C++. Therefore, the best way to explain +how they are used—and their limitations—is probably just to work +through several examples. + +# By example + +References, sometimes known as *borrowed pointers*, are only valid for +a limited duration. References never claim any kind of ownership +over the data that they point to: instead, they are used for cases +where you would like to use data for a short time. + +As an example, consider a simple struct type `Point`: + +~~~ +struct Point {x: f64, y: f64} +~~~ + +We can use this simple definition to allocate points in many different ways. For +example, in this code, each of these three local variables contains a +point, but allocated in a different place: + +~~~ +# struct Point {x: f64, y: f64} +let on_the_stack : Point = Point {x: 3.0, y: 4.0}; +let managed_box : @Point = @Point {x: 5.0, y: 1.0}; +let owned_box : ~Point = ~Point {x: 7.0, y: 9.0}; +~~~ + +Suppose we wanted to write a procedure that computed the distance between any +two points, no matter where they were stored. For example, we might like to +compute the distance between `on_the_stack` and `managed_box`, or between +`managed_box` and `owned_box`. One option is to define a function that takes +two arguments of type `Point`—that is, it takes the points by value. But if we +define it this way, calling the function will cause the points to be +copied. For points, this is probably not so bad, but often copies are +expensive. Worse, if the data type contains mutable fields, copying can change +the semantics of your program in unexpected ways. So we'd like to define a +function that takes the points by pointer. We can use references to do +this: + +~~~ +# struct Point {x: f64, y: f64} +# fn sqrt(f: f64) -> f64 { 0.0 } +fn compute_distance(p1: &Point, p2: &Point) -> f64 { + let x_d = p1.x - p2.x; + let y_d = p1.y - p2.y; + sqrt(x_d * x_d + y_d * y_d) +} +~~~ + +Now we can call `compute_distance()` in various ways: + +~~~ +# struct Point {x: f64, y: f64} +# let on_the_stack : Point = Point{x: 3.0, y: 4.0}; +# let managed_box : @Point = @Point{x: 5.0, y: 1.0}; +# let owned_box : ~Point = ~Point{x: 7.0, y: 9.0}; +# fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 } +compute_distance(&on_the_stack, managed_box); +compute_distance(managed_box, owned_box); +~~~ + +Here, the `&` operator takes the address of the variable +`on_the_stack`; this is because `on_the_stack` has the type `Point` +(that is, a struct value) and we have to take its address to get a +value. We also call this _borrowing_ the local variable +`on_the_stack`, because we have created an alias: that is, another +name for the same data. + +In contrast, we can pass the boxes `managed_box` and `owned_box` to +`compute_distance` directly. The compiler automatically converts a box like +`@Point` or `~Point` to a reference like `&Point`. This is another form +of borrowing: in this case, the caller lends the contents of the managed or +owned box to the callee. + +Whenever a caller lends data to a callee, there are some limitations on what +the caller can do with the original. For example, if the contents of a +variable have been lent out, you cannot send that variable to another task. In +addition, the compiler will reject any code that might cause the borrowed +value to be freed or overwrite its component fields with values of different +types (I'll get into what kinds of actions those are shortly). This rule +should make intuitive sense: you must wait for a borrower to return the value +that you lent it (that is, wait for the reference to go out of scope) +before you can make full use of it again. + +# Other uses for the & operator + +In the previous example, the value `on_the_stack` was defined like so: + +~~~ +# struct Point {x: f64, y: f64} +let on_the_stack: Point = Point {x: 3.0, y: 4.0}; +~~~ + +This declaration means that code can only pass `Point` by value to other +functions. As a consequence, we had to explicitly take the address of +`on_the_stack` to get a reference. Sometimes however it is more +convenient to move the & operator into the definition of `on_the_stack`: + +~~~ +# struct Point {x: f64, y: f64} +let on_the_stack2: &Point = &Point {x: 3.0, y: 4.0}; +~~~ + +Applying `&` to an rvalue (non-assignable location) is just a convenient +shorthand for creating a temporary and taking its address. A more verbose +way to write the same code is: + +~~~ +# struct Point {x: f64, y: f64} +let tmp = Point {x: 3.0, y: 4.0}; +let on_the_stack2 : &Point = &tmp; +~~~ + +# Taking the address of fields + +As in C, the `&` operator is not limited to taking the address of +local variables. It can also take the address of fields or +individual array elements. For example, consider this type definition +for `rectangle`: + +~~~ +struct Point {x: f64, y: f64} // as before +struct Size {w: f64, h: f64} // as before +struct Rectangle {origin: Point, size: Size} +~~~ + +Now, as before, we can define rectangles in a few different ways: + +~~~ +# struct Point {x: f64, y: f64} +# struct Size {w: f64, h: f64} // as before +# struct Rectangle {origin: Point, size: Size} +let rect_stack = &Rectangle {origin: Point {x: 1.0, y: 2.0}, + size: Size {w: 3.0, h: 4.0}}; +let rect_managed = @Rectangle {origin: Point {x: 3.0, y: 4.0}, + size: Size {w: 3.0, h: 4.0}}; +let rect_owned = ~Rectangle {origin: Point {x: 5.0, y: 6.0}, + size: Size {w: 3.0, h: 4.0}}; +~~~ + +In each case, we can extract out individual subcomponents with the `&` +operator. For example, I could write: + +~~~ +# struct Point {x: f64, y: f64} // as before +# struct Size {w: f64, h: f64} // as before +# struct Rectangle {origin: Point, size: Size} +# let rect_stack = &Rectangle {origin: Point {x: 1.0, y: 2.0}, size: Size {w: 3.0, h: 4.0}}; +# let rect_managed = @Rectangle {origin: Point {x: 3.0, y: 4.0}, size: Size {w: 3.0, h: 4.0}}; +# let rect_owned = ~Rectangle {origin: Point {x: 5.0, y: 6.0}, size: Size {w: 3.0, h: 4.0}}; +# fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 } +compute_distance(&rect_stack.origin, &rect_managed.origin); +~~~ + +which would borrow the field `origin` from the rectangle on the stack +as well as from the managed box, and then compute the distance between them. + +# Borrowing managed boxes and rooting + +We’ve seen a few examples so far of borrowing heap boxes, both managed +and owned. Up till this point, we’ve glossed over issues of +safety. As stated in the introduction, at runtime a reference +is simply a pointer, nothing more. Therefore, avoiding C's problems +with dangling pointers requires a compile-time safety check. + +The basis for the check is the notion of _lifetimes_. A lifetime is a +static approximation of the span of execution during which the pointer +is valid: it always corresponds to some expression or block within the +program. Code inside that expression can use the pointer without +restrictions. But if the pointer escapes from that expression (for +example, if the expression contains an assignment expression that +assigns the pointer to a mutable field of a data structure with a +broader scope than the pointer itself), the compiler reports an +error. We'll be discussing lifetimes more in the examples to come, and +a more thorough introduction is also available. + +When the `&` operator creates a reference, the compiler must +ensure that the pointer remains valid for its entire +lifetime. Sometimes this is relatively easy, such as when taking the +address of a local variable or a field that is stored on the stack: + +~~~ +struct X { f: int } +fn example1() { + let mut x = X { f: 3 }; + let y = &mut x.f; // -+ L + ... // | +} // -+ +~~~ + +Here, the lifetime of the reference `y` is simply L, the +remainder of the function body. The compiler need not do any other +work to prove that code will not free `x.f`. This is true even if the +code mutates `x`. + +The situation gets more complex when borrowing data inside heap boxes: + +~~~ +# struct X { f: int } +fn example2() { + let mut x = @X { f: 3 }; + let y = &x.f; // -+ L + ... // | +} // -+ +~~~ + +In this example, the value `x` is a heap box, and `y` is therefore a +pointer into that heap box. Again the lifetime of `y` is L, the +remainder of the function body. But there is a crucial difference: +suppose `x` were to be reassigned during the lifetime L? If the +compiler isn't careful, the managed box could become *unrooted*, and +would therefore be subject to garbage collection. A heap box that is +unrooted is one such that no pointer values in the heap point to +it. It would violate memory safety for the box that was originally +assigned to `x` to be garbage-collected, since a non-heap +pointer *`y`* still points into it. + +> ***Note:*** Our current implementation implements the garbage collector +> using reference counting and cycle detection. + +For this reason, whenever an `&` expression borrows the interior of a +managed box stored in a mutable location, the compiler inserts a +temporary that ensures that the managed box remains live for the +entire lifetime. So, the above example would be compiled as if it were +written + +~~~ +# struct X { f: int } +fn example2() { + let mut x = @X {f: 3}; + let x1 = x; + let y = &x1.f; // -+ L + ... // | +} // -+ +~~~ + +Now if `x` is reassigned, the pointer `y` will still remain valid. This +process is called *rooting*. + +# Borrowing owned boxes + +The previous example demonstrated *rooting*, the process by which the +compiler ensures that managed boxes remain live for the duration of a +borrow. Unfortunately, rooting does not work for borrows of owned +boxes, because it is not possible to have two references to a owned +box. + +For owned boxes, therefore, the compiler will only allow a borrow *if +the compiler can guarantee that the owned box will not be reassigned +or moved for the lifetime of the pointer*. This does not necessarily +mean that the owned box is stored in immutable memory. For example, +the following function is legal: + +~~~ +# fn some_condition() -> bool { true } +# struct Foo { f: int } +fn example3() -> int { + let mut x = ~Foo {f: 3}; + if some_condition() { + let y = &x.f; // -+ L + return *y; // | + } // -+ + x = ~Foo {f: 4}; + ... +# return 0; +} +~~~ + +Here, as before, the interior of the variable `x` is being borrowed +and `x` is declared as mutable. However, the compiler can prove that +`x` is not assigned anywhere in the lifetime L of the variable +`y`. Therefore, it accepts the function, even though `x` is mutable +and in fact is mutated later in the function. + +It may not be clear why we are so concerned about mutating a borrowed +variable. The reason is that the runtime system frees any owned box +_as soon as its owning reference changes or goes out of +scope_. Therefore, a program like this is illegal (and would be +rejected by the compiler): + +~~~ {.ignore} +fn example3() -> int { + let mut x = ~X {f: 3}; + let y = &x.f; + x = ~X {f: 4}; // Error reported here. + *y +} +~~~ + +To make this clearer, consider this diagram showing the state of +memory immediately before the re-assignment of `x`: + +~~~ {.notrust} + Stack Exchange Heap + + x +----------+ + | ~{f:int} | ----+ + y +----------+ | + | &int | ----+ + +----------+ | +---------+ + +--> | f: 3 | + +---------+ +~~~ + +Once the reassignment occurs, the memory will look like this: + +~~~ {.notrust} + Stack Exchange Heap + + x +----------+ +---------+ + | ~{f:int} | -------> | f: 4 | + y +----------+ +---------+ + | &int | ----+ + +----------+ | +---------+ + +--> | (freed) | + +---------+ +~~~ + +Here you can see that the variable `y` still points at the old box, +which has been freed. + +In fact, the compiler can apply the same kind of reasoning to any +memory that is _(uniquely) owned by the stack frame_. So we could +modify the previous example to introduce additional owned pointers +and structs, and the compiler will still be able to detect possible +mutations: + +~~~ {.ignore} +fn example3() -> int { + struct R { g: int } + struct S { f: ~R } + + let mut x = ~S {f: ~R {g: 3}}; + let y = &x.f.g; + x = ~S {f: ~R {g: 4}}; // Error reported here. + x.f = ~R {g: 5}; // Error reported here. + *y +} +~~~ + +In this case, two errors are reported, one when the variable `x` is +modified and another when `x.f` is modified. Either modification would +invalidate the pointer `y`. + +# Borrowing and enums + +The previous example showed that the type system forbids any borrowing +of owned boxes found in aliasable, mutable memory. This restriction +prevents pointers from pointing into freed memory. There is one other +case where the compiler must be very careful to ensure that pointers +remain valid: pointers into the interior of an `enum`. + +As an example, let’s look at the following `shape` type that can +represent both rectangles and circles: + +~~~ +struct Point {x: f64, y: f64}; // as before +struct Size {w: f64, h: f64}; // as before +enum Shape { + Circle(Point, f64), // origin, radius + Rectangle(Point, Size) // upper-left, dimensions +} +~~~ + +Now we might write a function to compute the area of a shape. This +function takes a reference to a shape, to avoid the need for +copying. + +~~~ +# struct Point {x: f64, y: f64}; // as before +# struct Size {w: f64, h: f64}; // as before +# enum Shape { +# Circle(Point, f64), // origin, radius +# Rectangle(Point, Size) // upper-left, dimensions +# } +# static tau: f64 = 6.28; +fn compute_area(shape: &Shape) -> f64 { + match *shape { + Circle(_, radius) => 0.5 * tau * radius * radius, + Rectangle(_, ref size) => size.w * size.h + } +} +~~~ + +The first case matches against circles. Here, the pattern extracts the +radius from the shape variant and the action uses it to compute the +area of the circle. (Like any up-to-date engineer, we use the [tau +circle constant][tau] and not that dreadfully outdated notion of pi). + +[tau]: http://www.math.utah.edu/~palais/pi.html + +The second match is more interesting. Here we match against a +rectangle and extract its size: but rather than copy the `size` +struct, we use a by-reference binding to create a pointer to it. In +other words, a pattern binding like `ref size` binds the name `size` +to a pointer of type `&size` into the _interior of the enum_. + +To make this more clear, let's look at a diagram of memory layout in +the case where `shape` points at a rectangle: + +~~~ {.notrust} +Stack Memory + ++-------+ +---------------+ +| shape | ------> | rectangle( | ++-------+ | {x: f64, | +| size | -+ | y: f64}, | ++-------+ +----> | {w: f64, | + | h: f64}) | + +---------------+ +~~~ + +Here you can see that rectangular shapes are composed of five words of +memory. The first is a tag indicating which variant this enum is +(`rectangle`, in this case). The next two words are the `x` and `y` +fields for the point and the remaining two are the `w` and `h` fields +for the size. The binding `size` is then a pointer into the inside of +the shape. + +Perhaps you can see where the danger lies: if the shape were somehow +to be reassigned, perhaps to a circle, then although the memory used +to store that shape value would still be valid, _it would have a +different type_! The following diagram shows what memory would look +like if code overwrote `shape` with a circle: + +~~~ {.notrust} +Stack Memory + ++-------+ +---------------+ +| shape | ------> | circle( | ++-------+ | {x: f64, | +| size | -+ | y: f64}, | ++-------+ +----> | f64) | + | | + +---------------+ +~~~ + +As you can see, the `size` pointer would be pointing at a `f64` +instead of a struct. This is not good: dereferencing the second field +of a `f64` as if it were a struct with two fields would be a memory +safety violation. + +So, in fact, for every `ref` binding, the compiler will impose the +same rules as the ones we saw for borrowing the interior of a owned +box: it must be able to guarantee that the `enum` will not be +overwritten for the duration of the borrow. In fact, the compiler +would accept the example we gave earlier. The example is safe because +the shape pointer has type `&Shape`, which means "reference to +immutable memory containing a `shape`". If, however, the type of that +pointer were `&mut Shape`, then the ref binding would be ill-typed. +Just as with owned boxes, the compiler will permit `ref` bindings +into data owned by the stack frame even if the data are mutable, +but otherwise it requires that the data reside in immutable memory. + +# Returning references + +So far, all of the examples we have looked at, use references in a +“downward” direction. That is, a method or code block creates a +reference, then uses it within the same scope. It is also +possible to return references as the result of a function, but +as we'll see, doing so requires some explicit annotation. + +For example, we could write a subroutine like this: + +~~~ +struct Point {x: f64, y: f64} +fn get_x<'r>(p: &'r Point) -> &'r f64 { &p.x } +~~~ + +Here, the function `get_x()` returns a pointer into the structure it +was given. The type of the parameter (`&'r Point`) and return type +(`&'r f64`) both use a new syntactic form that we have not seen so +far. Here the identifier `r` names the lifetime of the pointer +explicitly. So in effect, this function declares that it takes a +pointer with lifetime `r` and returns a pointer with that same +lifetime. + +In general, it is only possible to return references if they +are derived from a parameter to the procedure. In that case, the +pointer result will always have the same lifetime as one of the +parameters; named lifetimes indicate which parameter that +is. + +In the previous examples, function parameter types did not include a +lifetime name. In those examples, the compiler simply creates a fresh +name for the lifetime automatically: that is, the lifetime name is +guaranteed to refer to a distinct lifetime from the lifetimes of all +other parameters. + +Named lifetimes that appear in function signatures are conceptually +the same as the other lifetimes we have seen before, but they are a bit +abstract: they don’t refer to a specific expression within `get_x()`, +but rather to some expression within the *caller of `get_x()`*. The +lifetime `r` is actually a kind of *lifetime parameter*: it is defined +by the caller to `get_x()`, just as the value for the parameter `p` is +defined by that caller. + +In any case, whatever the lifetime of `r` is, the pointer produced by +`&p.x` always has the same lifetime as `p` itself: a pointer to a +field of a struct is valid as long as the struct is valid. Therefore, +the compiler accepts the function `get_x()`. + +To emphasize this point, let’s look at a variation on the example, this +time one that does not compile: + +~~~ {.ignore} +struct Point {x: f64, y: f64} +fn get_x_sh(p: @Point) -> &f64 { + &p.x // Error reported here +} +~~~ + +Here, the function `get_x_sh()` takes a managed box as input and +returns a reference. As before, the lifetime of the reference +that will be returned is a parameter (specified by the +caller). That means that `get_x_sh()` promises to return a reference +that is valid for as long as the caller would like: this is +subtly different from the first example, which promised to return a +pointer that was valid for as long as its pointer argument was valid. + +Within `get_x_sh()`, we see the expression `&p.x` which takes the +address of a field of a managed box. The presence of this expression +implies that the compiler must guarantee that, so long as the +resulting pointer is valid, the managed box will not be reclaimed by +the garbage collector. But recall that `get_x_sh()` also promised to +return a pointer that was valid for as long as the caller wanted it to +be. Clearly, `get_x_sh()` is not in a position to make both of these +guarantees; in fact, it cannot guarantee that the pointer will remain +valid at all once it returns, as the parameter `p` may or may not be +live in the caller. Therefore, the compiler will report an error here. + +In general, if you borrow a managed (or owned) box to create a +reference, it will only be valid within the function +and cannot be returned. This is why the typical way to return references +is to take references as input (the only other case in +which it can be legal to return a reference is if it +points at a static constant). + +# Named lifetimes + +Let's look at named lifetimes in more detail. Named lifetimes allow +for grouping of parameters by lifetime. For example, consider this +function: + +~~~ +# struct Point {x: f64, y: f64}; // as before +# struct Size {w: f64, h: f64}; // as before +# enum Shape { +# Circle(Point, f64), // origin, radius +# Rectangle(Point, Size) // upper-left, dimensions +# } +# fn compute_area(shape: &Shape) -> f64 { 0.0 } +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} +} +~~~ + +This function takes three references and assigns each the same +lifetime `r`. In practice, this means that, in the caller, the +lifetime `r` will be the *intersection of the lifetime of the three +region parameters*. This may be overly conservative, as in this +example: + +~~~ +# struct Point {x: f64, y: f64}; // as before +# struct Size {w: f64, h: f64}; // as before +# enum Shape { +# Circle(Point, f64), // origin, radius +# Rectangle(Point, Size) // upper-left, dimensions +# } +# fn compute_area(shape: &Shape) -> f64 { 0.0 } +# fn select<'r, T>(shape: &Shape, threshold: f64, +# a: &'r T, b: &'r T) -> &'r T { +# if compute_area(shape) > threshold {a} else {b} +# } + // -+ r +fn select_based_on_unit_circle<'r, T>( // |-+ B + threshold: f64, a: &'r T, b: &'r T) -> &'r T { // | | + // | | + let shape = Circle(Point {x: 0., y: 0.}, 1.); // | | + select(&shape, threshold, a, b) // | | +} // |-+ + // -+ +~~~ + +In this call to `select()`, the lifetime of the first parameter shape +is B, the function body. Both of the second two parameters `a` and `b` +share the same lifetime, `r`, which is a lifetime parameter of +`select_based_on_unit_circle()`. The caller will infer the +intersection of these two lifetimes as the lifetime of the returned +value, and hence the return value of `select()` will be assigned a +lifetime of B. This will in turn lead to a compilation error, because +`select_based_on_unit_circle()` is supposed to return a value with the +lifetime `r`. + +To address this, we can modify the definition of `select()` to +distinguish the lifetime of the first parameter from the lifetime of +the latter two. After all, the first parameter is not being +returned. Here is how the new `select()` might look: + +~~~ +# struct Point {x: f64, y: f64}; // as before +# struct Size {w: f64, h: f64}; // as before +# enum Shape { +# Circle(Point, f64), // origin, radius +# Rectangle(Point, Size) // upper-left, dimensions +# } +# fn compute_area(shape: &Shape) -> f64 { 0.0 } +fn select<'r, 'tmp, T>(shape: &'tmp Shape, threshold: f64, + a: &'r T, b: &'r T) -> &'r T { + if compute_area(shape) > threshold {a} else {b} +} +~~~ + +Here you can see that `shape`'s lifetime is now named `tmp`. The +parameters `a`, `b`, and the return value all have the lifetime `r`. +However, since the lifetime `tmp` is not returned, it would be more +concise to just omit the named lifetime for `shape` altogether: + +~~~ +# struct Point {x: f64, y: f64}; // as before +# struct Size {w: f64, h: f64}; // as before +# enum Shape { +# Circle(Point, f64), // origin, radius +# Rectangle(Point, Size) // upper-left, dimensions +# } +# fn compute_area(shape: &Shape) -> f64 { 0.0 } +fn select<'r, T>(shape: &Shape, threshold: f64, + a: &'r T, b: &'r T) -> &'r T { + if compute_area(shape) > threshold {a} else {b} +} +~~~ + +This is equivalent to the previous definition. + +# Conclusion + +So there you have it: a (relatively) brief tour of the lifetime +system. For more details, we refer to the (yet to be written) reference +document on references, which will explain the full notation +and give more examples. diff --git a/src/doc/guide-macros.md b/src/doc/guide-macros.md new file mode 100644 index 00000000000..b8ebca206d5 --- /dev/null +++ b/src/doc/guide-macros.md @@ -0,0 +1,409 @@ +% The Rust Macros Guide + +# Introduction + +Functions are the primary tool that programmers can use to build abstractions. +Sometimes, however, programmers want to abstract over compile-time syntax +rather than run-time values. +Macros provide syntactic abstraction. +For an example of how this can be useful, consider the following two code fragments, +which both pattern-match on their input and both return early in one case, +doing nothing otherwise: + +~~~~ +# enum t { special_a(uint), special_b(uint) }; +# fn f() -> uint { +# let input_1 = special_a(0); +# let input_2 = special_a(0); +match input_1 { + special_a(x) => { return x; } + _ => {} +} +// ... +match input_2 { + special_b(x) => { return x; } + _ => {} +} +# return 0u; +# } +~~~~ + +This code could become tiresome if repeated many times. +However, no function can capture its functionality to make it possible +to abstract the repetition away. +Rust's macro system, however, can eliminate the repetition. Macros are +lightweight custom syntax extensions, themselves defined using the +`macro_rules!` syntax extension. The following `early_return` macro captures +the pattern in the above code: + +~~~~ +# enum t { special_a(uint), special_b(uint) }; +# fn f() -> uint { +# let input_1 = special_a(0); +# let input_2 = special_a(0); +macro_rules! early_return( + ($inp:expr $sp:ident) => ( // invoke it like `(input_5 special_e)` + match $inp { + $sp(x) => { return x; } + _ => {} + } + ); +) +// ... +early_return!(input_1 special_a); +// ... +early_return!(input_2 special_b); +# return 0; +# } +~~~~ + +Macros are defined in pattern-matching style: in the above example, the text +`($inp:expr $sp:ident)` that appears on the left-hand side of the `=>` is the +*macro invocation syntax*, a pattern denoting how to write a call to the +macro. The text on the right-hand side of the `=>`, beginning with `match +$inp`, is the *macro transcription syntax*: what the macro expands to. + +# Invocation syntax + +The macro invocation syntax specifies the syntax for the arguments to the +macro. It appears on the left-hand side of the `=>` in a macro definition. It +conforms to the following rules: + +1. It must be surrounded by parentheses. +2. `$` has special meaning (described below). +3. The `()`s, `[]`s, and `{}`s it contains must balance. For example, `([)` is +forbidden. + +Otherwise, the invocation syntax is free-form. + +To take as an argument a fragment of Rust code, write `$` followed by a name + (for use on the right-hand side), followed by a `:`, followed by a *fragment + specifier*. The fragment specifier denotes the sort of fragment to match. The + most common fragment specifiers are: + +* `ident` (an identifier, referring to a variable or item. Examples: `f`, `x`, + `foo`.) +* `expr` (an expression. Examples: `2 + 2`; `if true then { 1 } else { 2 }`; + `f(42)`.) +* `ty` (a type. Examples: `int`, `~[(char, ~str)]`, `&T`.) +* `pat` (a pattern, usually appearing in a `match` or on the left-hand side of + a declaration. Examples: `Some(t)`; `(17, 'a')`; `_`.) +* `block` (a sequence of actions. Example: `{ log(error, "hi"); return 12; }`) + +The parser interprets any token that's not preceded by a `$` literally. Rust's usual +rules of tokenization apply, + +So `($x:ident -> (($e:expr)))`, though excessively fancy, would designate a macro +that could be invoked like: `my_macro!(i->(( 2+2 )))`. + +## Invocation location + +A macro invocation may take the place of (and therefore expand to) +an expression, an item, or a statement. +The Rust parser will parse the macro invocation as a "placeholder" +for whichever of those three nonterminals is appropriate for the location. + +At expansion time, the output of the macro will be parsed as whichever of the +three nonterminals it stands in for. This means that a single macro might, +for example, expand to an item or an expression, depending on its arguments +(and cause a syntax error if it is called with the wrong argument for its +location). Although this behavior sounds excessively dynamic, it is known to +be useful under some circumstances. + + +# Transcription syntax + +The right-hand side of the `=>` follows the same rules as the left-hand side, +except that a `$` need only be followed by the name of the syntactic fragment +to transcribe into the macro expansion; its type need not be repeated. + +The right-hand side must be enclosed by delimiters, which the transcriber ignores. +Therefore `() => ((1,2,3))` is a macro that expands to a tuple expression, +`() => (let $x=$val)` is a macro that expands to a statement, +and `() => (1,2,3)` is a macro that expands to a syntax error +(since the transcriber interprets the parentheses on the right-hand-size as delimiters, +and `1,2,3` is not a valid Rust expression on its own). + +Except for permissibility of `$name` (and `$(...)*`, discussed below), the +right-hand side of a macro definition is ordinary Rust syntax. In particular, +macro invocations (including invocations of the macro currently being defined) +are permitted in expression, statement, and item locations. However, nothing +else about the code is examined or executed by the macro system; execution +still has to wait until run-time. + +## Interpolation location + +The interpolation `$argument_name` may appear in any location consistent with +its fragment specifier (i.e., if it is specified as `ident`, it may be used +anywhere an identifier is permitted). + +# Multiplicity + +## Invocation + +Going back to the motivating example, recall that `early_return` expanded into +a `match` that would `return` if the `match`'s scrutinee matched the +"special case" identifier provided as the second argument to `early_return`, +and do nothing otherwise. Now suppose that we wanted to write a +version of `early_return` that could handle a variable number of "special" +cases. + +The syntax `$(...)*` on the left-hand side of the `=>` in a macro definition +accepts zero or more occurrences of its contents. It works much +like the `*` operator in regular expressions. It also supports a +separator token (a comma-separated list could be written `$(...),*`), and `+` +instead of `*` to mean "at least one". + +~~~~ +# enum t { special_a(uint),special_b(uint),special_c(uint),special_d(uint)}; +# fn f() -> uint { +# let input_1 = special_a(0); +# let input_2 = special_a(0); +macro_rules! early_return( + ($inp:expr, [ $($sp:ident)|+ ]) => ( + match $inp { + $( + $sp(x) => { return x; } + )+ + _ => {} + } + ); +) +// ... +early_return!(input_1, [special_a|special_c|special_d]); +// ... +early_return!(input_2, [special_b]); +# return 0; +# } +~~~~ + +### Transcription + +As the above example demonstrates, `$(...)*` is also valid on the right-hand +side of a macro definition. The behavior of `*` in transcription, +especially in cases where multiple `*`s are nested, and multiple different +names are involved, can seem somewhat magical and intuitive at first. The +system that interprets them is called "Macro By Example". The two rules to +keep in mind are (1) the behavior of `$(...)*` is to walk through one "layer" +of repetitions for all of the `$name`s it contains in lockstep, and (2) each +`$name` must be under at least as many `$(...)*`s as it was matched against. +If it is under more, it'll be repeated, as appropriate. + +## Parsing limitations + + +For technical reasons, there are two limitations to the treatment of syntax +fragments by the macro parser: + +1. The parser will always parse as much as possible of a Rust syntactic +fragment. For example, if the comma were omitted from the syntax of +`early_return!` above, `input_1 [` would've been interpreted as the beginning +of an array index. In fact, invoking the macro would have been impossible. +2. The parser must have eliminated all ambiguity by the time it reaches a +`$name:fragment_specifier` declaration. This limitation can result in parse +errors when declarations occur at the beginning of, or immediately after, +a `$(...)*`. For example, the grammar `$($t:ty)* $e:expr` will always fail to +parse because the parser would be forced to choose between parsing `t` and +parsing `e`. Changing the invocation syntax to require a distinctive token in +front can solve the problem. In the above example, `$(T $t:ty)* E $e:exp` +solves the problem. + +# Macro argument pattern matching + +## Motivation + +Now consider code like the following: + +~~~~ +# enum t1 { good_1(t2, uint), bad_1 }; +# struct t2 { body: t3 } +# enum t3 { good_2(uint), bad_2}; +# fn f(x: t1) -> uint { +match x { + good_1(g1, val) => { + match g1.body { + good_2(result) => { + // complicated stuff goes here + return result + val; + }, + _ => fail!("Didn't get good_2") + } + } + _ => return 0 // default value +} +# } +~~~~ + +All the complicated stuff is deeply indented, and the error-handling code is +separated from matches that fail. We'd like to write a macro that performs +a match, but with a syntax that suits the problem better. The following macro +can solve the problem: + +~~~~ +macro_rules! biased_match ( + // special case: `let (x) = ...` is illegal, so use `let x = ...` instead + ( ($e:expr) ~ ($p:pat) else $err:stmt ; + binds $bind_res:ident + ) => ( + let $bind_res = match $e { + $p => ( $bind_res ), + _ => { $err } + }; + ); + // more than one name; use a tuple + ( ($e:expr) ~ ($p:pat) else $err:stmt ; + binds $( $bind_res:ident ),* + ) => ( + let ( $( $bind_res ),* ) = match $e { + $p => ( $( $bind_res ),* ), + _ => { $err } + }; + ) +) + +# enum t1 { good_1(t2, uint), bad_1 }; +# struct t2 { body: t3 } +# enum t3 { good_2(uint), bad_2}; +# fn f(x: t1) -> uint { +biased_match!((x) ~ (good_1(g1, val)) else { return 0 }; + binds g1, val ) +biased_match!((g1.body) ~ (good_2(result) ) + else { fail!("Didn't get good_2") }; + binds result ) +// complicated stuff goes here +return result + val; +# } +~~~~ + +This solves the indentation problem. But if we have a lot of chained matches +like this, we might prefer to write a single macro invocation. The input +pattern we want is clear: + +~~~~ +# macro_rules! b( + ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )* + binds $( $bind_res:ident ),* + ) +# => (0)) +~~~~ + +However, it's not possible to directly expand to nested match statements. But +there is a solution. + +## The recursive approach to macro writing + +A macro may accept multiple different input grammars. The first one to +successfully match the actual argument to a macro invocation is the one that +"wins". + +In the case of the example above, we want to write a recursive macro to +process the semicolon-terminated lines, one-by-one. So, we want the following +input patterns: + +~~~~ +# macro_rules! b( + ( binds $( $bind_res:ident ),* ) +# => (0)) +~~~~ + +...and: + +~~~~ +# macro_rules! b( + ( ($e :expr) ~ ($p :pat) else $err :stmt ; + $( ($e_rest:expr) ~ ($p_rest:pat) else $err_rest:stmt ; )* + binds $( $bind_res:ident ),* + ) +# => (0)) +~~~~ + +The resulting macro looks like this. Note that the separation into +`biased_match!` and `biased_match_rec!` occurs only because we have an outer +piece of syntax (the `let`) which we only want to transcribe once. + +~~~~ + +macro_rules! biased_match_rec ( + // Handle the first layer + ( ($e :expr) ~ ($p :pat) else $err :stmt ; + $( ($e_rest:expr) ~ ($p_rest:pat) else $err_rest:stmt ; )* + binds $( $bind_res:ident ),* + ) => ( + match $e { + $p => { + // Recursively handle the next layer + biased_match_rec!($( ($e_rest) ~ ($p_rest) else $err_rest ; )* + binds $( $bind_res ),* + ) + } + _ => { $err } + } + ); + ( binds $( $bind_res:ident ),* ) => ( ($( $bind_res ),*) ) +) + +// Wrap the whole thing in a `let`. +macro_rules! biased_match ( + // special case: `let (x) = ...` is illegal, so use `let x = ...` instead + ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )* + binds $bind_res:ident + ) => ( + let ( $( $bind_res ),* ) = biased_match_rec!( + $( ($e) ~ ($p) else $err ; )* + binds $bind_res + ); + ); + // more than one name: use a tuple + ( $( ($e:expr) ~ ($p:pat) else $err:stmt ; )* + binds $( $bind_res:ident ),* + ) => ( + let ( $( $bind_res ),* ) = biased_match_rec!( + $( ($e) ~ ($p) else $err ; )* + binds $( $bind_res ),* + ); + ) +) + + +# enum t1 { good_1(t2, uint), bad_1 }; +# struct t2 { body: t3 } +# enum t3 { good_2(uint), bad_2}; +# fn f(x: t1) -> uint { +biased_match!( + (x) ~ (good_1(g1, val)) else { return 0 }; + (g1.body) ~ (good_2(result) ) else { fail!("Didn't get good_2") }; + binds val, result ) +// complicated stuff goes here +return result + val; +# } +~~~~ + +This technique applies to many cases where transcribing a result all at once is not possible. +The resulting code resembles ordinary functional programming in some respects, +but has some important differences from functional programming. + +The first difference is important, but also easy to forget: the transcription +(right-hand) side of a `macro_rules!` rule is literal syntax, which can only +be executed at run-time. If a piece of transcription syntax does not itself +appear inside another macro invocation, it will become part of the final +program. If it is inside a macro invocation (for example, the recursive +invocation of `biased_match_rec!`), it does have the opportunity to affect +transcription, but only through the process of attempted pattern matching. + +The second, related, difference is that the evaluation order of macros feels +"backwards" compared to ordinary programming. Given an invocation +`m1!(m2!())`, the expander first expands `m1!`, giving it as input the literal +syntax `m2!()`. If it transcribes its argument unchanged into an appropriate +position (in particular, not as an argument to yet another macro invocation), +the expander will then proceed to evaluate `m2!()` (along with any other macro +invocations `m1!(m2!())` produced). + +# A final note + +Macros, as currently implemented, are not for the faint of heart. Even +ordinary syntax errors can be more difficult to debug when they occur inside a +macro, and errors caused by parse problems in generated code can be very +tricky. Invoking the `log_syntax!` macro can help elucidate intermediate +states, invoking `trace_macros!(true)` will automatically print those +intermediate states out, and passing the flag `--pretty expanded` as a +command-line argument to the compiler will show the result of expansion. diff --git a/src/doc/guide-pointers.md b/src/doc/guide-pointers.md new file mode 100644 index 00000000000..19696b42a37 --- /dev/null +++ b/src/doc/guide-pointers.md @@ -0,0 +1,492 @@ +% The Rust Pointer Guide + +Rust's pointers are one of its more unique and compelling features. Pointers +are also one of the more confusing topics for newcomers to Rust. They can also +be confusing for people coming from other languages that support pointers, such +as C++. This guide will help you understand this important topic. + +# You don't actually need pointers + +I have good news for you: you probably don't need to care about pointers, +especially as you're getting started. Think of it this way: Rust is a language +that emphasizes safety. Pointers, as the joke goes, are very pointy: it's easy +to accidentally stab yourself. Therefore, Rust is made in a way such that you +don't need them very often. + +"But guide!" you may cry. "My co-worker wrote a function that looks like this: + +~~~rust +fn succ(x: &int) -> int { *x + 1 } +~~~ + +So I wrote this code to try it out: + +~~~rust{.ignore} +fn main() { + let number = 5; + let succ_number = succ(number); + println!("{}", succ_number); +} +~~~ + +And now I get an error: + +~~~ {.notrust} +error: mismatched types: expected `&int` but found `<VI0>` (expected &-ptr but found integral variable) +~~~ + +What gives? It needs a pointer! Therefore I have to use pointers!" + +Turns out, you don't. All you need is a reference. Try this on for size: + +~~~rust +# fn succ(x: &int) -> int { *x + 1 } +fn main() { + let number = 5; + let succ_number = succ(&number); + println!("{}", succ_number); +} +~~~ + +It's that easy! One extra little `&` there. This code will run, and print `6`. + +That's all you need to know. Your co-worker could have written the function +like this: + +~~~rust +fn succ(x: int) -> int { x + 1 } + +fn main() { + let number = 5; + let succ_number = succ(number); + println!("{}", succ_number); +} +~~~ + +No pointers even needed. Then again, this is a simple example. I assume that +your real-world `succ` function is more complicated, and maybe your co-worker +had a good reason for `x` to be a pointer of some kind. In that case, references +are your best friend. Don't worry about it, life is too short. + +However. + +Here are the use-cases for pointers. I've prefixed them with the name of the +pointer that satisfies that use-case: + +1. Owned: ~Trait must be a pointer, because you don't know the size of the +object, so indirection is mandatory. +2. Owned: You need a recursive data structure. These can be infinite sized, so +indirection is mandatory. +3. Owned: A very, very, very rare situation in which you have a *huge* chunk of +data that you wish to pass to many methods. Passing a pointer will make this +more efficient. If you're coming from another language where this technique is +common, such as C++, please read "A note..." below. +4. Managed: Having only a single owner to a piece of data would be inconvenient +or impossible. This is only often useful when a program is very large or very +complicated. Using a managed pointer will activate Rust's garbage collection +mechanism. +5. Reference: You're writing a function, and you need a pointer, but you don't +care about its ownership. If you make the argument a reference, callers +can send in whatever kind they want. + +Five exceptions. That's it. Otherwise, you shouldn't need them. Be sceptical +of pointers in Rust: use them for a deliberate purpose, not just to make the +compiler happy. + +## A note for those proficient in pointers + +If you're coming to Rust from a language like C or C++, you may be used to +passing things by reference, or passing things by pointer. In some languages, +like Java, you can't even have objects without a pointer to them. Therefore, if +you were writing this Rust code: + +~~~rust +# fn transform(p: Point) -> Point { p } +struct Point { + x: int, + y: int, +} + +fn main() { + let p0 = Point { x: 5, y: 10}; + let p1 = transform(p0); + println!("{:?}", p1); +} + +~~~ + +I think you'd implement `transform` like this: + +~~~rust +# struct Point { +# x: int, +# y: int, +# } +# let p0 = Point { x: 5, y: 10}; +fn transform(p: &Point) -> Point { + Point { x: p.x + 1, y: p.y + 1} +} + +// and change this: +let p1 = transform(&p0); +~~~ + +This does work, but you don't need to create those references! The better way to write this is simply: + +~~~rust +struct Point { + x: int, + y: int, +} + +fn transform(p: Point) -> Point { + Point { x: p.x + 1, y: p.y + 1} +} + +fn main() { + let p0 = Point { x: 5, y: 10}; + let p1 = transform(p0); + println!("{:?}", p1); +} +~~~ + +But won't this be inefficient? Well, that's a complicated question, but it's +important to know that Rust, like C and C++, store aggregate data types +'unboxed,' whereas languages like Java and Ruby store these types as 'boxed.' +For smaller structs, this way will be more efficient. For larger ones, it may +be less so. But don't reach for that pointer until you must! Make sure that the +struct is large enough by performing some tests before you add in the +complexity of pointers. + +# Owned Pointers + +Owned pointers are the conceptually simplest kind of pointer in Rust. A rough +approximation of owned pointers follows: + +1. Only one owned pointer may exist to a particular place in memory. It may be +borrowed from that owner, however. +2. The Rust compiler uses static analysis to determine where the pointer is in +scope, and handles allocating and de-allocating that memory. Owned pointers are +not garbage collected. + +These two properties make for three use cases. + +## References to Traits + +Traits must be referenced through a pointer, because the struct that implements +the trait may be a different size than a different struct that implements the +trait. Therefore, unboxed traits don't make any sense, and aren't allowed. + +## Recursive Data Structures + +Sometimes, you need a recursive data structure. The simplest is known as a 'cons list': + +~~~rust +enum List<T> { + Nil, + Cons(T, ~List<T>), +} + +fn main() { + let list: List<int> = Cons(1, ~Cons(2, ~Cons(3, ~Nil))); + println!("{:?}", list); +} +~~~ + +This prints: + +~~~ {.notrust} +Cons(1, ~Cons(2, ~Cons(3, ~Nil))) +~~~ + +The inner lists _must_ be an owned pointer, because we can't know how many +elements are in the list. Without knowing the length, we don't know the size, +and therefore require the indirection that pointers offer. + +## Efficiency + +This should almost never be a concern, but because creating an owned pointer +boxes its value, it therefore makes referring to the value the size of the box. +This may make passing an owned pointer to a function less expensive than +passing the value itself. Don't worry yourself with this case until you've +proved that it's an issue through benchmarks. + +For example, this will work: + +~~~rust +struct Point { + x: int, + y: int, +} + +fn main() { + let a = Point { x: 10, y: 20 }; + spawn(proc() { + println!("{}", a.x); + }); +} +~~~ + +This struct is tiny, so it's fine. If `Point` were large, this would be more +efficient: + +~~~rust +struct Point { + x: int, + y: int, +} + +fn main() { + let a = ~Point { x: 10, y: 20 }; + spawn(proc() { + println!("{}", a.x); + }); +} +~~~ + +Now it'll be copying a pointer-sized chunk of memory rather than the whole +struct. + +# Managed Pointers + +> **Note**: the `@` form of managed pointers is deprecated and behind a +> feature gate (it requires a `#[feature(managed_pointers)];` attribute on +> the crate root; remember the semicolon!). There are replacements, currently +> there is `std::rc::Rc` and `std::gc::Gc` for shared ownership via reference +> counting and garbage collection respectively. + +Managed pointers, notated by an `@`, are used when having a single owner for +some data isn't convenient or possible. This generally happens when your +program is very large and complicated. + +For example, let's say you're using an owned pointer, and you want to do this: + +~~~rust{.ignore} +struct Point { + x: int, + y: int, +} + +fn main() { + let a = ~Point { x: 10, y: 20 }; + let b = a; + println!("{}", b.x); + println!("{}", a.x); +} +~~~ + +You'll get this error: + +~~~ {.notrust} +test.rs:10:20: 10:21 error: use of moved value: `a` +test.rs:10 println!("{}", a.x); + ^ +note: in expansion of format_args! +<std-macros>:158:27: 158:81 note: expansion site +<std-macros>:157:5: 159:6 note: in expansion of println! +test.rs:10:5: 10:25 note: expansion site +test.rs:8:9: 8:10 note: `a` moved here because it has type `~Point`, which is moved by default (use `ref` to override) +test.rs:8 let b = a; + ^ +~~~ + +As the message says, owned pointers only allow for one owner at a time. When you assign `a` to `b`, `a` becomes invalid. Change your code to this, however: + +~~~rust +struct Point { + x: int, + y: int, +} + +fn main() { + let a = @Point { x: 10, y: 20 }; + let b = a; + println!("{}", b.x); + println!("{}", a.x); +} +~~~ + +And it works: + +~~~ {.notrust} +10 +10 +~~~ + +So why not just use managed pointers everywhere? There are two big drawbacks to +managed pointers: + +1. They activate Rust's garbage collector. Other pointer types don't share this +drawback. +2. You cannot pass this data to another task. Shared ownership across +concurrency boundaries is the source of endless pain in other languages, so +Rust does not let you do this. + +# References + +References are the third major kind of pointer Rust supports. They are +simultaneously the simplest and the most complicated kind. Let me explain: +references are considered 'borrowed' because they claim no ownership over the +data they're pointing to. They're just borrowing it for a while. So in that +sense, they're simple: just keep whatever ownership the data already has. For +example: + +~~~rust +use std::num::sqrt; + +struct Point { + x: f32, + y: f32, +} + +fn compute_distance(p1: &Point, p2: &Point) -> f32 { + let x_d = p1.x - p2.x; + let y_d = p1.y - p2.y; + + sqrt(x_d * x_d + y_d * y_d) +} + +fn main() { + let origin = @Point { x: 0.0, y: 0.0 }; + let p1 = ~Point { x: 5.0, y: 3.0 }; + + println!("{:?}", compute_distance(origin, p1)); +} +~~~ + +This prints `5.83095189`. You can see that the `compute_distance` function +takes in two references, but we give it a managed and unique pointer. Of +course, if this were a real program, we wouldn't have any of these pointers, +they're just there to demonstrate the concepts. + +So how is this hard? Well, because we're ignoring ownership, the compiler needs +to take great care to make sure that everything is safe. Despite their complete +safety, a reference's representation at runtime is the same as that of +an ordinary pointer in a C program. They introduce zero overhead. The compiler +does all safety checks at compile time. + +This theory is called 'region pointers,' and involve a concept called +'lifetimes'. Here's the simple explanation: would you expect this code to +compile? + +~~~rust{.ignore} +fn main() { + println!("{}", x); + let x = 5; +} +~~~ + +Probably not. That's because you know that the name `x` is valid from where +it's declared to when it goes out of scope. In this case, that's the end of +the `main` function. So you know this code will cause an error. We call this +duration a 'lifetime'. Let's try a more complex example: + +~~~rust +fn main() { + let mut x = ~5; + if *x < 10 { + let y = &x; + println!("Oh no: {:?}", y); + return; + } + *x -= 1; + println!("Oh no: {:?}", x); +} +~~~ + +Here, we're borrowing a pointer to `x` inside of the `if`. The compiler, however, +is able to determine that that pointer will go out of scope without `x` being +mutated, and therefore, lets us pass. This wouldn't work: + +~~~rust{.ignore} +fn main() { + let mut x = ~5; + if *x < 10 { + let y = &x; + *x -= 1; + + println!("Oh no: {:?}", y); + return; + } + *x -= 1; + println!("Oh no: {:?}", x); +} +~~~ + +It gives this error: + +~~~ {.notrust} +test.rs:5:8: 5:10 error: cannot assign to `*x` because it is borrowed +test.rs:5 *x -= 1; + ^~ +test.rs:4:16: 4:18 note: borrow of `*x` occurs here +test.rs:4 let y = &x; + ^~ +~~~ + +As you might guess, this kind of analysis is complex for a human, and therefore +hard for a computer, too! There is an entire [guide devoted to references +and lifetimes](guide-lifetimes.html) that goes into lifetimes in +great detail, so if you want the full details, check that out. + +# Returning Pointers + +We've talked a lot about functions that accept various kinds of pointers, but +what about returning them? Here's the rule of thumb: only return a unique or +managed pointer if you were given one in the first place. + +What does that mean? Don't do this: + +~~~rust +fn foo(x: ~int) -> ~int { + return ~*x; +} + +fn main() { + let x = ~5; + let y = foo(x); +} +~~~ + +Do this: + +~~~rust +fn foo(x: ~int) -> int { + return *x; +} + +fn main() { + let x = ~5; + let y = ~foo(x); +} +~~~ + +This gives you flexibility, without sacrificing performance. For example, this will +also work: + +~~~rust +fn foo(x: ~int) -> int { + return *x; +} + +fn main() { + let x = ~5; + let y = @foo(x); +} +~~~ + +You may think that this gives us terrible performance: return a value and then +immediately box it up?!?! Isn't that the worst of both worlds? Rust is smarter +than that. There is no copy in this code. `main` allocates enough room for the +`@int`, passes a pointer to that memory into `foo` as `x`, and then `foo` writes +the value straight into that pointer. This writes the return value directly into +the allocated box. + +This is important enough that it bears repeating: pointers are not for optimizing +returning values from your code. Allow the caller to choose how they want to +use your output. + + +# Related Resources + +* [Lifetimes guide](guide-lifetimes.html) diff --git a/src/doc/guide-runtime.md b/src/doc/guide-runtime.md new file mode 100644 index 00000000000..b6a54b042e9 --- /dev/null +++ b/src/doc/guide-runtime.md @@ -0,0 +1,263 @@ +% A Guide to the Rust Runtime + +Rust includes two runtime libraries in the standard distribution, which provide +a unified interface to primitives such as I/O, but the language itself does not +require a runtime. The compiler is capable of generating code that works in all +environments, even kernel environments. Neither does the Rust language need a +runtime to provide memory safety; the type system itself is sufficient to write +safe code, verified statically at compile time. The runtime merely uses the +safety features of the language to build a number of convenient and safe +high-level abstractions. + +That being said, code without a runtime is often very limited in what it can do. +As a result, Rust's standard libraries supply a set of functionality that is +normally considered the Rust runtime. This guide will discuss Rust's user-space +runtime, how to use it, and what it can do. + +# What is the runtime? + +The Rust runtime can be viewed as a collection of code which enables services +like I/O, task spawning, TLS, etc. It's essentially an ephemeral collection of +objects which enable programs to perform common tasks more easily. The actual +implementation of the runtime itself is mostly a sparse set of opt-in primitives +that are all self-contained and avoid leaking their abstractions into libraries. + +The current runtime is the engine behind these features (not a comprehensive +list): + +* I/O +* Task spawning +* Message passing +* Task synchronization +* Task-local storage +* Logging +* Local heaps (GC heaps) +* Task unwinding + +## What is the runtime accomplishing? + +The runtime is designed with a few goals in mind: + +* Rust libraries should work in a number of environments without having to worry + about the exact details of the environment itself. Two commonly referred to + environments are the M:N and 1:1 environments. Since the Rust runtime was + first designed, it has supported M:N threading, and it has since gained 1:1 + support as well. + +* The runtime should not enforce separate "modes of compilation" in order to + work in multiple circumstances. Is it an explicit goal that you compile a Rust + library once and use it forever (in all environments). + +* The runtime should be fast. There should be no architectural design barrier + which is preventing programs from running at optimal speeds. It is not a goal + for the runtime to be written "as fast as can be" at every moment in time. For + example, no claims will be made that the current implementation of the runtime + is the fastest it will ever be. This goal is simply to prevent any + architectural roadblock from hindering performance. + +* The runtime should be nearly invisible. The design of the runtime should not + encourage direct interaction with it, and using the runtime should be + essentially transparent to libraries. This does not mean it should be + impossible to query the runtime, but rather it should be unconventional. + +# Architecture of the runtime + +This section explains the current architecture of the Rust runtime. It has +evolved over the development of Rust through many iterations, and this is simply +the documentation of the current iteration. + +## A local task + +The core abstraction of the Rust runtime is the task. A task represents a +"thread" of execution of Rust code, but it does not necessarily correspond to an +OS thread. Most runtime services are accessed through the local task, allowing +for runtime policy decisions to be made on a per-task basis. + +A consequence of this decision is to require all Rust code using the standard +library to have a local `Task` structure available to them. This `Task` is +stored in the OS's thread local storage (OS TLS) to allow for efficient access +to it. + +It has also been decided that the presence or non-presence of a local `Task` is +essentially the *only* assumption that the runtime can make. Almost all runtime +services are routed through this local structure. + +This requirement of a local task is a core assumption on behalf of *all* code +using the standard library, hence it is defined in the standard library itself. + +## I/O + +When dealing with I/O in general, there are a few flavors by which it can be +dealt with, and not all flavors are right for all situations. I/O is also a +tricky topic that is nearly impossible to get consistent across all +environments. As a result, a Rust task is not guaranteed to have access to I/O, +and it is not even guaranteed what the implementation of the I/O will be. + +This conclusion implies that I/O *cannot* be defined in the standard library. +The standard library does, however, provide the interface to I/O that all Rust +tasks are able to consume. + +This interface is implemented differently for various flavors of tasks, and is +designed with a focus around synchronous I/O calls. This architecture does not +fundamentally prevent other forms of I/O from being defined, but it is not done +at this time. + +The I/O interface that the runtime must provide can be found in the +[std::rt::rtio](std/rt/rtio/trait.IoFactory.html) module. Note that this +interface is *unstable*, and likely always will be. + +## Task Spawning + +A frequent operation performed by tasks is to spawn a child task to perform some +work. This is the means by which parallelism is enabled in Rust. This decision +of how to spawn a task is not a general decision, and is hence a local decision +to the task (not defined in the standard library). + +Task spawning is interpreted as "spawning a sibling" and is enabled through the +high level interface in `std::task`. The child task can be configured +accordingly, and runtime implementations must respect these options when +spawning a new task. + +Another local task operation is dealing with the runnable state of the task +itself. This frequently comes up when the question is "how do I block a task?" +or "how do I wake up a task?". These decisions are inherently local to the task +itself, yet again implying that they are not defined in the standard library. + +## The `Runtime` trait and the `Task` structure + +The full complement of runtime features is defined by the [`Runtime` +trait](std/rt/trait.Runtime.html) and the [`Task` +struct](std/rt/task/struct.Task.html). A `Task` is constant among all runtime +implementations, but each runtime implements has its own implementation of the +`Runtime` trait. + +The local `Task` stores the runtime value inside of itself, and then ownership +dances ensue to invoke methods on the runtime. + +# Implementations of the runtime + +The Rust distribution provides two implementations of the runtime. These two +implementations are generally known as 1:1 threading and M:N threading. + +As with many problems in computer science, there is no right answer in this +question of which implementation of the runtime to choose. Each implementation +has its benefits and each has its drawbacks. The descriptions below are meant to +inform programmers about what the implementation provides and what it doesn't +provide in order to make an informed decision about which to choose. + +## 1:1 - using `libnative` + +The library `libnative` is an implementation of the runtime built upon native OS +threads plus libc blocking I/O calls. This is called 1:1 threading because each +user-space thread corresponds to exactly one kernel thread. + +In this model, each Rust task corresponds to one OS thread, and each I/O object +essentially corresponds to a file descriptor (or the equivalent of the platform +you're running on). + +Some benefits to using libnative are: + +* Guaranteed interop with FFI bindings. If a C library you are using blocks the + thread to do I/O (such as a database driver), then this will not interfere + with other Rust tasks (because only the OS thread will be blocked). +* Less I/O overhead as opposed to M:N in some cases. Not all M:N I/O is + guaranteed to be "as fast as can be", and some things (like filesystem APIs) + are not truly asynchronous on all platforms, meaning that the M:N + implementation may incur more overhead than a 1:1 implementation. + +## M:N - using `libgreen` + +The library `libgreen` implements the runtime with "green threads" on top of the +asynchronous I/O framework [libuv][libuv]. The M in M:N threading is the number +of OS threads that a process has, and the N is the number of Rust tasks. In this +model, N Rust tasks are multiplexed among M OS threads, and context switching is +implemented in user-space. + +The primary concern of an M:N runtime is that a Rust task cannot block itself in +a syscall. If this happens, then the entire OS thread is frozen and unavailable +for running more Rust tasks, making this a (M-1):N runtime (and you can see how +this can reach 0/deadlock). By using asynchronous I/O under the hood (all I/O +still looks synchronous in terms of code), OS threads are never blocked until +the appropriate time comes. + +Upon reading `libgreen`, you may notice that there is no I/O implementation +inside of the library, but rather just the infrastructure for maintaining a set +of green schedulers which switch among Rust tasks. The actual I/O implementation +is found in `librustuv` which are the Rust bindings to libuv. This distinction +is made to allow for other I/O implementations not built on libuv (but none +exist at this time). + +Some benefits of using libgreen are: + +* Fast task spawning. When using M:N threading, spawning a new task can avoid + executing a syscall entirely, which can lead to more efficient task spawning + times. +* Fast task switching. Because context switching is implemented in user-space, + all task contention operations (mutexes, channels, etc) never execute + syscalls, leading to much faster implementations and runtimes. An efficient + context switch also leads to higher throughput servers than 1:1 threading + because tasks can be switched out much more efficiently. + +### Pools of Schedulers + +M:N threading is built upon the concept of a pool of M OS threads (which +libgreen refers to as schedulers), able to run N Rust tasks. This abstraction is +encompassed in libgreen's [`SchedPool`](green/struct.SchedPool.html) type. This type allows for +fine-grained control over the pool of schedulers which will be used to run Rust +tasks. + +In addition the `SchedPool` type is the *only* way through which a new M:N task +can be spawned. Sibling tasks to Rust tasks themselves (created through +`std::task::spawn`) will be spawned into the same pool of schedulers that the +original task was home to. New tasks must previously have some form of handle +into the pool of schedulers in order to spawn a new task. + +## Which to choose? + +With two implementations of the runtime available, a choice obviously needs to +be made to see which will be used. The compiler itself will always by-default +link to one of these runtimes. At the time of this writing, the default runtime +is `libgreen` but in the future this will become `libnative`. + +Having a default decision made in the compiler is done out of necessity and +convenience. The compiler's decision of runtime to link to is *not* an +endorsement of one over the other. As always, this decision can be overridden. + +For example, this program will be linked to "the default runtime" + +~~~{.rust} +fn main() {} +~~~ + +Whereas this program explicitly opts into using a particular runtime + +~~~{.rust} +extern mod green; + +#[start] +fn start(argc: int, argv: **u8) -> int { + green::start(argc, argv, proc() { + main(); + }) +} + +fn main() {} +~~~ + +Both libgreen/libnative provide a top-level `start` function which is used to +boot an initial Rust task in that specified runtime. + +# Finding the runtime + +The actual code for the runtime is spread out among a few locations: + +* [std::rt][stdrt] +* [libnative][libnative] +* [libgreen][libgreen] +* [librustuv][librustuv] + +[libuv]: https://github.com/joyent/libuv/ +[stdrt]: std/rt/index.html +[libnative]: native/index.html +[libgreen]: green/index.html +[librustuv]: rustuv/index.html diff --git a/src/doc/guide-tasks.md b/src/doc/guide-tasks.md new file mode 100644 index 00000000000..c3bdbe3a3ee --- /dev/null +++ b/src/doc/guide-tasks.md @@ -0,0 +1,519 @@ +% The Rust Tasks and Communication Guide + +# Introduction + +Rust provides safe concurrency through a combination +of lightweight, memory-isolated tasks and message passing. +This guide will describe the concurrency model in Rust, how it +relates to the Rust type system, and introduce +the fundamental library abstractions for constructing concurrent programs. + +Rust tasks are not the same as traditional threads: rather, +they are considered _green threads_, lightweight units of execution that the Rust +runtime schedules cooperatively onto a small number of operating system threads. +On a multi-core system Rust tasks will be scheduled in parallel by default. +Because tasks are significantly +cheaper to create than traditional threads, Rust can create hundreds of +thousands of concurrent tasks on a typical 32-bit system. +In general, all Rust code executes inside a task, including the `main` function. + +In order to make efficient use of memory Rust tasks have dynamically sized stacks. +A task begins its life with a small +amount of stack space (currently in the low thousands of bytes, depending on +platform), and acquires more stack as needed. +Unlike in languages such as C, a Rust task cannot accidentally write to +memory beyond the end of the stack, causing crashes or worse. + +Tasks provide failure isolation and recovery. When a fatal error occurs in Rust +code as a result of an explicit call to `fail!()`, an assertion failure, or +another invalid operation, the runtime system destroys the entire +task. Unlike in languages such as Java and C++, there is no way to `catch` an +exception. Instead, tasks may monitor each other for failure. + +Tasks use Rust's type system to provide strong memory safety guarantees. In +particular, the type system guarantees that tasks cannot share mutable state +with each other. Tasks communicate with each other by transferring _owned_ +data through the global _exchange heap_. + +## A note about the libraries + +While Rust's type system provides the building blocks needed for safe +and efficient tasks, all of the task functionality itself is implemented +in the standard and extra libraries, which are still under development +and do not always present a consistent or complete interface. + +For your reference, these are the standard modules involved in Rust +concurrency at this writing: + +* [`std::task`] - All code relating to tasks and task scheduling, +* [`std::comm`] - The message passing interface, +* [`extra::comm`] - Additional messaging types based on `std::comm`, +* [`extra::sync`] - More exotic synchronization tools, including locks, +* [`extra::arc`] - The Arc (atomically reference counted) type, + for safely sharing immutable data, +* [`extra::future`] - A type representing values that may be computed concurrently and retrieved at a later time. + +[`std::task`]: std/task/index.html +[`std::comm`]: std/comm/index.html +[`extra::comm`]: extra/comm/index.html +[`extra::sync`]: extra/sync/index.html +[`extra::arc`]: extra/arc/index.html +[`extra::future`]: extra/future/index.html + +# Basics + +The programming interface for creating and managing tasks lives +in the `task` module of the `std` library, and is thus available to all +Rust code by default. At its simplest, creating a task is a matter of +calling the `spawn` function with a closure argument. `spawn` executes the +closure in the new task. + +~~~~ +# use std::task::spawn; + +// Print something profound in a different task using a named function +fn print_message() { println!("I am running in a different task!"); } +spawn(print_message); + +// Print something more profound in a different task using a lambda expression +spawn(proc() println!("I am also running in a different task!") ); +~~~~ + +In Rust, there is nothing special about creating tasks: a task is not a +concept that appears in the language semantics. Instead, Rust's type system +provides all the tools necessary to implement safe concurrency: particularly, +_owned types_. The language leaves the implementation details to the standard +library. + +The `spawn` function has a very simple type signature: `fn spawn(f: +proc())`. Because it accepts only owned closures, and owned closures +contain only owned data, `spawn` can safely move the entire closure +and all its associated state into an entirely different task for +execution. Like any closure, the function passed to `spawn` may capture +an environment that it carries across tasks. + +~~~ +# use std::task::spawn; +# fn generate_task_number() -> int { 0 } +// Generate some state locally +let child_task_number = generate_task_number(); + +spawn(proc() { + // Capture it in the remote task + println!("I am child number {}", child_task_number); +}); +~~~ + +## Communication + +Now that we have spawned a new task, it would be nice if we could +communicate with it. Recall that Rust does not have shared mutable +state, so one task may not manipulate variables owned by another task. +Instead we use *pipes*. + +A pipe is simply a pair of endpoints: one for sending messages and another for +receiving messages. Pipes are low-level communication building-blocks and so +come in a variety of forms, each one appropriate for a different use case. In +what follows, we cover the most commonly used varieties. + +The simplest way to create a pipe is to use `Chan::new` +function to create a `(Port, Chan)` pair. In Rust parlance, a *channel* +is a sending endpoint of a pipe, and a *port* is the receiving +endpoint. Consider the following example of calculating two results +concurrently: + +~~~~ +# use std::task::spawn; + +let (port, chan): (Port<int>, Chan<int>) = Chan::new(); + +spawn(proc() { + let result = some_expensive_computation(); + chan.send(result); +}); + +some_other_expensive_computation(); +let result = port.recv(); +# fn some_expensive_computation() -> int { 42 } +# fn some_other_expensive_computation() {} +~~~~ + +Let's examine this example in detail. First, the `let` statement creates a +stream for sending and receiving integers (the left-hand side of the `let`, +`(chan, port)`, is an example of a *destructuring let*: the pattern separates +a tuple into its component parts). + +~~~~ +let (port, chan): (Port<int>, Chan<int>) = Chan::new(); +~~~~ + +The child task will use the channel to send data to the parent task, +which will wait to receive the data on the port. The next statement +spawns the child task. + +~~~~ +# use std::task::spawn; +# fn some_expensive_computation() -> int { 42 } +# let (port, chan) = Chan::new(); +spawn(proc() { + let result = some_expensive_computation(); + chan.send(result); +}); +~~~~ + +Notice that the creation of the task closure transfers `chan` to the child +task implicitly: the closure captures `chan` in its environment. Both `Chan` +and `Port` are sendable types and may be captured into tasks or otherwise +transferred between them. In the example, the child task runs an expensive +computation, then sends the result over the captured channel. + +Finally, the parent continues with some other expensive +computation, then waits for the child's result to arrive on the +port: + +~~~~ +# fn some_other_expensive_computation() {} +# let (port, chan) = Chan::<int>::new(); +# chan.send(0); +some_other_expensive_computation(); +let result = port.recv(); +~~~~ + +The `Port` and `Chan` pair created by `Chan::new` enables efficient +communication between a single sender and a single receiver, but multiple +senders cannot use a single `Chan`, and multiple receivers cannot use a single +`Port`. What if our example needed to compute multiple results across a number +of tasks? The following program is ill-typed: + +~~~ {.ignore} +# use std::task::{spawn}; +# fn some_expensive_computation() -> int { 42 } +let (port, chan) = Chan::new(); + +spawn(proc() { + chan.send(some_expensive_computation()); +}); + +// ERROR! The previous spawn statement already owns the channel, +// so the compiler will not allow it to be captured again +spawn(proc() { + chan.send(some_expensive_computation()); +}); +~~~ + +Instead we can use a `SharedChan`, a type that allows a single +`Chan` to be shared by multiple senders. + +~~~ +# use std::task::spawn; + +let (port, chan) = SharedChan::new(); + +for init_val in range(0u, 3) { + // Create a new channel handle to distribute to the child task + let child_chan = chan.clone(); + spawn(proc() { + child_chan.send(some_expensive_computation(init_val)); + }); +} + +let result = port.recv() + port.recv() + port.recv(); +# fn some_expensive_computation(_i: uint) -> int { 42 } +~~~ + +Here we transfer ownership of the channel into a new `SharedChan` value. Like +`Chan`, `SharedChan` is a non-copyable, owned type (sometimes also referred to +as an *affine* or *linear* type). Unlike with `Chan`, though, the programmer +may duplicate a `SharedChan`, with the `clone()` method. A cloned +`SharedChan` produces a new handle to the same channel, allowing multiple +tasks to send data to a single port. Between `spawn`, `Chan` and +`SharedChan`, we have enough tools to implement many useful concurrency +patterns. + +Note that the above `SharedChan` example is somewhat contrived since +you could also simply use three `Chan` pairs, but it serves to +illustrate the point. For reference, written with multiple streams, it +might look like the example below. + +~~~ +# use std::task::spawn; +# use std::vec; + +// Create a vector of ports, one for each child task +let ports = vec::from_fn(3, |init_val| { + let (port, chan) = Chan::new(); + spawn(proc() { + chan.send(some_expensive_computation(init_val)); + }); + port +}); + +// Wait on each port, accumulating the results +let result = ports.iter().fold(0, |accum, port| accum + port.recv() ); +# fn some_expensive_computation(_i: uint) -> int { 42 } +~~~ + +## Backgrounding computations: Futures +With `extra::future`, rust has a mechanism for requesting a computation and getting the result +later. + +The basic example below illustrates this. + +~~~ +# fn make_a_sandwich() {}; +fn fib(n: u64) -> u64 { + // lengthy computation returning an uint + 12586269025 +} + +let mut delayed_fib = extra::future::Future::spawn(proc() fib(50)); +make_a_sandwich(); +println!("fib(50) = {:?}", delayed_fib.get()) +~~~ + +The call to `future::spawn` returns immediately a `future` object regardless of how long it +takes to run `fib(50)`. You can then make yourself a sandwich while the computation of `fib` is +running. The result of the execution of the method is obtained by calling `get` on the future. +This call will block until the value is available (*i.e.* the computation is complete). Note that +the future needs to be mutable so that it can save the result for next time `get` is called. + +Here is another example showing how futures allow you to background computations. The workload will +be distributed on the available cores. + +~~~ +# use std::vec; +fn partial_sum(start: uint) -> f64 { + let mut local_sum = 0f64; + for num in range(start*100000, (start+1)*100000) { + local_sum += (num as f64 + 1.0).powf(&-2.0); + } + local_sum +} + +fn main() { + let mut futures = vec::from_fn(1000, |ind| extra::future::Future::spawn( proc() { partial_sum(ind) })); + + let mut final_res = 0f64; + for ft in futures.mut_iter() { + final_res += ft.get(); + } + println!("π^2/6 is not far from : {}", final_res); +} +~~~ + +## Sharing immutable data without copy: Arc + +To share immutable data between tasks, a first approach would be to only use pipes as we have seen +previously. A copy of the data to share would then be made for each task. In some cases, this would +add up to a significant amount of wasted memory and would require copying the same data more than +necessary. + +To tackle this issue, one can use an Atomically Reference Counted wrapper (`Arc`) as implemented in +the `extra` library of Rust. With an Arc, the data will no longer be copied for each task. The Arc +acts as a reference to the shared data and only this reference is shared and cloned. + +Here is a small example showing how to use Arcs. We wish to run concurrently several computations on +a single large vector of floats. Each task needs the full vector to perform its duty. + +~~~ +# use std::vec; +# use std::rand; +use extra::arc::Arc; + +fn pnorm(nums: &~[f64], p: uint) -> f64 { + nums.iter().fold(0.0, |a,b| a+(*b).powf(&(p as f64)) ).powf(&(1.0 / (p as f64))) +} + +fn main() { + let numbers = vec::from_fn(1000000, |_| rand::random::<f64>()); + println!("Inf-norm = {}", *numbers.iter().max().unwrap()); + + let numbers_arc = Arc::new(numbers); + + for num in range(1u, 10) { + let (port, chan) = Chan::new(); + chan.send(numbers_arc.clone()); + + spawn(proc() { + let local_arc : Arc<~[f64]> = port.recv(); + let task_numbers = local_arc.get(); + println!("{}-norm = {}", num, pnorm(task_numbers, num)); + }); + } +} +~~~ + +The function `pnorm` performs a simple computation on the vector (it computes the sum of its items +at the power given as argument and takes the inverse power of this value). The Arc on the vector is +created by the line + +~~~ +# use extra::arc::Arc; +# use std::vec; +# use std::rand; +# let numbers = vec::from_fn(1000000, |_| rand::random::<f64>()); +let numbers_arc=Arc::new(numbers); +~~~ + +and a clone of it is sent to each task + +~~~ +# use extra::arc::Arc; +# use std::vec; +# use std::rand; +# let numbers=vec::from_fn(1000000, |_| rand::random::<f64>()); +# let numbers_arc = Arc::new(numbers); +# let (port, chan) = Chan::new(); +chan.send(numbers_arc.clone()); +~~~ + +copying only the wrapper and not its contents. + +Each task recovers the underlying data by + +~~~ +# use extra::arc::Arc; +# use std::vec; +# use std::rand; +# let numbers=vec::from_fn(1000000, |_| rand::random::<f64>()); +# let numbers_arc=Arc::new(numbers); +# let (port, chan) = Chan::new(); +# chan.send(numbers_arc.clone()); +# let local_arc : Arc<~[f64]> = port.recv(); +let task_numbers = local_arc.get(); +~~~ + +and can use it as if it were local. + +The `arc` module also implements Arcs around mutable data that are not covered here. + +# Handling task failure + +Rust has a built-in mechanism for raising exceptions. The `fail!()` macro +(which can also be written with an error string as an argument: `fail!( +~reason)`) and the `assert!` construct (which effectively calls `fail!()` +if a boolean expression is false) are both ways to raise exceptions. When a +task raises an exception the task unwinds its stack---running destructors and +freeing memory along the way---and then exits. Unlike exceptions in C++, +exceptions in Rust are unrecoverable within a single task: once a task fails, +there is no way to "catch" the exception. + +While it isn't possible for a task to recover from failure, tasks may notify +each other of failure. The simplest way of handling task failure is with the +`try` function, which is similar to `spawn`, but immediately blocks waiting +for the child task to finish. `try` returns a value of type `Result<T, +()>`. `Result` is an `enum` type with two variants: `Ok` and `Err`. In this +case, because the type arguments to `Result` are `int` and `()`, callers can +pattern-match on a result to check whether it's an `Ok` result with an `int` +field (representing a successful result) or an `Err` result (representing +termination with an error). + +~~~{.ignore .linked-failure} +# use std::task; +# fn some_condition() -> bool { false } +# fn calculate_result() -> int { 0 } +let result: Result<int, ()> = task::try(proc() { + if some_condition() { + calculate_result() + } else { + fail!("oops!"); + } +}); +assert!(result.is_err()); +~~~ + +Unlike `spawn`, the function spawned using `try` may return a value, +which `try` will dutifully propagate back to the caller in a [`Result`] +enum. If the child task terminates successfully, `try` will +return an `Ok` result; if the child task fails, `try` will return +an `Error` result. + +[`Result`]: std/result/index.html + +> ***Note:*** A failed task does not currently produce a useful error +> value (`try` always returns `Err(())`). In the +> future, it may be possible for tasks to intercept the value passed to +> `fail!()`. + +TODO: Need discussion of `future_result` in order to make failure +modes useful. + +But not all failures are created equal. In some cases you might need to +abort the entire program (perhaps you're writing an assert which, if +it trips, indicates an unrecoverable logic error); in other cases you +might want to contain the failure at a certain boundary (perhaps a +small piece of input from the outside world, which you happen to be +processing in parallel, is malformed and its processing task can't +proceed). + +## Creating a task with a bi-directional communication path + +A very common thing to do is to spawn a child task where the parent +and child both need to exchange messages with each other. The +function `extra::comm::DuplexStream()` supports this pattern. We'll +look briefly at how to use it. + +To see how `DuplexStream()` works, we will create a child task +that repeatedly receives a `uint` message, converts it to a string, and sends +the string in response. The child terminates when it receives `0`. +Here is the function that implements the child task: + +~~~{.ignore .linked-failure} +# use extra::comm::DuplexStream; +# use std::uint; +fn stringifier(channel: &DuplexStream<~str, uint>) { + let mut value: uint; + loop { + value = channel.recv(); + channel.send(uint::to_str(value)); + if value == 0 { break; } + } +} +~~~~ + +The implementation of `DuplexStream` supports both sending and +receiving. The `stringifier` function takes a `DuplexStream` that can +send strings (the first type parameter) and receive `uint` messages +(the second type parameter). The body itself simply loops, reading +from the channel and then sending its response back. The actual +response itself is simply the stringified version of the received value, +`uint::to_str(value)`. + +Here is the code for the parent task: + +~~~{.ignore .linked-failure} +# use std::task::spawn; +# use std::uint; +# use extra::comm::DuplexStream; +# fn stringifier(channel: &DuplexStream<~str, uint>) { +# let mut value: uint; +# loop { +# value = channel.recv(); +# channel.send(uint::to_str(value)); +# if value == 0u { break; } +# } +# } +# fn main() { + +let (from_child, to_child) = DuplexStream::new(); + +spawn(proc() { + stringifier(&to_child); +}); + +from_child.send(22); +assert!(from_child.recv() == ~"22"); + +from_child.send(23); +from_child.send(0); + +assert!(from_child.recv() == ~"23"); +assert!(from_child.recv() == ~"0"); + +# } +~~~~ + +The parent task first calls `DuplexStream` to create a pair of bidirectional +endpoints. It then uses `task::spawn` to create the child task, which captures +one end of the communication channel. As a result, both parent and child can +send and receive data to and from the other. diff --git a/src/doc/guide-testing.md b/src/doc/guide-testing.md new file mode 100644 index 00000000000..b8f7cf97412 --- /dev/null +++ b/src/doc/guide-testing.md @@ -0,0 +1,262 @@ +% The Rust Testing Guide + +# Quick start + +To create test functions, add a `#[test]` attribute like this: + +~~~ +fn return_two() -> int { + 2 +} + +#[test] +fn return_two_test() { + let x = return_two(); + assert!(x == 2); +} +~~~ + +To run these tests, use `rustc --test`: + +~~~ {.notrust} +$ rustc --test foo.rs; ./foo +running 1 test +test return_two_test ... ok + +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured +~~~ + +`rustc foo.rs` will *not* compile the tests, since `#[test]` implies +`#[cfg(test)]`. The `--test` flag to `rustc` implies `--cfg test`. + + +# Unit testing in Rust + +Rust has built in support for simple unit testing. Functions can be +marked as unit tests using the `test` attribute. + +~~~ +#[test] +fn return_none_if_empty() { + // ... test code ... +} +~~~ + +A test function's signature must have no arguments and no return +value. To run the tests in a crate, it must be compiled with the +`--test` flag: `rustc myprogram.rs --test -o myprogram-tests`. Running +the resulting executable will run all the tests in the crate. A test +is considered successful if its function returns; if the task running +the test fails, through a call to `fail!`, a failed `check` or +`assert`, or some other (`assert_eq`, ...) means, then the test fails. + +When compiling a crate with the `--test` flag `--cfg test` is also +implied, so that tests can be conditionally compiled. + +~~~ +#[cfg(test)] +mod tests { + #[test] + fn return_none_if_empty() { + // ... test code ... + } +} +~~~ + +Additionally `#[test]` items behave as if they also have the +`#[cfg(test)]` attribute, and will not be compiled when the `--test` flag +is not used. + +Tests that should not be run can be annotated with the `ignore` +attribute. The existence of these tests will be noted in the test +runner output, but the test will not be run. Tests can also be ignored +by configuration so, for example, to ignore a test on windows you can +write `#[ignore(cfg(target_os = "win32"))]`. + +Tests that are intended to fail can be annotated with the +`should_fail` attribute. The test will be run, and if it causes its +task to fail then the test will be counted as successful; otherwise it +will be counted as a failure. For example: + +~~~ +#[test] +#[should_fail] +fn test_out_of_bounds_failure() { + let v: [int] = []; + v[0]; +} +~~~ + +A test runner built with the `--test` flag supports a limited set of +arguments to control which tests are run: the first free argument +passed to a test runner specifies a filter used to narrow down the set +of tests being run; the `--ignored` flag tells the test runner to run +only tests with the `ignore` attribute. + +## Parallelism + +By default, tests are run in parallel, which can make interpreting +failure output difficult. In these cases you can set the +`RUST_TEST_TASKS` environment variable to 1 to make the tests run +sequentially. + +## Benchmarking + +The test runner also understands a simple form of benchmark execution. +Benchmark functions are marked with the `#[bench]` attribute, rather +than `#[test]`, and have a different form and meaning. They are +compiled along with `#[test]` functions when a crate is compiled with +`--test`, but they are not run by default. To run the benchmark +component of your testsuite, pass `--bench` to the compiled test +runner. + +The type signature of a benchmark function differs from a unit test: +it takes a mutable reference to type `test::BenchHarness`. Inside the +benchmark function, any time-variable or "setup" code should execute +first, followed by a call to `iter` on the benchmark harness, passing +a closure that contains the portion of the benchmark you wish to +actually measure the per-iteration speed of. + +For benchmarks relating to processing/generating data, one can set the +`bytes` field to the number of bytes consumed/produced in each +iteration; this will used to show the throughput of the benchmark. +This must be the amount used in each iteration, *not* the total +amount. + +For example: + +~~~ +extern mod extra; +use std::vec; + +#[bench] +fn bench_sum_1024_ints(b: &mut extra::test::BenchHarness) { + let v = vec::from_fn(1024, |n| n); + b.iter(|| {v.iter().fold(0, |old, new| old + *new);} ); +} + +#[bench] +fn initialise_a_vector(b: &mut extra::test::BenchHarness) { + b.iter(|| {vec::from_elem(1024, 0u64);} ); + b.bytes = 1024 * 8; +} +~~~ + +The benchmark runner will calibrate measurement of the benchmark +function to run the `iter` block "enough" times to get a reliable +measure of the per-iteration speed. + +Advice on writing benchmarks: + + - Move setup code outside the `iter` loop; only put the part you + want to measure inside + - Make the code do "the same thing" on each iteration; do not + accumulate or change state + - Make the outer function idempotent too; the benchmark runner is + likely to run it many times + - Make the inner `iter` loop short and fast so benchmark runs are + fast and the calibrator can adjust the run-length at fine + resolution + - Make the code in the `iter` loop do something simple, to assist in + pinpointing performance improvements (or regressions) + +To run benchmarks, pass the `--bench` flag to the compiled +test-runner. Benchmarks are compiled-in but not executed by default. + +## Examples + +### Typical test run + +~~~ {.notrust} +> mytests + +running 30 tests +running driver::tests::mytest1 ... ok +running driver::tests::mytest2 ... ignored +... snip ... +running driver::tests::mytest30 ... ok + +result: ok. 28 passed; 0 failed; 2 ignored +~~~ {.notrust} + +### Test run with failures + +~~~ {.notrust} +> mytests + +running 30 tests +running driver::tests::mytest1 ... ok +running driver::tests::mytest2 ... ignored +... snip ... +running driver::tests::mytest30 ... FAILED + +result: FAILED. 27 passed; 1 failed; 2 ignored +~~~ + +### Running ignored tests + +~~~ {.notrust} +> mytests --ignored + +running 2 tests +running driver::tests::mytest2 ... failed +running driver::tests::mytest10 ... ok + +result: FAILED. 1 passed; 1 failed; 0 ignored +~~~ + +### Running a subset of tests + +~~~ {.notrust} +> mytests mytest1 + +running 11 tests +running driver::tests::mytest1 ... ok +running driver::tests::mytest10 ... ignored +... snip ... +running driver::tests::mytest19 ... ok + +result: ok. 11 passed; 0 failed; 1 ignored +~~~ + +### Running benchmarks + +~~~ {.notrust} +> mytests --bench + +running 2 tests +test bench_sum_1024_ints ... bench: 709 ns/iter (+/- 82) +test initialise_a_vector ... bench: 424 ns/iter (+/- 99) = 19320 MB/s + +test result: ok. 0 passed; 0 failed; 0 ignored; 2 measured +~~~ + +## Saving and ratcheting metrics + +When running benchmarks or other tests, the test runner can record +per-test "metrics". Each metric is a scalar `f64` value, plus a noise +value which represents uncertainty in the measurement. By default, all +`#[bench]` benchmarks are recorded as metrics, which can be saved as +JSON in an external file for further reporting. + +In addition, the test runner supports _ratcheting_ against a metrics +file. Ratcheting is like saving metrics, except that after each run, +if the output file already exists the results of the current run are +compared against the contents of the existing file, and any regression +_causes the testsuite to fail_. If the comparison passes -- if all +metrics stayed the same (within noise) or improved -- then the metrics +file is overwritten with the new values. In this way, a metrics file +in your workspace can be used to ensure your work does not regress +performance. + +Test runners take 3 options that are relevant to metrics: + + - `--save-metrics=<file.json>` will save the metrics from a test run + to `file.json` + - `--ratchet-metrics=<file.json>` will ratchet the metrics against + the `file.json` + - `--ratchet-noise-percent=N` will override the noise measurements + in `file.json`, and consider a metric change less than `N%` to be + noise. This can be helpful if you are testing in a noisy + environment where the benchmark calibration loop cannot acquire a + clear enough signal. diff --git a/src/doc/index.md b/src/doc/index.md new file mode 100644 index 00000000000..d3270a96d80 --- /dev/null +++ b/src/doc/index.md @@ -0,0 +1,61 @@ +% Rust documentation + +<!-- Completely hide the TOC and the section numbers --> +<style type="text/css"> +#TOC { display: none; } +.header-section-number { display: none; } +li {list-style-type: none; } +</style> + +* [The Rust tutorial](tutorial.html) (* [PDF](tutorial.pdf)) +* [The Rust reference manual](rust.html) (* [PDF](rust.pdf)) + +# Guides + +* [Pointers](guide-pointers.html) +* [References and Lifetimes](guide-lifetimes.html) +* [Containers and Iterators](guide-container.html) +* [Tasks and Communication](guide-tasks.html) +* [Foreign Function Interface](guide-ffi.html) +* [Macros](guide-macros.html) +* [Packaging](guide-rustpkg.html) +* [Testing](guide-testing.html) +* [Conditions](guide-conditions.html) +* [Rust's Runtime](guide-runtime.html) + +# Libraries + +* [The standard library, `libstd`](std/index.html) +* [The extra library, `libextra`](extra/index.html) + +* [The M:N runtime library, `libgreen`](green/index.html) +* [The 1:1 runtime library, `libnative`](native/index.html) + +* [The Rust libuv library, `librustuv`](rustuv/index.html) +* [The Rust packaging library, `librustpkg`](rustpkg/index.html) + +* [The Rust parser, `libsyntax`](syntax/index.html) +* [The Rust compiler, `librustc`](rustc/index.html) + +* [The `arena` allocation library](arena/index.html) +* [The `flate` compression library](flate/index.html) +* [The `glob` file path matching library](glob/index.html) + +# Tooling + +* [The `rustdoc` manual](rustdoc.html) +* [The `rustpkg` manual](rustpkg.html) + +# FAQs + +* [Language FAQ](complement-lang-faq.html) +* [Project FAQ](complement-project-faq.html) +* [Usage FAQ](complement-usage-faq.html) +* [Code cheatsheet](complement-cheatsheet.html) - "How do I do X?" +* [How to submit a bug report](complement-bugreport.html) + +# External resources + +* The Rust [IRC channel](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust) - `#rust` on irc.mozilla.org +* The Rust community on [Reddit](http://reddit.com/r/rust) +* The Rust [wiki](http://github.com/mozilla/rust/wiki) diff --git a/src/doc/lib/codemirror-node.js b/src/doc/lib/codemirror-node.js new file mode 100644 index 00000000000..428ff2e576c --- /dev/null +++ b/src/doc/lib/codemirror-node.js @@ -0,0 +1,125 @@ +exports.htmlEscape = function(text) { + var replacements = {"<": "<", ">": ">", + "&": "&", "\"": """}; + return text.replace(/[<>&"]/g, function(character) { + return replacements[character]; + }); +}; + +exports.splitLines = function(string){return string.split(/\r?\n/);}; + +// Counts the column offset in a string, taking tabs into account. +// Used mostly to find indentation. +function countColumn(string, end) { + tabSize = 4; + if (end == null) { + end = string.search(/[^\s\u00a0]/); + if (end == -1) end = string.length; + } + for (var i = 0, n = 0; i < end; ++i) { + if (string.charAt(i) == "\t") n += tabSize - (n % tabSize); + else ++n; + } + return n; +} + +function StringStream(string) { + this.pos = this.start = 0; + this.string = string; +} +StringStream.prototype = { + eol: function() {return this.pos >= this.string.length;}, + sol: function() {return this.pos == 0;}, + peek: function() {return this.string.charAt(this.pos);}, + next: function() { + if (this.pos < this.string.length) + return this.string.charAt(this.pos++); + }, + eat: function(match) { + var ch = this.string.charAt(this.pos); + if (typeof match == "string") var ok = ch == match; + else var ok = ch && (match.test ? match.test(ch) : match(ch)); + if (ok) {++this.pos; return ch;} + }, + eatWhile: function(match) { + var start = this.pos; + while (this.eat(match)){} + return this.pos > start; + }, + eatSpace: function() { + var start = this.pos; + while (/[\s\u00a0]/.test(this.string.charAt(this.pos))) ++this.pos; + return this.pos > start; + }, + skipToEnd: function() {this.pos = this.string.length;}, + skipTo: function(ch) { + var found = this.string.indexOf(ch, this.pos); + if (found > -1) {this.pos = found; return true;} + }, + backUp: function(n) {this.pos -= n;}, + column: function() {return countColumn(this.string, this.start);}, + indentation: function() {return countColumn(this.string);}, + match: function(pattern, consume, caseInsensitive) { + if (typeof pattern == "string") { + function cased(str) {return caseInsensitive ? str.toLowerCase() : str;} + if (cased(this.string).indexOf(cased(pattern), this.pos) == this.pos) { + if (consume !== false) this.pos += pattern.length; + return true; + } + } + else { + var match = this.string.slice(this.pos).match(pattern); + if (match && consume !== false) this.pos += match[0].length; + return match; + } + }, + current: function(){return this.string.slice(this.start, this.pos);} +}; +exports.StringStream = StringStream; + +exports.startState = function(mode, a1, a2) { + return mode.startState ? mode.startState(a1, a2) : true; +}; + +var modes = {}, mimeModes = {}; +exports.defineMode = function(name, mode) { modes[name] = mode; }; +exports.defineMIME = function(mime, spec) { mimeModes[mime] = spec; }; +exports.getMode = function(options, spec) { + if (typeof spec == "string" && mimeModes.hasOwnProperty(spec)) + spec = mimeModes[spec]; + if (typeof spec == "string") + var mname = spec, config = {}; + else if (spec != null) + var mname = spec.name, config = spec; + var mfactory = modes[mname]; + if (!mfactory) throw new Error("Unknown mode: " + spec); + return mfactory(options, config || {}); +}; + +exports.runMode = function(string, modespec, callback) { + var mode = exports.getMode({indentUnit: 2}, modespec); + var isNode = callback.nodeType == 1; + if (isNode) { + var node = callback, accum = []; + callback = function(string, style) { + if (string == "\n") + accum.push("<br>"); + else if (style) + accum.push("<span class=\"cm-" + exports.htmlEscape(style) + "\">" + exports.htmlEscape(string) + "</span>"); + else + accum.push(exports.htmlEscape(string)); + } + } + var lines = exports.splitLines(string), state = exports.startState(mode); + for (var i = 0, e = lines.length; i < e; ++i) { + if (i) callback("\n"); + var stream = new exports.StringStream(lines[i]); + while (!stream.eol()) { + var style = mode.token(stream, state); + callback(stream.current(), style, i, stream.start); + stream.start = stream.pos; + } + } + if (isNode) + node.innerHTML = accum.join(""); +}; diff --git a/src/doc/lib/codemirror-rust.js b/src/doc/lib/codemirror-rust.js new file mode 100644 index 00000000000..052669be6f5 --- /dev/null +++ b/src/doc/lib/codemirror-rust.js @@ -0,0 +1,432 @@ +CodeMirror.defineMode("rust", function() { + var indentUnit = 4, altIndentUnit = 2; + var valKeywords = { + "if": "if-style", "while": "if-style", "loop": "if-style", "else": "else-style", + "do": "else-style", "return": "else-style", + "break": "atom", "cont": "atom", "const": "let", "resource": "fn", + "let": "let", "fn": "fn", "for": "for", "match": "match", "trait": "trait", + "impl": "impl", "type": "type", "enum": "enum", "struct": "atom", "mod": "mod", + "as": "op", "true": "atom", "false": "atom", "assert": "op", "check": "op", + "claim": "op", "extern": "ignore", "unsafe": "ignore", "import": "else-style", + "export": "else-style", "copy": "op", "log": "op", + "use": "op", "self": "atom", "pub": "atom", "priv": "atom" + }; + var typeKeywords = function() { + var keywords = {"fn": "fn"}; + var atoms = "bool uint int i8 i16 i32 i64 u8 u16 u32 u64 float f32 f64 str char".split(" "); + for (var i = 0, e = atoms.length; i < e; ++i) keywords[atoms[i]] = "atom"; + return keywords; + }(); + var operatorChar = /[+\-*&%=<>!?|\.@]/; + + // Tokenizer + + // Used as scratch variable to communicate multiple values without + // consing up tons of objects. + var tcat, content; + function r(tc, style) { + tcat = tc; + return style; + } + + function tokenBase(stream, state) { + var ch = stream.next(); + if (ch == '"') { + state.tokenize = tokenString; + return state.tokenize(stream, state); + } + if (ch == "'") { + tcat = "atom"; + if (stream.eat("\\")) { + if (stream.skipTo("'")) { stream.next(); return "string"; } + else { return "error"; } + } else { + stream.next(); + return stream.eat("'") ? "string" : "error"; + } + } + if (ch == "/") { + if (stream.eat("/")) { stream.skipToEnd(); return "comment"; } + if (stream.eat("*")) { + state.tokenize = tokenComment(1); + return state.tokenize(stream, state); + } + } + if (ch == "#") { + if (stream.eat("[")) { tcat = "open-attr"; return null; } + stream.eatWhile(/\w/); + return r("macro", "meta"); + } + if (ch == ":" && stream.match(":<")) { + return r("op", null); + } + if (ch.match(/\d/) || (ch == "." && stream.eat(/\d/))) { + var flp = false; + if (!stream.match(/^x[\da-f]+/i) && !stream.match(/^b[01]+/)) { + stream.eatWhile(/\d/); + if (stream.eat(".")) { flp = true; stream.eatWhile(/\d/); } + if (stream.match(/^e[+\-]?\d+/i)) { flp = true; } + } + if (flp) stream.match(/^f(?:32|64)/); + else stream.match(/^[ui](?:8|16|32|64)/); + return r("atom", "number"); + } + if (ch.match(/[()\[\]{}:;,]/)) return r(ch, null); + if (ch == "-" && stream.eat(">")) return r("->", null); + if (ch.match(operatorChar)) { + stream.eatWhile(operatorChar); + return r("op", null); + } + stream.eatWhile(/\w/); + content = stream.current(); + if (stream.match(/^::\w/)) { + stream.backUp(1); + return r("prefix", "variable-2"); + } + if (state.keywords.propertyIsEnumerable(content)) + return r(state.keywords[content], content.match(/true|false/) ? "atom" : "keyword"); + return r("name", "variable"); + } + + function tokenString(stream, state) { + var ch, escaped = false; + while (ch = stream.next()) { + if (ch == '"' && !escaped) { + state.tokenize = tokenBase; + return r("atom", "string"); + } + escaped = !escaped && ch == "\\"; + } + // Hack to not confuse the parser when a string is split in + // pieces. + return r("op", "string"); + } + + function tokenComment(depth) { + return function(stream, state) { + var lastCh = null, ch; + while (ch = stream.next()) { + if (ch == "/" && lastCh == "*") { + if (depth == 1) { + state.tokenize = tokenBase; + break; + } else { + state.tokenize = tokenComment(depth - 1); + return state.tokenize(stream, state); + } + } + if (ch == "*" && lastCh == "/") { + state.tokenize = tokenComment(depth + 1); + return state.tokenize(stream, state); + } + lastCh = ch; + } + return "comment"; + }; + } + + // Parser + + var cx = {state: null, stream: null, marked: null, cc: null}; + function pass() { + for (var i = arguments.length - 1; i >= 0; i--) cx.cc.push(arguments[i]); + } + function cont() { + pass.apply(null, arguments); + return true; + } + + function pushlex(type, info) { + var result = function() { + var state = cx.state; + state.lexical = {indented: state.indented, column: cx.stream.column(), + type: type, prev: state.lexical, info: info}; + }; + result.lex = true; + return result; + } + function poplex() { + var state = cx.state; + if (state.lexical.prev) { + if (state.lexical.type == ")") + state.indented = state.lexical.indented; + state.lexical = state.lexical.prev; + } + } + function typecx() { cx.state.keywords = typeKeywords; } + function valcx() { cx.state.keywords = valKeywords; } + poplex.lex = typecx.lex = valcx.lex = true; + + function commasep(comb, end) { + function more(type) { + if (type == ",") return cont(comb, more); + if (type == end) return cont(); + return cont(more); + } + return function(type) { + if (type == end) return cont(); + return pass(comb, more); + }; + } + + function stat_of(comb, tag) { + return cont(pushlex("stat", tag), comb, poplex, block); + } + function block(type) { + if (type == "}") return cont(); + if (type == "let") return stat_of(letdef1, "let"); + if (type == "fn") return stat_of(fndef); + if (type == "type") return cont(pushlex("stat"), tydef, endstatement, poplex, block); + if (type == "enum") return stat_of(tagdef); + if (type == "mod") return stat_of(mod); + if (type == "trait") return stat_of(trait); + if (type == "impl") return stat_of(impl); + if (type == "open-attr") return cont(pushlex("]"), commasep(expression, "]"), poplex); + if (type == "ignore" || type.match(/[\]\);,]/)) return cont(block); + return pass(pushlex("stat"), expression, poplex, endstatement, block); + } + function endstatement(type) { + if (type == ";") return cont(); + return pass(); + } + function expression(type) { + if (type == "atom" || type == "name") return cont(maybeop); + if (type == "{") return cont(pushlex("}"), exprbrace, poplex); + if (type.match(/[\[\(]/)) return matchBrackets(type, expression); + if (type.match(/[\]\)\};,]/)) return pass(); + if (type == "if-style") return cont(expression, expression); + if (type == "else-style" || type == "op") return cont(expression); + if (type == "for") return cont(pattern, maybetype, inop, expression, expression); + if (type == "match") return cont(expression, altbody); + if (type == "fn") return cont(fndef); + if (type == "macro") return cont(macro); + return cont(); + } + function maybeop(type) { + if (content == ".") return cont(maybeprop); + if (content == "::<"){return cont(typarams, maybeop);} + if (type == "op" || content == ":") return cont(expression); + if (type == "(" || type == "[") return matchBrackets(type, expression); + return pass(); + } + function maybeprop(type) { + if (content.match(/^\w+$/)) {cx.marked = "variable"; return cont(maybeop);} + return pass(expression); + } + function exprbrace(type) { + if (type == "op") { + if (content == "|") return cont(blockvars, poplex, pushlex("}", "block"), block); + if (content == "||") return cont(poplex, pushlex("}", "block"), block); + } + if (content == "mut" || (content.match(/^\w+$/) && cx.stream.peek() == ":" + && !cx.stream.match("::", false))) + return pass(record_of(expression)); + return pass(block); + } + function record_of(comb) { + function ro(type) { + if (content == "mut" || content == "with") {cx.marked = "keyword"; return cont(ro);} + if (content.match(/^\w*$/)) {cx.marked = "variable"; return cont(ro);} + if (type == ":") return cont(comb, ro); + if (type == "}") return cont(); + return cont(ro); + } + return ro; + } + function blockvars(type) { + if (type == "name") {cx.marked = "def"; return cont(blockvars);} + if (type == "op" && content == "|") return cont(); + return cont(blockvars); + } + + function letdef1(type) { + if (type.match(/[\]\)\};]/)) return cont(); + if (content == "=") return cont(expression, letdef2); + if (type == ",") return cont(letdef1); + return pass(pattern, maybetype, letdef1); + } + function letdef2(type) { + if (type.match(/[\]\)\};,]/)) return pass(letdef1); + else return pass(expression, letdef2); + } + function maybetype(type) { + if (type == ":") return cont(typecx, rtype, valcx); + return pass(); + } + function inop(type) { + if (type == "name" && content == "in") {cx.marked = "keyword"; return cont();} + return pass(); + } + function fndef(type) { + if (content == "@" || content == "~") {cx.marked = "keyword"; return cont(fndef);} + if (type == "name") {cx.marked = "def"; return cont(fndef);} + if (content == "<") return cont(typarams, fndef); + if (type == "{") return pass(expression); + if (type == "(") return cont(pushlex(")"), commasep(argdef, ")"), poplex, fndef); + if (type == "->") return cont(typecx, rtype, valcx, fndef); + if (type == ";") return cont(); + return cont(fndef); + } + function tydef(type) { + if (type == "name") {cx.marked = "def"; return cont(tydef);} + if (content == "<") return cont(typarams, tydef); + if (content == "=") return cont(typecx, rtype, valcx); + return cont(tydef); + } + function tagdef(type) { + if (type == "name") {cx.marked = "def"; return cont(tagdef);} + if (content == "<") return cont(typarams, tagdef); + if (content == "=") return cont(typecx, rtype, valcx, endstatement); + if (type == "{") return cont(pushlex("}"), typecx, tagblock, valcx, poplex); + return cont(tagdef); + } + function tagblock(type) { + if (type == "}") return cont(); + if (type == "(") return cont(pushlex(")"), commasep(rtype, ")"), poplex, tagblock); + if (content.match(/^\w+$/)) cx.marked = "def"; + return cont(tagblock); + } + function mod(type) { + if (type == "name") {cx.marked = "def"; return cont(mod);} + if (type == "{") return cont(pushlex("}"), block, poplex); + return pass(); + } + function trait(type) { + if (type == "name") {cx.marked = "def"; return cont(trait);} + if (content == "<") return cont(typarams, trait); + if (type == "{") return cont(pushlex("}"), block, poplex); + return pass(); + } + function impl(type) { + if (content == "<") return cont(typarams, impl); + if (content == "of" || content == "for") {cx.marked = "keyword"; return cont(rtype, impl);} + if (type == "name") {cx.marked = "def"; return cont(impl);} + if (type == "{") return cont(pushlex("}"), block, poplex); + return pass(); + } + function typarams(type) { + if (content == ">") return cont(); + if (content == ",") return cont(typarams); + if (content == ":") return cont(rtype, typarams); + return pass(rtype, typarams); + } + function argdef(type) { + if (type == "name") {cx.marked = "def"; return cont(argdef);} + if (type == ":") return cont(typecx, rtype, valcx); + return pass(); + } + function rtype(type) { + if (type == "name") {cx.marked = "variable-3"; return cont(rtypemaybeparam); } + if (content == "mut") {cx.marked = "keyword"; return cont(rtype);} + if (type == "atom") return cont(rtypemaybeparam); + if (type == "op" || type == "obj") return cont(rtype); + if (type == "fn") return cont(fntype); + if (type == "{") return cont(pushlex("{"), record_of(rtype), poplex); + return matchBrackets(type, rtype); + } + function rtypemaybeparam(type) { + if (content == "<") return cont(typarams); + return pass(); + } + function fntype(type) { + if (type == "(") return cont(pushlex("("), commasep(rtype, ")"), poplex, fntype); + if (type == "->") return cont(rtype); + return pass(); + } + function pattern(type) { + if (type == "name") {cx.marked = "def"; return cont(patternmaybeop);} + if (type == "atom") return cont(patternmaybeop); + if (type == "op") return cont(pattern); + if (type.match(/[\]\)\};,]/)) return pass(); + return matchBrackets(type, pattern); + } + function patternmaybeop(type) { + if (type == "op" && content == ".") return cont(); + if (content == "to") {cx.marked = "keyword"; return cont(pattern);} + else return pass(); + } + function altbody(type) { + if (type == "{") return cont(pushlex("}", "match"), altblock1, poplex); + return pass(); + } + function altblock1(type) { + if (type == "}") return cont(); + if (type == "|") return cont(altblock1); + if (content == "when") {cx.marked = "keyword"; return cont(expression, altblock2);} + if (type.match(/[\]\);,]/)) return cont(altblock1); + return pass(pattern, altblock2); + } + function altblock2(type) { + if (type == "{") return cont(pushlex("}", "match"), block, poplex, altblock1); + else return pass(altblock1); + } + + function macro(type) { + if (type.match(/[\[\(\{]/)) return matchBrackets(type, expression); + return pass(); + } + function matchBrackets(type, comb) { + if (type == "[") return cont(pushlex("]"), commasep(comb, "]"), poplex); + if (type == "(") return cont(pushlex(")"), commasep(comb, ")"), poplex); + if (type == "{") return cont(pushlex("}"), commasep(comb, "}"), poplex); + return cont(); + } + + function parse(state, stream, style) { + var cc = state.cc; + // Communicate our context to the combinators. + // (Less wasteful than consing up a hundred closures on every call.) + cx.state = state; cx.stream = stream; cx.marked = null, cx.cc = cc; + + while (true) { + var combinator = cc.length ? cc.pop() : block; + if (combinator(tcat)) { + while(cc.length && cc[cc.length - 1].lex) + cc.pop()(); + return cx.marked || style; + } + } + } + + return { + startState: function() { + return { + tokenize: tokenBase, + cc: [], + lexical: {indented: -indentUnit, column: 0, type: "top", align: false}, + keywords: valKeywords, + indented: 0 + }; + }, + + token: function(stream, state) { + if (stream.sol()) { + if (!state.lexical.hasOwnProperty("align")) + state.lexical.align = false; + state.indented = stream.indentation(); + } + if (stream.eatSpace()) return null; + tcat = content = null; + var style = state.tokenize(stream, state); + if (style == "comment") return style; + if (!state.lexical.hasOwnProperty("align")) + state.lexical.align = true; + if (tcat == "prefix") return style; + if (!content) content = stream.current(); + return parse(state, stream, style); + }, + + indent: function(state, textAfter) { + if (state.tokenize != tokenBase) return 0; + var firstChar = textAfter && textAfter.charAt(0), lexical = state.lexical, + type = lexical.type, closing = firstChar == type; + if (type == "stat") return lexical.indented + indentUnit; + if (lexical.align) return lexical.column + (closing ? 0 : 1); + return lexical.indented + (closing ? 0 : (lexical.info == "match" ? altIndentUnit : indentUnit)); + }, + + electricChars: "{}" + }; +}); + +CodeMirror.defineMIME("text/x-rustsrc", "rust"); diff --git a/src/doc/po/ja/complement-cheatsheet.md.po b/src/doc/po/ja/complement-cheatsheet.md.po new file mode 100644 index 00000000000..0089e4a81a3 --- /dev/null +++ b/src/doc/po/ja/complement-cheatsheet.md.po @@ -0,0 +1,152 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/complement-cheatsheet.md:13 +#, fuzzy +#| msgid "" +#| "~~~~ let x: f64 = 4.0; let y: uint = x as uint; assert!(y == 4u); ~~~~" +msgid "~~~ let x: int = 42; let y: ~str = x.to_str(); ~~~" +msgstr "" +"~~~~\n" +"let x: f64 = 4.0;\n" +"let y: uint = x as uint;\n" +"assert!(y == 4u);\n" +"~~~~" + +#. type: Plain text +#: doc/complement-cheatsheet.md:17 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"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)." +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/complement-cheatsheet.md:22 +#, fuzzy +#| msgid "" +#| "~~~~ let x: f64 = 4.0; let y: uint = x as uint; assert!(y == 4u); ~~~~" +msgid "~~~ let x: Option<int> = from_str(\"42\"); let y: int = x.unwrap(); ~~~" +msgstr "" +"~~~~\n" +"let x: f64 = 4.0;\n" +"let y: uint = x as uint;\n" +"assert!(y == 4u);\n" +"~~~~" + +#. type: Plain text +#: doc/complement-cheatsheet.md:29 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ use std::num::ToStrRadix;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/complement-cheatsheet.md:33 +#, fuzzy +#| msgid "" +#| "~~~~ let x: f64 = 4.0; let y: uint = x as uint; assert!(y == 4u); ~~~~" +msgid "let x: int = 42; let y: ~str = x.to_str_radix(16); ~~~" +msgstr "" +"~~~~\n" +"let x: f64 = 4.0;\n" +"let y: uint = x as uint;\n" +"assert!(y == 4u);\n" +"~~~~" + +#. type: Plain text +#: doc/complement-cheatsheet.md:37 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"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)." +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/complement-cheatsheet.md:40 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ use std::num::from_str_radix;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/complement-cheatsheet.md:46 +#, fuzzy +#| msgid "## Operators" +msgid "# File operations" +msgstr "## 演算子" + +#. type: Plain text +#: doc/complement-cheatsheet.md:54 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ {.ignore} use std::path::Path; use std::io::fs::File;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/complement-cheatsheet.md:63 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"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)." +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/complement-cheatsheet.md:77 +#, fuzzy +#| msgid "## Using other crates" +msgid "# String operations" +msgstr "## 他のクレートの利用" + +#. type: Plain text +#: doc/complement-cheatsheet.md:88 doc/guide-container.md:4 +#, fuzzy +msgid "# Containers" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/complement-cheatsheet.md:176 +#, fuzzy +#| msgid "[The foreign function interface][ffi]" +msgid "# FFI (Foreign Function Interface)" +msgstr "[他言語間インターフェース (foreign function inferface)][ffi]" diff --git a/src/doc/po/ja/complement-lang-faq.md.po b/src/doc/po/ja/complement-lang-faq.md.po new file mode 100644 index 00000000000..a4d16a82c44 --- /dev/null +++ b/src/doc/po/ja/complement-lang-faq.md.po @@ -0,0 +1,47 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/complement-lang-faq.md:83 +#, fuzzy +#| msgid "" +#| "[bug-3319]: https://github.com/mozilla/rust/issues/3319 [wiki-start]: " +#| "https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust" +msgid "" +"[rustc]: https://github.com/mozilla/rust/tree/master/src/librustc [resolve]: " +"https://github.com/mozilla/rust/blob/master/src/librustc/middle/resolve.rs " +"[borrowck]: https://github.com/mozilla/rust/blob/master/src/librustc/middle/" +"borrowck/" +msgstr "" +"[bug-3319]: https://github.com/mozilla/rust/issues/3319\n" +"[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-" +"developing-Rust" + +#. type: Plain text +#: doc/complement-lang-faq.md:110 +#, fuzzy +#| msgid "" +#| "[bug-3319]: https://github.com/mozilla/rust/issues/3319 [wiki-start]: " +#| "https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust" +msgid "" +"[unwind]: https://github.com/mozilla/rust/issues/908 [libgcc]: https://" +"github.com/mozilla/rust/issues/1603" +msgstr "" +"[bug-3319]: https://github.com/mozilla/rust/issues/3319\n" +"[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-" +"developing-Rust" diff --git a/src/doc/po/ja/complement-project-faq.md.po b/src/doc/po/ja/complement-project-faq.md.po new file mode 100644 index 00000000000..100e1d5653c --- /dev/null +++ b/src/doc/po/ja/complement-project-faq.md.po @@ -0,0 +1,24 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Bullet: '* ' +#: doc/complement-project-faq.md:36 +#, fuzzy +#| msgid "## The standard library" +msgid "An evolving standard library." +msgstr "## 標準ライブラリ" diff --git a/src/doc/po/ja/guide-conditions.md.po b/src/doc/po/ja/guide-conditions.md.po new file mode 100644 index 00000000000..505d55a512c --- /dev/null +++ b/src/doc/po/ja/guide-conditions.md.po @@ -0,0 +1,73 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% The Rust Condition and Error-handling Guide" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Bullet: ' - ' +#: doc/guide-conditions.md:14 +#, fuzzy +#| msgid "# Functions" +msgid "Options" +msgstr "# 関数" + +#. type: Bullet: ' - ' +#: doc/guide-conditions.md:14 +#, fuzzy +#| msgid "## Conditionals" +msgid "Conditions" +msgstr "## 条件式" + +#. type: Plain text +#: doc/guide-conditions.md:19 +#, fuzzy +#| msgid "## Tuples" +msgid "# Example program" +msgstr "## タプル" + +#. type: Plain text +#: doc/guide-conditions.md:112 +#, fuzzy +#| msgid "# Functions" +msgid "# Options" +msgstr "# 関数" + +#. type: Plain text +#: doc/guide-conditions.md:318 +#, fuzzy +#| msgid "## Conditionals" +msgid "# Conditions" +msgstr "## 条件式" + +#. type: Plain text +#: doc/guide-conditions.md:415 +#, fuzzy +#| msgid "## Traits" +msgid "# Trapping a condition" +msgstr "## トレイト" diff --git a/src/doc/po/ja/guide-container.md.po b/src/doc/po/ja/guide-container.md.po new file mode 100644 index 00000000000..6113f1f554e --- /dev/null +++ b/src/doc/po/ja/guide-container.md.po @@ -0,0 +1,114 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/complement-cheatsheet.md:88 doc/guide-container.md:4 +#, fuzzy +msgid "# Containers" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/guide-container.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% The Rust Containers and Iterators Guide" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/guide-container.md:8 +#, fuzzy +#| msgid "# Control structures" +msgid "## Unique vectors" +msgstr "# 制御構造" + +#. type: Plain text +#: doc/guide-container.md:18 +#, fuzzy +#| msgid "## Managed closures" +msgid "## Maps and sets" +msgstr "## マネージドクロージャ" + +#. type: Plain text +#: doc/guide-container.md:24 +#, fuzzy +#| msgid "## The standard library" +msgid "The standard library provides three owned map/set types:" +msgstr "## 標準ライブラリ" + +#. type: Plain text +#: doc/guide-container.md:68 +#, fuzzy +#| msgid "## Operators" +msgid "# Iterators" +msgstr "## 演算子" + +#. type: Plain text +#: doc/guide-container.md:70 +#, fuzzy +#| msgid "# Introduction" +msgid "## Iteration protocol" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-container.md:119 +#, fuzzy +#| msgid "# Control structures" +msgid "## Container iterators" +msgstr "# 制御構造" + +#. type: Plain text +#: doc/guide-container.md:131 +#, fuzzy +#| msgid "## Freezing" +msgid "### Freezing" +msgstr "## 凍結" + +#. type: Plain text +#: doc/guide-container.md:151 +#, fuzzy +#| msgid "## Operators" +msgid "## Iterator adaptors" +msgstr "## 演算子" + +#. type: Plain text +#: doc/guide-container.md:201 +#, fuzzy +#| msgid "## Loops" +msgid "## For loops" +msgstr "## ループ" + +#. type: Plain text +#: doc/guide-container.md:257 +#, fuzzy +#| msgid "## Conventions" +msgid "## Conversion" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/guide-container.md:334 +#, fuzzy +#| msgid "# Control structures" +msgid "## Double-ended iterators" +msgstr "# 制御構造" + +#. type: Plain text +#: doc/guide-container.md:385 +#, fuzzy +#| msgid "# Control structures" +msgid "## Random-access iterators" +msgstr "# 制御構造" diff --git a/src/doc/po/ja/guide-ffi.md.po b/src/doc/po/ja/guide-ffi.md.po new file mode 100644 index 00000000000..af1b566a0f4 --- /dev/null +++ b/src/doc/po/ja/guide-ffi.md.po @@ -0,0 +1,82 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-ffi.md:2 +#, fuzzy +#| msgid "[The foreign function interface][ffi]" +msgid "% The Rust Foreign Function Interface Guide" +msgstr "[他言語間インターフェース (foreign function inferface)][ffi]" + +#. type: Plain text +#: doc/guide-ffi.md:16 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~~ {.ignore} use std::libc::size_t;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-ffi.md:48 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~~ {.ignore} use std::libc::{c_int, size_t};" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-ffi.md:168 doc/tutorial.md:875 +msgid "# Destructors" +msgstr "# デストラクタ" + +#. type: Plain text +#: doc/guide-ffi.md:333 +#, fuzzy +#| msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~" +msgid "~~~~ unsafe fn kaboom(ptr: *int) -> int { *ptr } ~~~~" +msgstr "" +"~~~~\n" +"let square = |x: int| -> uint { (x * x) as uint };\n" +"~~~~~~~~\n" + +#. type: Plain text +#: doc/guide-ffi.md:344 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~{.ignore} use std::libc;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-ffi.md:363 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~{.ignore} use std::libc; use std::ptr;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" diff --git a/src/doc/po/ja/guide-lifetimes.md.po b/src/doc/po/ja/guide-lifetimes.md.po new file mode 100644 index 00000000000..ef7c51f52cf --- /dev/null +++ b/src/doc/po/ja/guide-lifetimes.md.po @@ -0,0 +1,315 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-lifetimes.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% The Rust References and Lifetimes Guide" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/guide-lifetimes.md:26 +#, fuzzy +#| msgid "## A minimal example" +msgid "# By example" +msgstr "## 最小限の例" + +#. type: Plain text +#: doc/guide-lifetimes.md:33 +#, fuzzy +#| msgid "As an example, consider a simple struct type, `Point`:" +msgid "As an example, consider a simple struct type `Point`:" +msgstr "例として、シンプルな構造体型の `Point` について考えます。" + +#. type: Plain text +#: doc/guide-lifetimes.md:41 +#, fuzzy +#| msgid "" +#| "We can use this simple definition to allocate points in many different " +#| "ways. For example, in this code, each of these three local variables " +#| "contains a point, but allocated in a different location:" +msgid "" +"We can use this simple definition to allocate points in many different ways. " +"For example, in this code, each of these three local variables contains a " +"point, but allocated in a different place:" +msgstr "" +"シンプルな定義ですが、この定義を使って `Point` 型のオブジェクトを様々な方法で" +"割り当てることができます。例えば、このコードの3つのローカル変数は、それぞれ異" +"なった場所に `Point` 型のオブジェクトを割り当てています。" + +#. type: Plain text +#: doc/guide-lifetimes.md:48 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"~~~\n" +"# struct Point {x: f64, y: f64}\n" +"let on_the_stack : Point = Point {x: 3.0, y: 4.0};\n" +"let managed_box : @Point = @Point {x: 5.0, y: 1.0};\n" +"let owned_box : ~Point = ~Point {x: 7.0, y: 9.0};\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-lifetimes.md:60 +#, fuzzy +#| msgid "" +#| "Suppose we want to write a procedure that computes the distance between " +#| "any two points, no matter where they are stored. For example, we might " +#| "like to compute the distance between `on_the_stack` and `managed_box`, or " +#| "between `managed_box` and `owned_box`. One option is to define a function " +#| "that takes two arguments of type point—that is, it takes the points by " +#| "value. But this will cause the points to be copied when we call the " +#| "function. For points, this is probably not so bad, but often copies are " +#| "expensive. So we’d like to define a function that takes the points by " +#| "pointer. We can use borrowed pointers to do this:" +msgid "" +"Suppose we wanted to write a procedure that computed the distance between " +"any two points, no matter where they were stored. For example, we might like " +"to compute the distance between `on_the_stack` and `managed_box`, or between " +"`managed_box` and `owned_box`. One option is to define a function that takes " +"two arguments of type `Point`—that is, it takes the points by value. But if " +"we define it this way, calling the function will cause the points to be " +"copied. For points, this is probably not so bad, but often copies are " +"expensive. Worse, if the data type contains mutable fields, copying can " +"change the semantics of your program in unexpected ways. So we'd like to " +"define a function that takes the points by pointer. We can use references to " +"do this:" +msgstr "" +"`Point` 型のオブジェクトの割り当て先がどこであったとしても利用可能な、任意の " +"2 点間の距離を計算する処理を書きたいとします。例えば、 `on_the_stack`, " +"`managed_box` 間や `managed_box`, `owned_box` 間の距離を計算する処理です。 1" +"つ目の実装方法として、2つの `Point` 型オブジェクトを引数にとる関数を定義する" +"方法、すなわち、オブジェクトを値で受け渡す方法があります。しかし、この方法で" +"は関数呼び出し時に `Point` オブジェクトのコピーが行われます。`Point` オブジェ" +"クトの場合、このような実装はそれほど悪いものではないでしょうが、コピー処理の" +"コストは高い場合もあります。したがって、`Point` オブジェクトをポインタ渡しす" +"る関数を定義する必要があります。そのために、借用ポインタを利用することが可能" +"です。" + +#. type: Plain text +#: doc/guide-lifetimes.md:72 doc/tutorial.md:1394 +msgid "Now we can call `compute_distance()` in various ways:" +msgstr "" +"上記の `compute_distance()` 関数は、様々な方法で呼び出すことができます。" + +#. type: Plain text +#: doc/guide-lifetimes.md:82 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"~~~\n" +"# struct Point {x: f64, y: f64}\n" +"# let on_the_stack : Point = Point{x: 3.0, y: 4.0};\n" +"# let managed_box : @Point = @Point{x: 5.0, y: 1.0};\n" +"# let owned_box : ~Point = ~Point{x: 7.0, y: 9.0};\n" +"# fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }\n" +"compute_distance(&on_the_stack, managed_box);\n" +"compute_distance(managed_box, owned_box);\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-lifetimes.md:89 +#, fuzzy +#| msgid "" +#| "Here the `&` operator is used to take the address of the variable " +#| "`on_the_stack`; this is because `on_the_stack` has the type `Point` (that " +#| "is, a struct value) and we have to take its address to get a value. We " +#| "also call this _borrowing_ the local variable `on_the_stack`, because we " +#| "are creating an alias: that is, another route to the same data." +msgid "" +"Here, the `&` operator takes the address of the variable `on_the_stack`; " +"this is because `on_the_stack` has the type `Point` (that is, a struct " +"value) and we have to take its address to get a value. We also call this " +"_borrowing_ the local variable `on_the_stack`, because we have created an " +"alias: that is, another name for the same data." +msgstr "" +"ここで `&` 演算子は `on_the_stack` 変数のアドレスを取得するために使われていま" +"す。これは、 `on_the_stack` の型は `Point` (つまり、構造体の値) であり、呼び" +"出した関数から値を取得させるため、構造体のアドレスを渡す必要があるからです。" +"値の別名 (エイリアス)、すなわち、同じデータへアクセスするための別の方法を提供" +"するので、このような操作のことをローカル変数 `on_the_stack` の __借用__ " +"(_borrowing_) と呼びます。" + +#. type: Plain text +#: doc/guide-lifetimes.md:95 +#, fuzzy +#| msgid "" +#| "In the case of the boxes `managed_box` and `owned_box`, however, no " +#| "explicit action is necessary. The compiler will automatically convert a " +#| "box like `@point` or `~point` to a borrowed pointer like `&point`. This " +#| "is another form of borrowing; in this case, the contents of the managed/" +#| "owned box are being lent out." +msgid "" +"In contrast, we can pass the boxes `managed_box` and `owned_box` to " +"`compute_distance` directly. The compiler automatically converts a box like " +"`@Point` or `~Point` to a reference like `&Point`. This is another form of " +"borrowing: in this case, the caller lends the contents of the managed or " +"owned box to the callee." +msgstr "" +"ボックスである `managed_box` と `owned_box` の場合は、特に明示的な操作を行う" +"必要はありません。コンパイラは `@point` や `~point` のようなボックスを自動的" +"に `&point` のような借用ポインタへと変換します。これは、別の形態の借用 " +"(borrowing) です。この場合、マネージド/所有ボックスの内容が貸し出されていま" +"す。" + +#. type: Plain text +#: doc/guide-lifetimes.md:105 +#, fuzzy +#| msgid "" +#| "Whenever a value is borrowed, there are some limitations on what you can " +#| "do with the original. For example, if the contents of a variable have " +#| "been lent out, you cannot send that variable to another task, nor will " +#| "you be permitted to take actions that might cause the borrowed value to " +#| "be freed or to change its type. This rule should make intuitive sense: " +#| "you must wait for a borrowed value to be returned (that is, for the " +#| "borrowed pointer to go out of scope) before you can make full use of it " +#| "again." +msgid "" +"Whenever a caller lends data to a callee, there are some limitations on what " +"the caller can do with the original. For example, if the contents of a " +"variable have been lent out, you cannot send that variable to another task. " +"In addition, the compiler will reject any code that might cause the borrowed " +"value to be freed or overwrite its component fields with values of different " +"types (I'll get into what kinds of actions those are shortly). This rule " +"should make intuitive sense: you must wait for a borrower to return the " +"value that you lent it (that is, wait for the reference to go out of scope) " +"before you can make full use of it again." +msgstr "" +"値が借用されている間、借用元の値に対して行える操作がいくらか制限されます。例" +"えば、変数の内容が貸し出された場合、その変数を他のタスクに送信することはでき" +"ませんし、借用された値を解放したり、型が変化させるような操作も行うことができ" +"ません。このルールは理にかなったものでしょう。貸し出した値を最大限に活用する " +"(make full use of it) ためには、貸し出した値の返却 (借用ポインタが存在するス" +"コープを抜ける) を待たなければなりません。" + +#. type: Plain text +#: doc/guide-lifetimes.md:114 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: " +#| "20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~ # struct Point {x: f64, y: f64} let on_the_stack: Point = Point {x: 3.0, " +"y: 4.0}; ~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/guide-lifetimes.md:124 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: " +#| "20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~ # struct Point {x: f64, y: f64} let on_the_stack2: &Point = &Point {x: " +"3.0, y: 4.0}; ~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/guide-lifetimes.md:134 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: " +#| "20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~ # struct Point {x: f64, y: f64} let tmp = Point {x: 3.0, y: 4.0}; let " +"on_the_stack2 : &Point = &tmp; ~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/guide-lifetimes.md:180 +#, fuzzy +#| msgid "# Borrowed pointers" +msgid "# Borrowing managed boxes and rooting" +msgstr "# 借用ポインタ" + +#. type: Plain text +#: doc/guide-lifetimes.md:262 +#, fuzzy +#| msgid "# Borrowed pointers" +msgid "# Borrowing owned boxes" +msgstr "# 借用ポインタ" + +#. type: Plain text +#: doc/guide-lifetimes.md:367 +#, fuzzy +#| msgid "# Borrowed pointers" +msgid "# Borrowing and enums" +msgstr "# 借用ポインタ" + +#. type: Plain text +#: doc/guide-lifetimes.md:477 +#, fuzzy +#| msgid "# Dereferencing pointers" +msgid "# Returning references" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/guide-lifetimes.md:490 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: " +#| "20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~ struct Point {x: f64, y: f64} fn get_x<'r>(p: &'r Point) -> &'r f64 { &p." +"x } ~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/guide-lifetimes.md:659 +#, fuzzy +#| msgid "## Conventions" +msgid "# Conclusion" +msgstr "## 本書の表記について" diff --git a/src/doc/po/ja/guide-macros.md.po b/src/doc/po/ja/guide-macros.md.po new file mode 100644 index 00000000000..41ba4b04926 --- /dev/null +++ b/src/doc/po/ja/guide-macros.md.po @@ -0,0 +1,94 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-macros.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% The Rust Macros Guide" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/guide-macros.md:67 +#, fuzzy +#| msgid "## Do syntax" +msgid "# Invocation syntax" +msgstr "## do 構文" + +#. type: Plain text +#: doc/guide-macros.md:100 +#, fuzzy +#| msgid "# Introduction" +msgid "## Invocation location" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-macros.md:115 +#, fuzzy +#| msgid "## Traits" +msgid "# Transcription syntax" +msgstr "## トレイト" + +#. type: Plain text +#: doc/guide-macros.md:135 +#, fuzzy +#| msgid "# Introduction" +msgid "## Interpolation location" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-macros.md:143 +#, fuzzy +#| msgid "# Introduction" +msgid "## Invocation" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-macros.md:181 +#, fuzzy +#| msgid "## Traits" +msgid "### Transcription" +msgstr "## トレイト" + +#. type: Plain text +#: doc/guide-macros.md:193 +#, fuzzy +#| msgid "## Pattern matching" +msgid "## Parsing limitations" +msgstr "## パターンマッチ" + +#. type: Plain text +#: doc/guide-macros.md:212 +#, fuzzy +#| msgid "## Pattern matching" +msgid "# Macro argument pattern matching" +msgstr "## パターンマッチ" + +#. type: Plain text +#: doc/guide-macros.md:214 +#, fuzzy +#| msgid "## Conventions" +msgid "## Motivation" +msgstr "## 本書の表記について" diff --git a/src/doc/po/ja/guide-pointers.md.po b/src/doc/po/ja/guide-pointers.md.po new file mode 100644 index 00000000000..e270babac85 --- /dev/null +++ b/src/doc/po/ja/guide-pointers.md.po @@ -0,0 +1,292 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-pointers.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% The Rust Pointer Guide" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/guide-pointers.md:21 +#, fuzzy +#| msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~" +msgid "~~~rust fn succ(x: &int) -> int { *x + 1 } ~~~" +msgstr "" +"~~~~\n" +"let square = |x: int| -> uint { (x * x) as uint };\n" +"~~~~~~~~\n" + +#. type: Plain text +#: doc/guide-pointers.md:58 +#, fuzzy +#| msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~" +msgid "~~~rust fn succ(x: int) -> int { x + 1 }" +msgstr "" +"~~~~\n" +"let square = |x: int| -> uint { (x * x) as uint };\n" +"~~~~~~~~\n" + +#. type: Plain text +#: doc/guide-pointers.md:115 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn main() {\n" +" let p0 = Point { x: 5, y: 10};\n" +" let p1 = transform(p0);\n" +" println!(\"{:?}\", p1);\n" +"}\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:129 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"~~~rust\n" +"# struct Point {\n" +"# x: int,\n" +"# y: int,\n" +"# }\n" +"# let p0 = Point { x: 5, y: 10};\n" +"fn transform(p: &Point) -> Point {\n" +" Point { x: p.x + 1, y: p.y + 1}\n" +"}\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:145 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn transform(p: Point) -> Point {\n" +" Point { x: p.x + 1, y: p.y + 1}\n" +"}\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:152 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn main() {\n" +" let p0 = Point { x: 5, y: 10};\n" +" let p1 = transform(p0);\n" +" println!(\"{:?}\", p1);\n" +"}\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:162 +#, fuzzy +#| msgid "# Borrowed pointers" +msgid "# Owned Pointers" +msgstr "# 借用ポインタ" + +#. type: Plain text +#: doc/guide-pointers.md:175 +#, fuzzy +msgid "## References to Traits" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/guide-pointers.md:181 +#, fuzzy +#| msgid "# Data structures" +msgid "## Recursive Data Structures" +msgstr "# データ構造" + +#. type: Plain text +#: doc/guide-pointers.md:229 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn main() {\n" +" let a = Point { x: 10, y: 20 };\n" +" do spawn {\n" +" println!(\"{}\", a.x);\n" +" }\n" +"}\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:246 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn main() {\n" +" let a = ~Point { x: 10, y: 20 };\n" +" do spawn {\n" +" println!(\"{}\", a.x);\n" +" }\n" +"}\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:251 +#, fuzzy +#| msgid "## Managed boxes" +msgid "# Managed Pointers" +msgstr "## マネージドボックス" + +#. type: Plain text +#: doc/guide-pointers.md:277 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn main() {\n" +" let a = ~Point { x: 10, y: 20 };\n" +" let b = a;\n" +" println!(\"{}\", b.x);\n" +" println!(\"{}\", a.x);\n" +"}\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:308 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn main() {\n" +" let a = @Point { x: 10, y: 20 };\n" +" let b = a;\n" +" println!(\"{}\", b.x);\n" +" println!(\"{}\", a.x);\n" +"}\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:326 doc/tutorial.md:1345 +#, fuzzy +msgid "# References" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/guide-pointers.md:336 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~rust use std::num::sqrt;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-pointers.md:352 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"fn main() {\n" +" let origin = @Point { x: 0.0, y: 0.0 };\n" +" let p1 = ~Point { x: 5.0, y: 3.0 };\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/guide-pointers.md:378 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"~~~rust{.ignore}\n" +"fn main() {\n" +" println!(\"{}\", x);\n" +" let x = 5;\n" +"}\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/guide-pointers.md:433 +#, fuzzy +#| msgid "# Dereferencing pointers" +msgid "# Returning Pointers" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/guide-pointers.md:444 +#, fuzzy, no-wrap +#| msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~" +msgid "" +"~~~rust\n" +"fn foo(x: ~int) -> ~int {\n" +" return ~*x;\n" +"}\n" +msgstr "" +"~~~~\n" +"let square = |x: int| -> uint { (x * x) as uint };\n" +"~~~~~~~~\n" + +#. type: Plain text +#: doc/guide-pointers.md:457 doc/guide-pointers.md:471 +#, fuzzy, no-wrap +#| msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~" +msgid "" +"~~~rust\n" +"fn foo(x: ~int) -> int {\n" +" return *x;\n" +"}\n" +msgstr "" +"~~~~\n" +"let square = |x: int| -> uint { (x * x) as uint };\n" +"~~~~~~~~\n" diff --git a/src/doc/po/ja/guide-tasks.md.po b/src/doc/po/ja/guide-tasks.md.po new file mode 100644 index 00000000000..a86a204397b --- /dev/null +++ b/src/doc/po/ja/guide-tasks.md.po @@ -0,0 +1,81 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-tasks.md:2 +#, fuzzy +#| msgid "[Tasks and communication][tasks]" +msgid "% The Rust Tasks and Communication Guide" +msgstr "[タスクと通信][tasks]" + +#. type: Plain text +#: doc/guide-tasks.md:64 +#, fuzzy +#| msgid "# Syntax basics" +msgid "# Basics" +msgstr "# 基本的な構文" + +#. type: Plain text +#: doc/guide-tasks.md:73 doc/guide-tasks.md:132 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~~ # use std::task::spawn;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-tasks.md:113 +#, fuzzy +#| msgid "## Conditionals" +msgid "## Communication" +msgstr "## 条件式" + +#. type: Plain text +#: doc/guide-tasks.md:214 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ # use std::task::spawn;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-tasks.md:246 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ # use std::task::spawn; # use std::vec;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-tasks.md:327 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ # use std::vec; # use std::rand; use extra::arc::Arc;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" diff --git a/src/doc/po/ja/guide-testing.md.po b/src/doc/po/ja/guide-testing.md.po new file mode 100644 index 00000000000..b42d0feee2f --- /dev/null +++ b/src/doc/po/ja/guide-testing.md.po @@ -0,0 +1,75 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-testing.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% The Rust Testing Guide" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/guide-testing.md:4 +#, fuzzy +#| msgid "# Getting started" +msgid "# Quick start" +msgstr "# はじめに" + +#. type: Plain text +#: doc/guide-testing.md:127 doc/tutorial.md:776 +#, fuzzy +#| msgid "## A minimal example" +msgid "For example:" +msgstr "## 最小限の例" + +#. type: Plain text +#: doc/guide-testing.md:131 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ extern mod extra; use std::vec;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/guide-testing.md:167 +#, fuzzy +#| msgid "## Tuples" +msgid "## Examples" +msgstr "## タプル" + +#. type: Plain text +#: doc/guide-testing.md:169 +#, fuzzy +#| msgid "## Tuple structs" +msgid "### Typical test run" +msgstr "## タプル構造体" + +#. type: Plain text +#: doc/guide-testing.md:197 +#, fuzzy +#| msgid "# Dereferencing pointers" +msgid "### Running ignored tests" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/guide-testing.md:235 +#, fuzzy +#| msgid "## Declaring and implementing traits" +msgid "## Saving and ratcheting metrics" +msgstr "## トレイトの宣言と実装" diff --git a/src/doc/po/ja/index.md.po b/src/doc/po/ja/index.md.po new file mode 100644 index 00000000000..2941d50012d --- /dev/null +++ b/src/doc/po/ja/index.md.po @@ -0,0 +1,31 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-14 21:02+0900\n" +"PO-Revision-Date: 2014-01-14 21:02+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/index.md:2 +#, fuzzy +#| msgid "## Using the rust tool" +msgid "% Rust documentation" +msgstr "## `rust` コマンドを利用する" + +#. type: Plain text +#: doc/index.md:26 +#, fuzzy +#| msgid "## Using other crates" +msgid "# Libraries" +msgstr "## 他のクレートの利用" diff --git a/src/doc/po/ja/rust.md.po b/src/doc/po/ja/rust.md.po new file mode 100644 index 00000000000..c43d7ed5c8b --- /dev/null +++ b/src/doc/po/ja/rust.md.po @@ -0,0 +1,1028 @@ +# Japanese translations for Rust package +# Copyright (C) 2013 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2013. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.8\n" +"POT-Creation-Date: 2014-01-14 21:02+0900\n" +"PO-Revision-Date: 2013-08-05 19:40+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/rust.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% The Rust Reference Manual" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/rust.md:54 +#, fuzzy +#| msgid "## Conventions" +msgid "# Notation" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:91 +#, fuzzy +#| msgid "# Introduction" +msgid "## Unicode productions" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/rust.md:98 +#, fuzzy +#| msgid "## Using other crates" +msgid "## String table productions" +msgstr "## 他のクレートの利用" + +#. type: Plain text +#: doc/rust.md:113 +#, fuzzy +#| msgid "# Data structures" +msgid "# Lexical structure" +msgstr "# データ構造" + +#. type: Plain text +#: doc/rust.md:152 +#, fuzzy +#| msgid "## Conventions" +msgid "## Comments" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:190 +#, fuzzy +#| msgid "## Tuples" +msgid "## Tokens" +msgstr "## タプル" + +#. type: Plain text +#: doc/rust.md:226 +#, fuzzy +#| msgid "## Operators" +msgid "### Literals" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:238 +#, fuzzy +#| msgid "# Vectors and strings" +msgid "#### Character and string literals" +msgstr "# ベクタと文字列" + +#. type: Plain text +#: doc/rust.md:345 +#, fuzzy +#| msgid "# Control structures" +msgid "##### Integer literals" +msgstr "# 制御構造" + +#. type: Plain text +#: doc/rust.md:459 +#, fuzzy +#| msgid "~~~~ {.ignore} let foo = 10;" +msgid "~~~~ {.ignore} x; x::y::z; ~~~~" +msgstr "" +"~~~~ {.ignore}\n" +"let foo = 10;" + +#. type: Plain text +#: doc/rust.md:479 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "# Syntax extensions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:524 +#, fuzzy +#| msgid "## A minimal example" +msgid "### Macro By Example" +msgstr "## 最小限の例" + +#. type: Plain text +#: doc/rust.md:560 +#, fuzzy +#| msgid "## Pattern matching" +msgid "### Parsing limitations" +msgstr "## パターンマッチ" + +#. type: Plain text +#: doc/rust.md:579 +#, fuzzy +#| msgid "# Modules and crates" +msgid "# Crates and source files" +msgstr "# モジュールとクレート" + +#. type: Plain text +#: doc/rust.md:626 +#, fuzzy +#| msgid "// Turn on a warning #[warn(non_camel_case_types)]" +msgid "// Turn on a warning #[ warn(non_camel_case_types) ]; ~~~~" +msgstr "" +"// 警告を有効にする\n" +"#[warn(non_camel_case_types)]" + +#. type: Plain text +#: doc/rust.md:631 +#, fuzzy +#| msgid "# Vectors and strings" +msgid "# Items and attributes" +msgstr "# ベクタと文字列" + +#. type: Plain text +#: doc/rust.md:636 +#, fuzzy +#| msgid "## Operators" +msgid "## Items" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:765 +#, fuzzy +#| msgid "## Using other crates" +msgid "##### Extern mod declarations" +msgstr "## 他のクレートの利用" + +#. type: Plain text +#: doc/rust.md:788 +#, fuzzy +#| msgid "~~~~ {.ignore} let foo = 10;" +msgid "~~~~ {.ignore} extern mod pcre;" +msgstr "" +"~~~~ {.ignore}\n" +"let foo = 10;" + +#. type: Plain text +#: doc/rust.md:797 +#, fuzzy +#| msgid "## Conventions" +msgid "##### Use declarations" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:827 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~~ use std::num::sin; use std::option::{Some, None};" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/rust.md:900 +#, fuzzy +#| msgid "# Functions" +msgid "### Functions" +msgstr "# 関数" + +#. type: Plain text +#: doc/rust.md:930 +#, fuzzy +#| msgid "~~~ fn first((value, _): (int, f64)) -> int { value } ~~~" +msgid "~~~~ fn first((value, _): (int, int)) -> int { value } ~~~~" +msgstr "" +"~~~\n" +"fn first((value, _): (int, f64)) -> int { value }\n" +"~~~" + +#. type: Plain text +#: doc/rust.md:933 +#, fuzzy +#| msgid "## Conventions" +msgid "#### Generic functions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:971 +#, fuzzy +#| msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~" +msgid "~~~~ fn id<T>(x: T) -> T { x } ~~~~" +msgstr "" +"~~~~\n" +"let square = |x: int| -> uint { (x * x) as uint };\n" +"~~~~~~~~\n" + +#. type: Plain text +#: doc/rust.md:978 +#, fuzzy +#| msgid "## Conventions" +msgid "#### Unsafety" +msgstr "## 本書の表記について" + +#. type: Bullet: ' - ' +#: doc/rust.md:985 +#, fuzzy +#| msgid "# Dereferencing pointers" +msgid "Dereferencing a [raw pointer](#pointer-types)." +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/rust.md:987 +#, fuzzy +#| msgid "## Conventions" +msgid "##### Unsafe functions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:992 +#, fuzzy +#| msgid "## Conventions" +msgid "##### Unsafe blocks" +msgstr "## 本書の表記について" + +#. type: Bullet: '* ' +#: doc/rust.md:1034 +#, fuzzy +#| msgid "# Data structures" +msgid "Data races" +msgstr "# データ構造" + +#. type: Bullet: '* ' +#: doc/rust.md:1034 +#, fuzzy +#| msgid "# Dereferencing pointers" +msgid "Dereferencing a null/dangling raw pointer" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/rust.md:1049 +#, fuzzy +#| msgid "## Conventions" +msgid "#### Diverging functions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:1096 +#, fuzzy +#| msgid "## Conventions" +msgid "#### Extern functions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:1125 +#, fuzzy +#| msgid "## Conventions" +msgid "### Type definitions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:1140 +#, fuzzy +#| msgid "## Structs" +msgid "### Structures" +msgstr "## 構造体" + +#. type: Plain text +#: doc/rust.md:1150 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: " +#| "20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~~ struct Point {x: int, y: int} let p = Point {x: 10, y: 11}; let px: int " +"= p.x; ~~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/rust.md:1170 +#, fuzzy +#| msgid "## Enums" +msgid "### Enumerations" +msgstr "## 列挙型" + +#. type: Plain text +#: doc/rust.md:1204 +#, fuzzy +#| msgid "## Structs" +msgid "### Static items" +msgstr "## 構造体" + +#. type: Plain text +#: doc/rust.md:1240 +#, fuzzy +#| msgid "# Move semantics" +msgid "#### Mutable statics" +msgstr "# ムーブセマンティクス" + +#. type: Plain text +#: doc/rust.md:1274 +#, fuzzy +#| msgid "## Traits" +msgid "### Traits" +msgstr "## トレイト" + +#. type: Plain text +#: doc/rust.md:1363 +#, fuzzy +#| msgid "Enum variants may also be structs. For example:" +msgid "Traits may inherit from other traits. For example, in" +msgstr "以下の例のように、列挙型バリアントを構造体にすることも可能です。" + +#. type: Plain text +#: doc/rust.md:1368 +#, fuzzy +#| msgid "" +#| "~~~~ trait Shape { fn area(&self) -> f64; } trait Circle : Shape { fn " +#| "radius(&self) -> f64; } ~~~~" +msgid "" +"~~~~ trait Shape { fn area() -> f64; } trait Circle : Shape { fn radius() -> " +"f64; } ~~~~" +msgstr "" +"~~~~\n" +"trait Shape { fn area(&self) -> f64; }\n" +"trait Circle : Shape { fn radius(&self) -> f64; }\n" +"~~~~" + +#. type: Plain text +#: doc/rust.md:1377 +#, fuzzy +#| msgid "" +#| "In type-parameterized functions, methods of the supertrait may be called " +#| "on values of subtrait-bound type parameters. Refering to the previous " +#| "example of `trait Circle : Shape`:" +msgid "" +"In type-parameterized functions, methods of the supertrait may be called on " +"values of subtrait-bound type parameters. Referring to the previous example " +"of `trait Circle : Shape`:" +msgstr "" +"型パラメータを持つ関数では、サブトレイトの境界型パラメータの値によりスーパー" +"トレイトのメソッドを呼び出すことになります。前の例の `trait Circle : Shape` " +"を参照してください。" + +#. type: Plain text +#: doc/rust.md:1386 +#, fuzzy, no-wrap +#| msgid "" +#| "~~~\n" +#| "# trait Shape { fn area(&self) -> f64; }\n" +#| "# trait Circle : Shape { fn radius(&self) -> f64; }\n" +#| "fn radius_times_area<T: Circle>(c: T) -> f64 {\n" +#| " // `c` is both a Circle and a Shape\n" +#| " c.radius() * c.area()\n" +#| "}\n" +#| "~~~\n" +msgid "" +"~~~~\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"fn radius_times_area<T: Circle>(c: T) -> f64 {\n" +" // `c` is both a Circle and a Shape\n" +" c.radius() * c.area()\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"fn radius_times_area<T: Circle>(c: T) -> f64 {\n" +" // `c` は Circle でもあり、Shape でもある\n" +" c.radius() * c.area()\n" +"}\n" +"~~~\n" + +#. type: Plain text +#: doc/rust.md:1388 doc/tutorial.md:2508 +msgid "Likewise, supertrait methods may also be called on trait objects." +msgstr "" +"同様に、スーパートレイトのメソッドは、トレイトオブジェクトについても呼び出す" +"ことが可能です。" + +#. type: Plain text +#: doc/rust.md:1395 +#, fuzzy +#| msgid "" +#| "~~~ {.ignore} use std::f64::consts::pi; # trait Shape { fn " +#| "area(&self) -> f64; } # trait Circle : Shape { fn radius(&self) -> f64; } " +#| "# struct Point { x: f64, y: f64 } # struct CircleStruct { center: Point, " +#| "radius: f64 } # impl Circle for CircleStruct { fn radius(&self) -> f64 " +#| "{ (self.area() / pi).sqrt() } } # impl Shape for CircleStruct { fn " +#| "area(&self) -> f64 { pi * square(self.radius) } }" +msgid "" +"~~~~ {.ignore} # trait Shape { fn area(&self) -> f64; } # trait Circle : " +"Shape { fn radius(&self) -> f64; } # impl Shape for int { fn area(&self) -> " +"f64 { 0.0 } } # impl Circle for int { fn radius(&self) -> f64 { 0.0 } } # " +"let mycircle = 0;" +msgstr "" +"~~~ {.ignore}\n" +"use std::f64::consts::pi;\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"# struct Point { x: f64, y: f64 }\n" +"# struct CircleStruct { center: Point, radius: f64 }\n" +"# impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / " +"pi).sqrt() } }\n" +"# impl Shape for CircleStruct { fn area(&self) -> f64 { pi * square(self." +"radius) } }" + +#. type: Plain text +#: doc/rust.md:1399 +#, fuzzy +#| msgid "" +#| "let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f}; let " +#| "mycircle: @Circle = concrete as @Circle; let nonsense = mycircle.radius() " +#| "* mycircle.area(); ~~~" +msgid "" +"let mycircle: Circle = @mycircle as @Circle; let nonsense = mycircle." +"radius() * mycircle.area(); ~~~~" +msgstr "" +"let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f};\n" +"let mycircle: @Circle = concrete as @Circle;\n" +"let nonsense = mycircle.radius() * mycircle.area();\n" +"~~~" + +#. type: Plain text +#: doc/rust.md:1401 +#, fuzzy +#| msgid "# Introduction" +msgid "### Implementations" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/rust.md:1841 +#, fuzzy +#| msgid "## Traits" +msgid "#### Traits" +msgstr "## トレイト" + +#. type: Plain text +#: doc/rust.md:1882 +#, fuzzy +#| msgid "## Operators" +msgid "#### Operations" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:1930 +#, fuzzy +#| msgid "Our example crate declared this set of `link` attributes:" +msgid "There are three different types of inline attributes:" +msgstr "" +"先ほどのクレートの例では、 `link` 属性は以下のように宣言されていました。" + +#. type: Plain text +#: doc/rust.md:1936 +#, fuzzy +#| msgid "## Freezing" +msgid "### Deriving" +msgstr "## 凍結" + +#. type: Plain text +#: doc/rust.md:2038 +#, fuzzy +#| msgid "## Crates" +msgid "### Compiler Features" +msgstr "## クレート" + +#. type: Plain text +#: doc/rust.md:2126 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "# Statements and expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2138 +#, fuzzy +#| msgid "## Structs" +msgid "## Statements" +msgstr "## 構造体" + +#. type: Plain text +#: doc/rust.md:2147 +#, fuzzy +#| msgid "## Declaring and implementing traits" +msgid "### Declaration statements" +msgstr "## トレイトの宣言と実装" + +#. type: Plain text +#: doc/rust.md:2152 +#, fuzzy +#| msgid "## Operators" +msgid "#### Item declarations" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:2164 +#, fuzzy +#| msgid "## Using other crates" +msgid "#### Slot declarations" +msgstr "## 他のクレートの利用" + +#. type: Plain text +#: doc/rust.md:2177 +#, fuzzy +#| msgid "## Expressions and semicolons" +msgid "### Expression statements" +msgstr "## 式とセミコロン" + +#. type: Plain text +#: doc/rust.md:2184 +#, fuzzy +#| msgid "## Expressions and semicolons" +msgid "## Expressions" +msgstr "## 式とセミコロン" + +#. type: Plain text +#: doc/rust.md:2238 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Literal expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2251 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Path expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2256 +#, fuzzy +#| msgid "## Tuples" +msgid "### Tuple expressions" +msgstr "## タプル" + +#. type: Plain text +#: doc/rust.md:2268 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Structure expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2320 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: " +#| "20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~~ # struct Point3d { x: int, y: int, z: int } let base = Point3d {x: 1, " +"y: 2, z: 3}; Point3d {y: 0, z: 10, .. base}; ~~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/rust.md:2341 +#, fuzzy +#| msgid "## Operators" +msgid "### Field expressions" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:2362 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Vector expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2384 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Index expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2400 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~~ {.ignore} # use std::task; # do task::spawn {" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/rust.md:2433 +#, fuzzy +#| msgid "## Using other crates" +msgid "### Binary operator expressions" +msgstr "## 他のクレートの利用" + +#. type: Plain text +#: doc/rust.md:2442 +#, fuzzy +#| msgid "## Operators" +msgid "#### Arithmetic operators" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:2465 +#, fuzzy +#| msgid "## Operators" +msgid "#### Bitwise operators" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:2497 +#, fuzzy +#| msgid "# Control structures" +msgid "#### Comparison operators" +msgstr "# 制御構造" + +#. type: Plain text +#: doc/rust.md:2524 +#, fuzzy +#| msgid "## Tuple structs" +msgid "#### Type cast expressions" +msgstr "## タプル構造体" + +#. type: Plain text +#: doc/rust.md:2557 +#, fuzzy +#| msgid "~~~~ let hi = \"hi\"; let mut count = 0;" +msgid "~~~~ # let mut x = 0; # let y = 0;" +msgstr "" +"~~~~\n" +" let hi = \"hi\";\n" +" let mut count = 0;" + +#. type: Plain text +#: doc/rust.md:2571 +#, fuzzy +#| msgid "## Operators" +msgid "#### Operator precedence" +msgstr "## 演算子" + +#. type: Plain text +#: doc/rust.md:2611 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Call expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2632 +#, fuzzy +#| msgid "" +#| "~~~~ let x: f64 = 4.0; let y: uint = x as uint; assert!(y == 4u); ~~~~" +msgid "" +"let x: int = add(1, 2); let pi: Option<f32> = FromStr::from_str(\"3.14\"); " +"~~~~" +msgstr "" +"~~~~\n" +"let x: f64 = 4.0;\n" +"let y: uint = x as uint;\n" +"assert!(y == 4u);\n" +"~~~~" + +#. type: Plain text +#: doc/rust.md:2634 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Lambda expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2677 +#, fuzzy +#| msgid "## Loops" +msgid "### While loops" +msgstr "## ループ" + +#. type: Plain text +#: doc/rust.md:2688 +#, fuzzy +#| msgid "## A minimal example" +msgid "An example:" +msgstr "## 最小限の例" + +#. type: Plain text +#: doc/rust.md:2691 +#, fuzzy +#| msgid "~~~~ let hi = \"hi\"; let mut count = 0;" +msgid "~~~~ let mut i = 0;" +msgstr "" +"~~~~\n" +" let hi = \"hi\";\n" +" let mut count = 0;" + +#. type: Plain text +#: doc/rust.md:2699 +#, fuzzy +#| msgid "## Loops" +msgid "### Infinite loops" +msgstr "## ループ" + +#. type: Plain text +#: doc/rust.md:2714 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Break expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2727 +#, fuzzy +#| msgid "# Control structures" +msgid "### Continue expressions" +msgstr "# 制御構造" + +#. type: Plain text +#: doc/rust.md:2746 +#, fuzzy +#| msgid "## Conventions" +msgid "### Do expressions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rust.md:2792 +#, fuzzy +#| msgid "## Freezing" +msgid "### For expressions" +msgstr "## 凍結" + +#. type: Plain text +#: doc/rust.md:2826 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### If expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2847 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Match expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2940 +#, fuzzy +#| msgid "~~~~ # let mystery_object = ();" +msgid "~~~~ # let x = 2;" +msgstr "" +"~~~~\n" +"# let mystery_object = ();" + +#. type: Plain text +#: doc/rust.md:2970 +#, fuzzy +#| msgid "## Syntax extensions" +msgid "### Return expressions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/rust.md:2994 +#, fuzzy +#| msgid "## Tuples" +msgid "## Types" +msgstr "## タプル" + +#. type: Plain text +#: doc/rust.md:3003 +#, fuzzy +#| msgid "## Primitive types and literals" +msgid "### Primitive types" +msgstr "## プリミティブ型とリテラル" + +#. type: Plain text +#: doc/rust.md:3005 +#, fuzzy +#| msgid "## Primitive types and literals" +msgid "The primitive types are the following:" +msgstr "## プリミティブ型とリテラル" + +#. type: Plain text +#: doc/rust.md:3013 +#, fuzzy +#| msgid "# Closures" +msgid "#### Machine types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3041 +#, fuzzy +#| msgid "# Closures" +msgid "### Textual types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3054 +#, fuzzy +#| msgid "## Tuples" +msgid "### Tuple types" +msgstr "## タプル" + +#. type: Plain text +#: doc/rust.md:3078 +#, fuzzy +#| msgid "# Closures" +msgid "### Vector types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3102 +#, fuzzy +#| msgid "" +#| "~~~~ let x: f64 = 4.0; let y: uint = x as uint; assert!(y == 4u); ~~~~" +msgid "" +"~~~~ let v: &[int] = &[7, 5, 3]; let i: int = v[2]; assert!(i == 3); ~~~~" +msgstr "" +"~~~~\n" +"let x: f64 = 4.0;\n" +"let y: uint = x as uint;\n" +"assert!(y == 4u);\n" +"~~~~" + +#. type: Plain text +#: doc/rust.md:3107 +#, fuzzy +#| msgid "# Closures" +msgid "### Structure types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3128 +#, fuzzy +#| msgid "# Closures" +msgid "### Enumerated types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3146 +#, fuzzy +#| msgid "# Closures" +msgid "### Recursive types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3173 +#, fuzzy +#| msgid "# Closures" +msgid "### Pointer types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3221 +#, fuzzy +#| msgid "# Functions" +msgid "### Function types" +msgstr "# 関数" + +#. type: Plain text +#: doc/rust.md:3241 +#, fuzzy +#| msgid "# Closures" +msgid "### Closure types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3251 +#, fuzzy +#| msgid "" +#| "let captured_var = 20; let closure = |arg| println(fmt!(\"captured_var=" +#| "%d, arg=%d\", captured_var, arg));" +msgid "let closure_no_args = || println!(\"captured_var={}\", captured_var);" +msgstr "" +"let captured_var = 20;\n" +"let closure = |arg| println(fmt!(\"captured_var=%d, arg=%d\", captured_var, " +"arg));" + +#. type: Plain text +#: doc/rust.md:3256 +#, fuzzy, no-wrap +#| msgid "let captured_var = 20; let closure = |arg| println(fmt!(\"captured_var=%d, arg=%d\", captured_var, arg));" +msgid "" +"let closure_args = |arg: int| -> int {\n" +" println!(\"captured_var={}, arg={}\", captured_var, arg);\n" +" arg // Note lack of semicolon after 'arg'\n" +"};\n" +msgstr "" +"let captured_var = 20;\n" +"let closure = |arg| println(fmt!(\"captured_var=%d, arg=%d\", captured_var, arg));" + +#. type: Plain text +#: doc/rust.md:3267 +#, fuzzy +#| msgid "# Closures" +msgid "### Object types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3299 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"fn main() {\n" +" print(@10 as @Printable);\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/rust.md:3322 +#, fuzzy +#| msgid "# Closures" +msgid "### Self types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3343 +#, fuzzy +#| msgid "## Tuples" +msgid "## Type kinds" +msgstr "## タプル" + +#. type: Plain text +#: doc/rust.md:3440 +#, fuzzy +#| msgid "# Ownership" +msgid "### Memory ownership" +msgstr "# 所有権" + +#. type: Plain text +#: doc/rust.md:3497 +#, fuzzy +#| msgid "## Managed boxes" +msgid "### Memory boxes" +msgstr "## マネージドボックス" + +#. type: Plain text +#: doc/rust.md:3519 +#, fuzzy +#| msgid "~~~~ let hi = \"hi\"; let mut count = 0;" +msgid "~~~~ let x: @int = @10; let x: ~int = ~10; ~~~~" +msgstr "" +"~~~~\n" +" let hi = \"hi\";\n" +" let mut count = 0;" + +#. type: Plain text +#: doc/rust.md:3555 +#, fuzzy +#| msgid "## Traits" +msgid "## Tasks" +msgstr "## トレイト" + +#. type: Plain text +#: doc/rust.md:3580 +#, fuzzy +#| msgid "## Conditionals" +msgid "### Communication between tasks" +msgstr "## 条件式" + +#. type: Plain text +#: doc/rust.md:3660 +#, fuzzy +#| msgid "# Introduction" +msgid "### Memory allocation" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/rust.md:3672 +#, fuzzy +#| msgid "# Closures" +msgid "### Built in types" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/rust.md:3681 +#, fuzzy +#| msgid "[Tasks and communication][tasks]" +msgid "### Task scheduling and communication" +msgstr "[タスクと通信][tasks]" + +#. type: Plain text +#: doc/rust.md:3689 +#, fuzzy +#| msgid "## Freezing" +msgid "### Linkage" +msgstr "## 凍結" + +#. type: Plain text +#: doc/rust.md:3861 +#, fuzzy +msgid "## Influences" +msgstr "# ポインタのデリファレンス" diff --git a/src/doc/po/ja/rustdoc.md.po b/src/doc/po/ja/rustdoc.md.po new file mode 100644 index 00000000000..9d5146ece7c --- /dev/null +++ b/src/doc/po/ja/rustdoc.md.po @@ -0,0 +1,52 @@ +# Japanese translations for Rust package +# Copyright (C) 2014 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2014. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.10-pre\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2014-01-13 12:01+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/rustdoc.md:2 +#, fuzzy +#| msgid "## Using the rust tool" +msgid "% Rust Documentation" +msgstr "## `rust` コマンドを利用する" + +#. type: Plain text +#: doc/rustdoc.md:9 +#, fuzzy +#| msgid "## Using the rust tool" +msgid "# Creating Documentation" +msgstr "## `rust` コマンドを利用する" + +#. type: Plain text +#: doc/rustdoc.md:79 +#, fuzzy +#| msgid "## Using the rust tool" +msgid "# Using the Documentation" +msgstr "## `rust` コマンドを利用する" + +#. type: Plain text +#: doc/rustdoc.md:90 +#, fuzzy +#| msgid "## Using the rust tool" +msgid "# Testing the Documentation" +msgstr "## `rust` コマンドを利用する" + +#. type: Plain text +#: doc/rustdoc.md:102 +#, fuzzy +#| msgid "# Dereferencing pointers" +msgid "## Defining tests" +msgstr "# ポインタのデリファレンス" diff --git a/src/doc/po/ja/rustpkg.md.po b/src/doc/po/ja/rustpkg.md.po new file mode 100644 index 00000000000..4df7d2fa583 --- /dev/null +++ b/src/doc/po/ja/rustpkg.md.po @@ -0,0 +1,65 @@ +# Japanese translations for Rust package +# Copyright (C) 2013 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2013. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.8\n" +"POT-Creation-Date: 2014-01-13 12:01+0900\n" +"PO-Revision-Date: 2013-07-28 20:32+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/rustpkg.md:2 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "% Rustpkg Reference Manual" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/rustpkg.md:14 +#, fuzzy +#| msgid "## Pattern matching" +msgid "# Package searching" +msgstr "## パターンマッチ" + +#. type: Plain text +#: doc/rustpkg.md:40 +#, fuzzy +#| msgid "# Data structures" +msgid "# Package structure" +msgstr "# データ構造" + +#. type: Plain text +#: doc/rustpkg.md:106 +#, fuzzy +#| msgid "## Conventions" +msgid "## Versions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/rustpkg.md:133 +#, fuzzy +msgid "# Command reference" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/rustpkg.md:150 +#, fuzzy +#| msgid "# Introduction" +msgid "## install" +msgstr "# イントロダクション" diff --git a/src/doc/po/ja/tutorial.md.po b/src/doc/po/ja/tutorial.md.po new file mode 100644 index 00000000000..ddbef4c93cc --- /dev/null +++ b/src/doc/po/ja/tutorial.md.po @@ -0,0 +1,4649 @@ +# Japanese translations for Rust package +# Copyright (C) 2013 The Rust Project Developers +# This file is distributed under the same license as the Rust package. +# Automatically generated, 2013. +# +msgid "" +msgstr "" +"Project-Id-Version: Rust 0.8\n" +"POT-Creation-Date: 2014-01-14 21:02+0900\n" +"PO-Revision-Date: 2013-08-08 22:27+0900\n" +"Last-Translator: Automatically generated\n" +"Language-Team: none\n" +"Language: ja\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=UTF-8\n" +"Content-Transfer-Encoding: UTF-8\n" +"Plural-Forms: nplurals=1; plural=0;\n" + +#. type: Plain text +#: doc/guide-conditions.md:4 doc/guide-ffi.md:4 doc/guide-lifetimes.md:4 +#: doc/guide-macros.md:4 doc/guide-rustpkg.md:4 doc/guide-tasks.md:4 +#: doc/rust.md:4 doc/rustpkg.md:4 doc/tutorial.md:4 +msgid "# Introduction" +msgstr "# イントロダクション" + +#. type: Plain text +#: doc/guide-ffi.md:168 doc/tutorial.md:875 +msgid "# Destructors" +msgstr "# デストラクタ" + +#. type: Plain text +#: doc/guide-lifetimes.md:72 doc/tutorial.md:1394 +msgid "Now we can call `compute_distance()` in various ways:" +msgstr "" +"上記の `compute_distance()` 関数は、様々な方法で呼び出すことができます。" + +#. type: Plain text +#: doc/guide-pointers.md:326 doc/tutorial.md:1345 +#, fuzzy +msgid "# References" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/guide-testing.md:127 doc/tutorial.md:776 +#, fuzzy +#| msgid "## A minimal example" +msgid "For example:" +msgstr "## 最小限の例" + +#. type: Plain text +#: doc/rust.md:1388 doc/tutorial.md:2508 +msgid "Likewise, supertrait methods may also be called on trait objects." +msgstr "" +"同様に、スーパートレイトのメソッドは、トレイトオブジェクトについても呼び出す" +"ことが可能です。" + +#. type: Plain text +#: doc/tutorial.md:2 +msgid "% The Rust Language Tutorial" +msgstr "% Rust 言語チュートリアル" + +#. type: Plain text +#: doc/tutorial.md:13 +msgid "" +"Rust is a programming language with a focus on type safety, memory safety, " +"concurrency and performance. It is intended for writing large-scale, high-" +"performance software that is free from several classes of common errors. " +"Rust has a sophisticated memory model that encourages efficient data " +"structures and safe concurrency patterns, forbidding invalid memory accesses " +"that would otherwise cause segmentation faults. It is statically typed and " +"compiled ahead of time." +msgstr "" +"Rust は、型安全性、メモリ安全性、並列性、パフォーマンスを重視したプログラミン" +"グ言語です。大規模でハイパフォーマンスなソフトウェア作成向きの、C++ 等の言語" +"でよくある誤りを犯しにくい言語仕様になっています。Rust の洗練されたメモリモデ" +"ルでは、効率的なデータ構造や安全な並行計算を実現することが可能であり、セグメ" +"ンテーション違反を引き起こす不正なメモリアクセスは起こりえません。Rust は、静" +"的型付けされた、コンパイル型の言語です。" + +#. type: Plain text +#: doc/tutorial.md:17 +msgid "" +"As a multi-paradigm language, Rust supports writing code in procedural, " +"functional and object-oriented styles. Some of its pleasant high-level " +"features include:" +msgstr "" +"Rust はマルチパラダイム言語であり、手続き型、関数型、オブジェクト指向型のプロ" +"グラミングをサポートします。Rust には、次のような素敵で高レベルな特徴がありま" +"す。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:30 +msgid "" +"**Type inference.** Type annotations on local variable declarations are " +"optional." +msgstr "" +"**型推論:** ローカル変数の宣言では型注釈 (type annotation) を省略できます。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:30 +msgid "" +"**Safe task-based concurrency.** Rust's lightweight tasks do not share " +"memory, instead communicating through messages." +msgstr "" +"**タスクベースの安全な並行計算:** Rust の軽量タスクはタスク間でメモリを共有す" +"るのではなく、メッセージを介して通信します。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:30 +msgid "" +"**Higher-order functions.** Efficient and flexible closures provide " +"iteration and other control structures" +msgstr "" +"**高階関数:** 効率的で柔軟なクロージャにより、イテレーションやその他の制御構" +"造を実現できます。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:30 +msgid "" +"**Pattern matching and algebraic data types.** Pattern matching on Rust's " +"enumeration types (a more powerful version of C's enums, similar to " +"algebraic data types in functional languages) is a compact and expressive " +"way to encode program logic." +msgstr "" +"**パターンマッチと代数的データ型:** Rust の列挙型 (C の列挙型の強化バージョ" +"ン。関数型言語における代数的データ型のようなもの) のパターンマッチにより、プ" +"ログラムの論理を、コンパクトで表現力豊かに記述することができます。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:30 +msgid "" +"**Polymorphism.** Rust has type-parametric functions and types, type classes " +"and OO-style interfaces." +msgstr "" +"**ポリモーフィズム:** Rust には、型パラメータをもつ関数や型、型クラスとオブ" +"ジェクト指向風のインターフェースがあります。" + +#. type: Plain text +#: doc/tutorial.md:32 +msgid "## Scope" +msgstr "## 本文書の位置づけ" + +#. type: Plain text +#: doc/tutorial.md:38 +msgid "" +"This is an introductory tutorial for the Rust programming language. It " +"covers the fundamentals of the language, including the syntax, the type " +"system and memory model, generics, and modules. [Additional tutorials](#what-" +"next) cover specific language features in greater depth." +msgstr "" +"この文章は、Rust プログラミング言語のチュートリアルです。構文、型システムとメ" +"モリモデル、ジェネリクス、モジュールなどの言語の基礎となる部分をカバーしてい" +"ます。 いくつかの言語機能の詳細については、 [その他のチュートリアル](#次のス" +"テップは) を参照してください。" + +#. type: Plain text +#: doc/tutorial.md:42 +msgid "" +"This tutorial assumes that the reader is already familiar with one or more " +"languages in the C family. Understanding of pointers and general memory " +"management techniques will help." +msgstr "" +"本チュートリアルは、読者がすでに 1 つ以上の C 系統言語 に精通していることを前" +"提としています。本書を理解する上で、ポインタやメモリ管理のテクニックに関する" +"知識が役に立つでしょう。" + +#. type: Plain text +#: doc/tutorial.md:44 +msgid "## Conventions" +msgstr "## 本書の表記について" + +#. type: Plain text +#: doc/tutorial.md:47 +msgid "" +"Throughout the tutorial, language keywords and identifiers defined in " +"example code are displayed in `code font`." +msgstr "" +"本チュートリアルでは、言語のキーワードや、サンプルコード中で定義される識別子" +"を `code font` のように示します。" + +#. type: Plain text +#: doc/tutorial.md:53 +msgid "" +"Code snippets are indented, and also shown in a monospaced font. Not all " +"snippets constitute whole programs. For brevity, we'll often show fragments " +"of programs that don't compile on their own. To try them out, you might have " +"to wrap them in `fn main() { ... }`, and make sure they don't contain " +"references to names that aren't actually defined." +msgstr "" +"コードスニペットは、インデントされ、固定幅フォントで表示されます。いくつかの" +"コードスニペットは、プログラムの一部を抜き出したものになっています。説明を簡" +"潔にするため、それだけではコンパイル不可能なプログラムの断片を掲載することが" +"あります。プログラムの動作を試す際には、全体を `fn main() { ... }` で囲んでく" +"ださい。また、プログラム中で未定義の名前を参照している箇所がないか確認してく" +"ださい。" + +#. type: Plain text +#: doc/tutorial.md:57 +msgid "" +"> ***Warning:*** Rust is a language under ongoing development. Notes > about " +"potential changes to the language, implementation > deficiencies, and other " +"caveats appear offset in blockquotes." +msgstr "" +"> ***警告:*** Rust は開発途上の言語です。将来予定されている言語への変更や、実" +"装上の不備、その他の注意事項など、 blockquote の段落 (この段落もそうです) に" +"注意してください。" + +#. type: Plain text +#: doc/tutorial.md:59 +msgid "# Getting started" +msgstr "# はじめに" + +#. type: Plain text +#: doc/tutorial.md:67 +#, fuzzy +#| msgid "" +#| "The Rust compiler currently must be built from a [tarball], unless you " +#| "are on Windows, in which case using the [installer][win-exe] is " +#| "recommended." +msgid "" +"The Rust compiler currently must be built from a [tarball] or [git], unless " +"you are on Windows, in which case using the [installer][win-exe] is " +"recommended. There is a list of community-maintained nightly builds and " +"packages [on the wiki][wiki-packages]." +msgstr "" +"Windows 以外の環境では、今のところ、Rust のコンパイラは [ソースコード]" +"[tarball] からビルドする必要があります。Windows をお使いの場合は、 [インス" +"トーラー][win-exe] の使用をおすすめします。" + +#. type: Plain text +#: doc/tutorial.md:72 +#, fuzzy +#| msgid "" +#| "Since the Rust compiler is written in Rust, it must be built by a " +#| "precompiled \"snapshot\" version of itself (made in an earlier state of " +#| "development). As such, source builds require a connection to the " +#| "Internet, to fetch snapshots, and an OS that can execute the available " +#| "snapshot binaries." +msgid "" +"Since the Rust compiler is written in Rust, it must be built by a " +"precompiled \"snapshot\" version of itself (made in an earlier state of " +"development). The source build automatically fetches these snapshots from " +"the Internet on our supported platforms." +msgstr "" +"Rust のコンパイラは Rust で書かれているため、最新版の少し前のソースからコンパ" +"イルされた「スナップショット」版コンパイラでビルドする必要があります。スナッ" +"プショットを利用してビルドするためには、スナップショットをダウンロードするた" +"めのインターネット接続と、スナップショットバイナリを実行できる OS が必要で" +"す。" + +#. type: Plain text +#: doc/tutorial.md:74 +msgid "Snapshot binaries are currently built and tested on several platforms:" +msgstr "" +"スナップショットバイナリは、現時点では以下のプラットフォーム向けのものがあり" +"ます。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:78 +msgid "Windows (7, Server 2008 R2), x86 only" +msgstr "Windows (7, Server 2008 R2), x86 のみ" + +#. type: Bullet: '* ' +#: doc/tutorial.md:78 +msgid "Linux (various distributions), x86 and x86-64" +msgstr "Linux (各種ディストリビューション), x86 または x86-64" + +#. type: Bullet: '* ' +#: doc/tutorial.md:78 +msgid "OSX 10.6 (\"Snow Leopard\") or greater, x86 and x86-64" +msgstr "OSX 10.6 (\"Snow Leopard\") 以降, x86 または x86-64" + +#. type: Plain text +#: doc/tutorial.md:81 +msgid "" +"You may find that other platforms work, but these are our \"tier 1\" " +"supported build environments that are most likely to work." +msgstr "" +"スナップショットは他のプラットフォームでも動作するかもしれませんが、\"tier " +"1\" プラットフォームとしてサポートされているのは上記のみです。" + +#. type: Plain text +#: doc/tutorial.md:88 +msgid "" +"> ***Note:*** Windows users should read the detailed > \"[getting started]" +"[wiki-start]\" notes on the wiki. Even when using > the binary installer, " +"the Windows build requires a MinGW installation, > the precise details of " +"which are not discussed here. Finally, `rustc` may > need to be [referred to " +"as `rustc.exe`][bug-3319]. It's a bummer, we > know." +msgstr "" +"> ***注意:*** Windows ユーザーは wiki の [getting started][wiki-start] の記事" +"を読んでください。 本書では詳細を説明しませんが、インストーラを利用する場合で" +"も、MinGW のインストールなど、追加の手順が必要です。また、コンパイラは " +"`rustc` ではなく、 [`rustc.exe` として呼び出す必要がある][bug-3319] かもしれ" +"ません。このような制限があることはは、本当に残念です。" + +#. type: Plain text +#: doc/tutorial.md:92 +#, fuzzy +#| msgid "" +#| "[bug-3319]: https://github.com/mozilla/rust/issues/3319 [wiki-start]: " +#| "https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust" +msgid "" +"[bug-3319]: https://github.com/mozilla/rust/issues/3319 [wiki-start]: " +"https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust " +"[git]: https://github.com/mozilla/rust.git" +msgstr "" +"[bug-3319]: https://github.com/mozilla/rust/issues/3319\n" +"[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-" +"developing-Rust" + +#. type: Plain text +#: doc/tutorial.md:95 +msgid "" +"To build from source you will also need the following prerequisite packages:" +msgstr "ソースからビルドするためには、以下のパッケージが必要です。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:101 +msgid "g++ 4.4 or clang++ 3.x" +msgstr "g++ 4.4 または clang++ 3.x" + +#. type: Bullet: '* ' +#: doc/tutorial.md:101 +msgid "python 2.6 or later (but not 3.x)" +msgstr "python 2.6 以降 (ただし、 3.x は除く)" + +#. type: Bullet: '* ' +#: doc/tutorial.md:101 +msgid "perl 5.0 or later" +msgstr "perl 5.0 以降" + +#. type: Bullet: '* ' +#: doc/tutorial.md:101 +msgid "gnu make 3.81 or later" +msgstr "gnu make 3.81 以降" + +#. type: Bullet: '* ' +#: doc/tutorial.md:101 +msgid "curl" +msgstr "curl" + +#. type: Plain text +#: doc/tutorial.md:104 +msgid "" +"If you've fulfilled those prerequisites, something along these lines should " +"work." +msgstr "上記条件を満たしていれば、以下のような手順でビルド可能なはずです。" + +#. type: Plain text +#: doc/tutorial.md:112 +#, fuzzy +#| msgid "" +#| "~~~~ {.notrust} $ curl -O http://static.rust-lang.org/dist/rust-0.7.tar." +#| "gz $ tar -xzf rust-0.7.tar.gz $ cd rust-0.7 $ ./configure $ make && make " +#| "install ~~~~" +msgid "" +"~~~~ {.notrust} $ curl -O http://static.rust-lang.org/dist/rust-0.9.tar.gz $ " +"tar -xzf rust-0.9.tar.gz $ cd rust-0.9 $ ./configure $ make && make install " +"~~~~" +msgstr "" +"~~~~ {.notrust}\n" +"$ curl -O http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"$ tar -xzf rust-0.7.tar.gz $ cd rust-0.7 $ ./configure\n" +"$ make && make install\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:118 +msgid "" +"You may need to use `sudo make install` if you do not normally have " +"permission to modify the destination directory. The install locations can be " +"adjusted by passing a `--prefix` argument to `configure`. Various other " +"options are also supported: pass `--help` for more information on them." +msgstr "" +"インストール先のディレクトリを変更する権限がない場合、 `sudo make install` を" +"実行する必要があるかもしれません。インストール先は `configure` に `--prefix` " +"引数を渡すことで変更できます。`configure` はその他いろいろなオプションをサ" +"ポートしています。詳細については、 `--help` 引数を指定して実行してください。" + +#. type: Plain text +#: doc/tutorial.md:122 +msgid "" +"When complete, `make install` will place several programs into `/usr/local/" +"bin`: `rustc`, the Rust compiler; `rustdoc`, the API-documentation tool; and " +"`rustpkg`, the Rust package manager." +msgstr "" +"ビルド完了後、`make install` を実行すると、以下のプログラムが `/usr/local/" +"bin` にインストールされます。\n" +"\n" +"* `rustc`: Rust のコンパイラ\n" +"* `rustdoc`: API ドキュメント作成ツール\n" +"* `rustpkg`: Rust のパッケージマネージャ\n" + +#. type: Plain text +#: doc/tutorial.md:125 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.9.tar.gz [win-exe]: " +"http://static.rust-lang.org/dist/rust-0.9-install.exe" +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/tutorial.md:127 +msgid "## Compiling your first program" +msgstr "## 最初のプログラム" + +#. type: Plain text +#: doc/tutorial.md:130 +msgid "" +"Rust program files are, by convention, given the extension `.rs`. Say we " +"have a file `hello.rs` containing this program:" +msgstr "" +"Rust プログラムのファイルの拡張子は、慣例的に `.rs` とされています。以下の内" +"容を持つファイル、`hello.rs` が存在するとします。" + +#. type: Plain text +#: doc/tutorial.md:136 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"~~~~\n" +"fn main() {\n" +" println!(\"hello?\");\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:140 +msgid "" +"If the Rust compiler was installed successfully, running `rustc hello.rs` " +"will produce an executable called `hello` (or `hello.exe` on Windows) which, " +"upon running, will likely do exactly what you expect." +msgstr "" +"Rust のコンパイラが正しくインストールされている場合、 `rustc hello.rs` を実行" +"することで、実行ファイル `hello` (Windows の場合 `hello.exe`) を生成すること" +"が可能です。このファイルを実行すれば、予想通りの出力が得られるでしょう。" + +#. type: Plain text +#: doc/tutorial.md:145 +#, fuzzy +#| msgid "" +#| "The Rust compiler tries to provide useful information when it encounters " +#| "an error. If you introduce an error into the program (for example, by " +#| "changing `println` to some nonexistent function), and then compile it, " +#| "you'll see an error message like this:" +msgid "" +"The Rust compiler tries to provide useful information when it encounters an " +"error. If you introduce an error into the program (for example, by changing " +"`println!` to some nonexistent macro), and then compile it, you'll see an " +"error message like this:" +msgstr "" +"コンパイルエラーが発生した場合、Rust コンパイラはエラー解決のための情報を出力" +"します。プログラム中にエラーが含まれる場合 (上記プログラムの `println` を存在" +"しない別の名前に変更した場合など)、コンパイル時に以下のようなエラーメッセージ" +"が出力されます。" + +#. type: Plain text +#: doc/tutorial.md:158 +#, fuzzy +#| msgid "" +#| "In its simplest form, a Rust program is a `.rs` file with some types and " +#| "functions defined in it. If it has a `main` function, it can be compiled " +#| "to an executable. Rust does not allow code that's not a declaration to " +#| "appear at the top level of the file: all statements must live inside a " +#| "function. Rust programs can also be compiled as libraries, and included " +#| "in other programs." +msgid "" +"In its simplest form, a Rust program is a `.rs` file with some types and " +"functions defined in it. If it has a `main` function, it can be compiled to " +"an executable. Rust does not allow code that's not a declaration to appear " +"at the top level of the file: all statements must live inside a function. " +"Rust programs can also be compiled as libraries, and included in other " +"programs, even ones not written in Rust." +msgstr "" +"最も単純な Rust プログラムは、いくつかの型や関数が定義された `.rs` ファイルの" +"みからなります。`.rs` ファイルをコンパイルして実行可能ファイルを作成する場" +"合、ファイル中に `main` 関数が含まれている必要があります。Rust プログラムで" +"ファイルのトップレベルに記述可能なのは宣言 (declaration) のみです。ステートメ" +"ント (statement) は、すべて関数内部に記述されます。Rust のプログラムは、他の" +"プログラムから利用するライブラリとしてコンパイルすることも可能です。" + +#. type: Plain text +#: doc/tutorial.md:160 +msgid "## Editing Rust code" +msgstr "## Rust のコードを編集する" + +#. type: Plain text +#: doc/tutorial.md:170 +msgid "" +"There are vim highlighting and indentation scripts in the Rust source " +"distribution under `src/etc/vim/`. There is an emacs mode under `src/etc/" +"emacs/` called `rust-mode`, but do read the instructions included in that " +"directory. In particular, if you are running emacs 24, then using emacs's " +"internal package manager to install `rust-mode` is the easiest way to keep " +"it up to date. There is also a package for Sublime Text 2, available both " +"[standalone][sublime] and through [Sublime Package Control][sublime-pkg], " +"and support for Kate under `src/etc/kate`." +msgstr "" +"vim のハイライトとインデント用スクリプトは、Rust のソースツリーの `src/etc/" +"vim` 以下にあります。emacs の Rust 編集用モードの `rust-mode` は、 `src/etc/" +"emacs/` 以下にありますが、当該ディレクトリに配置されているインストール手順に" +"従って操作する必要があります。 emacs 24 以降をご利用の場合、 emacs 組み込みの" +"パッケージマネージャで `rust-mode` をインストールするのが最もお手軽です。" +"Sublime Text 2 用のパッケージは、[スタンドアロン版][sublime] と、[Sublime " +"Package Control][sublime-pkg] 版の2つがあります。Kate 向けパッケージは `src/" +"etc/kate` 以下です。" + +#. type: Plain text +#: doc/tutorial.md:177 +msgid "" +"There is ctags support via `src/etc/ctags.rust`, but many other tools and " +"editors are not yet supported. If you end up writing a Rust mode for your " +"favorite editor, let us know so that we can link to it." +msgstr "" +"ctags は `src/etc/ctags.rust` を利用することで rust をサポートします。多くの" +"ツールやエディタは rust をサポートしていません。もしあなたがお気に入りのエ" +"ディタ向けのRust モードを作成した場合、リンクを貼りたいのでお知らせください。" + +#. type: Plain text +#: doc/tutorial.md:180 +msgid "" +"[sublime]: http://github.com/dbp/sublime-rust [sublime-pkg]: http://wbond." +"net/sublime_packages/package_control" +msgstr "" +"[sublime]: http://github.com/dbp/sublime-rust\n" +"[sublime-pkg]: http://wbond.net/sublime_packages/package_control" + +#. type: Plain text +#: doc/tutorial.md:182 +msgid "# Syntax basics" +msgstr "# 基本的な構文" + +#. type: Plain text +#: doc/tutorial.md:190 +msgid "" +"Assuming you've programmed in any C-family language (C++, Java, JavaScript, " +"C#, or PHP), Rust will feel familiar. Code is arranged in blocks delineated " +"by curly braces; there are control structures for branching and looping, " +"like the familiar `if` and `while`; function calls are written `myfunc(arg1, " +"arg2)`; operators are written the same and mostly have the same precedence " +"as in C; comments are again like C; module names are separated with double-" +"colon (`::`) as with C++." +msgstr "" +"あなたが C 系統の言語 (C++, Java, JavaScript, C# または PHP) でプログラミング" +"したことがあれば、Rust の構文には馴染みがあるでしょう。コードは波括弧で区切ら" +"れたブロックの中に配置され、分岐やループのための制御構文はお馴染みの `if` と " +"`while` で、関数呼び出しは `myfunc(arg1, arg2)` と書け、演算子は C のものと同" +"じで、優先順位もほとんど同じで、コメントもまた C と同じで、モジュール名のセパ" +"レータは C++ と同様 2つのコロン (`::`) です。" + +#. type: Plain text +#: doc/tutorial.md:195 +msgid "" +"The main surface difference to be aware of is that the condition at the head " +"of control structures like `if` and `while` does not require parentheses, " +"while their bodies *must* be wrapped in braces. Single-statement, unbraced " +"bodies are not allowed." +msgstr "" +"表記上の違いで注目すべき点は、`if` や `while` などの制御構造の先頭にある条件" +"句を丸括弧で囲う必要がない点と、ボディ部をで波括弧で **囲わなければならない" +"** という点です。ボディ部が単一のステートメントであっても、波括弧を省略するこ" +"とはできません。" + +#. type: Plain text +#: doc/tutorial.md:208 +#, no-wrap +msgid "" +"~~~~\n" +"# mod universe { pub fn recalibrate() -> bool { true } }\n" +"fn main() {\n" +" /* A simple loop */\n" +" loop {\n" +" // A tricky calculation\n" +" if universe::recalibrate() {\n" +" return;\n" +" }\n" +" }\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"# mod universe { pub fn recalibrate() -> bool { true } }\n" +"fn main() {\n" +" /* シンプルなループ */\n" +" loop {\n" +" // 複雑な計算\n" +" if universe::recalibrate() {\n" +" return;\n" +" }\n" +" }\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:212 +msgid "" +"The `let` keyword introduces a local variable. Variables are immutable by " +"default. To introduce a local variable that you can re-assign later, use " +"`let mut` instead." +msgstr "" +"`let` キーワードにより、ローカル変数を定義します。変数はデフォルトでは " +"immutable (変更不可) です。再代入可能なローカル変数を定義するためには、`let " +"mut` を用います。" + +#. type: Plain text +#: doc/tutorial.md:216 +msgid "~~~~ let hi = \"hi\"; let mut count = 0;" +msgstr "" +"~~~~\n" +" let hi = \"hi\";\n" +" let mut count = 0;" + +#. type: Plain text +#: doc/tutorial.md:226 +#, fuzzy +#| msgid "" +#| "Although Rust can almost always infer the types of local variables, you " +#| "can specify a variable's type by following it with a colon, then the type " +#| "name. Static items, on the other hand, always require a type annotation." +msgid "" +"Although Rust can almost always infer the types of local variables, you can " +"specify a variable's type by following it in the `let` with a colon, then " +"the type name. Static items, on the other hand, always require a type " +"annotation." +msgstr "" +"Rust は、ほぼすべてのローカル変数の型を推論してくれますが、コロンの後に続けて" +"型名を書くことで、明示的に変数の型を指定することもできます。一方、静的な項目 " +"(static item) には、常に型注釈を指定しなければなりません。" + +#. type: Plain text +#: doc/tutorial.md:233 +msgid "" +"~~~~ static MONSTER_FACTOR: f64 = 57.8; let monster_size = MONSTER_FACTOR * " +"10.0; let monster_size: int = 50; ~~~~" +msgstr "" +"~~~~\n" +"static MONSTER_FACTOR: f64 = 57.8;\n" +"let monster_size = MONSTER_FACTOR * 10.0;\n" +"let monster_size: int = 50;\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:242 +msgid "" +"Local variables may shadow earlier declarations, as in the previous example: " +"`monster_size` was first declared as a `f64`, and then a second " +"`monster_size` was declared as an `int`. If you were to actually compile " +"this example, though, the compiler would determine that the first " +"`monster_size` is unused and issue a warning (because this situation is " +"likely to indicate a programmer error). For occasions where unused variables " +"are intentional, their names may be prefixed with an underscore to silence " +"the warning, like `let _monster_size = 50;`." +msgstr "" +"ローカル変数は、先行する宣言を隠すことがあります。先の例では、1つ目の " +"`monster_size` は `f64` として宣言され、2つ目の `monster_size` は `int` とし" +"て宣言されています。このプログラムをコンパイルした場合、「1つ目の " +"`monster_size` は未使用である」という警告メッセージが出力されます (プログラマ" +"が何らかの誤りを犯している可能性があるため)。未使用変数の存在が意図的なもので" +"あった場合、未使用変数名の先頭にアンダースコアをつけることで、警告を抑制でき" +"ます (`let _monster_size = 50;`)。" + +#. type: Plain text +#: doc/tutorial.md:248 +msgid "" +"Rust identifiers start with an alphabetic character or an underscore, and " +"after that may contain any sequence of alphabetic characters, numbers, or " +"underscores. The preferred style is to write function, variable, and module " +"names with lowercase letters, using underscores where they help readability, " +"while writing types in camel case." +msgstr "" +"Rust の識別子 (identifier) は、アルファベット、数字、またはアンダースコア " +"(`_`) から構成されますが、先頭の文字は数字以外でなければなりません。関数名、" +"変数名、モジュール名はスネークケース (アルファベットは小文字にし、単語間をア" +"ンダースコアで区切る) にし、型の名前はアッパーキャメルケースにすることが推奨" +"されています。" + +#. type: Plain text +#: doc/tutorial.md:253 +#, no-wrap +msgid "" +"~~~\n" +"let my_variable = 100;\n" +"type MyType = int; // primitive types are _not_ camel case\n" +"~~~\n" +msgstr "" +"~~~\n" +"let my_variable = 100;\n" +"type MyType = int; // プリミティブ型はキャメルケース __ではない__\n" +"~~~\n" + +#. type: Plain text +#: doc/tutorial.md:255 +msgid "## Expressions and semicolons" +msgstr "## 式とセミコロン" + +#. type: Plain text +#: doc/tutorial.md:261 +msgid "" +"Though it isn't apparent in all code, there is a fundamental difference " +"between Rust's syntax and predecessors like C. Many constructs that are " +"statements in C are expressions in Rust, allowing code to be more concise. " +"For example, you might write a piece of code like this:" +msgstr "" +"コードの見た目から明らかではないのですが、Rust の構文と、C 等の先行言語の構文" +"との間の根本的な違いがとして、C ではステートメントとして扱われる多くの構文要" +"素が、Rust では式として扱われるという点があります。Rust のこの特徴により、" +"コードをより簡潔に書くことができるようになります。例えば、C 系言語では以下の" +"ようにコードを書きますが、" + +#. type: Plain text +#: doc/tutorial.md:275 +msgid "But, in Rust, you don't have to repeat the name `price`:" +msgstr "Rust では、変数名 `price` を繰り返し書く必要はありません。" + +#. type: Plain text +#: doc/tutorial.md:293 +msgid "" +"Both pieces of code are exactly equivalent: they assign a value to `price` " +"depending on the condition that holds. Note that there are no semicolons in " +"the blocks of the second snippet. This is important: the lack of a semicolon " +"after the last statement in a braced block gives the whole block the value " +"of that last expression." +msgstr "" +"どちらのコードも、全く等価です。`price` には、条件 (この場合は `item` の値) " +"に対応した値が代入されます。2つ目のコード例では、ブロックの中にセミコロンが書" +"かれていないことに注意してください。ブロック内の最後のステートメントの後にセ" +"ミコロンがない場合、**ブロック全体の値 (ブロックを式として評価した際の値) は" +"最後の式の値になります**。" + +#. type: Plain text +#: doc/tutorial.md:299 +msgid "" +"Put another way, the semicolon in Rust *ignores the value of an " +"expression*. Thus, if the branches of the `if` had looked like `{ 4; }`, " +"the above example would simply assign `()` (nil or void) to `price`. But " +"without the semicolon, each branch has a different value, and `price` gets " +"the value of the branch that was taken." +msgstr "" +"言い換えると、Rust では、セミコロンにより **式の値が無視されます。** したがっ" +"て、上記の例で `if` のすべての節 (branch) が `{ 4; }` のように書かれていたと" +"したら、`price` には単に `()` (nil または void の意) が代入されます。しかし、" +"式にセミコロンが付けられていない場合、各節はそれぞれ異なる値を持ち、 `price` " +"には節のうち実行されたものの値が代入されます。" + +#. type: Plain text +#: doc/tutorial.md:304 +msgid "" +"In short, everything that's not a declaration (declarations are `let` for " +"variables; `fn` for functions; and any top-level named items such as [traits]" +"(#traits), [enum types](#enums), and static items) is an expression, " +"including function bodies." +msgstr "" +"まとめると、宣言 (変数の `let`, 関数の `fn`, [トレイト](#トレイト) や [列挙" +"型](#列挙型)、静的な項目などの、トップレベルで名前を持つ項目) でないものは、" +"すべてが式となります。関数のボディ部も式です。" + +#. type: Plain text +#: doc/tutorial.md:312 +#, no-wrap +msgid "" +"~~~~\n" +"fn is_four(x: int) -> bool {\n" +" // No need for a return statement. The result of the expression\n" +" // is used as the return value.\n" +" x == 4\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"fn is_four(x: int) -> bool {\n" +" // return ステートメントは省略可能。最後の式の値が戻り値となる。\n" +" x == 4\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:314 +msgid "## Primitive types and literals" +msgstr "## プリミティブ型とリテラル" + +#. type: Plain text +#: doc/tutorial.md:321 +msgid "" +"There are general signed and unsigned integer types, `int` and `uint`, as " +"well as 8-, 16-, 32-, and 64-bit variants, `i8`, `u16`, etc. Integers can " +"be written in decimal (`144`), hexadecimal (`0x90`), octal (`0o70`), or " +"binary (`0b10010000`) base. Each integral type has a corresponding literal " +"suffix that can be used to indicate the type of a literal: `i` for `int`, " +"`u` for `uint`, `i8` for the `i8` type." +msgstr "" +"Rust には、他の言語と同様、符号付き整数の `int` と、符号なし整数の `uint` が" +"あります。同様に、8 または 16, 32, 64 ビット幅の `i8`, `u16` などもあります。" +"整数リテラルは、10進数 (`144`)、16進数 (`0x90`)、または2進数 (`0b10010000`) " +"の表記が可能です。整数リテラルの型を表すための、各整数型に対応したサフィック" +"スがあります。例えば、`i` は `int` 型、`u` は `uint` 型、`i8` は `i8` 型に対" +"応します。" + +#. type: Plain text +#: doc/tutorial.md:327 +msgid "" +"In the absence of an integer literal suffix, Rust will infer the integer " +"type based on type annotations and function signatures in the surrounding " +"program. In the absence of any type information at all, Rust will assume " +"that an unsuffixed integer literal has type `int`." +msgstr "" +"サフィックスが省略されている整数リテラルの型は、周囲にある型アノテーションや" +"関数のシグネチャから推論されます。型について一切情報が得られない場合、サ" +"フィックスなしの整数リテラルは `int` 型だとみなされます。" + +#. type: Plain text +#: doc/tutorial.md:334 +#, no-wrap +msgid "" +"~~~~\n" +"let a = 1; // a is an int\n" +"let b = 10i; // b is an int, due to the 'i' suffix\n" +"let c = 100u; // c is a uint\n" +"let d = 1000i32; // d is an i32\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"let a = 1; // a は int\n" +"let b = 10i; // b は int (サフィックス 'i' がある)\n" +"let c = 100u; // c は uint\n" +"let d = 1000i32; // d は i32\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:339 +#, fuzzy +#| msgid "" +#| "There are two floating-point types: `f32`, and `f64`. Floating-point " +#| "numbers are written `0.0`, `1e6`, or `2.1e-4`. Like integers, floating-" +#| "point literals are inferred to the correct type. Suffixes `f32`, and " +#| "`f64` can be used to create literals of a specific type." +msgid "" +"There are two floating-point types: `f32`, and `f64`. Floating-point " +"numbers are written `0.0`, `1e6`, or `2.1e-4`. Like integers, floating-" +"point literals are inferred to the correct type. Suffixes `f32`, and `f64` " +"can be used to create literals of a specific type." +msgstr "" +"浮動小数型は、 `f32`, `f64` の2種類があります。浮動小数リテラルは `0.0` や、 " +"`1e6`、 `2.1e-4` といった表記が可能です。整数と同じく、サフィックスが省略され" +"た浮動小数リテラルは型推論されます。浮動小数のサフィックスは `f32`、`f64` の3" +"種類で、リテラルの末尾につけることで、対応する型の値を作り出すことができま" +"す。" + +#. type: Plain text +#: doc/tutorial.md:341 +msgid "The keywords `true` and `false` produce literals of type `bool`." +msgstr "`true` キーワードと `false` キーワードは、`bool` 型のリテラルです。" + +#. type: Plain text +#: doc/tutorial.md:348 +#, fuzzy +#| msgid "" +#| "Characters, the `char` type, are four-byte Unicode codepoints, whose " +#| "literals are written between single quotes, as in `'x'`. Just like C, " +#| "Rust understands a number of character escapes, using the backslash " +#| "character, such as `\\n`, `\\r`, and `\\t`. String literals, written " +#| "between double quotes, allow the same escape sequences. More on strings " +#| "[later](#vectors-and-strings)." +msgid "" +"Characters, the `char` type, are four-byte Unicode codepoints, whose " +"literals are written between single quotes, as in `'x'`. Just like C, Rust " +"understands a number of character escapes, using the backslash character, " +"such as `\\n`, `\\r`, and `\\t`. String literals, written between double " +"quotes, allow the same escape sequences, and do no other processing, unlike " +"languages such as PHP or shell." +msgstr "" +"文字は `char` 型で表され、4バイトの Unicode コードポイントに対応しています。" +"`'x'` のように、文字をシングルクオートで囲んだものが文字リテラルです。C と同" +"様、 Rust もバックスラッシュを使ったエスケープシーケンス (`\\n`, `\\r`, `" +"\\t`) に対応しています。文字列リテラル (複数の文字をダブルクオートで囲ったも" +"の) も同じエスケープシーケンスに対応しています。詳細は [ベクタと文字列](#ベク" +"タと文字列) の章で述べます。" + +#. type: Plain text +#: doc/tutorial.md:356 +msgid "The nil type, written `()`, has a single value, also written `()`." +msgstr "" +"nil 型は `()` と表記されます。 nil 型の唯一の値も `()` と表記されます。" + +#. type: Plain text +#: doc/tutorial.md:358 +msgid "## Operators" +msgstr "## 演算子" + +#. type: Plain text +#: doc/tutorial.md:363 +msgid "" +"Rust's set of operators contains very few surprises. Arithmetic is done with " +"`*`, `/`, `%`, `+`, and `-` (multiply, quotient, remainder, add, and " +"subtract). `-` is also a unary prefix operator that negates numbers. As in " +"C, the bitwise operators `>>`, `<<`, `&`, `|`, and `^` are also supported." +msgstr "" +"Rust の演算子には、あまり変わったものはありません。算術演算子は `*` (乗算)、 " +"`/` (除算), `%` (剰余), `+` (加算), `-` (減算) です。`-` は数の符号を反転する" +"単行演算子でもあります。C と同様、ビット演算子 `>>`, `<<`, `&`, `|`, `^` もサ" +"ポートされています。" + +#. type: Plain text +#: doc/tutorial.md:366 +#, fuzzy +#| msgid "" +#| "Note that, if applied to an integer value, `!` flips all the bits (like " +#| "`~` in C)." +msgid "" +"Note that, if applied to an integer value, `!` flips all the bits (bitwise " +"NOT, like `~` in C)." +msgstr "" +"整数型に対して `!` 演算子を適用すると、ビット単位での反転操作 (C の `~` と同" +"じ動作) が行われることに注意してください。" + +#. type: Plain text +#: doc/tutorial.md:370 +msgid "" +"The comparison operators are the traditional `==`, `!=`, `<`, `>`, `<=`, and " +"`>=`. Short-circuiting (lazy) boolean operators are written `&&` (and) and " +"`||` (or)." +msgstr "" +"比較演算子は、従来の言語と同じく、`==`, `!=`, `<`, `>`, `<=`, `>=` です。短絡" +"評価 (遅延評価) されるブール演算子は、 `&&` (and 演算) と `||` (or 演算) があ" +"ります。" + +#. type: Plain text +#: doc/tutorial.md:377 +#, fuzzy +#| msgid "" +#| "For type casting, Rust uses the binary `as` operator. It takes an " +#| "expression on the left side and a type on the right side and will, if a " +#| "meaningful conversion exists, convert the result of the expression to the " +#| "given type." +msgid "" +"For compile-time type casting, Rust uses the binary `as` operator. It takes " +"an expression on the left side and a type on the right side and will, if a " +"meaningful conversion exists, convert the result of the expression to the " +"given type. Generally, `as` is only used with the primitive numeric types or " +"pointers, and is not overloadable. [`transmute`][transmute] can be used for " +"unsafe C-like casting of same-sized types." +msgstr "" +"Rust では、型のキャストには二項演算子 `as` を使います。`as` 演算子は、左辺に" +"式、右辺に型を取り、意味のある変換が可能な場合に限り、式の評価結果を指定され" +"た型に変換します。" + +#. type: Plain text +#: doc/tutorial.md:383 +msgid "~~~~ let x: f64 = 4.0; let y: uint = x as uint; assert!(y == 4u); ~~~~" +msgstr "" +"~~~~\n" +"let x: f64 = 4.0;\n" +"let y: uint = x as uint;\n" +"assert!(y == 4u);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:385 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"[transmute]: http://static.rust-lang.org/doc/master/std/cast/fn.transmute." +"html" +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/tutorial.md:387 +msgid "## Syntax extensions" +msgstr "## 構文拡張" + +#. type: Plain text +#: doc/tutorial.md:395 +#, fuzzy, no-wrap +#| msgid "" +#| "*Syntax extensions* are special forms that are not built into the language,\n" +#| "but are instead provided by the libraries. To make it clear to the reader when\n" +#| "a name refers to a syntax extension, the names of all syntax extensions end\n" +#| "with `!`. The standard library defines a few syntax extensions, the most\n" +#| "useful of which is `fmt!`, a `sprintf`-style text formatter that you will\n" +#| "often see in examples.\n" +msgid "" +"*Syntax extensions* are special forms that are not built into the language,\n" +"but are instead provided by the libraries. To make it clear to the reader when\n" +"a name refers to a syntax extension, the names of all syntax extensions end\n" +"with `!`. The standard library defines a few syntax extensions, the most\n" +"useful of which is [`format!`][fmt], a `sprintf`-like text formatter that you\n" +"will often see in examples, and its related family of macros: `print!`,\n" +"`println!`, and `write!`.\n" +msgstr "**構文拡張** *(Syntax extensions)* は言語組み込みではなく、ライブラリにより提供される特殊形式 (スペシャルフォーム) です。プログラム中に構文拡張が登場したことを外見上明確にするため、構文拡張の名前には末尾に `!` をつけますなければなりません。標準ライブラリではいくつかの構文拡張が定義されていますが、その中でも最も有用なのは `fmt!` です。`fmt!` は `sprintf`スタイルの書式整形を行うもので、後のコード例の中でも何度か見かけることになるでしょう。\n" + +#. type: Plain text +#: doc/tutorial.md:399 +#, fuzzy +#| msgid "" +#| "`fmt!` supports most of the directives that [printf][pf] supports, but " +#| "unlike printf, will give you a compile-time error when the types of the " +#| "directives don't match the types of the arguments." +msgid "" +"`format!` draws syntax from Python, but contains many of the same principles " +"that [printf][pf] has. Unlike printf, `format!` will give you a compile-time " +"error when the types of the directives don't match the types of the " +"arguments." +msgstr "" +"`fmt!` は、[`printf`][pf] がサポートするほとんどのディレクティブ (フォーマッ" +"ト指定子) をサポートしますが、`printf` とは異なり、ディレクティブと引数の型が" +"一致しない場合はコンパイルエラーとなります。" + +#. type: Plain text +#: doc/tutorial.md:402 +msgid "~~~~ # let mystery_object = ();" +msgstr "" +"~~~~\n" +"# let mystery_object = ();" + +#. type: Plain text +#: doc/tutorial.md:409 +#, fuzzy +#| msgid "" +#| "// %? will conveniently print any type println(fmt!(\"what is this thing: " +#| "%?\", mystery_object)); ~~~~" +msgid "" +"// {:?} will conveniently print any type println!(\"what is this thing: " +"{:?}\", mystery_object); ~~~~" +msgstr "" +"// %? は任意の型を表示できる便利なディレクティブです\n" +"println(fmt!(\"what is this thing: %?\", mystery_object));\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:412 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"[pf]: http://en.cppreference.com/w/cpp/io/c/fprintf [fmt]: http://static." +"rust-lang.org/doc/master/std/fmt/index.html" +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/tutorial.md:416 +#, fuzzy +#| msgid "" +#| "You can define your own syntax extensions with the macro system. For " +#| "details, see the [macro tutorial][macros]." +msgid "" +"You can define your own syntax extensions with the macro system. For " +"details, see the [macro tutorial][macros]. Note that macro definition is " +"currently considered an unstable feature." +msgstr "" +"マクロシステムを利用すれば、独自に構文拡張を定義することも可能です。詳細は " +"[マクロチュートリアル][macros] を参照してください。" + +#. type: Plain text +#: doc/tutorial.md:418 +msgid "# Control structures" +msgstr "# 制御構造" + +#. type: Plain text +#: doc/tutorial.md:420 +msgid "## Conditionals" +msgstr "## 条件式" + +#. type: Plain text +#: doc/tutorial.md:424 +msgid "" +"We've seen `if` expressions a few times already. To recap, braces are " +"compulsory, an `if` can have an optional `else` clause, and multiple `if`/" +"`else` constructs can be chained together:" +msgstr "" +"`if` 式は既に何度か登場しています。これまでの説明の要点をまとめると、波括弧は" +"省略不可であり、`if` 式には省略可能な `else` 句があり、複数個の `if`/`else` " +"構文は互いに連鎖できる、ということでした。" + +#. type: Plain text +#: doc/tutorial.md:439 +msgid "" +"The condition given to an `if` construct *must* be of type `bool` (no " +"implicit conversion happens). If the arms are blocks that have a value, this " +"value must be of the same type for every arm in which control reaches the " +"end of the block:" +msgstr "" +"`if` 構文の条件式は `bool` 型ででなければなりません (暗黙的な型変換は行われま" +"せん)。同一の `if` 構文に属する arm のうち、制御がブロックの末尾まで到達し得" +"るものは、すべて同じ型の値でなければなりません。" + +#. type: Plain text +#: doc/tutorial.md:449 +msgid "## Pattern matching" +msgstr "## パターンマッチ" + +#. type: Plain text +#: doc/tutorial.md:455 +msgid "" +"Rust's `match` construct is a generalized, cleaned-up version of C's " +"`switch` construct. You provide it with a value and a number of *arms*, each " +"labelled with a pattern, and the code compares the value against each " +"pattern in order until one matches. The matching pattern executes its " +"corresponding arm." +msgstr "" +"Rust の `match` 構文は、C の `switch` 構文を整理・一般化したものです。" +"`match` 構文は、パターンマッチの対象となる値と、いくつかの、 **arm** (**訳" +"注:** 分岐条件と、条件を満たした場合に実行される式の組のこと。`match` の場合" +"はパターンと式の組) から構成されます。`match` 構文では、指定された値とパター" +"ンの比較をコード内で記述された順番通りに行います。比較の結果、値とパターンが" +"マッチした場合、対応する式が実行されます。マッチしたパターンの後に現れるパ" +"ターンとの比較は行われません。" + +#. type: Plain text +#: doc/tutorial.md:469 +msgid "" +"Unlike in C, there is no \"falling through\" between arms: only one arm " +"executes, and it doesn't have to explicitly `break` out of the construct " +"when it is finished." +msgstr "" +"C とは異なり、Rust では arm 間での「フォールスルー」はないため、1つの arm の" +"みが実行されます。 そのため、 `match` 構文から抜ける箇所を `break` により明示" +"する必要はありません。" + +#. type: Plain text +#: doc/tutorial.md:478 +#, fuzzy +#| msgid "" +#| "A `match` arm consists of a *pattern*, then an arrow `=>`, followed by an " +#| "*action* (expression). Literals are valid patterns and match only their " +#| "own value. A single arm may match multiple different patterns by " +#| "combining them with the pipe operator (`|`), so long as every pattern " +#| "binds the same set of variables. Ranges of numeric literal patterns can " +#| "be expressed with two dots, as in `M..N`. The underscore (`_`) is a " +#| "wildcard pattern that matches any single value. The asterisk (`*`) is a " +#| "different wildcard that can match one or more fields in an `enum` variant." +msgid "" +"A `match` arm consists of a *pattern*, then an arrow `=>`, followed by an " +"*action* (expression). Literals are valid patterns and match only their own " +"value. A single arm may match multiple different patterns by combining them " +"with the pipe operator (`|`), so long as every pattern binds the same set of " +"variables. Ranges of numeric literal patterns can be expressed with two " +"dots, as in `M..N`. The underscore (`_`) is a wildcard pattern that matches " +"any single value. (`..`) is a different wildcard that can match one or more " +"fields in an `enum` variant." +msgstr "" +"`match` の arm は、 **パターン** および矢印 `=>` と、それらに続く **アクショ" +"ン** (式) から構成されます。リテラルはパターンとして利用可能で、リテラル自身" +"の値のみとマッチするパターンを意味します。複数のパターンをパイプ演算子 (`|`) " +"で結合させることで、複数の異なるパターンにマッチする単一の arm を作ることがで" +"きます。ただし、変数の束縛を行うパターンをパイプ演算子で結合する場合は、すべ" +"てのパータンで束縛する変数の名前・数が一致している必要があります (**訳注:** " +"変数の束縛については、本節の後半で説明します)。指定した範囲に含まれる任意の数" +"値にマッチするパターンは、2つのドットで `M..N` のように表記します。アンダース" +"コア (`_`) は任意の値1つにマッチするワイルドカードパターンです。アスタリスク " +"(`*`) は任意の値をもつ、`enum` バリアントの複数のフィールドにマッチする、ワイ" +"ルドカードです (**訳注** `enum` については、[列挙型](#列挙型) の節で説明しま" +"す)。" + +#. type: Plain text +#: doc/tutorial.md:483 +msgid "" +"The patterns in a match arm are followed by a fat arrow, `=>`, then an " +"expression to evaluate. Each case is separated by commas. It's often " +"convenient to use a block expression for each case, in which case the commas " +"are optional." +msgstr "" +"`match` の各 arm はカンマ (`,`) は区切ります。 arm のアクションとしてブロック" +"を記述することも可能で、その場合は arm 末尾のカンマを省略することが可能です。" + +#. type: Plain text +#: doc/tutorial.md:496 +msgid "" +"`match` constructs must be *exhaustive*: they must have an arm covering " +"every possible case. For example, the typechecker would reject the previous " +"example if the arm with the wildcard pattern was omitted." +msgstr "" +"`match` 構文は **網羅的** でなければなりません。すなわち、`match` 対象の値と" +"同じ型を持つ任意の値に対し、少なくとも 1 つ以上のパターンがマッチするだけの " +"arm を含んでいなければなりません。例えば、上記コード例のワイルドカードパター" +"ンの arm を削除した場合、型検査によりコンパイルエラーとされます。" + +#. type: Plain text +#: doc/tutorial.md:500 +msgid "" +"A powerful application of pattern matching is *destructuring*: matching in " +"order to bind names to the contents of data types." +msgstr "" +"パターンマッチの応用として、 **destructuring** という強力な機能があります。構" +"造化代入とは、データ型内部の値を名前に束縛 (bind) することです。" + +#. type: Plain text +#: doc/tutorial.md:504 +msgid "" +"> ***Note:*** The following code makes use of tuples (`(f64, f64)`) which > " +"are explained in section 5.3. For now you can think of tuples as a list of > " +"items." +msgstr "" +"> ***注意:*** 以下のコード例では5.3 節で説明されるタプル (`(f64, f64)`) を" +"使っています。現時点では、タプルは項目のリストのようなものだとみなしてくださ" +"い。" + +#. type: Plain text +#: doc/tutorial.md:523 +#, fuzzy +#| msgid "" +#| "A variable name in a pattern matches any value, *and* binds that name to " +#| "the value of the matched value inside of the arm's action. Thus, `(0f, " +#| "y)` matches any tuple whose first element is zero, and binds `y` to the " +#| "second element. `(x, y)` matches any two-element tuple, and binds both " +#| "elements to variables." +msgid "" +"A variable name in a pattern matches any value, *and* binds that name to the " +"value of the matched value inside of the arm's action. Thus, `(0.0, y)` " +"matches any tuple whose first element is zero, and binds `y` to the second " +"element. `(x, y)` matches any two-element tuple, and binds both elements to " +"variables." +msgstr "" +"パターン内に登場する変数は、任意の値にマッチ **するだけでなく**、arm のアク" +"ション内ではマッチした値が変数の名前に束縛されます。従って、 `(0f, y)` は1つ" +"目の要素が 0 である任意のタプルにマッチし、 `y` には2つ目の要素の値が束縛され" +"ます。`(x, y)` は任意の2要素のタプルにマッチし、タプルの各要素がそれぞれの変" +"数に束縛されます。" + +#. type: Plain text +#: doc/tutorial.md:530 +msgid "" +"Any `match` arm can have a guard clause (written `if EXPR`), called a " +"*pattern guard*, which is an expression of type `bool` that determines, " +"after the pattern is found to match, whether the arm is taken or not. The " +"variables bound by the pattern are in scope in this guard expression. The " +"first arm in the `angle` example shows an example of a pattern guard." +msgstr "" +"`match` の任意の arm は **パターンガード** と呼ばれる、ガード節 (`if EXPR` と" +"書かれる) を持つことができます。パターンガードは、 `bool` 型の値をもつ式で、" +"値にマッチするパターンが見つかった後に評価され、arm が実行されるかどうかを決" +"定します。パターンにより束縛される変数は、ガード式からも参照可能 (ガード式の" +"スコープに含まれる) です。`angle` 関数の例の最初の arm に、パターンガードの使" +"用例が示されています。" + +#. type: Plain text +#: doc/tutorial.md:535 +msgid "" +"You've already seen simple `let` bindings, but `let` is a little fancier " +"than you've been led to believe. It, too, supports destructuring patterns. " +"For example, you can write this to extract the fields from a tuple, " +"introducing two variables at once: `a` and `b`." +msgstr "" +"`let` は単純な変数束縛だけではなく、パターンによる destructuring をサポートし" +"ています。例えば、タプルからフィールドを抽出し、1度に2つの変数 `a` と `b` を" +"定義することが可能です。" + +#. type: Plain text +#: doc/tutorial.md:540 +msgid "" +"~~~~ # fn get_tuple_of_two_ints() -> (int, int) { (1, 1) } let (a, b) = " +"get_tuple_of_two_ints(); ~~~~" +msgstr "" +"~~~~\n" +"# fn get_tuple_of_two_ints() -> (int, int) { (1, 1) }\n" +"let (a, b) = get_tuple_of_two_ints();\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:544 +msgid "" +"Let bindings only work with _irrefutable_ patterns: that is, patterns that " +"can never fail to match. This excludes `let` from matching literals and most " +"`enum` variants." +msgstr "" +"let による変数定義が可能なのは、パターンが __不可反駁__ (iefutable; 必ず値に" +"マッチする) な場合のみです。この制限により、`let` を用いた destructuring で、" +"リテラルやほとんどの `enum` バリアントをパターンとして用いることはできませ" +"ん。" + +#. type: Plain text +#: doc/tutorial.md:546 +msgid "## Loops" +msgstr "## ループ" + +#. type: Plain text +#: doc/tutorial.md:551 +#, fuzzy +#| msgid "" +#| "`while` denotes a loop that iterates as long as its given condition " +#| "(which must have type `bool`) evaluates to `true`. Inside a loop, the " +#| "keyword `break` aborts the loop, and `loop` aborts the current iteration " +#| "and continues with the next." +msgid "" +"`while` denotes a loop that iterates as long as its given condition (which " +"must have type `bool`) evaluates to `true`. Inside a loop, the keyword " +"`break` aborts the loop, and `continue` aborts the current iteration and " +"continues with the next." +msgstr "" +"`while` は、与えられた条件 (`bool` 型の値でなければならない) が `true` と評価" +"されている間、繰り返し実行されるループを表します。`break` キーワードは、ルー" +"プの実行を中断させます。`loop` キーワードは、現在実行中の繰り返し (イテレー" +"ション) を中断し、次の繰り返しを実行します。" + +#. type: Plain text +#: doc/tutorial.md:560 +msgid "" +"`loop` denotes an infinite loop, and is the preferred way of writing `while " +"true`:" +msgstr "" +"`loop` は無限ループを表します。 `while true` と書く代わりに `loop` と書くこと" +"が推奨されています。" + +#. type: Plain text +#: doc/tutorial.md:572 +msgid "" +"This code prints out a weird sequence of numbers and stops as soon as it " +"finds one that can be divided by five." +msgstr "このコードは 5 で割り切れる数値が現れるまで、数値を出力し続けます。" + +#. type: Plain text +#: doc/tutorial.md:574 +msgid "# Data structures" +msgstr "# データ構造" + +#. type: Plain text +#: doc/tutorial.md:576 +msgid "## Structs" +msgstr "## 構造体" + +#. type: Plain text +#: doc/tutorial.md:581 +msgid "" +"Rust struct types must be declared before they are used using the `struct` " +"syntax: `struct Name { field1: T1, field2: T2 [, ...] }`, where `T1`, " +"`T2`, ... denote types. To construct a struct, use the same syntax, but " +"leave off the `struct`: for example: `Point { x: 1.0, y: 2.0 }`." +msgstr "" +"Rust の構造体 (struct) 型を利用するためには、`struct Name { field1: T1, " +"field2: T2 [, ...] }` (`T1`, `T2`, .. は型を意味する) のように、 `struct` 構" +"文を使った型の宣言が必要です。構造体型の値は、`Point { x: 1.0, y: 2.0 }` のよ" +"うに、構造体宣言から `struct` を取り除いたものと同じ構文で作成します。" + +#. type: Plain text +#: doc/tutorial.md:585 +msgid "" +"Structs are quite similar to C structs and are even laid out the same way in " +"memory (so you can read from a Rust struct in C, and vice-versa). Use the " +"dot operator to access struct fields, as in `mypoint.x`." +msgstr "" +"Rust の構造体は C の構造体とよく似ており、メモリ上のレイアウトも C と同じで" +"す (そのため、Rust と C で相互に構造体を読み込むことが可能です)。構造体の" +"フィールドにアクセスするには、 `mypoint.x` のように、ドット演算子を用います。" + +#. type: Plain text +#: doc/tutorial.md:595 +#, fuzzy +#| msgid "" +#| "Inherited mutability means that any field of a struct may be mutable, if " +#| "the struct is in a mutable slot (or a field of a struct in a mutable " +#| "slot, and so forth)." +msgid "" +"Structs have \"inherited mutability\", which means that any field of a " +"struct may be mutable, if the struct is in a mutable slot." +msgstr "" +"継承ミュータビリティ (inherited mutability) とは、構造体自体がミュータブルな" +"スロットに配置されている場合、構造体のすべてのフィールドもミュータブルになる" +"という性質を意味する言葉です (ミュータブルなスロットに配置された構造体の" +"フィールドに配置された構造体のフィールドもまた、ミュータブルになります) 。" + +#. type: Plain text +#: doc/tutorial.md:599 +msgid "" +"With a value (say, `mypoint`) of such a type in a mutable location, you can " +"do `mypoint.y += 1.0`. But in an immutable location, such an assignment to a " +"struct without inherited mutability would result in a type error." +msgstr "" +"ある構造体の値 (仮に `mypoint` とします) がミュータブルな場所に配置された場" +"合、 `mypoint.y += 1.0` というような操作を行うことができます。しかし、構造体" +"がイミュータブルな場所に配置された場合、ミュータビリティは継承されないため、" +"このような代入操作は型エラーとなります。" + +#. type: Plain text +#: doc/tutorial.md:604 +msgid "" +"~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point " +"{ x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/tutorial.md:608 +msgid "" +"mypoint.y += 1.0; // mypoint is mutable, and its fields as well origin.y += " +"1.0; // ERROR: assigning to immutable field ~~~~" +msgstr "" +"mypoint.y += 1.0;\n" +"// mypoint はミュータブル\n" +"origin.y += 1.0; // ERROR: assigning to immutable field\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:611 +msgid "" +"`match` patterns destructure structs. The basic syntax is `Name { fieldname: " +"pattern, ... }`:" +msgstr "" +"`match` のパターンで構造体の destructuring を行うことも可能です。パターン" +"は、 `Name { fieldname: pattern, ... }` という構文を持ちます。" + +#. type: Plain text +#: doc/tutorial.md:620 +#, fuzzy, no-wrap +#| msgid "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: 20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"# let mypoint = Point { x: 0.0, y: 0.0 };\n" +"match mypoint {\n" +" Point { x: 0.0, y: yy } => println!(\"{}\", yy),\n" +" Point { x: xx, y: yy } => println!(\"{} {}\", xx, yy),\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:627 +#, fuzzy +#| msgid "" +#| "In general, the field names of a struct do not have to appear in the same " +#| "order they appear in the type. When you are not interested in all the " +#| "fields of a struct, a struct pattern may end with `, _` (as in `Name " +#| "{ field1, _ }`) to indicate that you're ignoring all other fields. " +#| "Additionally, struct fields have a shorthand matching form that simply " +#| "reuses the field name as the binding name." +msgid "" +"In general, the field names of a struct do not have to appear in the same " +"order they appear in the type. When you are not interested in all the fields " +"of a struct, a struct pattern may end with `, ..` (as in `Name { field1, .. }" +"`) to indicate that you're ignoring all other fields. Additionally, struct " +"fields have a shorthand matching form that simply reuses the field name as " +"the binding name." +msgstr "" +"構造体のフィールド名の並び順は、型定義での並び順と同じにする必要はありませ" +"ん。構造体のパターンマッチで、すべてのフィールドについて考える必要がない場合" +"は、`Name { field1, _ }` のように、末尾に `, _` をつけることで、他のすべての" +"フィールドを無視することができます。" + +#. type: Plain text +#: doc/tutorial.md:635 +#, fuzzy, no-wrap +#| msgid "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: 20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"# let mypoint = Point { x: 0.0, y: 0.0 };\n" +"match mypoint {\n" +" Point { x, .. } => println!(\"{}\", x),\n" +"}\n" +"~~~\n" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:637 +msgid "## Enums" +msgstr "## 列挙型" + +#. type: Plain text +#: doc/tutorial.md:640 +msgid "" +"Enums are datatypes that have several alternate representations. For " +"example, consider the type shown earlier:" +msgstr "" +"列挙型 (enum) は、いくつかの代替表現を持つデータ型です。例えば、以下の型につ" +"いて考えます。" + +#. type: Plain text +#: doc/tutorial.md:654 +#, fuzzy +#| msgid "" +#| "A value of this type is either a `Circle`, in which case it contains a " +#| "`Point` struct and a `f64`, or a `Rectangle`, in which case it contains " +#| "two `Point` structs. The run-time representation of such a value includes " +#| "an identifier of the actual form that it holds, much like the \"tagged " +#| "union\" pattern in C, but with better static guarantees." +msgid "" +"A value of this type is either a `Circle`, in which case it contains a " +"`Point` struct and a f64, or a `Rectangle`, in which case it contains two " +"`Point` structs. The run-time representation of such a value includes an " +"identifier of the actual form that it holds, much like the \"tagged union\" " +"pattern in C, but with better static guarantees." +msgstr "" +"この型の値は、`Point` 構造体と `f64` を含む `Circle` か、2つの `Point` 構造体" +"を含む `Rectangle` のどちらかになります。列挙型の値の実行時表現には、値がどの" +"形式をとっているのか示す識別子が含まれます。この表現方法は C の \"タグ付き共" +"用体\" と非常によく似ていますが、Rust の列挙型はコンパイラにより値の正当性が" +"静的に保証されるという点でより良いものとなっています。" + +#. type: Plain text +#: doc/tutorial.md:660 +#, fuzzy +#| msgid "" +#| "The above declaration will define a type `Shape` that can refer to such " +#| "shapes, and two functions, `Circle` and `Rectangle`, which can be used to " +#| "construct values of the type (taking arguments of the specified types). " +#| "So `Circle(Point { x: 0f, y: 0f }, 10f)` is the way to create a new " +#| "circle." +msgid "" +"The above declaration will define a type `Shape` that can refer to such " +"shapes, and two functions, `Circle` and `Rectangle`, which can be used to " +"construct values of the type (taking arguments of the specified types). So " +"`Circle(Point { x: 0.0, y: 0.0 }, 10.0)` is the way to create a new circle." +msgstr "" +"上記の宣言は `Shape` 型と `Circle` と `Rectangle` という2つの関数も同時に定義" +"します。これらの関数により、関数名に対応した `Shape` 型の値を構築することがで" +"きます (引数の型も列挙型宣言時に指定されたものをとります)。例えば、" +"`Circle(Point { x: 0f, y: 0f }, 10f)` という記述により、新しい circle を作る" +"ことができます。" + +#. type: Plain text +#: doc/tutorial.md:663 +msgid "" +"Enum variants need not have parameters. This `enum` declaration, for " +"example, is equivalent to a C enum:" +msgstr "" +"列挙型のバリアントはパラメータを省略することもできます。以下の例の `enum` 宣" +"言は C の列挙型と等価です。" + +#. type: Plain text +#: doc/tutorial.md:675 +msgid "" +"This declaration defines `North`, `East`, `South`, and `West` as constants, " +"all of which have type `Direction`." +msgstr "" +"この宣言は `Direction` 型の定数 `North`, `East`, `South`, `West` を定義しま" +"す。" + +#. type: Plain text +#: doc/tutorial.md:679 +msgid "" +"When an enum is C-like (that is, when none of the variants have parameters), " +"it is possible to explicitly set the discriminator values to a constant " +"value:" +msgstr "" +"列挙型が Cライクな (すべてのバリアントがパラメータを持たない) 場合、各定数の" +"識別値 (discriminator value) を明示的に指定することも可能です。" + +#. type: Plain text +#: doc/tutorial.md:692 +msgid "" +"If an explicit discriminator is not specified for a variant, the value " +"defaults to the value of the previous variant plus one. If the first variant " +"does not have a discriminator, it defaults to 0. For example, the value of " +"`North` is 0, `East` is 1, `South` is 2, and `West` is 3." +msgstr "" +"バリアントの識別値が明に指定されていない場合、1つ前のバリアントの値に1を足し" +"たものが設定されます。また、最初のバリアントの場合は0が設定されます。上記の例" +"で言うと、 `North` は 0、 `East` は 1、 `South` は 2、`West` は3となります。" + +#. type: Plain text +#: doc/tutorial.md:695 +msgid "" +"When an enum is C-like, you can apply the `as` cast operator to convert it " +"to its discriminator value as an `int`." +msgstr "" +"C ライクな列挙型の値は、キャスト演算子 `as` を適用することで、`int` 型の識別" +"値へ変換することができます。" + +#. type: Plain text +#: doc/tutorial.md:699 +msgid "" +"For enum types with multiple variants, destructuring is the only way to get " +"at their contents. All variant constructors can be used as patterns, as in " +"this definition of `area`:" +msgstr "" +"複数のバリアントを持つ列挙型で、列挙型値の内部のデータを取得するには、 " +"destructuring を使う必要があります。以下の `area` 関数の例のように、バリアン" +"トのコンストラクタは、パターンとして用いることもできます。" + +#. type: Plain text +#: doc/tutorial.md:716 +#, fuzzy +#| msgid "" +#| "You can write a lone `_` to ignore an individual field, and can ignore " +#| "all fields of a variant like: `Circle(*)`. As in their introduction form, " +#| "nullary enum patterns are written without parentheses." +msgid "" +"You can write a lone `_` to ignore an individual field, and can ignore all " +"fields of a variant like: `Circle(..)`. As in their introduction form, " +"nullary enum patterns are written without parentheses." +msgstr "" +"パターンマッチの際に、特定のフィールドに対するマッチングが不要な場合、無視し" +"たいフィールドの場所に `_` を書くことで、個々のフィールドを無視することができ" +"ます。また、 `Circle(*)` のように書くことで、すべてのフィールドを無視すること" +"も可能です。引数をとらない列挙型のパターンは、定義時の形式と同様、丸括弧の無" +"い形式で記述します。" + +#. type: Plain text +#: doc/tutorial.md:731 +msgid "Enum variants may also be structs. For example:" +msgstr "以下の例のように、列挙型バリアントを構造体にすることも可能です。" + +#. type: Plain text +#: doc/tutorial.md:755 +msgid "## Tuples" +msgstr "## タプル" + +#. type: Plain text +#: doc/tutorial.md:760 +#, fuzzy +#| msgid "" +#| "Tuples in Rust behave exactly like structs, except that their fields do " +#| "not have names. Thus, you cannot access their fields with dot notation. " +#| "Tuples can have any arity except for 0 (though you may consider unit, " +#| "`()`, as the empty tuple if you like)." +msgid "" +"Tuples in Rust behave exactly like structs, except that their fields do not " +"have names. Thus, you cannot access their fields with dot notation. Tuples " +"can have any arity (number of elements) except for 0 (though you may " +"consider unit, `()`, as the empty tuple if you like)." +msgstr "" +"Rust のタプルは、フィールドが名前を持たないという点以外は、構造体と同じように" +"振る舞います。フィールド名が存在しないため、ドット記法を使ってタプルのフィー" +"ルドにアクセスすることはできません。タプルは 1 個以上の要素を持つことができま" +"す (必要ならば、ユニット型 `()` を 0 要素のタプルと見なすことはできます。)" + +#. type: Plain text +#: doc/tutorial.md:767 +#, fuzzy, no-wrap +#| msgid "" +#| "For example:\n" +#| "~~~~\n" +#| "struct MyTup(int, int, f64);\n" +#| "let mytup: MyTup = MyTup(10, 20, 30.0);\n" +#| "match mytup {\n" +#| " MyTup(a, b, c) => info!(a + b + (c as int))\n" +#| "}\n" +#| "~~~~\n" +msgid "" +"~~~~\n" +"let mytup: (int, int, f64) = (10, 20, 30.0);\n" +"match mytup {\n" +" (a, b, c) => info!(\"{}\", a + b + (c as int))\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"struct MyTup(int, int, f64);\n" +"let mytup: MyTup = MyTup(10, 20, 30.0);\n" +"match mytup {\n" +" MyTup(a, b, c) => info!(a + b + (c as int))\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:769 +msgid "## Tuple structs" +msgstr "## タプル構造体" + +#. type: Plain text +#: doc/tutorial.md:774 +msgid "" +"Rust also has _tuple structs_, which behave like both structs and tuples, " +"except that, unlike tuples, tuple structs have names (so `Foo(1, 2)` has a " +"different type from `Bar(1, 2)`), and tuple structs' _fields_ do not have " +"names." +msgstr "" +"Rust には __タプル構造体__ と呼ばれる、構造体とタプルの両者の特徴を併せ持つも" +"のが存在します。タプルと異なり、タプル構造体自体は名前を持ちます (従って、" +"`Foo(1, 2)` と `Bar(1, 2)` は異なる型になります。) しかし、タプル構造体の __" +"フィールド__ は名前を持ちません。" + +#. type: Plain text +#: doc/tutorial.md:784 +#, fuzzy, no-wrap +#| msgid "" +#| "For example:\n" +#| "~~~~\n" +#| "struct MyTup(int, int, f64);\n" +#| "let mytup: MyTup = MyTup(10, 20, 30.0);\n" +#| "match mytup {\n" +#| " MyTup(a, b, c) => info!(a + b + (c as int))\n" +#| "}\n" +#| "~~~~\n" +msgid "" +"~~~~\n" +"struct MyTup(int, int, f64);\n" +"let mytup: MyTup = MyTup(10, 20, 30.0);\n" +"match mytup {\n" +" MyTup(a, b, c) => info!(\"{}\", a + b + (c as int))\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"struct MyTup(int, int, f64);\n" +"let mytup: MyTup = MyTup(10, 20, 30.0);\n" +"match mytup {\n" +" MyTup(a, b, c) => info!(a + b + (c as int))\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:791 +msgid "" +"There is a special case for tuple structs with a single field, which are " +"sometimes called \"newtypes\" (after Haskell's \"newtype\" feature). These " +"are used to define new types in such a way that the new name is not just a " +"synonym for an existing type but is rather its own distinct type." +msgstr "" +"タプル構造体がフィールドを 1 つしか持たない場合、 \"newtype\" と呼ばれること" +"があります (Haskell の \"newtype\" 機能に由来しています)。 このようなタプル構" +"造体を使うことで、既存の型の別名 (シノニム) となる新しい型を定義することがで" +"きます。この新しい型は、元にした型とは異なった型として扱われます。" + +#. type: Plain text +#: doc/tutorial.md:795 +msgid "~~~~ struct GizmoId(int); ~~~~" +msgstr "" +"~~~~\n" +"struct GizmoId(int);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:798 +#, fuzzy +#| msgid "" +#| "Types like this can be useful to differentiate between data that have the " +#| "same type but must be used in different ways." +msgid "" +"Types like this can be useful to differentiate between data that have the " +"same underlying type but must be used in different ways." +msgstr "" +"このような型は、型は同一でも、それぞれ全く異なる扱い方をしなければならない" +"データを扱う場合に用いると便利です。" + +#. type: Plain text +#: doc/tutorial.md:803 +msgid "~~~~ struct Inches(int); struct Centimeters(int); ~~~~" +msgstr "" +"~~~~\n" +"struct Inches(int);\n" +"struct Centimeters(int);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:807 +#, fuzzy +#| msgid "" +#| "The above definitions allow for a simple way for programs to avoid " +#| "confusing numbers that correspond to different units." +msgid "" +"The above definitions allow for a simple way for programs to avoid confusing " +"numbers that correspond to different units. Their integer values can be " +"extracted with pattern matching:" +msgstr "" +"上記のような単純な定義により、異なる単位を持つ数値を混同することなく扱うこと" +"が可能になります。" + +#. type: Plain text +#: doc/tutorial.md:810 +#, fuzzy +#| msgid "~~~~ struct GizmoId(int); ~~~~" +msgid "~~~ # struct Inches(int);" +msgstr "" +"~~~~\n" +"struct GizmoId(int);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:817 +msgid "# Functions" +msgstr "# 関数" + +#. type: Plain text +#: doc/tutorial.md:825 +#, fuzzy +#| msgid "" +#| "We've already seen several function definitions. Like all other static " +#| "declarations, such as `type`, functions can be declared both at the top " +#| "level and inside other functions (or in modules, which we'll come back to " +#| "[later](#modules-and-crates)). The `fn` keyword introduces a function. A " +#| "function has an argument list, which is a parenthesized list of `expr: " +#| "type` pairs separated by commas. An arrow `->` separates the argument " +#| "list and the function's return type." +msgid "" +"We've already seen several function definitions. Like all other static " +"declarations, such as `type`, functions can be declared both at the top " +"level and inside other functions (or in modules, which we'll come back to " +"[later](#crates-and-the-module-system)). The `fn` keyword introduces a " +"function. A function has an argument list, which is a parenthesized list of " +"`name: type` pairs separated by commas. An arrow `->` separates the argument " +"list and the function's return type." +msgstr "" +"関数定義はこれまでに何度か登場しています。他の静的な宣言 (`type` など)と同様" +"に、関数はトップレベルまたは、他の関数の内部、モジュールの内部で定義すること" +"ができます (モジュールについては、[後述](#モジュールとクレート)します) 。" + +#. type: Plain text +#: doc/tutorial.md:831 +#, fuzzy, no-wrap +#| msgid "~~~~ fn line(a: int, b: int, x: int) -> int { a * x + b } fn oops(a: int, b: int, x: int) -> () { a * x + b; }" +msgid "" +"~~~~\n" +"fn line(a: int, b: int, x: int) -> int {\n" +" return a * x + b;\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"fn line(a: int, b: int, x: int) -> int { a * x + b }\n" +"fn oops(a: int, b: int, x: int) -> () { a * x + b; }" + +#. type: Plain text +#: doc/tutorial.md:836 +msgid "" +"The `return` keyword immediately returns from the body of a function. It is " +"optionally followed by an expression to return. A function can also return a " +"value by having its top-level block produce an expression." +msgstr "" +"`return` キーワードにより、呼び出し中の関数を即座に復帰させることができます。" +"`return` の後に式を書くことで、呼び出し元へ戻り値として返すことも可能です。ま" +"た、関数トップレベルのブロックを式と解釈した場合の値 (ブロック内最後の式の" +"値) も関数の戻り値になります。" + +#. type: Plain text +#: doc/tutorial.md:842 +#, fuzzy, no-wrap +#| msgid "~~~~ fn line(a: int, b: int, x: int) -> int { a * x + b } fn oops(a: int, b: int, x: int) -> () { a * x + b; }" +msgid "" +"~~~~\n" +"fn line(a: int, b: int, x: int) -> int {\n" +" a * x + b\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"fn line(a: int, b: int, x: int) -> int { a * x + b }\n" +"fn oops(a: int, b: int, x: int) -> () { a * x + b; }" + +#. type: Plain text +#: doc/tutorial.md:849 +msgid "" +"It's better Rust style to write a return value this way instead of writing " +"an explicit `return`. The utility of `return` comes in when returning early " +"from a function. Functions that do not return a value are said to return " +"nil, `()`, and both the return type and the return value may be omitted from " +"the definition. The following two functions are equivalent." +msgstr "" +"Rust では、明示的に `return` を書くのではなく、上記のような方法で戻り値を返す" +"スタイルが推奨されています。 `return` は、関数を途中で復帰させたい場合に使い" +"ます。値を返さない関数は、 nil `()` を返す関数として取り扱われ、関数の戻り値" +"の型や、戻り値を返す処理を省略することが可能です。以下の2つの関数は等価です。" + +#. type: Plain text +#: doc/tutorial.md:852 +msgid "~~~~ fn do_nothing_the_hard_way() -> () { return (); }" +msgstr "" +"~~~~\n" +"fn do_nothing_the_hard_way() -> () { return (); }" + +#. type: Plain text +#: doc/tutorial.md:855 +msgid "fn do_nothing_the_easy_way() { } ~~~~" +msgstr "" +"fn do_nothing_the_easy_way() { }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:857 +msgid "" +"Ending the function with a semicolon like so is equivalent to returning `()`." +msgstr "以下のように、セミコロンで終わる関数は `()` を返す関数と等価です。" + +#. type: Plain text +#: doc/tutorial.md:861 +msgid "" +"~~~~ fn line(a: int, b: int, x: int) -> int { a * x + b } fn oops(a: int, b: " +"int, x: int) -> () { a * x + b; }" +msgstr "" +"~~~~\n" +"fn line(a: int, b: int, x: int) -> int { a * x + b }\n" +"fn oops(a: int, b: int, x: int) -> () { a * x + b; }" + +#. type: Plain text +#: doc/tutorial.md:865 +msgid "assert!(8 == line(5, 3, 1)); assert!(() == oops(5, 3, 1)); ~~~~" +msgstr "" +"assert!(8 == line(5, 3, 1));\n" +"assert!(() == oops(5, 3, 1));\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:869 +msgid "" +"As with `match` expressions and `let` bindings, function arguments support " +"pattern destructuring. Like `let`, argument patterns must be irrefutable, as " +"in this example that unpacks the first value from a tuple and returns it." +msgstr "" +"`match` 式や `let` による変数定義のように、関数の引数もパターンによる " +"destructuring をサポートしています。`let` と同様、引数のパターンは 不可反駁 " +"(irrefutable) でなければなりません。以下の例では、タプルの最初の要素を取得" +"し、呼び出し元へ返します。" + +#. type: Plain text +#: doc/tutorial.md:873 +msgid "~~~ fn first((value, _): (int, f64)) -> int { value } ~~~" +msgstr "" +"~~~\n" +"fn first((value, _): (int, f64)) -> int { value }\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:879 +msgid "" +"A *destructor* is a function responsible for cleaning up the resources used " +"by an object when it is no longer accessible. Destructors can be defined to " +"handle the release of resources like files, sockets and heap memory." +msgstr "" +"**デストラクタ** はアクセスできなくなったオブジェクトから利用されていたリソー" +"スを解放する役割を持つ関数です。デストラクタはファイルやソケット、ヒープメモ" +"リのようなリソースの解放を処理するために定義することができます。" + +#. type: Plain text +#: doc/tutorial.md:883 +#, fuzzy +#| msgid "" +#| "Objects are never accessible after their destructor has been called, so " +#| "there are no dynamic failures from accessing freed resources. When a task " +#| "fails, the destructors of all objects in the task are called." +msgid "" +"Objects are never accessible after their destructor has been called, so no " +"dynamic failures are possible from accessing freed resources. When a task " +"fails, destructors of all objects in the task are called." +msgstr "" +"オブジェクトは、デストラクタが呼び出された後にアクセス不能になります。そのた" +"め、解放済みリソースへアクセスしたことによる動的なエラーは発生しません。タス" +"クの実行に失敗した場合、タスクに属するすべてのオブジェクトのデストラクタが呼" +"び出されます。" + +#. type: Plain text +#: doc/tutorial.md:885 +msgid "" +"The `~` sigil represents a unique handle for a memory allocation on the heap:" +msgstr "" +"シジル `~` はヒープに獲得されたメモリへのユニークな (唯一の) ハンドルを表しま" +"す。" + +#. type: Plain text +#: doc/tutorial.md:897 +msgid "" +"Rust includes syntax for heap memory allocation in the language since it's " +"commonly used, but the same semantics can be implemented by a type with a " +"custom destructor." +msgstr "" +"Rust はヒープメモリ獲得のための構文を持っています。これは、ヒープメモリ獲得が" +"よく利用されるというのが理由ですが、同じ動作は独自のデストラクタを持つ型によ" +"り実装することが可能です。" + +#. type: Plain text +#: doc/tutorial.md:899 +msgid "# Ownership" +msgstr "# 所有権" + +#. type: Plain text +#: doc/tutorial.md:904 +msgid "" +"Rust formalizes the concept of object ownership to delegate management of an " +"object's lifetime to either a variable or a task-local garbage collector. An " +"object's owner is responsible for managing the lifetime of the object by " +"calling the destructor, and the owner determines whether the object is " +"mutable." +msgstr "" +"Rust は、オブジェクトの寿命の管理を変数またはタスクローカルのガベージコレクタ" +"に委譲するために、オブジェクトの所有権という考え方を取り入れています。オブ" +"ジェクトの所有者はデストラクタを呼び出すことにより、オブジェクトの寿命を管理" +"する責任を負っています。また、所有者はオブジェクトがミュータブルかどうかも判" +"断します。" + +#. type: Plain text +#: doc/tutorial.md:908 +#, fuzzy +#| msgid "" +#| "Ownership is recursive, so mutability is inherited recursively and a " +#| "destructor destroys the contained tree of owned objects. Variables are " +#| "top-level owners and destroy the contained object when they go out of " +#| "scope. A box managed by the garbage collector starts a new ownership " +#| "tree, and the destructor is called when it is collected." +msgid "" +"Ownership is recursive, so mutability is inherited recursively and a " +"destructor destroys the contained tree of owned objects. Variables are top-" +"level owners and destroy the contained object when they go out of scope." +msgstr "" +"所有権は再帰的であるため、ミュータビリティは再帰的に継承され、デストラクタは" +"所有しているオブジェクトの含まれているツリーを破壊します。変数はトップレベル" +"の所有者です。変数の存在しているスコープを抜けるタイミングで、変数は所有して" +"いるオブジェクトを破棄します。ガベージコレクタによって管理されるボックスは、" +"新しい所有権ツリーを生成し、ガベージコレクタによりオブジェクトが回収されると" +"きにデストラクタが呼び出されます。" + +#. type: Plain text +#: doc/tutorial.md:912 +msgid "" +"~~~~ // the struct owns the objects contained in the `x` and `y` fields " +"struct Foo { x: int, y: ~int }" +msgstr "" +"~~~~\n" +"// この構造体はフィールド `x` と `y` に含まれるオブジェクトを所有している\n" +"struct Foo { x: int, y: ~int }" + +#. type: Plain text +#: doc/tutorial.md:919 +#, no-wrap +msgid "" +"{\n" +" // `a` is the owner of the struct, and thus the owner of the struct's fields\n" +" let a = Foo { x: 5, y: ~10 };\n" +"}\n" +"// when `a` goes out of scope, the destructor for the `~int` in the struct's\n" +"// field is called\n" +msgstr "" +"{\n" +" // `a` は構造体の所有者であり、構造体のフィールドの所有者でもある\n" +" let a = Foo { x: 5, y: ~10 };\n" +"}\n" +"// `a` の含まれているスコープから抜けるとき、 構造体のフィールドの `~int` のデストラクタが呼ばれる\n" + +#. type: Plain text +#: doc/tutorial.md:924 +msgid "" +"// `b` is mutable, and the mutability is inherited by the objects it owns " +"let mut b = Foo { x: 5, y: ~10 }; b.x = 10; ~~~~" +msgstr "" +"// `b` はミュータブルなので、所有しているオブジェクトにもミュターブル性が継承" +"される\n" +"let mut b = Foo { x: 5, y: ~10 };\n" +"b.x = 10;\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:931 +#, fuzzy +#| msgid "" +#| "If an object doesn't contain garbage-collected boxes, it consists of a " +#| "single ownership tree and is given the `Owned` trait which allows it to " +#| "be sent between tasks. Custom destructors can only be implemented " +#| "directly on types that are `Owned`, but garbage-collected boxes can still " +#| "*contain* types with custom destructors." +msgid "" +"If an object doesn't contain any non-Send types, it consists of a single " +"ownership tree and is itself given the `Send` trait which allows it to be " +"sent between tasks. Custom destructors can only be implemented directly on " +"types that are `Send`, but non-`Send` types can still *contain* types with " +"custom destructors. Example of types which are not `Send` are [`Gc<T>`][gc] " +"and [`Rc<T>`][rc], the shared-ownership types." +msgstr "" +"オブジェクトにガベージコレクトされるボックスが含まれていない場合、オブジェク" +"トは単一の継承ツリーからの構成され、`Owned` トレイトが付与されます。`Owned` " +"トレイトが付与されたデータは、タスク間を跨いで受け渡すことが可能です。独自の" +"デストラクタは、`Owned` トレイトを満たす型に対して直接実装されなければなりま" +"せんが、ガベージコレクトされるボックスが独自のデストラクタをもつ型を **含む" +"** ことは依然可能です。" + +#. type: Plain text +#: doc/tutorial.md:934 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"[gc]: http://static.rust-lang.org/doc/master/std/gc/struct.Gc.html [rc]: " +"http://static.rust-lang.org/doc/master/std/rc/struct.Rc.html" +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/tutorial.md:963 +#, fuzzy +#| msgid "# Boxes" +msgid "## Boxes" +msgstr "# ボックス" + +#. type: Plain text +#: doc/tutorial.md:1032 +#, fuzzy +#| msgid "# Move semantics" +msgid "## Move semantics" +msgstr "# ムーブセマンティクス" + +#. type: Plain text +#: doc/tutorial.md:1076 +msgid "" +"~~~~ let x = ~5; let y = x.clone(); // y is a newly allocated box let z = " +"x; // no new memory allocated, x can no longer be used ~~~~" +msgstr "" +"~~~~\n" +"let x = ~5;\n" +"let y = x.clone();\n" +"// y は新しく獲得されるボックス\n" +"let z = x; // 新たなメモリの獲得は行われない。x を使うことはできなくなる\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:1105 +msgid "" +"~~~~ let r = ~13; let mut s = r; // box becomes mutable *s += 1; let t = " +"s; // box becomes immutable ~~~~" +msgstr "" +"~~~~\n" +"let r = ~13;\n" +"let mut s = r; // ボックスはミュータブルになる\n" +"*s += 1;\n" +"let t = s; // ボックスはイミュータブルになる\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:1129 +#, fuzzy +msgid "## References" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/tutorial.md:1175 +#, fuzzy +#| msgid "## Using other crates" +msgid "## Lists of other types" +msgstr "## 他のクレートの利用" + +#. type: Plain text +#: doc/tutorial.md:1307 +#, fuzzy +#| msgid "## Managed boxes" +msgid "# More on boxes" +msgstr "## マネージドボックス" + +#. type: Plain text +#: doc/tutorial.md:1338 +msgid "~~~~ let x = 5; // immutable let mut y = 5; // mutable y += 2;" +msgstr "" +"~~~~\n" +"let x = 5; // イミュータブル\n" +"let mut y = 5; // ミュータブル\n" +"y += 2;" + +#. type: Plain text +#: doc/tutorial.md:1343 +msgid "" +"let x = ~5; // immutable let mut y = ~5; // mutable *y += 2; // the * " +"operator is needed to access the contained value ~~~~" +msgstr "" +"let x = ~5; // イミュータブル\n" +"let mut y = ~5; // ミュータブル\n" +"*y += 2; // ボックスの中身にアクセスするには、 * 演算子が必要\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:1352 +#, fuzzy +#| msgid "" +#| "Rust's borrowed pointers are a general purpose reference type. In " +#| "contrast with owned boxes, where the holder of an owned box is the owner " +#| "of the pointed-to memory, borrowed pointers never imply ownership. A " +#| "pointer can be borrowed to any object, and the compiler verifies that it " +#| "cannot outlive the lifetime of the object." +msgid "" +"In contrast with owned boxes, where the holder of an owned box is the owner " +"of the pointed-to memory, references never imply ownership - they are " +"\"borrowed\". A reference can be borrowed to any object, and the compiler " +"verifies that it cannot outlive the lifetime of the object." +msgstr "" +"Rust の借用ポインタ (borrowed pointer) は汎用的な参照型です。所有ボックスの場" +"合、ボックスの所有者が参照されているメモリの所有者となるのに対して、借用ポイ" +"ンタを所有することがメモリを所有を意味することはありません。ポインタは任意の" +"オブジェクトから借用することが可能で、参照先のオブジェクトよりもポインタが長" +"生きしないことがコンパイラにより保証されます。" + +#. type: Plain text +#: doc/tutorial.md:1354 +msgid "As an example, consider a simple struct type, `Point`:" +msgstr "例として、シンプルな構造体型の `Point` について考えます。" + +#. type: Plain text +#: doc/tutorial.md:1365 +msgid "" +"We can use this simple definition to allocate points in many different ways. " +"For example, in this code, each of these three local variables contains a " +"point, but allocated in a different location:" +msgstr "" +"シンプルな定義ですが、この定義を使って `Point` 型のオブジェクトを様々な方法で" +"割り当てることができます。例えば、このコードの3つのローカル変数は、それぞれ異" +"なった場所に `Point` 型のオブジェクトを割り当てています。" + +#. type: Plain text +#: doc/tutorial.md:1372 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let on_the_stack : Point = Point { x: 3.0, y: 4.0 };\n" +"let managed_box : @Point = @Point { x: 5.0, y: 1.0 };\n" +"let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/tutorial.md:1382 +#, fuzzy +#| msgid "" +#| "Suppose we want to write a procedure that computes the distance between " +#| "any two points, no matter where they are stored. For example, we might " +#| "like to compute the distance between `on_the_stack` and `managed_box`, or " +#| "between `managed_box` and `owned_box`. One option is to define a function " +#| "that takes two arguments of type point—that is, it takes the points by " +#| "value. But this will cause the points to be copied when we call the " +#| "function. For points, this is probably not so bad, but often copies are " +#| "expensive. So we’d like to define a function that takes the points by " +#| "pointer. We can use borrowed pointers to do this:" +msgid "" +"Suppose we want to write a procedure that computes the distance between any " +"two points, no matter where they are stored. For example, we might like to " +"compute the distance between `on_the_stack` and `managed_box`, or between " +"`managed_box` and `owned_box`. One option is to define a function that takes " +"two arguments of type point—that is, it takes the points by value. But this " +"will cause the points to be copied when we call the function. For points, " +"this is probably not so bad, but often copies are expensive. So we’d like to " +"define a function that takes the points by pointer. We can use references to " +"do this:" +msgstr "" +"`Point` 型のオブジェクトの割り当て先がどこであったとしても利用可能な、任意の " +"2 点間の距離を計算する処理を書きたいとします。例えば、 `on_the_stack`, " +"`managed_box` 間や `managed_box`, `owned_box` 間の距離を計算する処理です。 1" +"つ目の実装方法として、2つの `Point` 型オブジェクトを引数にとる関数を定義する" +"方法、すなわち、オブジェクトを値で受け渡す方法があります。しかし、この方法で" +"は関数呼び出し時に `Point` オブジェクトのコピーが行われます。`Point` オブジェ" +"クトの場合、このような実装はそれほど悪いものではないでしょうが、コピー処理の" +"コストは高い場合もあります。したがって、`Point` オブジェクトをポインタ渡しす" +"る関数を定義する必要があります。そのために、借用ポインタを利用することが可能" +"です。" + +#. type: Plain text +#: doc/tutorial.md:1404 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} # struct Point { x: f64, y: f64 } let mut mypoint = Point { x: 1.0, y: 1.0 }; let origin = Point { x: 0.0, y: 0.0 };" +msgid "" +"~~~\n" +"# struct Point{ x: f64, y: f64 };\n" +"# let on_the_stack : Point = Point { x: 3.0, y: 4.0 };\n" +"# let managed_box : @Point = @Point { x: 5.0, y: 1.0 };\n" +"# let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 };\n" +"# fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 }\n" +"compute_distance(&on_the_stack, managed_box);\n" +"compute_distance(managed_box, owned_box);\n" +"~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"# struct Point { x: f64, y: f64 }\n" +"let mut mypoint = Point { x: 1.0, y: 1.0 };\n" +"let origin = Point { x: 0.0, y: 0.0 };" + +#. type: Plain text +#: doc/tutorial.md:1411 +#, fuzzy +#| msgid "" +#| "Here the `&` operator is used to take the address of the variable " +#| "`on_the_stack`; this is because `on_the_stack` has the type `Point` (that " +#| "is, a struct value) and we have to take its address to get a value. We " +#| "also call this _borrowing_ the local variable `on_the_stack`, because we " +#| "are creating an alias: that is, another route to the same data." +msgid "" +"Here the `&` operator is used to take the address of the variable " +"`on_the_stack`; this is because `on_the_stack` has the type `Point` (that " +"is, a struct value) and we have to take its address to get a reference. We " +"also call this _borrowing_ the local variable `on_the_stack`, because we are " +"creating an alias: that is, another route to the same data." +msgstr "" +"ここで `&` 演算子は `on_the_stack` 変数のアドレスを取得するために使われていま" +"す。これは、 `on_the_stack` の型は `Point` (つまり、構造体の値) であり、呼び" +"出した関数から値を取得させるため、構造体のアドレスを渡す必要があるからです。" +"値の別名 (エイリアス)、すなわち、同じデータへアクセスするための別の方法を提供" +"するので、このような操作のことをローカル変数 `on_the_stack` の __借用__ " +"(_borrowing_) と呼びます。" + +#. type: Plain text +#: doc/tutorial.md:1417 +#, fuzzy +#| msgid "" +#| "In the case of the boxes `managed_box` and `owned_box`, however, no " +#| "explicit action is necessary. The compiler will automatically convert a " +#| "box like `@point` or `~point` to a borrowed pointer like `&point`. This " +#| "is another form of borrowing; in this case, the contents of the managed/" +#| "owned box are being lent out." +msgid "" +"In the case of the boxes `managed_box` and `owned_box`, however, no explicit " +"action is necessary. The compiler will automatically convert a box like " +"`@point` or `~point` to a reference like `&point`. This is another form of " +"borrowing; in this case, the contents of the managed/owned box are being " +"lent out." +msgstr "" +"ボックスである `managed_box` と `owned_box` の場合は、特に明示的な操作を行う" +"必要はありません。コンパイラは `@point` や `~point` のようなボックスを自動的" +"に `&point` のような借用ポインタへと変換します。これは、別の形態の借用 " +"(borrowing) です。この場合、マネージド/所有ボックスの内容が貸し出されていま" +"す。" + +#. type: Plain text +#: doc/tutorial.md:1426 +#, fuzzy +#| msgid "" +#| "Whenever a value is borrowed, there are some limitations on what you can " +#| "do with the original. For example, if the contents of a variable have " +#| "been lent out, you cannot send that variable to another task, nor will " +#| "you be permitted to take actions that might cause the borrowed value to " +#| "be freed or to change its type. This rule should make intuitive sense: " +#| "you must wait for a borrowed value to be returned (that is, for the " +#| "borrowed pointer to go out of scope) before you can make full use of it " +#| "again." +msgid "" +"Whenever a value is borrowed, there are some limitations on what you can do " +"with the original. For example, if the contents of a variable have been lent " +"out, you cannot send that variable to another task, nor will you be " +"permitted to take actions that might cause the borrowed value to be freed or " +"to change its type. This rule should make intuitive sense: you must wait for " +"a borrowed value to be returned (that is, for the reference to go out of " +"scope) before you can make full use of it again." +msgstr "" +"値が借用されている間、借用元の値に対して行える操作がいくらか制限されます。例" +"えば、変数の内容が貸し出された場合、その変数を他のタスクに送信することはでき" +"ませんし、借用された値を解放したり、型が変化させるような操作も行うことができ" +"ません。このルールは理にかなったものでしょう。貸し出した値を最大限に活用する " +"(make full use of it) ためには、貸し出した値の返却 (借用ポインタが存在するス" +"コープを抜ける) を待たなければなりません。" + +#. type: Plain text +#: doc/tutorial.md:1429 +#, fuzzy +#| msgid "" +#| "For a more in-depth explanation of borrowed pointers, read the [borrowed " +#| "pointer tutorial][borrowtut]." +msgid "" +"For a more in-depth explanation of references and lifetimes, read the " +"[references and lifetimes guide][lifetimes]." +msgstr "" +"借用ポインタの詳細については、[借用ポインタのチュートリアル][borrowtut]を参照" +"してください。" + +#. type: Plain text +#: doc/tutorial.md:1431 +msgid "## Freezing" +msgstr "## 凍結" + +#. type: Plain text +#: doc/tutorial.md:1435 +#, fuzzy +#| msgid "" +#| "Borrowing an immutable pointer to an object freezes it and prevents " +#| "mutation. `Owned` objects have freezing enforced statically at compile-" +#| "time." +msgid "" +"Lending an immutable pointer to an object freezes it and prevents mutation. " +"`Freeze` objects have freezing enforced statically at compile-time. An " +"example of a non-`Freeze` type is [`RefCell<T>`][refcell]." +msgstr "" +"オブジェクトへのイミュータブルな (借用) ポインタを借用した場合、借用されたオ" +"ブジェクトは凍結 (freezing) され、変更することができなくなります。`Owned` ト" +"レイトが付与されたオブジェクトは、コンパイル時の静的解析により、強制的に凍結" +"されます (凍結された値を変更しようとすると、コンパイルエラーとなります)。" + +#. type: Plain text +#: doc/tutorial.md:1444 +#, no-wrap +msgid "" +"~~~~\n" +"let mut x = 5;\n" +"{\n" +" let y = &x; // x is now frozen, it cannot be modified\n" +"}\n" +"// x is now unfrozen again\n" +"# x = 3;\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"let mut x = 5;\n" +"{\n" +" let y = &x; // x は凍結されたので、変更することができない\n" +"}\n" +"// x の凍結状態は解除される\n" +"# x = 3;\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:1446 +#, fuzzy +#| msgid "" +#| "[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz [win-exe]: " +#| "http://static.rust-lang.org/dist/rust-0.7-install.exe" +msgid "" +"[refcell]: http://static.rust-lang.org/doc/master/std/cell/struct.RefCell." +"html" +msgstr "" +"[tarball]: http://static.rust-lang.org/dist/rust-0.7.tar.gz\n" +"[win-exe]: http://static.rust-lang.org/dist/rust-0.7-install.exe" + +#. type: Plain text +#: doc/tutorial.md:1448 +msgid "# Dereferencing pointers" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/tutorial.md:1451 +msgid "" +"Rust uses the unary star operator (`*`) to access the contents of a box or " +"pointer, similarly to C." +msgstr "" +"Rust では、C と同様、ボックスの内容やポインタの参照先にアクセスするためには単" +"項スター演算子 (`*`) を使います。" + +#. type: Plain text +#: doc/tutorial.md:1456 +msgid "~~~ let managed = @10; let owned = ~20; let borrowed = &30;" +msgstr "" +"~~~\n" +"let managed = @10;\n" +"let owned = ~20;\n" +"let borrowed = &30;" + +#. type: Plain text +#: doc/tutorial.md:1459 +msgid "let sum = *managed + *owned + *borrowed; ~~~" +msgstr "" +"let sum = *managed + *owned + *borrowed;\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1463 +msgid "" +"Dereferenced mutable pointers may appear on the left hand side of " +"assignments. Such an assignment modifies the value that the pointer points " +"to." +msgstr "" +"ミュータブルなポインタをデリファレンスしたものは、代入文の左辺に置くことがで" +"きます。このような代入文は、ポインタが指す値を変更します。" + +#. type: Plain text +#: doc/tutorial.md:1467 +#, fuzzy +#| msgid "~~~ let managed = @mut 10; let mut owned = ~20;" +msgid "~~~ let managed = @10; let mut owned = ~20;" +msgstr "" +"~~~\n" +"let managed = @mut 10;\n" +"let mut owned = ~20;" + +#. type: Plain text +#: doc/tutorial.md:1470 +msgid "let mut value = 30; let borrowed = &mut value;" +msgstr "" +"let mut value = 30;\n" +"let borrowed = &mut value;" + +#. type: Plain text +#: doc/tutorial.md:1478 +msgid "" +"Pointers have high operator precedence, but lower precedence than the dot " +"operator used for field and method access. This precedence order can " +"sometimes make code awkward and parenthesis-filled." +msgstr "" +"ポインタ演算子の優先順位は高いですが、フィールドやメソッドのアクセスに用いる" +"ドット演算子よりは優先順位は低いです。この優先順位により、コードが不格好で括" +"弧だらけなものになることがあります。" + +#. type: Plain text +#: doc/tutorial.md:1488 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } # enum Shape { Rectangle(Point, " +#| "Point) } # impl Shape { fn area(&self) -> int { 0 } } let start = @Point " +#| "{ x: 10f, y: 20f }; let end = ~Point { x: (*start).x + 100f, y: (*start)." +#| "y + 100f }; let rect = &Rectangle(*start, *end); let area = (*rect)." +#| "area(); ~~~" +msgid "" +"~~~ # struct Point { x: f64, y: f64 } # enum Shape { Rectangle(Point, " +"Point) } # impl Shape { fn area(&self) -> int { 0 } } let start = @Point " +"{ x: 10.0, y: 20.0 }; let end = ~Point { x: (*start).x + 100.0, y: (*start)." +"y + 100.0 }; let rect = &Rectangle(*start, *end); let area = (*rect).area(); " +"~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"# enum Shape { Rectangle(Point, Point) }\n" +"# impl Shape { fn area(&self) -> int { 0 } }\n" +"let start = @Point { x: 10f, y: 20f };\n" +"let end = ~Point { x: (*start).x + 100f, y: (*start).y + 100f };\n" +"let rect = &Rectangle(*start, *end);\n" +"let area = (*rect).area();\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1492 +msgid "" +"To combat this ugliness the dot operator applies _automatic pointer " +"dereferencing_ to the receiver (the value on the left-hand side of the dot), " +"so in most cases, explicitly dereferencing the receiver is not necessary." +msgstr "" +"コードが醜くなるのを防ぐため、ドット演算子はレシーバ (ドットの左にある値) の " +"__ポインタを自動的にデリファレンス__ します。これにより、ほとんどのケースでは" +"レシーバを明示的にデリファレンスする必要がなくなります。" + +#. type: Plain text +#: doc/tutorial.md:1502 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } # enum Shape { Rectangle(Point, " +#| "Point) } # impl Shape { fn area(&self) -> int { 0 } } let start = @Point " +#| "{ x: 10f, y: 20f }; let end = ~Point { x: start.x + 100f, y: start.y + " +#| "100f }; let rect = &Rectangle(*start, *end); let area = rect.area(); ~~~" +msgid "" +"~~~ # struct Point { x: f64, y: f64 } # enum Shape { Rectangle(Point, " +"Point) } # impl Shape { fn area(&self) -> int { 0 } } let start = @Point " +"{ x: 10.0, y: 20.0 }; let end = ~Point { x: start.x + 100.0, y: start.y + " +"100.0 }; let rect = &Rectangle(*start, *end); let area = rect.area(); ~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"# enum Shape { Rectangle(Point, Point) }\n" +"# impl Shape { fn area(&self) -> int { 0 } }\n" +"let start = @Point { x: 10f, y: 20f };\n" +"let end = ~Point { x: start.x + 100f, y: start.y + 100f };\n" +"let rect = &Rectangle(*start, *end);\n" +"let area = rect.area();\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1506 +msgid "" +"You can write an expression that dereferences any number of pointers " +"automatically. For example, if you feel inclined, you could write something " +"silly like" +msgstr "" +"1つのドット演算子で何度も自動デリファレンスが行うことができます。例えば、やろ" +"うと思えば以下のような馬鹿げたものを書くこともできます。" + +#. type: Plain text +#: doc/tutorial.md:1512 +#, fuzzy +#| msgid "" +#| "~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10f, y: " +#| "20f }; println(fmt!(\"%f\", point.x)); ~~~" +msgid "" +"~~~ # struct Point { x: f64, y: f64 } let point = &@~Point { x: 10.0, y: " +"20.0 }; println!(\"{:f}\", point.x); ~~~" +msgstr "" +"~~~\n" +"# struct Point { x: f64, y: f64 }\n" +"let point = &@~Point { x: 10f, y: 20f };\n" +"println(fmt!(\"%f\", point.x));\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1514 +msgid "The indexing operator (`[]`) also auto-dereferences." +msgstr "添字演算子 (`[]`) も自動でリファレンスを行います。" + +#. type: Plain text +#: doc/tutorial.md:1516 +msgid "# Vectors and strings" +msgstr "# ベクタと文字列" + +#. type: Plain text +#: doc/tutorial.md:1520 +#, fuzzy +#| msgid "" +#| "A vector is a contiguous section of memory containing zero or more values " +#| "of the same type. Like other types in Rust, vectors can be stored on the " +#| "stack, the local heap, or the exchange heap. Borrowed pointers to vectors " +#| "are also called 'slices'." +msgid "" +"A vector is a contiguous block of memory containing zero or more values of " +"the same type. Rust also supports vector reference types, called slices, " +"which are a view into a block of memory represented as a pointer and a " +"length." +msgstr "" +"ベクタは同じ型の値が0個以上含まれる、メモリ上の連続した部分のことです。Rust " +"の他の型と同様、ベクタもスタック、ローカルヒープ、交換ヒープ (exchange heap) " +"上に格納することができます。ベクトルの借用ポインタは、「スライス」と呼ばれる" +"場合もあります。" + +#. type: Plain text +#: doc/tutorial.md:1593 +msgid "Square brackets denote indexing into a vector:" +msgstr "角括弧はベクタの添字を表します。" + +#. type: Plain text +#: doc/tutorial.md:1607 +msgid "A vector can be destructured using pattern matching:" +msgstr "ベクタはパターンマッチにより destructuring することができます。" + +#. type: Plain text +#: doc/tutorial.md:1620 +#, fuzzy +#| msgid "" +#| "Both vectors and strings support a number of useful [methods](#methods), " +#| "defined in [`std::vec`] and [`std::str`]. Here are some examples." +msgid "" +"Both vectors and strings support a number of useful [methods](#methods), " +"defined in [`std::vec`] and [`std::str`]." +msgstr "" +"ベクタと文字列は、[`std::vec`] と [`std::str`] で定義された、多くの有用な [メ" +"ソッド](#methods) を持ちます。以下にいくつか例を挙げます。" + +#. type: Plain text +#: doc/tutorial.md:1623 +#, fuzzy +#| msgid "[`std::vec`]: std/vec.html [`std::str`]: std/str.html" +msgid "[`std::vec`]: std/vec/index.html [`std::str`]: std/str/index.html" +msgstr "" +"[`std::vec`]: std/vec.html\n" +"[`std::str`]: std/str.html" + +#. type: Plain text +#: doc/tutorial.md:1635 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ use std::rc::Rc;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/tutorial.md:1654 +#, fuzzy +#| msgid "~~~~ use std::task::spawn;" +msgid "~~~ use std::gc::Gc;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/tutorial.md:1671 +msgid "# Closures" +msgstr "# クロージャ" + +#. type: Plain text +#: doc/tutorial.md:1676 +msgid "" +"Named functions, like those we've seen so far, may not refer to local " +"variables declared outside the function: they do not close over their " +"environment (sometimes referred to as \"capturing\" variables in their " +"environment). For example, you couldn't write the following:" +msgstr "" +"これまで登場したような名前のある関数は、関数の外で定義されるローカル変数を参" +"照することはできません。ローカル変数は環境を閉じ込める (環境中の変数を「キャ" +"プチャする」と呼ばれることもあります) ことはありません。例えば、以下のような" +"コードを書くことはできません。" + +#. type: Plain text +#: doc/tutorial.md:1679 +msgid "~~~~ {.ignore} let foo = 10;" +msgstr "" +"~~~~ {.ignore}\n" +"let foo = 10;" + +#. type: Plain text +#: doc/tutorial.md:1684 +#, no-wrap +msgid "" +"fn bar() -> int {\n" +" return foo; // `bar` cannot refer to `foo`\n" +"}\n" +"~~~~\n" +msgstr "" +"fn bar() -> int {\n" +" return foo; // `bar` ば `foo` を参照できない\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:1687 +msgid "" +"Rust also supports _closures_, functions that can access variables in the " +"enclosing scope." +msgstr "" +"Rust は __クロージャ__ という、周囲のスコープの変数にアクセスできる関数をサ" +"ポートしています。" + +#. type: Plain text +#: doc/tutorial.md:1690 +msgid "~~~~ fn call_closure_with_ten(b: |int|) { b(10); }" +msgstr "" +"~~~~\n" +"fn call_closure_with_ten(b: |int|) { b(10); }" + +#. type: Plain text +#: doc/tutorial.md:1693 +#, fuzzy +#| msgid "" +#| "let captured_var = 20; let closure = |arg| println(fmt!(\"captured_var=" +#| "%d, arg=%d\", captured_var, arg));" +msgid "" +"let captured_var = 20; let closure = |arg| println!(\"captured_var={}, " +"arg={}\", captured_var, arg);" +msgstr "" +"let captured_var = 20;\n" +"let closure = |arg| println(fmt!(\"captured_var=%d, arg=%d\", captured_var, " +"arg));" + +#. type: Plain text +#: doc/tutorial.md:1696 +msgid "call_closure_with_ten(closure); ~~~~" +msgstr "" +"call_closure_with_ten(closure);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:1702 +msgid "" +"Closures begin with the argument list between vertical bars and are followed " +"by a single expression. Remember that a block, `{ <expr1>; <expr2>; ... }`, " +"is considered a single expression: it evaluates to the result of the last " +"expression it contains if that expression is not followed by a semicolon, " +"otherwise the block evaluates to `()`." +msgstr "" +"クロージャはバーティカルバー (`|`) で囲まれた引数リストと、それに続く単一の式" +"から構成されます。ブロック `{ <expr1>; <expr2>; ...}` は単一の式とみなされる" +"ことを思い出してください。ブロックに含まれる最後の式に続けてセミコロンがない" +"場合、ブロックの値は最後の式の値となり、そうでなければ `()` となります。" + +#. type: Plain text +#: doc/tutorial.md:1707 +msgid "" +"The types of the arguments are generally omitted, as is the return type, " +"because the compiler can almost always infer them. In the rare case where " +"the compiler needs assistance, though, the arguments and return types may be " +"annotated." +msgstr "" +"引数の型や戻り値の型は、ほとんどすべての場合においてコンパイラにより推論され" +"るため、通常省略できます。発生するのはまれですが、コンパイラが推論に失敗する" +"場合は、引数と戻り値の型注釈を付けることがあります。" + +#. type: Plain text +#: doc/tutorial.md:1711 +msgid "~~~~ let square = |x: int| -> uint { (x * x) as uint }; ~~~~" +msgstr "" +"~~~~\n" +"let square = |x: int| -> uint { (x * x) as uint };\n" +"~~~~~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:1715 +msgid "" +"There are several forms of closure, each with its own role. The most common, " +"called a _stack closure_, has type `||` and can directly access local " +"variables in the enclosing scope." +msgstr "" +"クロージャにはいくつかの形態があり、それぞれに独自の役割があります。最も一般" +"的なのはスタッククロージャと呼ばれるもので、 `||` という型を持ち、外側のロー" +"カル変数に直接アクセスすることができます。" + +#. type: Plain text +#: doc/tutorial.md:1720 +msgid "~~~~ let mut max = 0; [1, 2, 3].map(|x| if *x > max { max = *x }); ~~~~" +msgstr "" +"~~~~\n" +"let mut max = 0;\n" +"[1, 2, 3].map(|x| if *x > max { max = *x });\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:1729 +msgid "" +"Stack closures are very efficient because their environment is allocated on " +"the call stack and refers by pointer to captured locals. To ensure that " +"stack closures never outlive the local variables to which they refer, stack " +"closures are not first-class. That is, they can only be used in argument " +"position; they cannot be stored in data structures or returned from " +"functions. Despite these limitations, stack closures are used pervasively in " +"Rust code." +msgstr "" +"スタッククロージャは、閉じ込める環境はコールスタック上に獲得され、ローカル変" +"数をポインタで参照するため、非常に効率的です。スタッククロージャが参照してい" +"るローカル変数よりも長生きしないことを保証するため、スタッククロージャは第一" +"級の値ではありません。すなわち、スタッククロージャは引数としてしか使うことが" +"できず、データ構造や関数の戻り値となることはありません。この制限にも関わら" +"ず、スタッククロージャは Rust のコードのあちこちに登場します。" + +#. type: Plain text +#: doc/tutorial.md:1731 +msgid "## Owned closures" +msgstr "## 所有クロージャ" + +#. type: Plain text +#: doc/tutorial.md:1738 +msgid "" +"Owned closures, written `proc`, hold on to things that can safely be sent " +"between processes. They copy the values they close over, much like managed " +"closures, but they also own them: that is, no other code can access them. " +"Owned closures are used in concurrent code, particularly for spawning [tasks]" +"[tasks]." +msgstr "" +"`~` `proc` で書き表される所有クロージャは安全にプロセス間で送信することができ" +"ます。所有クローじゃはマネージドクロージャと全く同じように閉じ込める値をコ" +"ピーしますが、値を所有します。つまり、他のコードは閉じ込められた値にアクセス" +"できなくなります。所有クロージャは並列プログラム、特に [タスク][tasks] 生成で" +"利用されます。" + +#. type: Plain text +#: doc/tutorial.md:1740 +msgid "## Closure compatibility" +msgstr "## クロージャの互換性" + +#. type: Plain text +#: doc/tutorial.md:1747 +msgid "" +"Rust closures have a convenient subtyping property: you can pass any kind of " +"closure (as long as the arguments and return types match) to functions that " +"expect a `||`. Thus, when writing a higher-order function that only calls " +"its function argument, and does nothing else with it, you should almost " +"always declare the type of that argument as `||`. That way, callers may pass " +"any kind of closure." +msgstr "" +"Rust のクロージャは型の派生 (subtyping) という便利な性質を持っています。この" +"性質により、`||` 型を期待する関数には (引数と戻り値の型が一致する限り) 任意の" +"種類のクロージャを渡すことができます。したがって、引数で渡された関数について" +"は呼び出すだけで他に何もしない高階関数を書くときには、ほぼすべてのケースで引" +"数の型を `||` と宣言するべきです。そうすることで、呼び出し元は任意の種類のク" +"ロージャを渡すことができるよになります。" + +#. type: Plain text +#: doc/tutorial.md:1755 +msgid "" +"~~~~ fn call_twice(f: ||) { f(); f(); } let closure = || { \"I'm a closure, " +"and it doesn't matter what type I am\"; }; fn function() { \"I'm a normal " +"function\"; } call_twice(closure); call_twice(function); ~~~~" +msgstr "" +"~~~~\n" +"fn call_twice(f: ||) { f(); f(); }\n" +"let closure = || { \"I'm a closure, and it doesn't matter what type I am" +"\"; };\n" +"fn function() { \"I'm a normal function\"; }\n" +"call_twice(closure);\n" +"call_twice(function);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:1759 +msgid "" +"> ***Note:*** Both the syntax and the semantics will be changing > in small " +"ways. At the moment they can be unsound in some > scenarios, particularly " +"with non-copyable types." +msgstr "" +"> ***注意*** コードの文法と意味は将来的に変更されるかもしれません。現時点では" +"いくつかの状況、特にコピーできない型が関連するケースにおいて望ましくない振る" +"舞いが起こされる場合があります。" + +#. type: Plain text +#: doc/tutorial.md:1761 +msgid "## Do syntax" +msgstr "## do 構文" + +#. type: Plain text +#: doc/tutorial.md:1764 +#, fuzzy +#| msgid "" +#| "The `do` expression provides a way to treat higher-order functions " +#| "(functions that take closures as arguments) as control structures." +msgid "" +"The `do` expression makes it easier to call functions that take procedures " +"as arguments." +msgstr "" +"`do` 式は高階関数 (クロージャを引数にとる関数) を制御構造のように取り扱う方法" +"を提供します。" + +#. type: Plain text +#: doc/tutorial.md:1776 +msgid "" +"As a caller, if we use a closure to provide the final operator argument, we " +"can write it in a way that has a pleasant, block-like structure." +msgstr "" +"最後の引数にクロージャをとる関数を呼び出す場合、ブロック構造を持つかのように" +"コードを書くことが可能です。" + +#. type: Plain text +#: doc/tutorial.md:1786 +#, fuzzy +#| msgid "" +#| "This is such a useful pattern that Rust has a special form of function " +#| "call that can be written more like a built-in control structure:" +msgid "" +"This is such a useful pattern that Rust has a special form of function call " +"for these functions." +msgstr "" +"このような便利なパターンに対応するため、Rust には、言語組み込みの制御構造のよ" +"うな記述が可能な、特別な関数呼び出し形式があります。" + +#. type: Plain text +#: doc/tutorial.md:1798 +#, fuzzy +#| msgid "" +#| "The call is prefixed with the keyword `do` and, instead of writing the " +#| "final closure inside the argument list, it appears outside of the " +#| "parentheses, where it looks more like a typical block of code." +msgid "" +"The call is prefixed with the keyword `do` and, instead of writing the final " +"procedure inside the argument list, it appears outside of the parentheses, " +"where it looks more like a typical block of code." +msgstr "" +"関数呼び出しの前には `do` キーワードをつけ、引数リストの中に最後のクロージャ" +"引数を書くのではなく、普通のコードブロックのように、丸括弧の外に記述します。" + +#. type: Plain text +#: doc/tutorial.md:1803 +msgid "" +"`do` is a convenient way to create tasks with the `task::spawn` function. " +"`spawn` has the signature `spawn(fn: proc())`. In other words, it is a " +"function that takes an owned closure that takes no arguments." +msgstr "" +"`task::spawn` 関数を用いてタスクを生成する場合、 `do` を用いると便利です。" +"`spawn` は、 `spawn(fn: proc())` という方を持っています。言い換えると、" +"`spawn` は「引数をとらない所有クロージャ」を引数としてとる関数ということで" +"す。" + +#. type: Plain text +#: doc/tutorial.md:1806 doc/tutorial.md:1818 +msgid "~~~~ use std::task::spawn;" +msgstr "" +"~~~~\n" +"use std::task::spawn;" + +#. type: Plain text +#: doc/tutorial.md:1815 +msgid "" +"Look at all those bars and parentheses -- that's two empty argument lists " +"back to back. Since that is so unsightly, empty argument lists may be " +"omitted from `do` expressions." +msgstr "" +"このコードの丸括弧と縦棒に注目してください。立て続けに2の空の引数リストが現れ" +"ているます。これは非常に見苦しいので、`do` 式では空の引数リストを省略すること" +"が可能です。" + +#. type: Plain text +#: doc/tutorial.md:1826 +msgid "" +"If you want to see the output of `debug!` statements, you will need to turn " +"on `debug!` logging. To enable `debug!` logging, set the RUST_LOG " +"environment variable to the name of your crate, which, for a file named `foo." +"rs`, will be `foo` (e.g., with bash, `export RUST_LOG=foo`)." +msgstr "" +"`debug!` ステートメントの出力を見たい場合、`debug!` によるロギングを有効にす" +"る必要があるでしょう。`debug!` によるロギングを有効にするためには、 RUST_LOG " +"環境変数をクレートの名前に設定する必要があります (例えば、bash の場合、 " +"`export RUST_LOG=foo` を実行する)。 `foo.rs` というファイルの場合、クレート名" +"は `foo` になります。" + +#. type: Plain text +#: doc/tutorial.md:1828 +msgid "# Methods" +msgstr "# メソッド" + +#. type: Plain text +#: doc/tutorial.md:1834 +msgid "" +"Methods are like functions except that they always begin with a special " +"argument, called `self`, which has the type of the method's receiver. The " +"`self` argument is like `this` in C++ and many other languages. Methods are " +"called with dot notation, as in `my_vec.len()`." +msgstr "" +"メソッドは、`self` という、メソッドのレシーバと同じ型の特別な引数を第一引数と" +"してとる関数のようなものです。`self` は、 C++ や他の言語の `this` のようなも" +"のです。メソッドはドット記法を浸かって `my_vec.len()` のように呼び出します。" + +#. type: Plain text +#: doc/tutorial.md:1838 +msgid "" +"_Implementations_, written with the `impl` keyword, can define methods on " +"most Rust types, including structs and enums. As an example, let's define a " +"`draw` method on our `Shape` enum." +msgstr "" +"`impl` キーワードを使って記述される __実装__ (_implementation_) により、構造" +"体や列挙型を含むほとんどの Rust の型に対してメソッドを定義することができま" +"す。例のように、 `draw` メソッドを `Shape` 列挙型に定義してみましょう。" + +#. type: Plain text +#: doc/tutorial.md:1864 +#, fuzzy +#| msgid "let s = Circle(Point { x: 1f, y: 2f }, 3f); s.draw(); ~~~" +msgid "let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0); s.draw(); ~~~" +msgstr "" +"let s = Circle(Point { x: 1f, y: 2f }, 3f);\n" +"s.draw();\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1868 +msgid "" +"This defines an _implementation_ for `Shape` containing a single method, " +"`draw`. In most respects the `draw` method is defined like any other " +"function, except for the name `self`." +msgstr "" +"この例では、 `Shape` に1つのメソッド `draw` をもつ __実装__ を定義していま" +"す。`draw` メソッドは、`self` という名前を除くほとんどの面で他の関数と同じよ" +"うに定義されます。" + +#. type: Plain text +#: doc/tutorial.md:1873 +msgid "" +"The type of `self` is the type on which the method is implemented, or a " +"pointer thereof. As an argument it is written either `self`, `&self`, " +"`@self`, or `~self`. A caller must in turn have a compatible pointer type " +"to call the method." +msgstr "" +"`self` の型は、メソッドが実装されている型か、それらのポインタである。引数とし" +"ては、 `self`, `&self`, `@self` または `~self` と記述されます。呼び出し側も同" +"様、メソッドを呼び出すための互換性のあるポインタ型をもつ必要があります。" + +#. type: Plain text +#: doc/tutorial.md:1888 +#, fuzzy, no-wrap +#| msgid "" +#| "~~~\n" +#| "# fn draw_circle(p: Point, f: f64) { }\n" +#| "# fn draw_rectangle(p: Point, p: Point) { }\n" +#| "# struct Point { x: f64, y: f64 }\n" +#| "# enum Shape {\n" +#| "# Circle(Point, f64),\n" +#| "# Rectangle(Point, Point)\n" +#| "# }\n" +#| "# impl Shape {\n" +#| "# fn draw_borrowed(&self) { ... }\n" +#| "# fn draw_managed(@self) { ... }\n" +#| "# fn draw_owned(~self) { ... }\n" +#| "# fn draw_value(self) { ... }\n" +#| "# }\n" +#| "# let s = Circle(Point { x: 1f, y: 2f }, 3f);\n" +#| "// As with typical function arguments, managed and owned pointers\n" +#| "// are automatically converted to borrowed pointers\n" +msgid "" +"~~~\n" +"# fn draw_circle(p: Point, f: f64) { }\n" +"# fn draw_rectangle(p: Point, p: Point) { }\n" +"# struct Point { x: f64, y: f64 }\n" +"# enum Shape {\n" +"# Circle(Point, f64),\n" +"# Rectangle(Point, Point)\n" +"# }\n" +"impl Shape {\n" +" fn draw_reference(&self) { ... }\n" +" fn draw_managed(@self) { ... }\n" +" fn draw_owned(~self) { ... }\n" +" fn draw_value(self) { ... }\n" +"}\n" +msgstr "" +"~~~\n" +"# fn draw_circle(p: Point, f: f64) { }\n" +"# fn draw_rectangle(p: Point, p: Point) { }\n" +"# struct Point { x: f64, y: f64 }\n" +"# enum Shape {\n" +"# Circle(Point, f64),\n" +"# Rectangle(Point, Point)\n" +"# }\n" +"# impl Shape {\n" +"# fn draw_borrowed(&self) { ... }\n" +"# fn draw_managed(@self) { ... }\n" +"# fn draw_owned(~self) { ... }\n" +"# fn draw_value(self) { ... }\n" +"# }\n" +"# let s = Circle(Point { x: 1f, y: 2f }, 3f);\n" +"// 関数の引数と同様、マネージドポインタと所有ポインタは、\n" +"// 自動的に借用ポインタに変換される\n" + +#. type: Plain text +#: doc/tutorial.md:1890 +#, fuzzy +#| msgid "let s = Circle(Point { x: 1f, y: 2f }, 3f); s.draw(); ~~~" +msgid "let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);" +msgstr "" +"let s = Circle(Point { x: 1f, y: 2f }, 3f);\n" +"s.draw();\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1896 +#, fuzzy +#| msgid "" +#| "(@s).draw_managed(); (~s).draw_owned(); (&s).draw_borrowed(); s." +#| "draw_value(); ~~~" +msgid "" +"(@s).draw_managed(); (~s).draw_owned(); (&s).draw_reference(); s." +"draw_value(); ~~~" +msgstr "" +"(@s).draw_managed();\n" +"(~s).draw_owned();\n" +"(&s).draw_borrowed();\n" +"s.draw_value();\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1900 +#, fuzzy +#| msgid "" +#| "Methods typically take a borrowed pointer self type, so the compiler will " +#| "go to great lengths to convert a callee to a borrowed pointer." +msgid "" +"Methods typically take a reference self type, so the compiler will go to " +"great lengths to convert a callee to a reference." +msgstr "" +"多くのメソッドは、借用ポインタの self 型を持つので、コンパイラは呼び出し先を" +"借用ポインタに変換するためあらゆる手段を講じます。" + +#. type: Plain text +#: doc/tutorial.md:1918 +#, fuzzy, no-wrap +#| msgid "" +#| "~~~\n" +#| "# fn draw_circle(p: Point, f: f64) { }\n" +#| "# fn draw_rectangle(p: Point, p: Point) { }\n" +#| "# struct Point { x: f64, y: f64 }\n" +#| "# enum Shape {\n" +#| "# Circle(Point, f64),\n" +#| "# Rectangle(Point, Point)\n" +#| "# }\n" +#| "# impl Shape {\n" +#| "# fn draw_borrowed(&self) { ... }\n" +#| "# fn draw_managed(@self) { ... }\n" +#| "# fn draw_owned(~self) { ... }\n" +#| "# fn draw_value(self) { ... }\n" +#| "# }\n" +#| "# let s = Circle(Point { x: 1f, y: 2f }, 3f);\n" +#| "// As with typical function arguments, managed and owned pointers\n" +#| "// are automatically converted to borrowed pointers\n" +msgid "" +"~~~\n" +"# fn draw_circle(p: Point, f: f64) { }\n" +"# fn draw_rectangle(p: Point, p: Point) { }\n" +"# struct Point { x: f64, y: f64 }\n" +"# enum Shape {\n" +"# Circle(Point, f64),\n" +"# Rectangle(Point, Point)\n" +"# }\n" +"# impl Shape {\n" +"# fn draw_reference(&self) { ... }\n" +"# fn draw_managed(@self) { ... }\n" +"# fn draw_owned(~self) { ... }\n" +"# fn draw_value(self) { ... }\n" +"# }\n" +"# let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0);\n" +"// As with typical function arguments, managed and owned pointers\n" +"// are automatically converted to references\n" +msgstr "" +"~~~\n" +"# fn draw_circle(p: Point, f: f64) { }\n" +"# fn draw_rectangle(p: Point, p: Point) { }\n" +"# struct Point { x: f64, y: f64 }\n" +"# enum Shape {\n" +"# Circle(Point, f64),\n" +"# Rectangle(Point, Point)\n" +"# }\n" +"# impl Shape {\n" +"# fn draw_borrowed(&self) { ... }\n" +"# fn draw_managed(@self) { ... }\n" +"# fn draw_owned(~self) { ... }\n" +"# fn draw_value(self) { ... }\n" +"# }\n" +"# let s = Circle(Point { x: 1f, y: 2f }, 3f);\n" +"// 関数の引数と同様、マネージドポインタと所有ポインタは、\n" +"// 自動的に借用ポインタに変換される\n" + +#. type: Plain text +#: doc/tutorial.md:1921 +#, fuzzy +#| msgid "(@s).draw_borrowed(); (~s).draw_borrowed();" +msgid "(@s).draw_reference(); (~s).draw_reference();" +msgstr "" +"(@s).draw_borrowed();\n" +"(~s).draw_borrowed();" + +#. type: Plain text +#: doc/tutorial.md:1925 +#, fuzzy +#| msgid "" +#| "// Unlike typical function arguments, the self value will // " +#| "automatically be referenced ... s.draw_borrowed();" +msgid "" +"// Unlike typical function arguments, the self value will // automatically " +"be referenced ... s.draw_reference();" +msgstr "" +"// 関数の引数とは異なり、 self の値は自動的にリファレンスされたり、 ...\n" +"s.draw_borrowed();" + +#. type: Plain text +#: doc/tutorial.md:1928 +#, fuzzy +#| msgid "// ... and dereferenced (& &s).draw_borrowed();" +msgid "// ... and dereferenced (& &s).draw_reference();" +msgstr "" +"// ... デリファレンスされたり、\n" +"(& &s).draw_borrowed();" + +#. type: Plain text +#: doc/tutorial.md:1932 +#, fuzzy +#| msgid "// ... and dereferenced and borrowed (&@~s).draw_borrowed(); ~~~" +msgid "// ... and dereferenced and borrowed (&@~s).draw_reference(); ~~~" +msgstr "" +"// ... デリファレンス後借用されたりします\n" +"(&@~s).draw_borrowed();\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:1936 +msgid "" +"Implementations may also define standalone (sometimes called \"static\") " +"methods. The absence of a `self` parameter distinguishes such methods. " +"These methods are the preferred way to define constructor functions." +msgstr "" +"実装では、スタンドアロンなメソッド (「静的 (static)」メソッドと呼ばれる場合も" +"あります)を定義することも可能です。引数に `self` をつけない場合、スタンドアロ" +"ンなメソッドとなります。コンストラクタ関数は、スタンドアロンなメソッドとして" +"定義することが推奨されています。" + +#. type: Plain text +#: doc/tutorial.md:1945 +msgid "" +"To call such a method, just prefix it with the type name and a double colon:" +msgstr "" +"メソッド名の前に型名と2つのコロンを付けることで、スタンドアロンメソッドは呼び" +"出せます。" + +#. type: Plain text +#: doc/tutorial.md:1956 +msgid "# Generics" +msgstr "# ジェネリクス" + +#. type: Plain text +#: doc/tutorial.md:1964 +msgid "" +"Throughout this tutorial, we've been defining functions that act only on " +"specific data types. With type parameters we can also define functions whose " +"arguments have generic types, and which can be invoked with a variety of " +"types. Consider a generic `map` function, which takes a function `function` " +"and a vector `vector` and returns a new vector consisting of the result of " +"applying `function` to each element of `vector`:" +msgstr "" +"このチュートリアルでは、特定のデータ型のみに対して動作する関数を定義してきま" +"した。型パラメータを用いるとジェネリックな型を引数にとり、様々な型で呼び出す" +"ことの可能な関数を定義できます。関数 `function` とベクタ `vector` を引数にと" +"り、`function` を`vector` の各要素に適用した結果からなる新たなベクタを返す、" +"`map` というジェネリック関数について考えます。" + +#. type: Plain text +#: doc/tutorial.md:1979 +msgid "" +"When defined with type parameters, as denoted by `<T, U>`, this function can " +"be applied to any type of vector, as long as the type of `function`'s " +"argument and the type of the vector's contents agree with each other." +msgstr "" +"上記例で `<T, U>` と示されているように、型パラメータとともに関数を定義するこ" +"とで、`function` の引数の型と`vectror` の要素の型が一致する場合に限りますが、" +"任意の型のベクタを引数として渡すことが可能になります。" + +#. type: Plain text +#: doc/tutorial.md:1989 +msgid "" +"Inside a generic function, the names of the type parameters (capitalized by " +"convention) stand for opaque types. All you can do with instances of these " +"types is pass them around: you can't apply any operations to them or pattern-" +"match on them. Note that instances of generic types are often passed by " +"pointer. For example, the parameter `function()` is supplied with a pointer " +"to a value of type `T` and not a value of type `T` itself. This ensures that " +"the function works with the broadest set of types possible, since some types " +"are expensive or illegal to copy and pass by value." +msgstr "" +"ジェネリック関数の内部では、型パラメータの名前 (慣例的に大文字で表されます) " +"は不透明型 (opaque type) を意味します。これらの型のインスタンスに対しては、他" +"の関数に渡すことだけが可能で、演算子を適用したり、パターンマッチすることはで" +"きません。ジェネリック型のインスタンスは、ポインタにより渡されることもあるこ" +"とに注意してください。例えば、 `function()` パラメータが `T` 型自身の値ではな" +"く `T` 型の値へのポインタとして渡されるということです。いくつかの型は、値をコ" +"ピーするコストが高かったり、コピーが禁じられていたりするので、ポインタ渡しに" +"することで、関数の引数としてとることのできる型の範囲が広がります。" + +#. type: Plain text +#: doc/tutorial.md:1991 +msgid "" +"Generic `type`, `struct`, and `enum` declarations follow the same pattern:" +msgstr "" +"ジェネリックな型、構造体、および列挙型の宣言は、同じパターンに従います。" + +#. type: Plain text +#: doc/tutorial.md:1995 +msgid "~~~~ use std::hashmap::HashMap; type Set<T> = HashMap<T, ()>;" +msgstr "" +"~~~~\n" +"use std::hashmap::HashMap;\n" +"type Set<T> = HashMap<T, ()>;" + +#. type: Plain text +#: doc/tutorial.md:2008 +msgid "" +"These declarations can be instantiated to valid types like `Set<int>`, " +"`Stack<int>`, and `Option<int>`." +msgstr "" +"これらの宣言により、 `Set<int>` や `Stack<int>`、 `Option<int>` のような正当" +"な型を生成することができます。" + +#. type: Plain text +#: doc/tutorial.md:2014 +msgid "" +"The last type in that example, `Option`, appears frequently in Rust code. " +"Because Rust does not have null pointers (except in unsafe code), we need " +"another way to write a function whose result isn't defined on every possible " +"combination of arguments of the appropriate types. The usual way is to write " +"a function that returns `Option<T>` instead of `T`." +msgstr "" +"最後の例の `Option` 型は、Rust のコード中に頻繁に現れます。Rust には null ポ" +"インタが存在しない (unsafe なコードを除く) ため、引数の組み合わせがとりうるす" +"べての値に対し結果が定義されないような関数を記述するための別の方法が必要で" +"す。このような場合には、 `T` 型ではなく `Option<T>` 型を返すよう関数を定義す" +"ることが一般的です。" + +#. type: Plain text +#: doc/tutorial.md:2033 +msgid "" +"The Rust compiler compiles generic functions very efficiently by " +"*monomorphizing* them. *Monomorphization* is a fancy name for a simple idea: " +"generate a separate copy of each generic function at each call site, a copy " +"that is specialized to the argument types and can thus be optimized " +"specifically for them. In this respect, Rust's generics have similar " +"performance characteristics to C++ templates." +msgstr "" +"Rust のコンパイラは、ジェネリック関数を *monomorphizing* することで効率的にコ" +"ンパイルします。*monomorphization* という名前は大げさに聞こえますが、考え方は" +"単純です。ジェネリック関数のコピーを関数の呼び出し箇所に別々に生成し、引数の" +"型により特殊化された各コピーは、それぞれの特性に応じて最適化が施されます。こ" +"の点において、Rust のジェネリクスは C++ のテンプレートと似たパフォーマンス上" +"の特性を持ちます。" + +#. type: Plain text +#: doc/tutorial.md:2035 +msgid "## Traits" +msgstr "## トレイト" + +#. type: Plain text +#: doc/tutorial.md:2047 +#, fuzzy +#| msgid "" +#| "Within a generic function the operations available on generic types are " +#| "very limited. After all, since the function doesn't know what types it is " +#| "operating on, it can't safely modify or query their values. This is where " +#| "_traits_ come into play. Traits are Rust's most powerful tool for writing " +#| "polymorphic code. Java developers will see them as similar to Java " +#| "interfaces, and Haskellers will notice their similarities to type " +#| "classes. Rust's traits are a form of *bounded polymorphism*: a trait is a " +#| "way of limiting the set of possible types that a type parameter could " +#| "refer to." +msgid "" +"Within a generic function -- that is, a function parameterized by a type " +"parameter, say, `T` -- the operations we can do on arguments of type `T` are " +"quite limited. After all, since we don't know what type `T` will be " +"instantiated with, we can't safely modify or query values of type `T`. This " +"is where _traits_ come into play. Traits are Rust's most powerful tool for " +"writing polymorphic code. Java developers will see them as similar to Java " +"interfaces, and Haskellers will notice their similarities to type classes. " +"Rust's traits give us a way to express *bounded polymorphism*: by limiting " +"the set of possible types that a type parameter could refer to, they expand " +"the number of operations we can safely perform on arguments of that type." +msgstr "" +"ジェネリック関数の内部では、ジェネリック型に対して非常に限られた操作しか行え" +"ません。つまるところ、ジェネリック関数は操作の対象とする型が何なのか知らない" +"ため、対象の値を安全に変更・参照することができません。__トレイト__ (_trait_) " +"の出番です。トレイトは Rust でポリモーフィックなコードを書くための最も強力な" +"ツールです。Java 開発者にとってトレイトは Java のインターフェースのように見え" +"ますし、Haskeller は型クラスとの類似点に気づくでしょう。Rust のトレイトは **" +"有界ポリモーフィズム** (*bounded polymorphism*) の形式をとります。トレイトに" +"より、型パラメータが示す得る型の集合を限定することができます。" + +#. type: Plain text +#: doc/tutorial.md:2054 +#, fuzzy +#| msgid "" +#| "As motivation, let us consider copying in Rust. The `clone` method is " +#| "not defined for all Rust types. One reason is user-defined destructors: " +#| "copying a type that has a destructor could result in the destructor " +#| "running multiple times. Therefore, types with destructors cannot be " +#| "copied unless you explicitly implement `Clone` for them." +msgid "" +"As motivation, let us consider copying of values in Rust. The `clone` " +"method is not defined for values of every type. One reason is user-defined " +"destructors: copying a value of a type that has a destructor could result in " +"the destructor running multiple times. Therefore, values of types that have " +"destructors cannot be copied unless we explicitly implement `clone` for them." +msgstr "" +"トレイト導入の動機となる例として、Rust でのコピーについて考えます。`clone` メ" +"ソッドはすべての Rust の型に対して定義されていません。定義されていない理由の" +"一つとして、ユーザ定義のデストラクタの存在が挙げられます。デストラクタを持つ" +"型をコピーすることで、デストラクタが複数回実行されるという事態を招いてしまう" +"かもしれません。そのため、明示的に `Clone` を実装していない型を除き、デストラ" +"クタをもつ型をコピーすることはできません。" + +#. type: Plain text +#: doc/tutorial.md:2060 +#, fuzzy +#| msgid "" +#| "This complicates handling of generic functions. If you have a type " +#| "parameter `T`, can you copy values of that type? In Rust, you can't, and " +#| "if you try to run the following code the compiler will complain." +msgid "" +"This complicates handling of generic functions. If we have a function with " +"a type parameter `T`, can we copy values of type `T` inside that function? " +"In Rust, we can't, and if we try to run the following code the compiler will " +"complain." +msgstr "" +"このことはジェネリック関数の扱い方を複雑にします。型パラメータ `T` が存在した" +"として、この型の値をコピーすることができるでしょうか？Rust では、コピーするこ" +"とはできません。以下のコードを実行しようとしてもコンパイラが文句を言うでしょ" +"う。" + +#. type: Plain text +#: doc/tutorial.md:2067 +#, no-wrap +msgid "" +"~~~~ {.ignore}\n" +"// This does not compile\n" +"fn head_bad<T>(v: &[T]) -> T {\n" +" v[0] // error: copying a non-copyable value\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// このコードはコンパイルできない\n" +"fn head_bad<T>(v: &[T]) -> T {\n" +" v[0] // error: copying a non-copyable value\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:2073 +#, fuzzy +#| msgid "" +#| "However, we can tell the compiler that the `head` function is only for " +#| "copyable types: that is, those that implement the `Clone` trait. In that " +#| "case, we can explicitly create a second copy of the value we are " +#| "returning using the `clone` keyword:" +msgid "" +"However, we can tell the compiler that the `head` function is only for " +"copyable types. In Rust, copyable types are those that _implement the " +"`Clone` trait_. We can then explicitly create a second copy of the value we " +"are returning by calling the `clone` method:" +msgstr "" +"`head` 関数はコピー可能な型、つまり `Clone` トレイトを実装している型だけを対" +"象にしていることをコンパイラに教えることはできます。この場合、`clone` メソッ" +"ドを使うことで、値のコピーを明示的に作成し、戻り値として返すことができます。" + +#. type: Plain text +#: doc/tutorial.md:2080 +#, no-wrap +msgid "" +"~~~~\n" +"// This does\n" +"fn head<T: Clone>(v: &[T]) -> T {\n" +" v[0].clone()\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~\n" +"// このコードはコンパイルできる\n" +"fn head<T: Clone>(v: &[T]) -> T {\n" +" v[0].clone()\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:2090 +#, fuzzy +#| msgid "" +#| "This says that we can call `head` on any type `T` as long as that type " +#| "implements the `Clone` trait. When instantiating a generic function, you " +#| "can only instantiate it with types that implement the correct trait, so " +#| "you could not apply `head` to a type that does not implement `Clone`." +msgid "" +"The bounded type parameter `T: Clone` says that `head` can be called on an " +"argument of type `&[T]` for any `T`, so long as there is an implementation " +"of the `Clone` trait for `T`. When instantiating a generic function, we can " +"only instantiate it with types that implement the correct trait, so we could " +"not apply `head` to a vector whose elements are of some type that does not " +"implement `Clone`." +msgstr "" +"このことは、`Clone` トレイトを実装している任意の型 `T` について、 `head` 関数" +"を呼び出すことができることを示しています。ジェネリック関数を実体化する場合、" +"正しいトレイトを実装した型を用いた場合のみ実体化できます。つまり、`Clone` ト" +"レイトを実装していない型に対して `head` を呼び出すことはできません。" + +#. type: Plain text +#: doc/tutorial.md:2095 +#, fuzzy +#| msgid "" +#| "While most traits can be defined and implemented by user code, two traits " +#| "are automatically derived and implemented for all applicable types by the " +#| "compiler, and may not be overridden:" +msgid "" +"While most traits can be defined and implemented by user code, three traits " +"are automatically derived and implemented for all applicable types by the " +"compiler, and may not be overridden:" +msgstr "" +"ほとんどのトレイトはユーザコードにより定義・実装できますが、2つのトレイトはコ" +"ンパイラにより自動的に導出され、適用可能なすべての型に対し自動的に実装され、" +"上書きすることはできません。" + +#. type: Plain text +#: doc/tutorial.md:2099 +#, fuzzy, no-wrap +#| msgid "" +#| "* `Send` - Sendable types.\n" +#| "Types are sendable\n" +#| "unless they contain managed boxes, managed closures, or borrowed pointers.\n" +msgid "" +"* `Send` - Sendable types.\n" +"Types are sendable\n" +"unless they contain managed boxes, managed closures, or references.\n" +msgstr "" +"* `Send` - 送信可能な型。\n" +"マネージドボックスやマネージドクロージャ、借用ポインタを含まない場合、型は送信可能である。" + +#. type: Plain text +#: doc/tutorial.md:2103 +#, fuzzy, no-wrap +#| msgid "" +#| "* `Freeze` - Constant (immutable) types.\n" +#| "These are types that do not contain anything intrinsically mutable.\n" +#| "Intrinsically mutable values include `@mut`\n" +#| "and `Cell` in the standard library.\n" +msgid "" +"* `Freeze` - Constant (immutable) types.\n" +"These are types that do not contain anything intrinsically mutable.\n" +"Intrinsically mutable values include `Cell` in the standard library.\n" +msgstr "" +"* `Freeze` - 定数 (イミュータブル) 型。\n" +"本質的に変更可能な値を含まない型のことです。本質的に変更可能な値には、`@mut` や標準ライブラリで定義されている `Cell` が含まれます。\n" + +#. type: Plain text +#: doc/tutorial.md:2112 +msgid "" +"> ***Note:*** These two traits were referred to as 'kinds' in earlier > " +"iterations of the language, and often still are." +msgstr "" +"> ***注意*** これら2つのトレイトは、以前は 「種」 (kind) と呼ばれており、現在" +"でもそう呼ばれる場合があります。" + +#. type: Plain text +#: doc/tutorial.md:2118 +#, fuzzy +#| msgid "" +#| "Additionally, the `Drop` trait is used to define destructors. This trait " +#| "defines one method called `drop`, which is automatically called when a " +#| "value of the type that implements this trait is destroyed, either because " +#| "the value went out of scope or because the garbage collector reclaimed it." +msgid "" +"Additionally, the `Drop` trait is used to define destructors. This trait " +"provides one method called `drop`, which is automatically called when a " +"value of the type that implements this trait is destroyed, either because " +"the value went out of scope or because the garbage collector reclaimed it." +msgstr "" +"上記に加え、 `Drop` トレイトはデストラクタを定義するために使われます。このト" +"レイトは `drop` というこのトレイトを実装した型が破壊されるタイミング(値がス" +"コープの外に出たタイミングか、ガベージコレクタが回収するタイミング) で呼び出" +"されるメソッドを1つ定義しています。" + +#. type: Plain text +#: doc/tutorial.md:2135 +msgid "" +"It is illegal to call `drop` directly. Only code inserted by the compiler " +"may call it." +msgstr "" +"`drop` を直接呼び出すことはできません。コンパイラにより挿入されたコードのみ" +"が `drop` を呼び出すことができます。" + +#. type: Plain text +#: doc/tutorial.md:2137 +msgid "## Declaring and implementing traits" +msgstr "## トレイトの宣言と実装" + +#. type: Plain text +#: doc/tutorial.md:2142 +#, fuzzy +#| msgid "" +#| "A trait consists of a set of methods without bodies, or may be empty, as " +#| "is the case with `Send` and `Freeze`. For example, we could declare the " +#| "trait `Printable` for things that can be printed to the console, with a " +#| "single method:" +msgid "" +"At its simplest, a trait is a set of zero or more _method signatures_. For " +"example, we could declare the trait `Printable` for things that can be " +"printed to the console, with a single method signature:" +msgstr "" +"トレイトはボディを持たないメソッドの集合から構成されるか、 `Send` や " +"`Freeze` トレイトのように空の場合があります。例えば、コンソールに出力可能なも" +"のを表しメソッドを1つもつ `Printable` トレイトは以下のように宣言できます。" + +#. type: Plain text +#: doc/tutorial.md:2148 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"~~~~\n" +"trait Printable {\n" +" fn print(&self);\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2161 +#, fuzzy +#| msgid "" +#| "Traits may be implemented for specific types with [impls]. An impl that " +#| "implements a trait includes the name of the trait at the start of the " +#| "definition, as in the following impls of `Printable` for `int` and `~str`." +msgid "" +"Traits may be implemented for specific types with [impls]. An impl for a " +"particular trait gives an implementation of the methods that trait " +"provides. For instance, the following impls of `Printable` for `int` and " +"`~str` give implementations of the `print` method." +msgstr "" +"[impl][impls] により特定の型にトレイトを実装することができます。トレイトを実" +"装する impl は、以下の `Printable` の `int` と `~str` に対する実装のように、" +"定義の先頭にトレイトの名前を含みます。" + +#. type: Plain text +#: doc/tutorial.md:2163 +msgid "[impls]: #methods" +msgstr "[impls]: #メソッド" + +#. type: Plain text +#: doc/tutorial.md:2177 +msgid "# 1.print(); # (~\"foo\").print(); ~~~~" +msgstr "" +"# 1.print();\n" +"# (~\"foo\").print();\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2180 +#, fuzzy +#| msgid "" +#| "Methods defined in an implementation of a trait may be called just like " +#| "any other method, using dot notation, as in `1.print()`. Traits may " +#| "themselves contain type parameters. A trait for generalized sequence " +#| "types might look like the following:" +msgid "" +"Methods defined in an impl for a trait may be called just like any other " +"method, using dot notation, as in `1.print()`." +msgstr "" +"トレイトの実装により定義されたメソッドは他のメソッドと全く同じように、ドット" +"記法を用いて `1.print()` のように呼び出せます。トレイト自体に型パラメータを持" +"たせることもできます。一般化されたシーケンスを表すトレイトは以下のように定義" +"されるでしょう。" + +#. type: Plain text +#: doc/tutorial.md:2182 +#, fuzzy +#| msgid "## Deriving implementations for traits" +msgid "## Default method implementations in trait definitions" +msgstr "## トレイトの実装の導出" + +#. type: Plain text +#: doc/tutorial.md:2202 +#, fuzzy +#| msgid "# 1.print(); # (~\"foo\").print(); ~~~~" +msgid "# true.print(); # 3.14159.print(); ~~~~" +msgstr "" +"# 1.print();\n" +"# (~\"foo\").print();\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2229 +#, fuzzy +#| msgid "# 1.print(); # (~\"foo\").print(); ~~~~" +msgid "" +"# 1.print(); # (~\"foo\").print(); # true.print(); # 3.14159.print(); ~~~~" +msgstr "" +"# 1.print();\n" +"# (~\"foo\").print();\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2260 +msgid "" +"The implementation has to explicitly declare the type parameter that it " +"binds, `T`, before using it to specify its trait type. Rust requires this " +"declaration because the `impl` could also, for example, specify an " +"implementation of `Seq<int>`. The trait type (appearing between `impl` and " +"`for`) *refers* to a type, rather than defining one." +msgstr "" +"実装が束縛する型パラメータ `T` は、トレイトの型を指定する前に明示的に宣言しな" +"ければなりません。Rust でこの宣言が必要なのは、 `impl` では例えば `Seq<int>` " +"の実装を指定することも可能だからです。トレイトの型 (`impl` と `for` の間に現" +"れるもの) は、型を定義するのではなく、型を **参照** します。" + +#. type: Plain text +#: doc/tutorial.md:2265 +msgid "" +"The type parameters bound by a trait are in scope in each of the method " +"declarations. So, re-declaring the type parameter `T` as an explicit type " +"parameter for `len`, in either the trait or the impl, would be a compile-" +"time error." +msgstr "" +"トレイトにより束縛される型パラメータは、各メソッドの宣言のスコープに属しま" +"す。したがって、trait と impl のいずれかで、型パラメータ `T` を `len` で用い" +"る明示的な型パラメータとして再宣言すると、コンパイル時エラーとなります。" + +#. type: Plain text +#: doc/tutorial.md:2270 +msgid "" +"Within a trait definition, `Self` is a special type that you can think of as " +"a type parameter. An implementation of the trait for any given type `T` " +"replaces the `Self` type parameter with `T`. The following trait describes " +"types that support an equality operation:" +msgstr "" +"トレイトの定義内部では、`Self` は型パラメータとみなすことのできる特別な型とな" +"ります。型 `T` に対するトレイトの実装では `Self` は型パラメータ `T` で置き換" +"えられます。以下のトレイトは等価性演算をサポートする型を意味します。" + +#. type: Plain text +#: doc/tutorial.md:2277 +#, no-wrap +msgid "" +"~~~~\n" +"// In a trait, `self` refers to the self argument.\n" +"// `Self` refers to the type implementing the trait.\n" +"trait Eq {\n" +" fn equals(&self, other: &Self) -> bool;\n" +"}\n" +msgstr "" +"~~~~\n" +"// trait の内側では, `self` は self 引数を指します。\n" +"// `Self` はトレイトを実装する型を指します。\n" +"trait Eq {\n" +" fn equals(&self, other: &Self) -> bool;\n" +"}\n" + +#. type: Plain text +#: doc/tutorial.md:2283 +#, no-wrap +msgid "" +"// In an impl, `self` refers just to the value of the receiver\n" +"impl Eq for int {\n" +" fn equals(&self, other: &int) -> bool { *other == *self }\n" +"}\n" +"~~~~\n" +msgstr "" +"// impl の内側では `self` はレシーバの値を指します\n" +"impl Eq for int {\n" +" fn equals(&self, other: &int) -> bool { *other == *self }\n" +"}\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:2288 +msgid "" +"Notice that in the trait definition, `equals` takes a second parameter of " +"type `Self`. In contrast, in the `impl`, `equals` takes a second parameter " +"of type `int`, only using `self` as the name of the receiver." +msgstr "" +"トレイトの定義では、`equals` の第二引数の型は `Self` であることに注意してくだ" +"さい。対照的に `impl` では、 `equals` の第二引数の型は `int` で、 `self` はレ" +"シーバの名前としてのみ使用されます。" + +#. type: Plain text +#: doc/tutorial.md:2293 +msgid "" +"Just as in type implementations, traits can define standalone (static) " +"methods. These methods are called by prefixing the method name with the " +"trait name and a double colon. The compiler uses type inference to decide " +"which implementation to use." +msgstr "" +"型への実装の場合と同様、トレイトもスタンドアロン (静的) メソッドを定義するこ" +"とができます。メソッド名の前にトレイト名とコロン2つをつけることで、これらのメ" +"ソッドを呼び出すことができます。コンパイラはどの実装を利用するか決定するた" +"め、型推論を行います。" + +#. type: Plain text +#: doc/tutorial.md:2299 +#, fuzzy +#| msgid "" +#| "~~~~ use std::f64::consts::pi; trait Shape { fn new(area: f64) -> Self; } " +#| "struct Circle { radius: f64 } struct Square { length: f64 }" +msgid "" +"~~~~ use std::f64::consts::PI; trait Shape { fn new(area: f64) -> Self; } " +"struct Circle { radius: f64 } struct Square { length: f64 }" +msgstr "" +"~~~~\n" +"use std::f64::consts::pi;\n" +"trait Shape { fn new(area: f64) -> Self; }\n" +"struct Circle { radius: f64 }\n" +"struct Square { length: f64 }" + +#. type: Plain text +#: doc/tutorial.md:2311 +msgid "" +"let area = 42.5; let c: Circle = Shape::new(area); let s: Square = Shape::" +"new(area); ~~~~" +msgstr "" +"let area = 42.5;\n" +"let c: Circle = Shape::new(area);\n" +"let s: Square = Shape::new(area);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2313 +msgid "## Bounded type parameters and static method dispatch" +msgstr "## 境界型パラメータと静的メソッドディスパッチ" + +#. type: Plain text +#: doc/tutorial.md:2318 +msgid "" +"Traits give us a language for defining predicates on types, or abstract " +"properties that types can have. We can use this language to define _bounds_ " +"on type parameters, so that we can then operate on generic types." +msgstr "" +"トレイトは型の述語 (predicate) や型がもつことのできる抽象的な属性を定義するた" +"めの言語として利用することができます。この言語を使うこととで型パラメータの __" +"境界__ (_bound_) を定義することができ、ジェネリックな型を操作することが可能に" +"なります。" + +#. type: Plain text +#: doc/tutorial.md:2333 +msgid "" +"Declaring `T` as conforming to the `Printable` trait (as we earlier did with " +"`Clone`) makes it possible to call methods from that trait on values of type " +"`T` inside the function. It will also cause a compile-time error when anyone " +"tries to call `print_all` on an array whose element type does not have a " +"`Printable` implementation." +msgstr "" +"(先に登場した `Clone` の例のように) `T` が `Printable` トレイトに従うことを宣" +"言することで、関数内部で `T` 型の値に対して `Printable` トレイトのメソッドを" +"呼び出すことが可能になります。また、この宣言により、`Printable` を実装してい" +"ない型を要素とする配列に対して `print_all` 関数を呼びだそうとすると、コンパイ" +"ル時エラーとなります。" + +#. type: Plain text +#: doc/tutorial.md:2336 +msgid "" +"Type parameters can have multiple bounds by separating them with `+`, as in " +"this version of `print_all` that copies elements." +msgstr "" +"型パラメータは `+` で区切ることで複数の境界を持つことができます。以下の " +"`print_all` は、ベクタの要素をコピーするバージョンです。" + +#. type: Plain text +#: doc/tutorial.md:2352 +msgid "" +"Method calls to bounded type parameters are _statically dispatched_, " +"imposing no more overhead than normal function invocation, so are the " +"preferred way to use traits polymorphically." +msgstr "" +"境界型パラメータに対するメソッドの呼び出しは __静的にディスパッチ__ " +"(_statically dispatched_) されるため、通常の関数呼び出し以上のオーバーヘッド" +"は発生しません。そのため、ポリモーフィックにトレイトを使う方法としては、境界" +"型パラメータが推奨されます。 " + +#. type: Plain text +#: doc/tutorial.md:2354 +msgid "This usage of traits is similar to Haskell type classes." +msgstr "トレイトのこのような使い方は、Haskell の型クラスと似ています。" + +#. type: Plain text +#: doc/tutorial.md:2356 +msgid "## Trait objects and dynamic method dispatch" +msgstr "## トレイトオブジェクトと動的メソッドディスパッチ" + +#. type: Plain text +#: doc/tutorial.md:2360 +msgid "" +"The above allows us to define functions that polymorphically act on values " +"of a single unknown type that conforms to a given trait. However, consider " +"this function:" +msgstr "" +"上述の例では、指定されたトレイトに従う、単一の未知の型の値についてポリモー" +"フィックにふるまう関数を定義しました。ここでは、以下の関数について考えます。" + +#. type: Plain text +#: doc/tutorial.md:2366 +msgid "" +"~~~~ # type Circle = int; type Rectangle = int; # impl Drawable for int { fn " +"draw(&self) {} } # fn new_circle() -> int { 1 } trait Drawable { fn " +"draw(&self); }" +msgstr "" +"~~~~\n" +"# type Circle = int; type Rectangle = int;\n" +"# impl Drawable for int { fn draw(&self) {} }\n" +"# fn new_circle() -> int { 1 }\n" +"trait Drawable { fn draw(&self); }" + +#. type: Plain text +#: doc/tutorial.md:2379 +msgid "" +"You can call that on an array of circles, or an array of rectangles " +"(assuming those have suitable `Drawable` traits defined), but not on an " +"array containing both circles and rectangles. When such behavior is needed, " +"a trait name can alternately be used as a type, called an _object_." +msgstr "" +"円の配列や長方形の配列に対してこの関数を呼び出すことは (円や長方形に対し適切" +"に `Drawable` トレイトが定義されていると仮定すれば) 可能ですが、円や長方形を" +"両方共含む配列に対しては呼び出すことができません。そのような動作が必要な場" +"合、__オブジェクト__ 型として、トレイトの名前を代わりに利用することができま" +"す。" + +#. type: Plain text +#: doc/tutorial.md:2391 +msgid "" +"In this example, there is no type parameter. Instead, the `@Drawable` type " +"denotes any managed box value that implements the `Drawable` trait. To " +"construct such a value, you use the `as` operator to cast a value to an " +"object:" +msgstr "" +"この例中には、型パラメータはありません。代わりに、「`Drawable` トレイトを実装" +"した、任意のマネージドボックス値」を表す型 `@Drawable` 型があります。このよ" +"うな値を作成するには、 `as` 演算子を使って値をオブジェクトへキャストします。" + +#. type: Plain text +#: doc/tutorial.md:2398 +msgid "" +"~~~~ # type Circle = int; type Rectangle = bool; # trait Drawable { fn " +"draw(&self); } # fn new_circle() -> Circle { 1 } # fn new_rectangle() -> " +"Rectangle { true } # fn draw_all(shapes: &[@Drawable]) {}" +msgstr "" +"~~~~\n" +"# type Circle = int; type Rectangle = bool;\n" +"# trait Drawable { fn draw(&self); }\n" +"# fn new_circle() -> Circle { 1 }\n" +"# fn new_rectangle() -> Rectangle { true }\n" +"# fn draw_all(shapes: &[@Drawable]) {}" + +#. type: Plain text +#: doc/tutorial.md:2401 +msgid "" +"impl Drawable for Circle { fn draw(&self) { ... } } impl Drawable for " +"Rectangle { fn draw(&self) { ... } }" +msgstr "" +"impl Drawable for Circle { fn draw(&self) { ... } }\n" +"impl Drawable for Rectangle { fn draw(&self) { ... } }" + +#. type: Plain text +#: doc/tutorial.md:2406 +msgid "" +"let c: @Circle = @new_circle(); let r: @Rectangle = @new_rectangle(); " +"draw_all([c as @Drawable, r as @Drawable]); ~~~~" +msgstr "" +"let c: @Circle = @new_circle();\n" +"let r: @Rectangle = @new_rectangle();\n" +"draw_all([c as @Drawable, r as @Drawable]);\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2414 +msgid "" +"We omit the code for `new_circle` and `new_rectangle`; imagine that these " +"just return `Circle`s and `Rectangle`s with a default size. Note that, like " +"strings and vectors, objects have dynamic size and may only be referred to " +"via one of the pointer types. Other pointer types work as well. Casts to " +"traits may only be done with compatible pointers so, for example, an " +"`@Circle` may not be cast to an `~Drawable`." +msgstr "" +"`new_circle` と `new_rectangle` のコードは省略されていますが、デフォルトのサ" +"イズをもつ `Circle` と `Rectangle` をただ返すものだと考えてください。文字列や" +"ベクタのように、オブジェクトも動的なサイズを持ち、いずれかのポインタ型を経由" +"してしか参照できないことに注意してください。他のポインタ型でもうまく動作しま" +"す。トレイトへのキャストは互換性のあるポインタの場合しか行えません。例えば、" +"`@Cicle` を `~Drawable` にキャストすることはできません。" + +#. type: Plain text +#: doc/tutorial.md:2428 +msgid "" +"~~~ # type Circle = int; type Rectangle = int; # trait Drawable { fn " +"draw(&self); } # impl Drawable for int { fn draw(&self) {} } # fn " +"new_circle() -> int { 1 } # fn new_rectangle() -> int { 2 } // A managed " +"object let boxy: @Drawable = @new_circle() as @Drawable; // An owned object " +"let owny: ~Drawable = ~new_circle() as ~Drawable; // A borrowed object let " +"stacky: &Drawable = &new_circle() as &Drawable; ~~~" +msgstr "" +"~~~\n" +"# type Circle = int; type Rectangle = int;\n" +"# trait Drawable { fn draw(&self); }\n" +"# impl Drawable for int { fn draw(&self) {} }\n" +"# fn new_circle() -> int { 1 }\n" +"# fn new_rectangle() -> int { 2 }\n" +"// A managed object\n" +"let boxy: @Drawable = @new_circle() as @Drawable;\n" +"// An owned object\n" +"let owny: ~Drawable = ~new_circle() as ~Drawable;\n" +"// A borrowed object\n" +"let stacky: &Drawable = &new_circle() as &Drawable;\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:2433 +msgid "" +"Method calls to trait types are _dynamically dispatched_. Since the compiler " +"doesn't know specifically which functions to call at compile time, it uses a " +"lookup table (also known as a vtable or dictionary) to select the method to " +"call at runtime." +msgstr "" +"トレイト型のメソッド呼び出しは __動的にディスパッチ__ (_dynamically " +"dispatched_) されます。どの関数を呼び出すべきかコンパイル時にはわからないた" +"め、ルックアップテーブル (vtable や dictionary としても知られている) を用い" +"て、呼び出すメソッドの選択を実行時に行います。" + +#. type: Plain text +#: doc/tutorial.md:2435 +msgid "This usage of traits is similar to Java interfaces." +msgstr "トレイトのこのような使い方は、Java のインターフェースと似ています。" + +#. type: Plain text +#: doc/tutorial.md:2461 +msgid "## Trait inheritance" +msgstr "## トレイトの継承" + +#. type: Plain text +#: doc/tutorial.md:2466 +msgid "" +"We can write a trait declaration that _inherits_ from other traits, called " +"_supertraits_. Types that implement a trait must also implement its " +"supertraits. For example, we can define a `Circle` trait that inherits from " +"`Shape`." +msgstr "" +"__スーパートレイト__ と呼ばれる他のトレイトから __継承した__ トレイトを宣言す" +"ることができます。継承されたトレイトを実装する型は、スーパートレイトも実装し" +"なければなりません。例えば、 `Circle` トレイトを `Shape` トレイトを継承したも" +"のとして定義できます。" + +#. type: Plain text +#: doc/tutorial.md:2471 +msgid "" +"~~~~ trait Shape { fn area(&self) -> f64; } trait Circle : Shape { fn " +"radius(&self) -> f64; } ~~~~" +msgstr "" +"~~~~\n" +"trait Shape { fn area(&self) -> f64; }\n" +"trait Circle : Shape { fn radius(&self) -> f64; }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2473 +msgid "" +"Now, we can implement `Circle` on a type only if we also implement `Shape`." +msgstr "`Circle` トレイトの実装は、 `Shape` を実装した型についてのみ行えます。" + +#. type: Plain text +#: doc/tutorial.md:2488 +#, fuzzy, no-wrap +#| msgid "~~~ {.ignore} use std::f64::consts::pi; # trait Shape { fn area(&self) -> f64; } # trait Circle : Shape { fn radius(&self) -> f64; } # struct Point { x: f64, y: f64 } # struct CircleStruct { center: Point, radius: f64 } # impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / pi).sqrt() } } # impl Shape for CircleStruct { fn area(&self) -> f64 { pi * square(self.radius) } }" +msgid "" +"~~~~\n" +"use std::f64::consts::PI;\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"# struct Point { x: f64, y: f64 }\n" +"# fn square(x: f64) -> f64 { x * x }\n" +"struct CircleStruct { center: Point, radius: f64 }\n" +"impl Circle for CircleStruct {\n" +" fn radius(&self) -> f64 { (self.area() / PI).sqrt() }\n" +"}\n" +"impl Shape for CircleStruct {\n" +" fn area(&self) -> f64 { PI * square(self.radius) }\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~ {.ignore}\n" +"use std::f64::consts::pi;\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"# struct Point { x: f64, y: f64 }\n" +"# struct CircleStruct { center: Point, radius: f64 }\n" +"# impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / pi).sqrt() } }\n" +"# impl Shape for CircleStruct { fn area(&self) -> f64 { pi * square(self.radius) } }" + +#. type: Plain text +#: doc/tutorial.md:2493 +msgid "" +"Notice that methods of `Circle` can call methods on `Shape`, as our `radius` " +"implementation calls the `area` method. This is a silly way to compute the " +"radius of a circle (since we could just return the `radius` field), but you " +"get the idea." +msgstr "" +"`radius` の実装から `area` メソッドを呼び出せるように、`Circle` のメソッドは " +"`Shape` のメソッドを呼び出せることに注意してください。(単純に `radius` フィー" +"ルドの値を返すことができるにも関わらず) 円の半径を面積から計算するのは馬鹿げ" +"ていますが、メソッド呼び出しの考え方は分かったでしょう。" + +#. type: Plain text +#: doc/tutorial.md:2497 +msgid "" +"In type-parameterized functions, methods of the supertrait may be called on " +"values of subtrait-bound type parameters. Refering to the previous example " +"of `trait Circle : Shape`:" +msgstr "" +"型パラメータを持つ関数では、サブトレイトの境界型パラメータの値によりスーパー" +"トレイトのメソッドを呼び出すことになります。前の例の `trait Circle : Shape` " +"を参照してください。" + +#. type: Plain text +#: doc/tutorial.md:2506 +#, no-wrap +msgid "" +"~~~\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"fn radius_times_area<T: Circle>(c: T) -> f64 {\n" +" // `c` is both a Circle and a Shape\n" +" c.radius() * c.area()\n" +"}\n" +"~~~\n" +msgstr "" +"~~~\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"fn radius_times_area<T: Circle>(c: T) -> f64 {\n" +" // `c` は Circle でもあり、Shape でもある\n" +" c.radius() * c.area()\n" +"}\n" +"~~~\n" + +#. type: Plain text +#: doc/tutorial.md:2517 +#, fuzzy +#| msgid "" +#| "~~~ {.ignore} use std::f64::consts::pi; # trait Shape { fn " +#| "area(&self) -> f64; } # trait Circle : Shape { fn radius(&self) -> f64; } " +#| "# struct Point { x: f64, y: f64 } # struct CircleStruct { center: Point, " +#| "radius: f64 } # impl Circle for CircleStruct { fn radius(&self) -> f64 " +#| "{ (self.area() / pi).sqrt() } } # impl Shape for CircleStruct { fn " +#| "area(&self) -> f64 { pi * square(self.radius) } }" +msgid "" +"~~~ {.ignore} use std::f64::consts::PI; # trait Shape { fn area(&self) -" +"> f64; } # trait Circle : Shape { fn radius(&self) -> f64; } # struct Point " +"{ x: f64, y: f64 } # struct CircleStruct { center: Point, radius: f64 } # " +"impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / PI)." +"sqrt() } } # impl Shape for CircleStruct { fn area(&self) -> f64 { PI * " +"square(self.radius) } }" +msgstr "" +"~~~ {.ignore}\n" +"use std::f64::consts::pi;\n" +"# trait Shape { fn area(&self) -> f64; }\n" +"# trait Circle : Shape { fn radius(&self) -> f64; }\n" +"# struct Point { x: f64, y: f64 }\n" +"# struct CircleStruct { center: Point, radius: f64 }\n" +"# impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / " +"pi).sqrt() } }\n" +"# impl Shape for CircleStruct { fn area(&self) -> f64 { pi * square(self." +"radius) } }" + +#. type: Plain text +#: doc/tutorial.md:2522 +msgid "" +"let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f}; let " +"mycircle: @Circle = concrete as @Circle; let nonsense = mycircle.radius() * " +"mycircle.area(); ~~~" +msgstr "" +"let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f};\n" +"let mycircle: @Circle = concrete as @Circle;\n" +"let nonsense = mycircle.radius() * mycircle.area();\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:2524 +msgid "> ***Note:*** Trait inheritance does not actually work with objects yet" +msgstr "" +"> ***注意*** トレイトの継承は、実際にはまだオブジェクトに対しては動作しませ" +"ん。" + +#. type: Plain text +#: doc/tutorial.md:2526 +msgid "## Deriving implementations for traits" +msgstr "## トレイトの実装の導出" + +#. type: Plain text +#: doc/tutorial.md:2533 +msgid "" +"A small number of traits in `std` and `extra` can have implementations that " +"can be automatically derived. These instances are specified by placing the " +"`deriving` attribute on a data type declaration. For example, the following " +"will mean that `Circle` has an implementation for `Eq` and can be used with " +"the equality operators, and that a value of type `ABC` can be randomly " +"generated and converted to a string:" +msgstr "" +"`std` と `extra` で定義されているいくつかのトレイトは、自動的に実装を導出可能" +"です。データ型の宣言時に `deriving` 属性を書くことで、これらのトレイトを実装" +"することを指定します。例えば、以下の例では `Circle` は `Eq` を実装し等価演算" +"子で比較することが可能であり、`ABC` 型の値はランダムに生成することや、文字列" +"に変換することが可能です。" + +#. type: Plain text +#: doc/tutorial.md:2537 +msgid "~~~ #[deriving(Eq)] struct Circle { radius: f64 }" +msgstr "" +"~~~\n" +"#[deriving(Eq)]\n" +"struct Circle { radius: f64 }" + +#. type: Plain text +#: doc/tutorial.md:2541 +msgid "#[deriving(Rand, ToStr)] enum ABC { A, B, C } ~~~" +msgstr "" +"#[deriving(Rand, ToStr)]\n" +"enum ABC { A, B, C }\n" +"~~~" + +#. type: Plain text +#: doc/tutorial.md:2545 +#, fuzzy +#| msgid "" +#| "The full list of derivable traits is `Eq`, `TotalEq`, `Ord`, `TotalOrd`, " +#| "`Encodable` `Decodable`, `Clone`, `DeepClone`, `IterBytes`, `Rand`, " +#| "`Zero`, and `ToStr`." +msgid "" +"The full list of derivable traits is `Eq`, `TotalEq`, `Ord`, `TotalOrd`, " +"`Encodable` `Decodable`, `Clone`, `DeepClone`, `IterBytes`, `Rand`, " +"`Default`, `Zero`, and `ToStr`." +msgstr "" +"実装を自動的に導出可能なトレイトは、 `Eq`, `TotalEq`, `Ord`, `TotalOrd`, " +"`Encodable` `Decodable`, `Clone`, `DeepClone`, `IterBytes`, `Rand`, `Zero`, " +"および `ToStr` です。." + +#. type: Plain text +#: doc/tutorial.md:2547 +#, fuzzy +#| msgid "# Modules and crates" +msgid "# Crates and the module system" +msgstr "# モジュールとクレート" + +#. type: Plain text +#: doc/tutorial.md:2552 +msgid "## Crates" +msgstr "## クレート" + +#. type: Plain text +#: doc/tutorial.md:2567 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"~~~~\n" +"// main.rs\n" +"fn main() {\n" +" println!(\"Hello world!\");\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2570 +#, fuzzy +#| msgid "" +#| "The unit of independent compilation in Rust is the crate: rustc compiles " +#| "a single crate at a time, from which it produces either a library or an " +#| "executable." +msgid "" +"A crate is also the unit of independent compilation in Rust: `rustc` always " +"compiles a single crate at a time, from which it produces either a library " +"or an executable." +msgstr "" +"Rust の独立コンパイルの単位はクレートです。rustc は1度に1つのクレートをコンパ" +"イルし、ライブラリか実行可能ファイルを生成します。" + +#. type: Plain text +#: doc/tutorial.md:2574 +#, fuzzy +#| msgid "## The standard library" +msgid "## The module hierarchy" +msgstr "## 標準ライブラリ" + +#. type: Plain text +#: doc/tutorial.md:2600 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"fn main() {\n" +" println!(\"Hello farm!\");\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2608 +#, fuzzy +#| msgid "## Managed closures" +msgid "## Paths and visibility" +msgstr "## マネージドクロージャ" + +#. type: Plain text +#: doc/tutorial.md:2620 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"fn main() {\n" +" println!(\"Hello chicken!\");\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2659 +#, fuzzy +#| msgid "" +#| "Visibility restrictions in Rust exist only at module boundaries. This is " +#| "quite different from most object-oriented languages that also enforce " +#| "restrictions on objects themselves. That's not to say that Rust doesn't " +#| "support encapsulation: both struct fields and methods can be private. But " +#| "this encapsulation is at the module level, not the struct level. Note " +#| "that fields and methods are _public_ by default." +msgid "" +"Visibility restrictions in Rust exist only at module boundaries. This is " +"quite different from most object-oriented languages that also enforce " +"restrictions on objects themselves. That's not to say that Rust doesn't " +"support encapsulation: both struct fields and methods can be private. But " +"this encapsulation is at the module level, not the struct level." +msgstr "" +"Rust での可視性の制約はモジュールの境界にのみ存在します。これは、オブジェクト" +"自体にも可視性の制約を課すほとんどのオブジェクト指向言語とは全く異なっていま" +"す。しかし、Rust がカプセル化をサポートしていないというわけではありません。構" +"造体のフィールドとメソッドはプライベートにすることができます。しかし、このカ" +"プセル化はモジュールレベルで働くもので、構造体のレベルで働くものではありませ" +"ん。フィールドとメソッドでは、デフォルトでは __パブリック__ であることに注意" +"してください。" + +#. type: Plain text +#: doc/tutorial.md:2702 +#, fuzzy +#| msgid "# Modules and crates" +msgid "## Files and modules" +msgstr "# モジュールとクレート" + +#. type: Plain text +#: doc/tutorial.md:2732 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"fn main() {\n" +" println!(\"Hello farm!\");\n" +" ::farm::cow();\n" +"}\n" +"~~~~\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:2791 +#, fuzzy +#| msgid "~~~~ {.ignore} let foo = 10;" +msgid "~~~ {.ignore} // src/main.rs mod plants; mod animals; ~~~" +msgstr "" +"~~~~ {.ignore}\n" +"let foo = 10;" + +#. type: Plain text +#: doc/tutorial.md:2929 +#, fuzzy, no-wrap +#| msgid "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~\"hello \" + world::explore()); } ~~~~" +msgid "" +"fn main() {\n" +" println!(\"Hello farm!\");\n" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:3004 +#, fuzzy +#| msgid "# Dereferencing pointers" +msgid "## Reexporting names" +msgstr "# ポインタのデリファレンス" + +#. type: Plain text +#: doc/tutorial.md:3039 +#, fuzzy +#| msgid "## Using other crates" +msgid "## Using libraries" +msgstr "## 他のクレートの利用" + +#. type: Plain text +#: doc/tutorial.md:3080 +#, fuzzy +#| msgid "~~~~ {.ignore} let foo = 10;" +msgid "~~~ extern mod extra;" +msgstr "" +"~~~~ {.ignore}\n" +"let foo = 10;" + +#. type: Plain text +#: doc/tutorial.md:3144 +#, fuzzy +#| msgid "" +#| "~~~~ {.ignore} extern mod farm; extern mod my_farm (name = \"farm\", " +#| "vers = \"2.5\"); extern mod my_auxiliary_farm (name = \"farm\", author = " +#| "\"mjh\"); ~~~~" +msgid "" +"~~~~ {.ignore} extern mod farm; extern mod farm = \"farm#2.5\"; extern " +"mod my_farm = \"farm\"; ~~~~" +msgstr "" +"~~~~ {.ignore}\n" +"extern mod farm;\n" +"extern mod my_farm (name = \"farm\", vers = \"2.5\");\n" +"extern mod my_auxiliary_farm (name = \"farm\", author = \"mjh\");\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:3155 +#, fuzzy +#| msgid "// Make a library (\"bin\" is the default) #[crate_type = \"lib\"];" +msgid "" +"// This crate is a library (\"bin\" is the default) #[crate_id = " +"\"farm#2.5\"]; #[crate_type = \"lib\"];" +msgstr "" +"// ライブラリを作成する (\"bin\" がデフォルト値)\n" +"#[crate_type = \"lib\"];" + +#. type: Plain text +#: doc/tutorial.md:3160 +#, fuzzy +#| msgid "// Turn on a warning #[warn(non_camel_case_types)]" +msgid "// Turn on a warning #[warn(non_camel_case_types)] # fn farm() {} ~~~~" +msgstr "" +"// 警告を有効にする\n" +"#[warn(non_camel_case_types)]" + +#. type: Plain text +#: doc/tutorial.md:3167 +msgid "## A minimal example" +msgstr "## 最小限の例" + +#. type: Plain text +#: doc/tutorial.md:3169 +#, fuzzy +#| msgid "" +#| "Now for something that you can actually compile yourself, we have these " +#| "two files:" +msgid "Now for something that you can actually compile yourself." +msgstr "" +"あなた自身で実際にコンパイルが行える例として、以下の2つのファイルを例示しま" +"す。" + +#. type: Plain text +#: doc/tutorial.md:3179 +#, fuzzy +#| msgid "" +#| "~~~~ // world.rs #[link(name = \"world\", vers = \"1.0\")]; pub fn " +#| "explore() -> &str { \"world\" } ~~~~" +msgid "" +"~~~~ // world.rs #[crate_id = \"world#0.42\"]; # extern mod extra; pub fn " +"explore() -> &'static str { \"world\" } # fn main() {} ~~~~" +msgstr "" +"~~~~\n" +"// world.rs\n" +"#[link(name = \"world\", vers = \"1.0\")];\n" +"pub fn explore() -> &str { \"world\" }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:3185 +#, fuzzy +#| msgid "" +#| "~~~~ {.ignore} // main.rs extern mod world; fn main() { println(~" +#| "\"hello \" + world::explore()); } ~~~~" +msgid "" +"~~~~ {.ignore} // main.rs extern mod world; fn main() { println!(\"hello " +"{}\", world::explore()); } ~~~~" +msgstr "" +"~~~~ {.ignore}\n" +"// main.rs\n" +"extern mod world;\n" +"fn main() { println(~\"hello \" + world::explore()); }\n" +"~~~~" + +#. type: Plain text +#: doc/tutorial.md:3187 +msgid "Now compile and run like this (adjust to your platform if necessary):" +msgstr "" +"以下のようにコンパイルし、実行します (必要であれば、お使いのプラットフォーム" +"に合わせて修正してください。)" + +#. type: Plain text +#: doc/tutorial.md:3194 +#, fuzzy, no-wrap +#| msgid "" +#| "~~~~ {.notrust}\n" +#| "> rustc --lib world.rs # compiles libworld-94839cbfe144198-1.0.so\n" +#| "> rustc main.rs -L . # compiles main\n" +#| "> ./main\n" +#| "\"hello world\"\n" +#| "~~~~\n" +msgid "" +"~~~~ {.notrust}\n" +"> rustc --lib world.rs # compiles libworld-<HASH>-0.42.so\n" +"> rustc main.rs -L . # compiles main\n" +"> ./main\n" +"\"hello world\"\n" +"~~~~\n" +msgstr "" +"~~~~ {.notrust}\n" +"> rustc --lib world.rs # libworld-94839cbfe144198-1.0.so が生成される\n" +"> rustc main.rs -L . # main が生成される\n" +"> ./main\n" +"\"hello world\"\n" +"~~~~\n" + +#. type: Plain text +#: doc/tutorial.md:3199 +#, fuzzy +#| msgid "" +#| "Notice that the library produced contains the version in the filename as " +#| "well as an inscrutable string of alphanumerics. These are both part of " +#| "Rust's library versioning scheme. The alphanumerics are a hash " +#| "representing the crate metadata." +msgid "" +"Notice that the library produced contains the version in the file name as " +"well as an inscrutable string of alphanumerics. As explained in the previous " +"paragraph, these are both part of Rust's library versioning scheme. The " +"alphanumerics are a hash representing the crates package ID." +msgstr "" +"生成されたライブラリのファイル名には、バージョン番号だけでなく謎めいた英数字" +"が含まれていることに注意してください。これらは両方共 Rust のバージョン管理ス" +"キームの一員です。英数字は、クレートのメタデータを表すハッシュ値です。" + +#. type: Plain text +#: doc/tutorial.md:3201 +#, fuzzy +#| msgid "## The standard library" +msgid "## The standard library and the prelude" +msgstr "## 標準ライブラリ" + +#. type: Plain text +#: doc/tutorial.md:3213 +#, fuzzy +#| msgid "~~~~ {.ignore} let foo = 10;" +msgid "~~~ {.ignore} extern mod std; ~~~" +msgstr "" +"~~~~ {.ignore}\n" +"let foo = 10;" + +#. type: Plain text +#: doc/tutorial.md:3219 +#, fuzzy +#| msgid "~~~~ {.ignore} let foo = 10;" +msgid "~~~ {.ignore} use std::prelude::*; ~~~" +msgstr "" +"~~~~ {.ignore}\n" +"let foo = 10;" + +#. type: Plain text +#: doc/tutorial.md:3260 +#, fuzzy +#| msgid "## The standard library" +msgid "## The extra library" +msgstr "## 標準ライブラリ" + +#. type: Plain text +#: doc/tutorial.md:3271 +msgid "# What next?" +msgstr "# 次のステップは？" + +#. type: Plain text +#: doc/tutorial.md:3274 +#, fuzzy +#| msgid "" +#| "Now that you know the essentials, check out any of the additional " +#| "tutorials on individual topics." +msgid "" +"Now that you know the essentials, check out any of the additional guides on " +"individual topics." +msgstr "" +"Rust の本質的な部分に関する説明は以上です。個々のトピックにおける追加のチュー" +"トリアルもチェックしてみてください。" + +#. type: Bullet: '* ' +#: doc/tutorial.md:3286 +msgid "[Tasks and communication][tasks]" +msgstr "[タスクと通信][tasks]" + +#. type: Bullet: '* ' +#: doc/tutorial.md:3286 +msgid "[Macros][macros]" +msgstr "[マクロ][macros]" + +#. type: Bullet: '* ' +#: doc/tutorial.md:3286 +msgid "[The foreign function interface][ffi]" +msgstr "[他言語間インターフェース (foreign function inferface)][ffi]" + +#. type: Bullet: '* ' +#: doc/tutorial.md:3286 +#, fuzzy +#| msgid "[Containers and iterators](tutorial-container.html)" +msgid "[Containers and iterators][container]" +msgstr "[コンテナとイテレータ](tutorial-container.html)" + +#. type: Bullet: '* ' +#: doc/tutorial.md:3286 +#, fuzzy +#| msgid "% The Rust Language Tutorial" +msgid "[The Rust Runtime][runtime]" +msgstr "% Rust 言語チュートリアル" diff --git a/src/doc/po4a.conf b/src/doc/po4a.conf new file mode 100644 index 00000000000..e3f69516f9d --- /dev/null +++ b/src/doc/po4a.conf @@ -0,0 +1,26 @@ +# Add here a list of target languages; po4a will automatically +# generates .po for them and build .md when translated, eg: +# [po4a_langs] es fr it pt_BR +[po4a_langs] ja +[po4a_paths] doc/po/$master.pot $lang:doc/po/$lang/$master.po + +# Add here below all source documents to be translated +[type: text] doc/complement-bugreport.md $lang:doc/l10n/$lang/complement-bugreport.md +[type: text] doc/complement-cheatsheet.md $lang:doc/l10n/$lang/complement-cheatsheet.md +[type: text] doc/complement-lang-faq.md $lang:doc/l10n/$lang/complement-lang-faq.md +[type: text] doc/complement-project-faq.md $lang:doc/l10n/$lang/complement-project-faq.md +[type: text] doc/complement-usage-faq.md $lang:doc/l10n/$lang/complement-usage-faq.md +[type: text] doc/guide-conditions.md $lang:doc/l10n/$lang/guide-conditions.md +[type: text] doc/guide-container.md $lang:doc/l10n/$lang/guide-container.md +[type: text] doc/guide-ffi.md $lang:doc/l10n/$lang/guide-ffi.md +[type: text] doc/guide-lifetimes.md $lang:doc/l10n/$lang/guide-lifetimes.md +[type: text] doc/guide-macros.md $lang:doc/l10n/$lang/guide-macros.md +[type: text] doc/guide-pointers.md $lang:doc/l10n/$lang/guide-pointers.md +[type: text] doc/guide-rustpkg.md $lang:doc/l10n/$lang/guide-rustpkg.md +[type: text] doc/guide-tasks.md $lang:doc/l10n/$lang/guide-tasks.md +[type: text] doc/guide-testing.md $lang:doc/l10n/$lang/guide-testing.md +[type: text] doc/index.md $lang:doc/l10n/$lang/index.md +[type: text] doc/rust.md $lang:doc/l10n/$lang/rust.md +[type: text] doc/rustdoc.md $lang:doc/l10n/$lang/rustdoc.md +[type: text] doc/rustpkg.md $lang:doc/l10n/$lang/rustpkg.md +[type: text] doc/tutorial.md $lang:doc/l10n/$lang/tutorial.md diff --git a/src/doc/prep.js b/src/doc/prep.js new file mode 100755 index 00000000000..3a1e60ec423 --- /dev/null +++ b/src/doc/prep.js @@ -0,0 +1,77 @@ +#!/usr/local/bin/node + +/*** + * Pandoc-style markdown preprocessor that drops extra directives + * included for running doc code, and that optionally, when + * --highlight is provided, replaces code blocks that are Rust code + * with highlighted HTML blocks. The directives recognized are: + * + * '## ignore' tells the test extractor (extract-tests.js) to ignore + * the block completely. + * '## notrust' makes the test extractor ignore the block, makes + * this script not highlight the block. + * '# [any text]' is a line that is stripped out by this script, and + * converted to a normal line of code (without the leading #) by + * the test extractor. + */ + +var fs = require("fs"); +CodeMirror = require("./lib/codemirror-node"); +require("./lib/codemirror-rust"); + +function help() { + console.log("usage: " + process.argv[0] + " [--highlight] [-o outfile] [infile]"); + process.exit(1); +} + +var highlight = false, infile, outfile; + +for (var i = 2; i < process.argv.length; ++i) { + var arg = process.argv[i]; + if (arg == "--highlight") highlight = true; + else if (arg == "-o" && outfile == null && ++i < process.argv.length) outfile = process.argv[i]; + else if (arg[0] != "-") infile = arg; + else help(); +} + +var lines = fs.readFileSync(infile || "/dev/stdin").toString().split(/\n\r?/g), cur = 0, line; +var out = outfile ? fs.createWriteStream(outfile) : process.stdout; + +while ((line = lines[cur++]) != null) { + if (/^~~~/.test(line)) { + var block = "", bline; + var notRust = + /notrust/.test(line) + // These are all used by the language ref to indicate things + // that are not Rust source code + || /ebnf/.test(line) + || /abnf/.test(line) + || /keyword/.test(line) + || /field/.test(line) + || /precedence/.test(line); + var isRust = !notRust; + while ((bline = lines[cur++]) != null) { + if (/^~~~/.test(bline)) break; + if (!/^\s*##? /.test(bline)) block += bline + "\n"; + } + if (!highlight || !isRust) + out.write(line + "\n" + block + bline + "\n"); + else { + var html = '<pre class="cm-s-default">', curstr = "", curstyle = null; + function add(str, style) { + if (style != curstyle) { + if (curstyle) html += + '<span class="cm-' + CodeMirror.htmlEscape(curstyle) + '">' + + CodeMirror.htmlEscape(curstr) + "</span>"; + else if (curstr) html += CodeMirror.htmlEscape(curstr); + curstr = str; curstyle = style; + } else curstr += str; + } + CodeMirror.runMode(block, "rust", add); + add("", "bogus"); // Flush pending string. + out.write(html + "</pre>\n"); + } + } else { + out.write(line + "\n"); + } +} diff --git a/src/doc/rust.css b/src/doc/rust.css new file mode 100644 index 00000000000..194a401395f --- /dev/null +++ b/src/doc/rust.css @@ -0,0 +1,290 @@ +/** + * Copyright 2013 The Rust Project Developers. See the COPYRIGHT + * file at the top-level directory of this distribution and at + * http://rust-lang.org/COPYRIGHT. + * With elements taken from Bootstrap v3.0.2 (MIT licensed). + * + * Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or + * http://www.apache.org/licenses/LICENSE-2.0> or the MIT license + * <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your + * option. This file may not be copied, modified, or distributed + * except according to those terms. + */ +/* Global page semantics + ========================================================================== */ +body { + margin: 0 auto; + padding: 0 15px; + margin-bottom: 4em; + font-family: "Helvetica Neue", Helvetica, Arial, sans-serif; + font-size: 14px; + color: #333; + line-height: 1.428571429; +} +@media (min-width: 768px) { + body { + max-width: 750px; + } +} + +h1, h2, h3, h4, h5, h6 { + color: black; + font-weight: 500; + line-height: 1.1; +} +h1, h2, h3 { + margin-top: 20px; + margin-bottom: 10px; +} +h4, h5, h6 { + margin-top: 12px; + margin-bottom: 10px; + padding: .2em .8em; + text-decoration: underline; +} + +h1 { + font-size: 36px; + padding: .1em .4em; + margin: 0.67em 0; + border-bottom: 2px solid #ddd; +} +h1.title { + line-height: 1.5em; +} +h2 { + font-size: 30px; + padding: .2em .5em; + border-bottom: 1px solid #ddd; +} +h3 { + font-size: 24px; + padding: .2em .7em; + border-bottom: 1px solid #DDE8FC; +} +h4 { + font-size: 18px; +} +h5 { + font-size: 16px; +} +h6 { + font-size: 14px; +} + +p { + margin: 0 0 10px; +} + +/* Links layout + ========================================================================== */ +a { + text-decoration: none; + color: #428BCA; + background: transparent; +} +a:hover, a:focus { + color: #2A6496; + text-decoration: underline; +} +a:focus { + outline: thin dotted #333; + outline: 5px auto -webkit-focus-ring-color; + outline-offset: -2px; +} +a:hover, a:active { + outline: 0; +} + +h1 a:link, h1 a:visited, h2 a:link, h2 a:visited, +h3 a:link, h3 a:visited, h4 a:link, h4 a:visited, +h5 a:link, h5 a:visited {color: black;} + +/* Code + ========================================================================== */ +pre, code { + font-family: Menlo, Monaco, Consolas, "Courier New", monospace; + border-radius: 4px; +} +pre { + background-color: #F5F5F5; + border: 1px solid #CCC; + border-radius: 0.5em; + white-space: pre-wrap; + padding: 9.5px; + margin: 10px 0; + font-size: 13px; + word-break: break-all; + word-wrap: break-word; +} +code { + padding: 2px 4px; + font-size: 90%; + color: #C7254E; + background-color: #F9F2F4; + white-space: nowrap; +} +pre code { + padding: 0; + font-size: inherit; + color: inherit; + white-space: pre-wrap; + background-color: transparent; + border-radius: 0; +} + +/* Code highlighting */ +.cm-s-default span.cm-keyword {color: #803C8D;} +.cm-s-default span.cm-atom {color: #219;} +.cm-s-default span.cm-number {color: #2AA198;} +.cm-s-default span.cm-def {color: #256EB8;} +.cm-s-default span.cm-variable {color: black;} +.cm-s-default span.cm-variable-2 {color: #817E61;} +.cm-s-default span.cm-variable-3 {color: #085;} +.cm-s-default span.cm-property {color: black;} +.cm-s-default span.cm-operator {color: black;} +.cm-s-default span.cm-comment {color: #A82323;} +.cm-s-default span.cm-string {color: #866544;} +.cm-s-default span.cm-string-2 {color: #F50;} +.cm-s-default span.cm-meta {color: #555;} +/*.cm-s-default span.cm-error {color: #F00;}*/ +.cm-s-default span.cm-qualifier {color: #555;} +.cm-s-default span.cm-builtin {color: #30A;} +.cm-s-default span.cm-bracket {color: #CC7;} +.cm-s-default span.cm-tag {color: #170;} +.cm-s-default span.cm-attribute {color: #00C;} + +/* The rest + ========================================================================== */ +#versioninfo { + text-align: center; + margin: 0.5em; + font-size: 1.1em; +} +@media (min-width: 768px) { + #versioninfo { + position: fixed; + bottom: 0px; + right: 0px; + } + .white-sticker { + background-color: #fff; + margin: 2px; + padding: 0 2px; + border-radius: .3em; + } +} +#versioninfo a.hash { + color: gray; + font-size: 70%; +} + +blockquote { + color: black; + border-left: 5px solid #eee; + margin: 0 0 20px; + padding: 10px 20px; +} +blockquote p { + font-size: 17px; + font-weight: 300; + line-height: 1.25; +} +blockquote p:last-child { + margin-bottom: 0; +} + +ul, +ol { + margin-top: 0; + margin-bottom: 10px; +} +ul ul, +ol ul, +ul ol, +ol ol { + margin-bottom: 0; +} +dl { + margin-bottom: 20px; +} +dd { + margin-left: 0; +} + +#TOC ul { + list-style-type: none; + padding-left: 0px; +} + +/* Only display one level of hierarchy in the TOC */ +#TOC ul ul { + display: none; +} + +sub, +sup { + font-size: 75%; + line-height: 0; + position: relative; +} + +hr { + margin-top: 20px; + margin-bottom: 20px; + border: 0; + border-top: 1px solid #eeeeee; +} + +table { + border-collapse: collapse; + border-spacing: 0; +} + +table tr.odd { + background: #eee; +} + +table td, +table th { + border: 1px solid #ddd; + padding: 5px; +} + +@media print { + * { + text-shadow: none !important; + color: #000 !important; + background: transparent !important; + box-shadow: none !important; + } + a, a:visited { + text-decoration: underline; + } + a[href]:after { + content: " (" attr(href) ")"; + } + a[href^="javascript:"]:after, a[href^="#"]:after { + content: ""; + } + pre, blockquote { + border: 1px solid #999; + page-break-inside: avoid; + } + @page { + margin: 2cm .5cm; + } + p, h2, h3 { + orphans: 3; + widows: 3; + } + h2, h3 { + page-break-after: avoid; + } + table { + border-collapse: collapse !important; + } + table td, table th { + background-color: #fff !important; + } +} diff --git a/src/doc/rust.md b/src/doc/rust.md new file mode 100644 index 00000000000..6869e794195 --- /dev/null +++ b/src/doc/rust.md @@ -0,0 +1,3954 @@ +% The Rust Reference Manual + +# Introduction + +This document is the reference manual for the Rust programming language. It +provides three kinds of material: + + - Chapters that formally define the language grammar and, for each + construct, informally describe its semantics and give examples of its + use. + - Chapters that informally describe the memory model, concurrency model, + runtime services, linkage model and debugging facilities. + - Appendix chapters providing rationale and references to languages that + influenced the design. + +This document does not serve as a tutorial introduction to the +language. Background familiarity with the language is assumed. A separate +[tutorial] document is available to help acquire such background familiarity. + +This document also does not serve as a reference to the [standard] or [extra] +libraries included in the language distribution. Those libraries are +documented separately by extracting documentation attributes from their +source code. + +[tutorial]: tutorial.html +[standard]: std/index.html +[extra]: extra/index.html + +## Disclaimer + +Rust is a work in progress. The language continues to evolve as the design +shifts and is fleshed out in working code. Certain parts work, certain parts +do not, certain parts will be removed or changed. + +This manual is a snapshot written in the present tense. All features described +exist in working code unless otherwise noted, but some are quite primitive or +remain to be further modified by planned work. Some may be temporary. It is a +*draft*, and we ask that you not take anything you read here as final. + +If you have suggestions to make, please try to focus them on *reductions* to +the language: possible features that can be combined or omitted. We aim to +keep the size and complexity of the language under control. + +> **Note:** The grammar for Rust given in this document is rough and +> very incomplete; only a modest number of sections have accompanying grammar +> rules. Formalizing the grammar accepted by the Rust parser is ongoing work, +> but future versions of this document will contain a complete +> grammar. Moreover, we hope that this grammar will be extracted and verified +> as LL(1) by an automated grammar-analysis tool, and further tested against the +> Rust sources. Preliminary versions of this automation exist, but are not yet +> complete. + +# Notation + +Rust's grammar is defined over Unicode codepoints, each conventionally +denoted `U+XXXX`, for 4 or more hexadecimal digits `X`. _Most_ of Rust's +grammar is confined to the ASCII range of Unicode, and is described in this +document by a dialect of Extended Backus-Naur Form (EBNF), specifically a +dialect of EBNF supported by common automated LL(k) parsing tools such as +`llgen`, rather than the dialect given in ISO 14977. The dialect can be +defined self-referentially as follows: + +~~~~ {.ebnf .notation} +grammar : rule + ; +rule : nonterminal ':' productionrule ';' ; +productionrule : production [ '|' production ] * ; +production : term * ; +term : element repeats ; +element : LITERAL | IDENTIFIER | '[' productionrule ']' ; +repeats : [ '*' | '+' ] NUMBER ? | NUMBER ? | '?' ; +~~~~ + +Where: + + - Whitespace in the grammar is ignored. + - Square brackets are used to group rules. + - `LITERAL` is a single printable ASCII character, or an escaped hexadecimal + ASCII code of the form `\xQQ`, in single quotes, denoting the corresponding + Unicode codepoint `U+00QQ`. + - `IDENTIFIER` is a nonempty string of ASCII letters and underscores. + - The `repeat` forms apply to the adjacent `element`, and are as follows: + - `?` means zero or one repetition + - `*` means zero or more repetitions + - `+` means one or more repetitions + - NUMBER trailing a repeat symbol gives a maximum repetition count + - NUMBER on its own gives an exact repetition count + +This EBNF dialect should hopefully be familiar to many readers. + +## Unicode productions + +A few productions in Rust's grammar permit Unicode codepoints outside the ASCII range. +We define these productions in terms of character properties specified in the Unicode standard, +rather than in terms of ASCII-range codepoints. +The section [Special Unicode Productions](#special-unicode-productions) lists these productions. + +## String table productions + +Some rules in the grammar -- notably [unary +operators](#unary-operator-expressions), [binary +operators](#binary-operator-expressions), and [keywords](#keywords) -- +are given in a simplified form: as a listing of a table of unquoted, +printable whitespace-separated strings. These cases form a subset of +the rules regarding the [token](#tokens) rule, and are assumed to be +the result of a lexical-analysis phase feeding the parser, driven by a +DFA, operating over the disjunction of all such string table entries. + +When such a string enclosed in double-quotes (`"`) occurs inside the +grammar, it is an implicit reference to a single member of such a string table +production. See [tokens](#tokens) for more information. + +# Lexical structure + +## Input format + +Rust input is interpreted as a sequence of Unicode codepoints encoded in UTF-8, +normalized to Unicode normalization form NFKC. +Most Rust grammar rules are defined in terms of printable ASCII-range codepoints, +but a small number are defined in terms of Unicode properties or explicit codepoint lists. +^[Substitute definitions for the special Unicode productions are provided to the grammar verifier, restricted to ASCII range, when verifying the grammar in this document.] + +## Special Unicode Productions + +The following productions in the Rust grammar are defined in terms of Unicode properties: +`ident`, `non_null`, `non_star`, `non_eol`, `non_slash_or_star`, `non_single_quote` and `non_double_quote`. + +### Identifiers + +The `ident` production is any nonempty Unicode string of the following form: + + - The first character has property `XID_start` + - The remaining characters have property `XID_continue` + +that does _not_ occur in the set of [keywords](#keywords). + +Note: `XID_start` and `XID_continue` as character properties cover the +character ranges used to form the more familiar C and Java language-family +identifiers. + +### Delimiter-restricted productions + +Some productions are defined by exclusion of particular Unicode characters: + + - `non_null` is any single Unicode character aside from `U+0000` (null) + - `non_eol` is `non_null` restricted to exclude `U+000A` (`'\n'`) + - `non_star` is `non_null` restricted to exclude `U+002A` (`*`) + - `non_slash_or_star` is `non_null` restricted to exclude `U+002F` (`/`) and `U+002A` (`*`) + - `non_single_quote` is `non_null` restricted to exclude `U+0027` (`'`) + - `non_double_quote` is `non_null` restricted to exclude `U+0022` (`"`) + +## Comments + +~~~~ {.ebnf .gram} +comment : block_comment | line_comment ; +block_comment : "/*" block_comment_body * '*' + '/' ; +block_comment_body : (block_comment | character) * ; +line_comment : "//" non_eol * ; +~~~~ + +Comments in Rust code follow the general C++ style of line and block-comment forms, +with no nesting of block-comment delimiters. + +Line comments beginning with exactly _three_ slashes (`///`), and block +comments beginning with a exactly one repeated asterisk in the block-open +sequence (`/**`), are interpreted as a special syntax for `doc` +[attributes](#attributes). That is, they are equivalent to writing +`#[doc="..."]` around the body of the comment (this includes the comment +characters themselves, ie `/// Foo` turns into `#[doc="/// Foo"]`). + +Non-doc comments are interpreted as a form of whitespace. + +## Whitespace + +~~~~ {.ebnf .gram} +whitespace_char : '\x20' | '\x09' | '\x0a' | '\x0d' ; +whitespace : [ whitespace_char | comment ] + ; +~~~~ + +The `whitespace_char` production is any nonempty Unicode string consisting of any +of the following Unicode characters: `U+0020` (space, `' '`), `U+0009` (tab, +`'\t'`), `U+000A` (LF, `'\n'`), `U+000D` (CR, `'\r'`). + +Rust is a "free-form" language, meaning that all forms of whitespace serve +only to separate _tokens_ in the grammar, and have no semantic significance. + +A Rust program has identical meaning if each whitespace element is replaced +with any other legal whitespace element, such as a single space character. + +## Tokens + +~~~~ {.ebnf .gram} +simple_token : keyword | unop | binop ; +token : simple_token | ident | literal | symbol | whitespace token ; +~~~~ + +Tokens are primitive productions in the grammar defined by regular +(non-recursive) languages. "Simple" tokens are given in [string table +production](#string-table-productions) form, and occur in the rest of the +grammar as double-quoted strings. Other tokens have exact rules given. + +### Keywords + +The keywords are the following strings: + +~~~~ {.keyword} +as +break +do +else enum extern +false fn for +if impl in +let loop +match mod mut +priv pub +ref return +self static struct super +true trait type +unsafe use +while +~~~~ + +Each of these keywords has special meaning in its grammar, +and all of them are excluded from the `ident` rule. + +### Literals + +A literal is an expression consisting of a single token, rather than a +sequence of tokens, that immediately and directly denotes the value it +evaluates to, rather than referring to it by name or some other evaluation +rule. A literal is a form of constant expression, so is evaluated (primarily) +at compile time. + +~~~~ {.ebnf .gram} +literal : string_lit | char_lit | num_lit ; +~~~~ + +#### Character and string literals + +~~~~ {.ebnf .gram} +char_lit : '\x27' char_body '\x27' ; +string_lit : '"' string_body * '"' | 'r' raw_string ; + +char_body : non_single_quote + | '\x5c' [ '\x27' | common_escape ] ; + +string_body : non_double_quote + | '\x5c' [ '\x22' | common_escape ] ; +raw_string : '"' raw_string_body '"' | '#' raw_string '#' ; + +common_escape : '\x5c' + | 'n' | 'r' | 't' | '0' + | 'x' hex_digit 2 + | 'u' hex_digit 4 + | 'U' hex_digit 8 ; + +hex_digit : 'a' | 'b' | 'c' | 'd' | 'e' | 'f' + | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' + | dec_digit ; +oct_digit : '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' ; +dec_digit : '0' | nonzero_dec ; +nonzero_dec: '1' | '2' | '3' | '4' + | '5' | '6' | '7' | '8' | '9' ; +~~~~ + +A _character literal_ is a single Unicode character enclosed within two +`U+0027` (single-quote) characters, with the exception of `U+0027` itself, +which must be _escaped_ by a preceding U+005C character (`\`). + +A _string literal_ is a sequence of any Unicode characters enclosed within +two `U+0022` (double-quote) characters, with the exception of `U+0022` +itself, which must be _escaped_ by a preceding `U+005C` character (`\`), +or a _raw string literal_. + +Some additional _escapes_ are available in either character or non-raw string +literals. An escape starts with a `U+005C` (`\`) and continues with one of +the following forms: + + * An _8-bit codepoint escape_ escape starts with `U+0078` (`x`) and is + followed by exactly two _hex digits_. It denotes the Unicode codepoint + equal to the provided hex value. + * A _16-bit codepoint escape_ starts with `U+0075` (`u`) and is followed + by exactly four _hex digits_. It denotes the Unicode codepoint equal to + the provided hex value. + * A _32-bit codepoint escape_ starts with `U+0055` (`U`) and is followed + by exactly eight _hex digits_. It denotes the Unicode codepoint equal to + the provided hex value. + * A _whitespace escape_ is one of the characters `U+006E` (`n`), `U+0072` + (`r`), or `U+0074` (`t`), denoting the unicode values `U+000A` (LF), + `U+000D` (CR) or `U+0009` (HT) respectively. + * The _backslash escape_ is the character `U+005C` (`\`) which must be + escaped in order to denote *itself*. + +Raw string literals do not process any escapes. They start with the character +`U+0072` (`r`), followed zero or more of the character `U+0023` (`#`) and a +`U+0022` (double-quote) character. The _raw string body_ is not defined in the +EBNF grammar above: it can contain any sequence of Unicode characters and is +terminated only by another `U+0022` (double-quote) character, followed by the +same number of `U+0023` (`#`) characters that preceeded the opening `U+0022` +(double-quote) character. + +All Unicode characters contained in the raw string body represent themselves, +the characters `U+0022` (double-quote) (except when followed by at least as +many `U+0023` (`#`) characters as were used to start the raw string literal) or +`U+005C` (`\`) do not have any special meaning. + +Examples for string literals: + +~~~~ +"foo"; r"foo"; // foo +"\"foo\""; r#""foo""#; // "foo" + +"foo #\"# bar"; +r##"foo #"# bar"##; // foo #"# bar + +"\x52"; "R"; r"R"; // R +"\\x52"; r"\x52"; // \x52 +~~~~ + +#### Number literals + +~~~~ {.ebnf .gram} +num_lit : nonzero_dec [ dec_digit | '_' ] * num_suffix ? + | '0' [ [ dec_digit | '_' ] * num_suffix ? + | 'b' [ '1' | '0' | '_' ] + int_suffix ? + | 'o' [ oct_digit | '_' ] + int_suffix ? + | 'x' [ hex_digit | '_' ] + int_suffix ? ] ; + +num_suffix : int_suffix | float_suffix ; + +int_suffix : 'u' int_suffix_size ? + | 'i' int_suffix_size ? ; +int_suffix_size : [ '8' | '1' '6' | '3' '2' | '6' '4' ] ; + +float_suffix : [ exponent | '.' dec_lit exponent ? ] ? float_suffix_ty ? ; +float_suffix_ty : 'f' [ '3' '2' | '6' '4' ] ; +exponent : ['E' | 'e'] ['-' | '+' ] ? dec_lit ; +dec_lit : [ dec_digit | '_' ] + ; +~~~~ + +A _number literal_ is either an _integer literal_ or a _floating-point +literal_. The grammar for recognizing the two kinds of literals is mixed, +as they are differentiated by suffixes. + +##### Integer literals + +An _integer literal_ has one of four forms: + + * A _decimal literal_ starts with a *decimal digit* and continues with any + mixture of *decimal digits* and _underscores_. + * A _hex literal_ starts with the character sequence `U+0030` `U+0078` + (`0x`) and continues as any mixture hex digits and underscores. + * An _octal literal_ starts with the character sequence `U+0030` `U+006F` + (`0o`) and continues as any mixture octal digits and underscores. + * A _binary literal_ starts with the character sequence `U+0030` `U+0062` + (`0b`) and continues as any mixture binary digits and underscores. + +An integer literal may be followed (immediately, without any spaces) by an +_integer suffix_, which changes the type of the literal. There are two kinds +of integer literal suffix: + + * The `i` and `u` suffixes give the literal type `int` or `uint`, + respectively. + * Each of the signed and unsigned machine types `u8`, `i8`, + `u16`, `i16`, `u32`, `i32`, `u64` and `i64` + give the literal the corresponding machine type. + +The type of an _unsuffixed_ integer literal is determined by type inference. +If a integer type can be _uniquely_ determined from the surrounding program +context, the unsuffixed integer literal has that type. If the program context +underconstrains the type, the unsuffixed integer literal's type is `int`; if +the program context overconstrains the type, it is considered a static type +error. + +Examples of integer literals of various forms: + +~~~~ +123; 0xff00; // type determined by program context + // defaults to int in absence of type + // information + +123u; // type uint +123_u; // type uint +0xff_u8; // type u8 +0o70_i16; // type i16 +0b1111_1111_1001_0000_i32; // type i32 +~~~~ + +##### Floating-point literals + +A _floating-point literal_ has one of two forms: + +* Two _decimal literals_ separated by a period + character `U+002E` (`.`), with an optional _exponent_ trailing after the + second decimal literal. +* A single _decimal literal_ followed by an _exponent_. + +By default, a floating-point literal has a generic type, but will fall back to +`f64`. A floating-point literal may be followed (immediately, without any +spaces) by a _floating-point suffix_, which changes the type of the literal. +There are two floating-point suffixes: `f32`, and `f64` (the 32-bit and 64-bit +floating point types). + +Examples of floating-point literals of various forms: + +~~~~ +123.0; // type f64 +0.1; // type f64 +0.1f32; // type f32 +12E+99_f64; // type f64 +~~~~ + +##### Unit and boolean literals + +The _unit value_, the only value of the type that has the same name, is written as `()`. +The two values of the boolean type are written `true` and `false`. + +### Symbols + +~~~~ {.ebnf .gram} +symbol : "::" "->" + | '#' | '[' | ']' | '(' | ')' | '{' | '}' + | ',' | ';' ; +~~~~ + +Symbols are a general class of printable [token](#tokens) that play structural +roles in a variety of grammar productions. They are catalogued here for +completeness as the set of remaining miscellaneous printable tokens that do not +otherwise appear as [unary operators](#unary-operator-expressions), [binary +operators](#binary-operator-expressions), or [keywords](#keywords). + + +## Paths + +~~~~ {.ebnf .gram} +expr_path : ident [ "::" expr_path_tail ] + ; +expr_path_tail : '<' type_expr [ ',' type_expr ] + '>' + | expr_path ; + +type_path : ident [ type_path_tail ] + ; +type_path_tail : '<' type_expr [ ',' type_expr ] + '>' + | "::" type_path ; +~~~~ + +A _path_ is a sequence of one or more path components _logically_ separated by +a namespace qualifier (`::`). If a path consists of only one component, it may +refer to either an [item](#items) or a [slot](#memory-slots) in a local +control scope. If a path has multiple components, it refers to an item. + +Every item has a _canonical path_ within its crate, but the path naming an +item is only meaningful within a given crate. There is no global namespace +across crates; an item's canonical path merely identifies it within the crate. + +Two examples of simple paths consisting of only identifier components: + +~~~~ {.ignore} +x; +x::y::z; +~~~~ + +Path components are usually [identifiers](#identifiers), but the trailing +component of a path may be an angle-bracket-enclosed list of type +arguments. In [expression](#expressions) context, the type argument list is +given after a final (`::`) namespace qualifier in order to disambiguate it +from a relational expression involving the less-than symbol (`<`). In type +expression context, the final namespace qualifier is omitted. + +Two examples of paths with type arguments: + +~~~~ +# use std::hashmap::HashMap; +# fn f() { +# fn id<T>(t: T) -> T { t } +type t = HashMap<int,~str>; // Type arguments used in a type expression +let x = id::<int>(10); // Type arguments used in a call expression +# } +~~~~ + +# Syntax extensions + +A number of minor features of Rust are not central enough to have their own +syntax, and yet are not implementable as functions. Instead, they are given +names, and invoked through a consistent syntax: `name!(...)`. Examples +include: + +* `format!` : format data into a string +* `env!` : look up an environment variable's value at compile time +* `file!`: return the path to the file being compiled +* `stringify!` : pretty-print the Rust expression given as an argument +* `include!` : include the Rust expression in the given file +* `include_str!` : include the contents of the given file as a string +* `include_bin!` : include the contents of the given file as a binary blob +* `error!`, `warn!`, `info!`, `debug!` : provide diagnostic information. + +All of the above extensions are expressions with values. + +## Macros + +~~~~ {.ebnf .gram} +expr_macro_rules : "macro_rules" '!' ident '(' macro_rule * ')' +macro_rule : '(' matcher * ')' "=>" '(' transcriber * ')' ';' +matcher : '(' matcher * ')' | '[' matcher * ']' + | '{' matcher * '}' | '$' ident ':' ident + | '$' '(' matcher * ')' sep_token? [ '*' | '+' ] + | non_special_token +transcriber : '(' transcriber * ')' | '[' transcriber * ']' + | '{' transcriber * '}' | '$' ident + | '$' '(' transcriber * ')' sep_token? [ '*' | '+' ] + | non_special_token +~~~~ + +User-defined syntax extensions are called "macros", +and the `macro_rules` syntax extension defines them. +Currently, user-defined macros can expand to expressions, statements, or items. + +(A `sep_token` is any token other than `*` and `+`. +A `non_special_token` is any token other than a delimiter or `$`.) + +The macro expander looks up macro invocations by name, +and tries each macro rule in turn. +It transcribes the first successful match. +Matching and transcription are closely related to each other, +and we will describe them together. + +### Macro By Example + +The macro expander matches and transcribes every token that does not begin with a `$` literally, including delimiters. +For parsing reasons, delimiters must be balanced, but they are otherwise not special. + +In the matcher, `$` _name_ `:` _designator_ matches the nonterminal in the +Rust syntax named by _designator_. Valid designators are `item`, `block`, +`stmt`, `pat`, `expr`, `ty` (type), `ident`, `path`, `matchers` (lhs of the `=>` in macro rules), +`tt` (rhs of the `=>` in macro rules). In the transcriber, the designator is already known, and so only +the name of a matched nonterminal comes after the dollar sign. + +In both the matcher and transcriber, the Kleene star-like operator indicates repetition. +The Kleene star operator consists of `$` and parens, optionally followed by a separator token, followed by `*` or `+`. +`*` means zero or more repetitions, `+` means at least one repetition. +The parens are not matched or transcribed. +On the matcher side, a name is bound to _all_ of the names it +matches, in a structure that mimics the structure of the repetition +encountered on a successful match. The job of the transcriber is to sort that +structure out. + +The rules for transcription of these repetitions are called "Macro By Example". +Essentially, one "layer" of repetition is discharged at a time, and all of +them must be discharged by the time a name is transcribed. Therefore, +`( $( $i:ident ),* ) => ( $i )` is an invalid macro, but +`( $( $i:ident ),* ) => ( $( $i:ident ),* )` is acceptable (if trivial). + +When Macro By Example encounters a repetition, it examines all of the `$` +_name_ s that occur in its body. At the "current layer", they all must repeat +the same number of times, so +` ( $( $i:ident ),* ; $( $j:ident ),* ) => ( $( ($i,$j) ),* )` is valid if +given the argument `(a,b,c ; d,e,f)`, but not `(a,b,c ; d,e)`. The repetition +walks through the choices at that layer in lockstep, so the former input +transcribes to `( (a,d), (b,e), (c,f) )`. + +Nested repetitions are allowed. + +### Parsing limitations + +The parser used by the macro system is reasonably powerful, but the parsing of +Rust syntax is restricted in two ways: + +1. The parser will always parse as much as possible. If it attempts to match +`$i:expr [ , ]` against `8 [ , ]`, it will attempt to parse `i` as an array +index operation and fail. Adding a separator can solve this problem. +2. The parser must have eliminated all ambiguity by the time it reaches a `$` _name_ `:` _designator_. +This requirement most often affects name-designator pairs when they occur at the beginning of, or immediately after, a `$(...)*`; requiring a distinctive token in front can solve the problem. + +## Syntax extensions useful for the macro author + +* `log_syntax!` : print out the arguments at compile time +* `trace_macros!` : supply `true` or `false` to enable or disable macro expansion logging +* `stringify!` : turn the identifier argument into a string literal +* `concat!` : concatenates a comma-separated list of literals +* `concat_idents!` : create a new identifier by concatenating the arguments + +# Crates and source files + +Rust is a *compiled* language. +Its semantics obey a *phase distinction* between compile-time and run-time. +Those semantic rules that have a *static interpretation* govern the success or failure of compilation. +We refer to these rules as "static semantics". +Semantic rules called "dynamic semantics" govern the behavior of programs at run-time. +A program that fails to compile due to violation of a compile-time rule has no defined dynamic semantics; the compiler should halt with an error report, and produce no executable artifact. + +The compilation model centres on artifacts called _crates_. +Each compilation processes a single crate in source form, and if successful, produces a single crate in binary form: either an executable or a library.^[A crate is somewhat +analogous to an *assembly* in the ECMA-335 CLI model, a *library* in the +SML/NJ Compilation Manager, a *unit* in the Owens and Flatt module system, +or a *configuration* in Mesa.] + +A _crate_ is a unit of compilation and linking, as well as versioning, distribution and runtime loading. +A crate contains a _tree_ of nested [module](#modules) scopes. +The top level of this tree is a module that is anonymous (from the point of view of paths within the module) and any item within a crate has a canonical [module path](#paths) denoting its location within the crate's module tree. + +The Rust compiler is always invoked with a single source file as input, and always produces a single output crate. +The processing of that source file may result in other source files being loaded as modules. +Source files have the extension `.rs`. + +A Rust source file describes a module, the name and +location of which -- in the module tree of the current crate -- are defined +from outside the source file: either by an explicit `mod_item` in +a referencing source file, or by the name of the crate itself. + +Each source file contains a sequence of zero or more `item` definitions, +and may optionally begin with any number of `attributes` that apply to the containing module. +Attributes on the anonymous crate module define important metadata that influences +the behavior of the compiler. + +~~~~ +// Package ID +#[ crate_id = "projx#2.5" ]; + +// Additional metadata attributes +#[ desc = "Project X" ]; +#[ license = "BSD" ]; +#[ comment = "This is a comment on Project X." ]; + +// Specify the output type +#[ crate_type = "lib" ]; + +// Turn on a warning +#[ warn(non_camel_case_types) ]; +~~~~ + +A crate that contains a `main` function can be compiled to an executable. +If a `main` function is present, its return type must be [`unit`](#primitive-types) and it must take no arguments. + +# Items and attributes + +Crates contain [items](#items), +each of which may have some number of [attributes](#attributes) attached to it. + +## Items + +~~~~ {.ebnf .gram} +item : mod_item | fn_item | type_item | struct_item | enum_item + | static_item | trait_item | impl_item | extern_block ; +~~~~ + +An _item_ is a component of a crate; some module items can be defined in crate +files, but most are defined in source files. Items are organized within a +crate by a nested set of [modules](#modules). Every crate has a single +"outermost" anonymous module; all further items within the crate have +[paths](#paths) within the module tree of the crate. + +Items are entirely determined at compile-time, generally remain fixed during +execution, and may reside in read-only memory. + +There are several kinds of item: + + * [modules](#modules) + * [functions](#functions) + * [type definitions](#type-definitions) + * [structures](#structures) + * [enumerations](#enumerations) + * [static items](#static-items) + * [traits](#traits) + * [implementations](#implementations) + +Some items form an implicit scope for the declaration of sub-items. In other +words, within a function or module, declarations of items can (in many cases) +be mixed with the statements, control blocks, and similar artifacts that +otherwise compose the item body. The meaning of these scoped items is the same +as if the item was declared outside the scope -- it is still a static item -- +except that the item's *path name* within the module namespace is qualified by +the name of the enclosing item, or is private to the enclosing item (in the +case of functions). +The grammar specifies the exact locations in which sub-item declarations may appear. + +### Type Parameters + +All items except modules may be *parameterized* by type. Type parameters are +given as a comma-separated list of identifiers enclosed in angle brackets +(`<...>`), after the name of the item and before its definition. +The type parameters of an item are considered "part of the name", not part of the type of the item. +A referencing [path](#paths) must (in principle) provide type arguments as a list of comma-separated types enclosed within angle brackets, in order to refer to the type-parameterized item. +In practice, the type-inference system can usually infer such argument types from context. +There are no general type-parametric types, only type-parametric items. +That is, Rust has no notion of type abstraction: there are no first-class "forall" types. + +### Modules + +~~~~ {.ebnf .gram} +mod_item : "mod" ident ( ';' | '{' mod '}' ); +mod : [ view_item | item ] * ; +~~~~ + +A module is a container for zero or more [view items](#view-items) and zero or +more [items](#items). The view items manage the visibility of the items +defined within the module, as well as the visibility of names from outside the +module when referenced from inside the module. + +A _module item_ is a module, surrounded in braces, named, and prefixed with +the keyword `mod`. A module item introduces a new, named module into the tree +of modules making up a crate. Modules can nest arbitrarily. + +An example of a module: + +~~~~ +mod math { + type complex = (f64, f64); + fn sin(f: f64) -> f64 { + ... +# fail!(); + } + fn cos(f: f64) -> f64 { + ... +# fail!(); + } + fn tan(f: f64) -> f64 { + ... +# fail!(); + } +} +~~~~ + +Modules and types share the same namespace. +Declaring a named type that has the same name as a module in scope is forbidden: +that is, a type definition, trait, struct, enumeration, or type parameter +can't shadow the name of a module in scope, or vice versa. + +A module without a body is loaded from an external file, by default with the same +name as the module, plus the `.rs` extension. +When a nested submodule is loaded from an external file, +it is loaded from a subdirectory path that mirrors the module hierarchy. + +~~~~ {.ignore} +// Load the `vec` module from `vec.rs` +mod vec; + +mod task { + // Load the `local_data` module from `task/local_data.rs` + mod local_data; +} +~~~~ + +The directories and files used for loading external file modules can be influenced +with the `path` attribute. + +~~~~ {.ignore} +#[path = "task_files"] +mod task { + // Load the `local_data` module from `task_files/tls.rs` + #[path = "tls.rs"] + mod local_data; +} +~~~~ + +#### View items + +~~~~ {.ebnf .gram} +view_item : extern_mod_decl | use_decl ; +~~~~ + +A view item manages the namespace of a module. +View items do not define new items, but rather, simply change other items' visibility. +There are several kinds of view item: + + * [`extern mod` declarations](#extern-mod-declarations) + * [`use` declarations](#use-declarations) + +##### Extern mod declarations + +~~~~ {.ebnf .gram} +extern_mod_decl : "extern" "mod" ident [ '(' link_attrs ')' ] ? [ '=' string_lit ] ? ; +link_attrs : link_attr [ ',' link_attrs ] + ; +link_attr : ident '=' literal ; +~~~~ + +An _`extern mod` declaration_ specifies a dependency on an external crate. +The external crate is then bound into the declaring scope +as the `ident` provided in the `extern_mod_decl`. + +The external crate is resolved to a specific `soname` at compile time, and a +runtime linkage requirement to that `soname` is passed to the linker for +loading at runtime. The `soname` is resolved at compile time by scanning the +compiler's library path and matching the optional `crateid` provided as a string literal +against the `crateid` attributes that were declared on the external crate when +it was compiled. If no `crateid` is provided, a default `name` attribute is +assumed, equal to the `ident` given in the `extern_mod_decl`. + +Four examples of `extern mod` declarations: + +~~~~ {.ignore} +extern mod pcre; + +extern mod extra; // equivalent to: extern mod extra = "extra"; + +extern mod rustextra = "extra"; // linking to 'extra' under another name + +extern mod foo = "some/where/rust-foo#foo:1.0"; // a full package ID for external tools +~~~~ + +##### Use declarations + +~~~~ {.ebnf .gram} +use_decl : "pub" ? "use" ident [ '=' path + | "::" path_glob ] ; + +path_glob : ident [ "::" path_glob ] ? + | '*' + | '{' ident [ ',' ident ] * '}' +~~~~ + +A _use declaration_ creates one or more local name bindings synonymous +with some other [path](#paths). +Usually a `use` declaration is used to shorten the path required to refer to a +module item. These declarations may appear at the top of [modules](#modules) and +[blocks](#blocks). + +*Note*: Unlike in many languages, +`use` declarations in Rust do *not* declare linkage dependency with external crates. +Rather, [`extern mod` declarations](#extern-mod-declarations) declare linkage dependencies. + +Use declarations support a number of convenient shortcuts: + + * Rebinding the target name as a new local name, using the syntax `use x = p::q::r;`. + * Simultaneously binding a list of paths differing only in their final element, + using the glob-like brace syntax `use a::b::{c,d,e,f};` + * Binding all paths matching a given prefix, using the asterisk wildcard syntax `use a::b::*;` + +An example of `use` declarations: + +~~~~ +use std::num::sin; +use std::option::{Some, None}; + +# fn foo<T>(_: T){} + +fn main() { + // Equivalent to 'std::num::sin(1.0);' + sin(1.0); + + // Equivalent to 'foo(~[std::option::Some(1.0), std::option::None]);' + foo(~[Some(1.0), None]); +} +~~~~ + +Like items, `use` declarations are private to the containing module, by default. +Also like items, a `use` declaration can be public, if qualified by the `pub` keyword. +Such a `use` declaration serves to _re-export_ a name. +A public `use` declaration can therefore _redirect_ some public name to a different target definition: +even a definition with a private canonical path, inside a different module. +If a sequence of such redirections form a cycle or cannot be resolved unambiguously, +they represent a compile-time error. + +An example of re-exporting: + +~~~~ +# fn main() { } +mod quux { + pub use quux::foo::*; + + pub mod foo { + pub fn bar() { } + pub fn baz() { } + } +} +~~~~ + +In this example, the module `quux` re-exports all of the public names defined in `foo`. + +Also note that the paths contained in `use` items are relative to the crate root. +So, in the previous example, the `use` refers to `quux::foo::*`, and not simply to `foo::*`. +This also means that top-level module declarations should be at the crate root if direct usage +of the declared modules within `use` items is desired. It is also possible to use `self` and `super` +at the beginning of a `use` item to refer to the current and direct parent modules respectively. +All rules regarding accessing declared modules in `use` declarations applies to both module declarations +and `extern mod` declarations. + +An example of what will and will not work for `use` items: + +~~~~ +# #[allow(unused_imports)]; +use foo::extra; // good: foo is at the root of the crate +use foo::baz::foobaz; // good: foo is at the root of the crate + +mod foo { + extern mod extra; + + use foo::extra::list; // good: foo is at crate root +// use extra::*; // bad: extra is not at the crate root + use self::baz::foobaz; // good: self refers to module 'foo' + use foo::bar::foobar; // good: foo is at crate root + + pub mod bar { + pub fn foobar() { } + } + + pub mod baz { + use super::bar::foobar; // good: super refers to module 'foo' + pub fn foobaz() { } + } +} + +fn main() {} +~~~~ + +### Functions + +A _function item_ defines a sequence of [statements](#statements) and an optional final [expression](#expressions), along with a name and a set of parameters. +Functions are declared with the keyword `fn`. +Functions declare a set of *input* [*slots*](#memory-slots) as parameters, through which the caller passes arguments into the function, and an *output* [*slot*](#memory-slots) through which the function passes results back to the caller. + +A function may also be copied into a first class *value*, in which case the +value has the corresponding [*function type*](#function-types), and can be +used otherwise exactly as a function item (with a minor additional cost of +calling the function indirectly). + +Every control path in a function logically ends with a `return` expression or a +diverging expression. If the outermost block of a function has a +value-producing expression in its final-expression position, that expression +is interpreted as an implicit `return` expression applied to the +final-expression. + +An example of a function: + +~~~~ +fn add(x: int, y: int) -> int { + return x + y; +} +~~~~ + +As with `let` bindings, function arguments are irrefutable patterns, +so any pattern that is valid in a let binding is also valid as an argument. + +~~~~ +fn first((value, _): (int, int)) -> int { value } +~~~~ + + +#### Generic functions + +A _generic function_ allows one or more _parameterized types_ to +appear in its signature. Each type parameter must be explicitly +declared, in an angle-bracket-enclosed, comma-separated list following +the function name. + +~~~~ {.ignore} +fn iter<T>(seq: &[T], f: |T|) { + for elt in seq.iter() { f(elt); } +} +fn map<T, U>(seq: &[T], f: |T| -> U) -> ~[U] { + let mut acc = ~[]; + for elt in seq.iter() { acc.push(f(elt)); } + acc +} +~~~~ + +Inside the function signature and body, the name of the type parameter +can be used as a type name. + +When a generic function is referenced, its type is instantiated based +on the context of the reference. For example, calling the `iter` +function defined above on `[1, 2]` will instantiate type parameter `T` +with `int`, and require the closure parameter to have type +`fn(int)`. + +The type parameters can also be explicitly supplied in a trailing +[path](#paths) component after the function name. This might be necessary +if there is not sufficient context to determine the type parameters. For +example, `mem::size_of::<u32>() == 4`. + +Since a parameter type is opaque to the generic function, the set of +operations that can be performed on it is limited. Values of parameter +type can only be moved, not copied. + +~~~~ +fn id<T>(x: T) -> T { x } +~~~~ + +Similarly, [trait](#traits) bounds can be specified for type +parameters to allow methods with that trait to be called on values +of that type. + + +#### Unsafety + +Unsafe operations are those that potentially violate the memory-safety guarantees of Rust's static semantics. + +The following language level features cannot be used in the safe subset of Rust: + + - Dereferencing a [raw pointer](#pointer-types). + - Calling an unsafe function (including an intrinsic or foreign function). + +##### Unsafe functions + +Unsafe functions are functions that are not safe in all contexts and/or for all possible inputs. +Such a function must be prefixed with the keyword `unsafe`. + +##### Unsafe blocks + +A block of code can also be prefixed with the `unsafe` keyword, to permit calling `unsafe` functions +or dereferencing raw pointers within a safe function. + +When a programmer has sufficient conviction that a sequence of potentially unsafe operations is +actually safe, they can encapsulate that sequence (taken as a whole) within an `unsafe` block. The +compiler will consider uses of such code safe, in the surrounding context. + +Unsafe blocks are used to wrap foreign libraries, make direct use of hardware or implement features +not directly present in the language. For example, Rust provides the language features necessary to +implement memory-safe concurrency in the language but the implementation of tasks and message +passing is in the standard library. + +Rust's type system is a conservative approximation of the dynamic safety requirements, so in some +cases there is a performance cost to using safe code. For example, a doubly-linked list is not a +tree structure and can only be represented with managed or reference-counted pointers in safe code. +By using `unsafe` blocks to represent the reverse links as raw pointers, it can be implemented with +only owned pointers. + +##### Behavior considered unsafe + +This is a list of behavior which is forbidden in all Rust code. Type checking provides the guarantee +that these issues are never caused by safe code. An `unsafe` block or function is responsible for +never invoking this behaviour or exposing an API making it possible for it to occur in safe code. + +* Data races +* Dereferencing a null/dangling raw pointer +* Mutating an immutable value/reference, if it is not marked as non-`Freeze` +* Reads of [undef](http://llvm.org/docs/LangRef.html#undefined-values) (uninitialized) memory +* Breaking the [pointer aliasing rules](http://llvm.org/docs/LangRef.html#pointer-aliasing-rules) + with raw pointers (a subset of the rules used by C) +* Invoking undefined behavior via compiler intrinsics: + * Indexing outside of the bounds of an object with `std::ptr::offset` (`offset` intrinsic), with + the exception of one byte past the end which is permitted. + * Using `std::ptr::copy_nonoverlapping_memory` (`memcpy32`/`memcpy64` instrinsics) on + overlapping buffers +* Invalid values in primitive types, even in private fields/locals: + * Dangling/null pointers in non-raw pointers, or slices + * A value other than `false` (0) or `true` (1) in a `bool` + * A discriminant in an `enum` not included in the type definition + * A value in a `char` which is a surrogate or above `char::MAX` + * non-UTF-8 byte sequences in a `str` + +##### Behaviour not considered unsafe + +This is a list of behaviour not considered *unsafe* in Rust terms, but that may be undesired. + +* Deadlocks +* Reading data from private fields (`std::repr`, `format!("{:?}", x)`) +* Leaks due to reference count cycles, even in the global heap +* Exiting without calling destructors +* Sending signals +* Accessing/modifying the file system +* Unsigned integer overflow (well-defined as wrapping) +* Signed integer overflow (well-defined as two's complement representation wrapping) + +#### Diverging functions + +A special kind of function can be declared with a `!` character where the +output slot type would normally be. For example: + +~~~~ +fn my_err(s: &str) -> ! { + info!("{}", s); + fail!(); +} +~~~~ + +We call such functions "diverging" because they never return a value to the +caller. Every control path in a diverging function must end with a +`fail!()` or a call to another diverging function on every +control path. The `!` annotation does *not* denote a type. Rather, the result +type of a diverging function is a special type called $\bot$ ("bottom") that +unifies with any type. Rust has no syntax for $\bot$. + +It might be necessary to declare a diverging function because as mentioned +previously, the typechecker checks that every control path in a function ends +with a [`return`](#return-expressions) or diverging expression. So, if `my_err` +were declared without the `!` annotation, the following code would not +typecheck: + +~~~~ +# fn my_err(s: &str) -> ! { fail!() } + +fn f(i: int) -> int { + if i == 42 { + return 42; + } + else { + my_err("Bad number!"); + } +} +~~~~ + +This will not compile without the `!` annotation on `my_err`, +since the `else` branch of the conditional in `f` does not return an `int`, +as required by the signature of `f`. +Adding the `!` annotation to `my_err` informs the typechecker that, +should control ever enter `my_err`, no further type judgments about `f` need to hold, +since control will never resume in any context that relies on those judgments. +Thus the return type on `f` only needs to reflect the `if` branch of the conditional. + + +#### Extern functions + +Extern functions are part of Rust's foreign function interface, +providing the opposite functionality to [external blocks](#external-blocks). +Whereas external blocks allow Rust code to call foreign code, +extern functions with bodies defined in Rust code _can be called by foreign +code_. They are defined in the same way as any other Rust function, +except that they have the `extern` modifier. + +~~~~ +// Declares an extern fn, the ABI defaults to "C" +extern fn new_vec() -> ~[int] { ~[] } + +// Declares an extern fn with "stdcall" ABI +extern "stdcall" fn new_vec_stdcall() -> ~[int] { ~[] } +~~~~ + +Unlike normal functions, extern fns have an `extern "ABI" fn()`. +This is the same type as the functions declared in an extern +block. + +~~~~ +# extern fn new_vec() -> ~[int] { ~[] } +let fptr: extern "C" fn() -> ~[int] = new_vec; +~~~~ + +Extern functions may be called directly from Rust code as Rust uses large, +contiguous stack segments like C. + +### Type definitions + +A _type definition_ defines a new name for an existing [type](#types). Type +definitions are declared with the keyword `type`. Every value has a single, +specific type; the type-specified aspects of a value include: + +* Whether the value is composed of sub-values or is indivisible. +* Whether the value represents textual or numerical information. +* Whether the value represents integral or floating-point information. +* The sequence of memory operations required to access the value. +* The [kind](#type-kinds) of the type. + +For example, the type `(u8, u8)` defines the set of immutable values that are composite pairs, +each containing two unsigned 8-bit integers accessed by pattern-matching and laid out in memory with the `x` component preceding the `y` component. + +### Structures + +A _structure_ is a nominal [structure type](#structure-types) defined with the keyword `struct`. + +An example of a `struct` item and its use: + +~~~~ +struct Point {x: int, y: int} +let p = Point {x: 10, y: 11}; +let px: int = p.x; +~~~~ + +A _tuple structure_ is a nominal [tuple type](#tuple-types), also defined with the keyword `struct`. +For example: + +~~~~ +struct Point(int, int); +let p = Point(10, 11); +let px: int = match p { Point(x, _) => x }; +~~~~ + +A _unit-like struct_ is a structure without any fields, defined by leaving off the list of fields entirely. +Such types will have a single value, just like the [unit value `()`](#unit-and-boolean-literals) of the unit type. +For example: + +~~~~ +struct Cookie; +let c = [Cookie, Cookie, Cookie, Cookie]; +~~~~ + +### Enumerations + +An _enumeration_ is a simultaneous definition of a nominal [enumerated type](#enumerated-types) as well as a set of *constructors*, +that can be used to create or pattern-match values of the corresponding enumerated type. + +Enumerations are declared with the keyword `enum`. + +An example of an `enum` item and its use: + +~~~~ +enum Animal { + Dog, + Cat +} + +let mut a: Animal = Dog; +a = Cat; +~~~~ + +Enumeration constructors can have either named or unnamed fields: + +~~~~ +enum Animal { + Dog (~str, f64), + Cat { name: ~str, weight: f64 } +} + +let mut a: Animal = Dog(~"Cocoa", 37.2); +a = Cat{ name: ~"Spotty", weight: 2.7 }; +~~~~ + +In this example, `Cat` is a _struct-like enum variant_, +whereas `Dog` is simply called an enum variant. + +### Static items + +~~~~ {.ebnf .gram} +static_item : "static" ident ':' type '=' expr ';' ; +~~~~ + +A *static item* is a named _constant value_ stored in the global data section of a crate. +Immutable static items are stored in the read-only data section. +The constant value bound to a static item is, like all constant values, evaluated at compile time. +Static items have the `static` lifetime, which outlives all other lifetimes in a Rust program. +Static items are declared with the `static` keyword. +A static item must have a _constant expression_ giving its definition. + +Static items must be explicitly typed. +The type may be ```bool```, ```char```, a number, or a type derived from those primitive types. +The derived types are references with the `static` lifetime, +fixed-size arrays, tuples, and structs. + +~~~~ +static BIT1: uint = 1 << 0; +static BIT2: uint = 1 << 1; + +static BITS: [uint, ..2] = [BIT1, BIT2]; +static STRING: &'static str = "bitstring"; + +struct BitsNStrings<'a> { + mybits: [uint, ..2], + mystring: &'a str +} + +static bits_n_strings: BitsNStrings<'static> = BitsNStrings { + mybits: BITS, + mystring: STRING +}; +~~~~ + +#### Mutable statics + +If a static item is declared with the ```mut``` keyword, then it is allowed to +be modified by the program. One of Rust's goals is to make concurrency bugs hard +to run into, and this is obviously a very large source of race conditions or +other bugs. For this reason, an ```unsafe``` block is required when either +reading or writing a mutable static variable. Care should be taken to ensure +that modifications to a mutable static are safe with respect to other tasks +running in the same process. + +Mutable statics are still very useful, however. They can be used with C +libraries and can also be bound from C libraries (in an ```extern``` block). + +~~~~ +# fn atomic_add(_: &mut uint, _: uint) -> uint { 2 } + +static mut LEVELS: uint = 0; + +// This violates the idea of no shared state, and this doesn't internally +// protect against races, so this function is `unsafe` +unsafe fn bump_levels_unsafe1() -> uint { + let ret = LEVELS; + LEVELS += 1; + return ret; +} + +// Assuming that we have an atomic_add function which returns the old value, +// this function is "safe" but the meaning of the return value may not be what +// callers expect, so it's still marked as `unsafe` +unsafe fn bump_levels_unsafe2() -> uint { + return atomic_add(&mut LEVELS, 1); +} +~~~~ + +### Traits + +A _trait_ describes a set of method types. + +Traits can include default implementations of methods, +written in terms of some unknown [`self` type](#self-types); +the `self` type may either be completely unspecified, +or constrained by some other trait. + +Traits are implemented for specific types through separate [implementations](#implementations). + +~~~~ +# type Surface = int; +# type BoundingBox = int; + +trait Shape { + fn draw(&self, Surface); + fn bounding_box(&self) -> BoundingBox; +} +~~~~ + +This defines a trait with two methods. +All values that have [implementations](#implementations) of this trait in scope can have their `draw` and `bounding_box` methods called, +using `value.bounding_box()` [syntax](#method-call-expressions). + +Type parameters can be specified for a trait to make it generic. +These appear after the trait name, using the same syntax used in [generic functions](#generic-functions). + +~~~~ +trait Seq<T> { + fn len(&self) -> uint; + fn elt_at(&self, n: uint) -> T; + fn iter(&self, |T|); +} +~~~~ + +Generic functions may use traits as _bounds_ on their type parameters. +This will have two effects: only types that have the trait may instantiate the parameter, +and within the generic function, +the methods of the trait can be called on values that have the parameter's type. +For example: + +~~~~ +# type Surface = int; +# trait Shape { fn draw(&self, Surface); } + +fn draw_twice<T: Shape>(surface: Surface, sh: T) { + sh.draw(surface); + sh.draw(surface); +} +~~~~ + +Traits also define an [object type](#object-types) with the same name as the trait. +Values of this type are created by [casting](#type-cast-expressions) pointer values +(pointing to a type for which an implementation of the given trait is in scope) +to pointers to the trait name, used as a type. + +~~~~ +# trait Shape { } +# impl Shape for int { } +# let mycircle = 0; + +let myshape: @Shape = @mycircle as @Shape; +~~~~ + +The resulting value is a managed box containing the value that was cast, +along with information that identifies the methods of the implementation that was used. +Values with a trait type can have [methods called](#method-call-expressions) on them, +for any method in the trait, +and can be used to instantiate type parameters that are bounded by the trait. + +Trait methods may be static, +which means that they lack a `self` argument. +This means that they can only be called with function call syntax (`f(x)`) +and not method call syntax (`obj.f()`). +The way to refer to the name of a static method is to qualify it with the trait name, +treating the trait name like a module. +For example: + +~~~~ +trait Num { + fn from_int(n: int) -> Self; +} +impl Num for f64 { + fn from_int(n: int) -> f64 { n as f64 } +} +let x: f64 = Num::from_int(42); +~~~~ + +Traits may inherit from other traits. For example, in + +~~~~ +trait Shape { fn area() -> f64; } +trait Circle : Shape { fn radius() -> f64; } +~~~~ + +the syntax `Circle : Shape` means that types that implement `Circle` must also have an implementation for `Shape`. +Multiple supertraits are separated by spaces, `trait Circle : Shape Eq { }`. +In an implementation of `Circle` for a given type `T`, methods can refer to `Shape` methods, +since the typechecker checks that any type with an implementation of `Circle` also has an implementation of `Shape`. + +In type-parameterized functions, +methods of the supertrait may be called on values of subtrait-bound type parameters. +Referring to the previous example of `trait Circle : Shape`: + +~~~~ +# trait Shape { fn area(&self) -> f64; } +# trait Circle : Shape { fn radius(&self) -> f64; } +fn radius_times_area<T: Circle>(c: T) -> f64 { + // `c` is both a Circle and a Shape + c.radius() * c.area() +} +~~~~ + +Likewise, supertrait methods may also be called on trait objects. + +~~~~ {.ignore} +# trait Shape { fn area(&self) -> f64; } +# trait Circle : Shape { fn radius(&self) -> f64; } +# impl Shape for int { fn area(&self) -> f64 { 0.0 } } +# impl Circle for int { fn radius(&self) -> f64 { 0.0 } } +# let mycircle = 0; + +let mycircle: Circle = @mycircle as @Circle; +let nonsense = mycircle.radius() * mycircle.area(); +~~~~ + +### Implementations + +An _implementation_ is an item that implements a [trait](#traits) for a specific type. + +Implementations are defined with the keyword `impl`. + +~~~~ +# struct Point {x: f64, y: f64}; +# type Surface = int; +# struct BoundingBox {x: f64, y: f64, width: f64, height: f64}; +# trait Shape { fn draw(&self, Surface); fn bounding_box(&self) -> BoundingBox; } +# fn do_draw_circle(s: Surface, c: Circle) { } + +struct Circle { + radius: f64, + center: Point, +} + +impl Shape for Circle { + fn draw(&self, s: Surface) { do_draw_circle(s, *self); } + fn bounding_box(&self) -> BoundingBox { + let r = self.radius; + BoundingBox{x: self.center.x - r, y: self.center.y - r, + width: 2.0 * r, height: 2.0 * r} + } +} +~~~~ + +It is possible to define an implementation without referring to a trait. +The methods in such an implementation can only be used +as direct calls on the values of the type that the implementation targets. +In such an implementation, the trait type and `for` after `impl` are omitted. +Such implementations are limited to nominal types (enums, structs), +and the implementation must appear in the same module or a sub-module as the `self` type. + +When a trait _is_ specified in an `impl`, +all methods declared as part of the trait must be implemented, +with matching types and type parameter counts. + +An implementation can take type parameters, +which can be different from the type parameters taken by the trait it implements. +Implementation parameters are written after the `impl` keyword. + +~~~~ +# trait Seq<T> { } + +impl<T> Seq<T> for ~[T] { + ... +} +impl Seq<bool> for u32 { + /* Treat the integer as a sequence of bits */ +} +~~~~ + +### External blocks + +~~~~ {.ebnf .gram} +extern_block_item : "extern" '{' extern_block '} ; +extern_block : [ foreign_fn ] * ; +~~~~ + +External blocks form the basis for Rust's foreign function interface. +Declarations in an external block describe symbols +in external, non-Rust libraries. + +Functions within external blocks +are declared in the same way as other Rust functions, +with the exception that they may not have a body +and are instead terminated by a semicolon. + +~~~~ +# use std::libc::{c_char, FILE}; +# #[nolink] + +extern { + fn fopen(filename: *c_char, mode: *c_char) -> *FILE; +} +~~~~ + +Functions within external blocks may be called by Rust code, +just like functions defined in Rust. +The Rust compiler automatically translates +between the Rust ABI and the foreign ABI. + +A number of [attributes](#attributes) control the behavior of external +blocks. + +By default external blocks assume that the library they are calling +uses the standard C "cdecl" ABI. Other ABIs may be specified using +an `abi` string, as shown here: + +~~~~ {.ignore} +// Interface to the Windows API +extern "stdcall" { } +~~~~ + +The `link` attribute allows the name of the library to be specified. When +specified the compiler will attempt to link against the native library of the +specified name. + +~~~~ {.ignore} +#[link(name = "crypto")] +extern { } +~~~~ + +The type of a function +declared in an extern block +is `extern "abi" fn(A1, ..., An) -> R`, +where `A1...An` are the declared types of its arguments +and `R` is the decalred return type. + +## Visibility and Privacy + +These two terms are often used interchangeably, and what they are attempting to +convey is the answer to the question "Can this item be used at this location?" + +Rust's name resolution operates on a global hierarchy of namespaces. Each level +in the hierarchy can be thought of as some item. The items are one of those +mentioned above, but also include external crates. Declaring or defining a new +module can be thought of as inserting a new tree into the hierarchy at the +location of the definition. + +To control whether interfaces can be used across modules, Rust checks each use +of an item to see whether it should be allowed or not. This is where privacy +warnings are generated, or otherwise "you used a private item of another module +and weren't allowed to." + +By default, everything in rust is *private*, with two exceptions. The first +exception is that struct fields are public by default (but the struct itself is +still private by default), and the remaining exception is that enum variants in +a `pub` enum are the default visibility of the enum container itself.. You are +allowed to alter this default visibility with the `pub` keyword (or `priv` +keyword for struct fields and enum variants). When an item is declared as `pub`, +it can be thought of as being accessible to the outside world. For example: + +~~~~ +# fn main() {} +// Declare a private struct +struct Foo; + +// Declare a public struct with a private field +pub struct Bar { + priv field: int +} + +// Declare a public enum with public and private variants +pub enum State { + PubliclyAccessibleState, + priv PrivatelyAccessibleState +} +~~~~ + +With the notion of an item being either public or private, Rust allows item +accesses in two cases: + +1. If an item is public, then it can be used externally through any of its + public ancestors. +2. If an item is private, it may be accessed by the current module and its + descendants. + +These two cases are surprisingly powerful for creating module hierarchies +exposing public APIs while hiding internal implementation details. To help +explain, here's a few use cases and what they would entail. + +* A library developer needs to expose functionality to crates which link against + their library. As a consequence of the first case, this means that anything + which is usable externally must be `pub` from the root down to the destination + item. Any private item in the chain will disallow external accesses. + +* A crate needs a global available "helper module" to itself, but it doesn't + want to expose the helper module as a public API. To accomplish this, the root + of the crate's hierarchy would have a private module which then internally has + a "public api". Because the entire crate is a descendant of the root, then the + entire local crate can access this private module through the second case. + +* When writing unit tests for a module, it's often a common idiom to have an + immediate child of the module to-be-tested named `mod test`. This module could + access any items of the parent module through the second case, meaning that + internal implementation details could also be seamlessly tested from the child + module. + +In the second case, it mentions that a private item "can be accessed" by the +current module and its descendants, but the exact meaning of accessing an item +depends on what the item is. Accessing a module, for example, would mean looking +inside of it (to import more items). On the other hand, accessing a function +would mean that it is invoked. Additionally, path expressions and import +statements are considered to access an item in the sense that the +import/expression is only valid if the destination is in the current visibility +scope. + +Here's an example of a program which exemplifies the three cases outlined above. + +~~~~ +// This module is private, meaning that no external crate can access this +// module. Because it is private at the root of this current crate, however, any +// module in the crate may access any publicly visible item in this module. +mod crate_helper_module { + + // This function can be used by anything in the current crate + pub fn crate_helper() {} + + // This function *cannot* be used by anything else in the crate. It is not + // publicly visible outside of the `crate_helper_module`, so only this + // current module and its descendants may access it. + fn implementation_detail() {} +} + +// This function is "public to the root" meaning that it's available to external +// crates linking against this one. +pub fn public_api() {} + +// Similarly to 'public_api', this module is public so external crates may look +// inside of it. +pub mod submodule { + use crate_helper_module; + + pub fn my_method() { + // Any item in the local crate may invoke the helper module's public + // interface through a combination of the two rules above. + crate_helper_module::crate_helper(); + } + + // This function is hidden to any module which is not a descendant of + // `submodule` + fn my_implementation() {} + + #[cfg(test)] + mod test { + + #[test] + fn test_my_implementation() { + // Because this module is a descendant of `submodule`, it's allowed + // to access private items inside of `submodule` without a privacy + // violation. + super::my_implementation(); + } + } +} + +# fn main() {} +~~~~ + +For a rust program to pass the privacy checking pass, all paths must be valid +accesses given the two rules above. This includes all use statements, +expressions, types, etc. + +### Re-exporting and Visibility + +Rust allows publicly re-exporting items through a `pub use` directive. Because +this is a public directive, this allows the item to be used in the current +module through the rules above. It essentially allows public access into the +re-exported item. For example, this program is valid: + +~~~~ +pub use api = self::implementation; + +mod implementation { + pub fn f() {} +} + +# fn main() {} +~~~~ + +This means that any external crate referencing `implementation::f` would receive +a privacy violation, while the path `api::f` would be allowed. + +When re-exporting a private item, it can be thought of as allowing the "privacy +chain" being short-circuited through the reexport instead of passing through the +namespace hierarchy as it normally would. + +### Glob imports and Visibility + +Currently glob imports are considered an "experimental" language feature. For +sanity purpose along with helping the implementation, glob imports will only +import public items from their destination, not private items. + +> **Note:** This is subject to change, glob exports may be removed entirely or +> they could possibly import private items for a privacy error to later be +> issued if the item is used. + +## Attributes + +~~~~ {.ebnf .gram} +attribute : '#' '[' attr_list ']' ; +attr_list : attr [ ',' attr_list ]* +attr : ident [ '=' literal + | '(' attr_list ')' ] ? ; +~~~~ + +Static entities in Rust -- crates, modules and items -- may have _attributes_ +applied to them. ^[Attributes in Rust are modeled on Attributes in ECMA-335, +C#] +An attribute is a general, free-form metadatum that is interpreted according to name, convention, and language and compiler version. +Attributes may appear as any of + +* A single identifier, the attribute name +* An identifier followed by the equals sign '=' and a literal, providing a key/value pair +* An identifier followed by a parenthesized list of sub-attribute arguments + +Attributes terminated by a semi-colon apply to the entity that the attribute is declared +within. Attributes that are not terminated by a semi-colon apply to the next entity. + +An example of attributes: + +~~~~ {.ignore} +// General metadata applied to the enclosing module or crate. +#[license = "BSD"]; + +// A function marked as a unit test +#[test] +fn test_foo() { + ... +} + +// A conditionally-compiled module +#[cfg(target_os="linux")] +mod bar { + ... +} + +// A lint attribute used to suppress a warning/error +#[allow(non_camel_case_types)] +pub type int8_t = i8; +~~~~ + +> **Note:** In future versions of Rust, user-provided extensions to the compiler will be able to interpret attributes. +> When this facility is provided, the compiler will distinguish between language-reserved and user-available attributes. + +At present, only the Rust compiler interprets attributes, so all attribute +names are effectively reserved. Some significant attributes include: + +* The `doc` attribute, for documenting code in-place. +* The `cfg` attribute, for conditional-compilation by build-configuration. +* The `crate_id` attribute, for describing the package ID of a crate. +* The `lang` attribute, for custom definitions of traits and functions that are + known to the Rust compiler (see [Language items](#language-items)). +* The `link` attribute, for describing linkage metadata for a extern blocks. +* The `test` attribute, for marking functions as unit tests. +* The `allow`, `warn`, `forbid`, and `deny` attributes, for + controlling lint checks (see [Lint check attributes](#lint-check-attributes)). +* The `deriving` attribute, for automatically generating + implementations of certain traits. +* The `inline` attribute, for expanding functions at caller location (see + [Inline attributes](#inline-attributes)). +* The `static_assert` attribute, for asserting that a static bool is true at compiletime +* The `thread_local` attribute, for defining a `static mut` as a thread-local. Note that this is + only a low-level building block, and is not local to a *task*, nor does it provide safety. + +Other attributes may be added or removed during development of the language. + +### Lint check attributes + +A lint check names a potentially undesirable coding pattern, such as +unreachable code or omitted documentation, for the static entity to +which the attribute applies. + +For any lint check `C`: + + * `warn(C)` warns about violations of `C` but continues compilation, + * `deny(C)` signals an error after encountering a violation of `C`, + * `allow(C)` overrides the check for `C` so that violations will go + unreported, + * `forbid(C)` is the same as `deny(C)`, but also forbids uses of + `allow(C)` within the entity. + +The lint checks supported by the compiler can be found via `rustc -W help`, +along with their default settings. + +~~~~ {.ignore} +mod m1 { + // Missing documentation is ignored here + #[allow(missing_doc)] + pub fn undocumented_one() -> int { 1 } + + // Missing documentation signals a warning here + #[warn(missing_doc)] + pub fn undocumented_too() -> int { 2 } + + // Missing documentation signals an error here + #[deny(missing_doc)] + pub fn undocumented_end() -> int { 3 } +} +~~~~ + +This example shows how one can use `allow` and `warn` to toggle +a particular check on and off. + +~~~~ {.ignore} +#[warn(missing_doc)] +mod m2{ + #[allow(missing_doc)] + mod nested { + // Missing documentation is ignored here + pub fn undocumented_one() -> int { 1 } + + // Missing documentation signals a warning here, + // despite the allow above. + #[warn(missing_doc)] + pub fn undocumented_two() -> int { 2 } + } + + // Missing documentation signals a warning here + pub fn undocumented_too() -> int { 3 } +} +~~~~ + +This example shows how one can use `forbid` to disallow uses +of `allow` for that lint check. + +~~~~ {.ignore} +#[forbid(missing_doc)] +mod m3 { + // Attempting to toggle warning signals an error here + #[allow(missing_doc)] + /// Returns 2. + pub fn undocumented_too() -> int { 2 } +} +~~~~ + +### Language items + +Some primitive Rust operations are defined in Rust code, +rather than being implemented directly in C or assembly language. +The definitions of these operations have to be easy for the compiler to find. +The `lang` attribute makes it possible to declare these operations. +For example, the `str` module in the Rust standard library defines the string equality function: + +~~~~ {.ignore} +#[lang="str_eq"] +pub fn eq_slice(a: &str, b: &str) -> bool { + // details elided +} +~~~~ + +The name `str_eq` has a special meaning to the Rust compiler, +and the presence of this definition means that it will use this definition +when generating calls to the string equality function. + +A complete list of the built-in language items follows: + +#### Traits + +`const` + : Cannot be mutated. +`owned` + : Are uniquely owned. +`durable` + : Contain references. +`drop` + : Have finalizers. +`add` + : Elements can be added (for example, integers and floats). +`sub` + : Elements can be subtracted. +`mul` + : Elements can be multiplied. +`div` + : Elements have a division operation. +`rem` + : Elements have a remainder operation. +`neg` + : Elements can be negated arithmetically. +`not` + : Elements can be negated logically. +`bitxor` + : Elements have an exclusive-or operation. +`bitand` + : Elements have a bitwise `and` operation. +`bitor` + : Elements have a bitwise `or` operation. +`shl` + : Elements have a left shift operation. +`shr` + : Elements have a right shift operation. +`index` + : Elements can be indexed. +`eq` + : Elements can be compared for equality. +`ord` + : Elements have a partial ordering. + +#### Operations + +`str_eq` + : Compare two strings for equality. +`uniq_str_eq` + : Compare two owned strings for equality. +`annihilate` + : Destroy a box before freeing it. +`log_type` + : Generically print a string representation of any type. +`fail_` + : Abort the program with an error. +`fail_bounds_check` + : Abort the program with a bounds check error. +`exchange_malloc` + : Allocate memory on the exchange heap. +`exchange_free` + : Free memory that was allocated on the exchange heap. +`malloc` + : Allocate memory on the managed heap. +`free` + : Free memory that was allocated on the managed heap. +`borrow_as_imm` + : Create an immutable reference to a mutable value. +`return_to_mut` + : Release a reference created with `return_to_mut` +`check_not_borrowed` + : Fail if a value has existing references to it. +`strdup_uniq` + : Return a new unique string + containing a copy of the contents of a unique string. + +> **Note:** This list is likely to become out of date. We should auto-generate it +> from `librustc/middle/lang_items.rs`. + +### Inline attributes + +The inline attribute is used to suggest to the compiler to perform an inline +expansion and place a copy of the function in the caller rather than generating +code to call the function where it is defined. + +The compiler automatically inlines functions based on internal heuristics. +Incorrectly inlining functions can actually making the program slower, so it +should be used with care. + +`#[inline]` and `#[inline(always)]` always causes the function to be serialized +into crate metadata to allow cross-crate inlining. + +There are three different types of inline attributes: + +* `#[inline]` hints the compiler to perform an inline expansion. +* `#[inline(always)]` asks the compiler to always perform an inline expansion. +* `#[inline(never)]` asks the compiler to never perform an inline expansion. + +### Deriving + +The `deriving` attribute allows certain traits to be automatically +implemented for data structures. For example, the following will +create an `impl` for the `Eq` and `Clone` traits for `Foo`, the type +parameter `T` will be given the `Eq` or `Clone` constraints for the +appropriate `impl`: + +~~~~ +#[deriving(Eq, Clone)] +struct Foo<T> { + a: int, + b: T +} +~~~~ + +The generated `impl` for `Eq` is equivalent to + +~~~~ +# struct Foo<T> { a: int, b: T } +impl<T: Eq> Eq for Foo<T> { + fn eq(&self, other: &Foo<T>) -> bool { + self.a == other.a && self.b == other.b + } + + fn ne(&self, other: &Foo<T>) -> bool { + self.a != other.a || self.b != other.b + } +} +~~~~ + +Supported traits for `deriving` are: + +* Comparison traits: `Eq`, `TotalEq`, `Ord`, `TotalOrd`. +* Serialization: `Encodable`, `Decodable`. These require `extra`. +* `Clone` and `DeepClone`, to perform (deep) copies. +* `IterBytes`, to iterate over the bytes in a data type. +* `Rand`, to create a random instance of a data type. +* `Default`, to create an empty instance of a data type. +* `Zero`, to create an zero instance of a numeric data type. +* `FromPrimitive`, to create an instance from a numeric primitve. + +### Stability +One can indicate the stability of an API using the following attributes: + +* `deprecated`: This item should no longer be used, e.g. it has been + replaced. No guarantee of backwards-compatibility. +* `experimental`: This item was only recently introduced or is + otherwise in a state of flux. It may change significantly, or even + be removed. No guarantee of backwards-compatibility. +* `unstable`: This item is still under development, but requires more + testing to be considered stable. No guarantee of backwards-compatibility. +* `stable`: This item is considered stable, and will not change + significantly. Guarantee of backwards-compatibility. +* `frozen`: This item is very stable, and is unlikely to + change. Guarantee of backwards-compatibility. +* `locked`: This item will never change unless a serious bug is + found. Guarantee of backwards-compatibility. + +These levels are directly inspired by +[Node.js' "stability index"](http://nodejs.org/api/documentation.html). + +There are lints for disallowing items marked with certain levels: +`deprecated`, `experimental` and `unstable`; the first two will warn +by default. Items with not marked with a stability are considered to +be unstable for the purposes of the lint. One can give an optional +string that will be displayed when the lint flags the use of an item. + +~~~~ {.ignore} +#[warn(unstable)]; + +#[deprecated="replaced by `best`"] +fn bad() { + // delete everything +} + +fn better() { + // delete fewer things +} + +#[stable] +fn best() { + // delete nothing +} + +fn main() { + bad(); // "warning: use of deprecated item: replaced by `best`" + + better(); // "warning: use of unmarked item" + + best(); // no warning +} +~~~~ + +> **Note:** Currently these are only checked when applied to +> individual functions, structs, methods and enum variants, *not* to +> entire modules, traits, impls or enums themselves. + +### Compiler Features + +Certain aspects of Rust may be implemented in the compiler, but they're not +necessarily ready for every-day use. These features are often of "prototype +quality" or "almost production ready", but may not be stable enough to be +considered a full-fleged language feature. + +For this reason, rust recognizes a special crate-level attribute of the form: + +~~~~ {.ignore} +#[feature(feature1, feature2, feature3)] +~~~~ + +This directive informs the compiler that the feature list: `feature1`, +`feature2`, and `feature3` should all be enabled. This is only recognized at a +crate-level, not at a module-level. Without this directive, all features are +considered off, and using the features will result in a compiler error. + +The currently implemented features of the compiler are: + +* `macro_rules` - The definition of new macros. This does not encompass + macro-invocation, that is always enabled by default, this only + covers the definition of new macros. There are currently + various problems with invoking macros, how they interact with + their environment, and possibly how they are used outside of + location in which they are defined. Macro definitions are + likely to change slightly in the future, so they are currently + hidden behind this feature. + +* `globs` - Importing everything in a module through `*`. This is currently a + large source of bugs in name resolution for Rust, and it's not clear + whether this will continue as a feature or not. For these reasons, + the glob import statement has been hidden behind this feature flag. + +* `struct_variant` - Structural enum variants (those with named fields). It is + currently unknown whether this style of enum variant is as + fully supported as the tuple-forms, and it's not certain + that this style of variant should remain in the language. + For now this style of variant is hidden behind a feature + flag. + +* `once_fns` - Onceness guarantees a closure is only executed once. Defining a + closure as `once` is unlikely to be supported going forward. So + they are hidden behind this feature until they are to be removed. + +* `managed_boxes` - Usage of `@` pointers is gated due to many + planned changes to this feature. In the past, this has meant + "a GC pointer", but the current implementation uses + reference counting and will likely change drastically over + time. Additionally, the `@` syntax will no longer be used to + create GC boxes. + +* `asm` - The `asm!` macro provides a means for inline assembly. This is often + useful, but the exact syntax for this feature along with its semantics + are likely to change, so this macro usage must be opted into. + +* `non_ascii_idents` - The compiler supports the use of non-ascii identifiers, + but the implementation is a little rough around the + edges, so this can be seen as an experimental feature for + now until the specification of identifiers is fully + fleshed out. + +* `thread_local` - The usage of the `#[thread_local]` attribute is experimental + and should be seen as unstable. This attribute is used to + declare a `static` as being unique per-thread leveraging + LLVM's implementation which works in concert with the kernel + loader and dynamic linker. This is not necessarily available + on all platforms, and usage of it is discouraged (rust + focuses more on task-local data instead of thread-local + data). + +* `link_args` - This attribute is used to specify custom flags to the linker, + but usage is strongly discouraged. The compiler's usage of the + system linker is not guaranteed to continue in the future, and + if the system linker is not used then specifying custom flags + doesn't have much meaning. + +If a feature is promoted to a language feature, then all existing programs will +start to receive compilation warnings about #[feature] directives which enabled +the new feature (because the directive is no longer necessary). However, if +a feature is decided to be removed from the language, errors will be issued (if +there isn't a parser error first). The directive in this case is no longer +necessary, and it's likely that existing code will break if the feature isn't +removed. + +If a unknown feature is found in a directive, it results in a compiler error. An +unknown feature is one which has never been recognized by the compiler. + +# Statements and expressions + +Rust is _primarily_ an expression language. This means that most forms of +value-producing or effect-causing evaluation are directed by the uniform +syntax category of _expressions_. Each kind of expression can typically _nest_ +within each other kind of expression, and rules for evaluation of expressions +involve specifying both the value produced by the expression and the order in +which its sub-expressions are themselves evaluated. + +In contrast, statements in Rust serve _mostly_ to contain and explicitly +sequence expression evaluation. + +## Statements + +A _statement_ is a component of a block, which is in turn a component of an +outer [expression](#expressions) or [function](#functions). + +Rust has two kinds of statement: +[declaration statements](#declaration-statements) and +[expression statements](#expression-statements). + +### Declaration statements + +A _declaration statement_ is one that introduces one or more *names* into the enclosing statement block. +The declared names may denote new slots or new items. + +#### Item declarations + +An _item declaration statement_ has a syntactic form identical to an +[item](#items) declaration within a module. Declaring an item -- a function, +enumeration, structure, type, static, trait, implementation or module -- locally +within a statement block is simply a way of restricting its scope to a narrow +region containing all of its uses; it is otherwise identical in meaning to +declaring the item outside the statement block. + +Note: there is no implicit capture of the function's dynamic environment when +declaring a function-local item. + +#### Slot declarations + +~~~~ {.ebnf .gram} +let_decl : "let" pat [':' type ] ? [ init ] ? ';' ; +init : [ '=' ] expr ; +~~~~ + +A _slot declaration_ introduces a new set of slots, given by a pattern. +The pattern may be followed by a type annotation, and/or an initializer expression. +When no type annotation is given, the compiler will infer the type, +or signal an error if insufficient type information is available for definite inference. +Any slots introduced by a slot declaration are visible from the point of declaration until the end of the enclosing block scope. + +### Expression statements + +An _expression statement_ is one that evaluates an [expression](#expressions) +and ignores its result. +The type of an expression statement `e;` is always `()`, regardless of the type of `e`. +As a rule, an expression statement's purpose is to trigger the effects of evaluating its expression. + +## Expressions + +An expression may have two roles: it always produces a *value*, and it may have *effects* +(otherwise known as "side effects"). +An expression *evaluates to* a value, and has effects during *evaluation*. +Many expressions contain sub-expressions (operands). +The meaning of each kind of expression dictates several things: + * Whether or not to evaluate the sub-expressions when evaluating the expression + * The order in which to evaluate the sub-expressions + * How to combine the sub-expressions' values to obtain the value of the expression. + +In this way, the structure of expressions dictates the structure of execution. +Blocks are just another kind of expression, +so blocks, statements, expressions, and blocks again can recursively nest inside each other +to an arbitrary depth. + +#### Lvalues, rvalues and temporaries + +Expressions are divided into two main categories: _lvalues_ and _rvalues_. +Likewise within each expression, sub-expressions may occur in _lvalue context_ or _rvalue context_. +The evaluation of an expression depends both on its own category and the context it occurs within. + +An lvalue is an expression that represents a memory location. These +expressions are [paths](#path-expressions) (which refer to local +variables, function and method arguments, or static variables), +dereferences (`*expr`), [indexing expressions](#index-expressions) +(`expr[expr]`), and [field references](#field-expressions) (`expr.f`). +All other expressions are rvalues. + +The left operand of an [assignment](#assignment-expressions) or +[compound-assignment](#compound-assignment-expressions) expression is an lvalue context, +as is the single operand of a unary [borrow](#unary-operator-expressions). +All other expression contexts are rvalue contexts. + +When an lvalue is evaluated in an _lvalue context_, it denotes a memory location; +when evaluated in an _rvalue context_, it denotes the value held _in_ that memory location. + +When an rvalue is used in lvalue context, a temporary un-named lvalue is created and used instead. +A temporary's lifetime equals the largest lifetime of any reference that points to it. + +#### Moved and copied types + +When a [local variable](#memory-slots) is used +as an [rvalue](#lvalues-rvalues-and-temporaries) +the variable will either be moved or copied, depending on its type. +For types that contain [owning pointers](#pointer-types) +or values that implement the special trait `Drop`, +the variable is moved. +All other types are copied. + +### Literal expressions + +A _literal expression_ consists of one of the [literal](#literals) +forms described earlier. It directly describes a number, character, +string, boolean value, or the unit value. + +~~~~ {.literals} +(); // unit type +"hello"; // string type +'5'; // character type +5; // integer type +~~~~ + +### Path expressions + +A [path](#paths) used as an expression context denotes either a local variable or an item. +Path expressions are [lvalues](#lvalues-rvalues-and-temporaries). + +### Tuple expressions + +Tuples are written by enclosing one or more comma-separated +expressions in parentheses. They are used to create [tuple-typed](#tuple-types) +values. + +~~~~ {.tuple} +(0,); +(0.0, 4.5); +("a", 4u, true); +~~~~ + +### Structure expressions + +~~~~ {.ebnf .gram} +struct_expr : expr_path '{' ident ':' expr + [ ',' ident ':' expr ] * + [ ".." expr ] '}' | + expr_path '(' expr + [ ',' expr ] * ')' | + expr_path +~~~~ + +There are several forms of structure expressions. +A _structure expression_ consists of the [path](#paths) of a [structure item](#structures), +followed by a brace-enclosed list of one or more comma-separated name-value pairs, +providing the field values of a new instance of the structure. +A field name can be any identifier, and is separated from its value expression by a colon. +The location denoted by a structure field is mutable if and only if the enclosing structure is mutable. + +A _tuple structure expression_ consists of the [path](#paths) of a [structure item](#structures), +followed by a parenthesized list of one or more comma-separated expressions +(in other words, the path of a structure item followed by a tuple expression). +The structure item must be a tuple structure item. + +A _unit-like structure expression_ consists only of the [path](#paths) of a [structure item](#structures). + +The following are examples of structure expressions: + +~~~~ +# struct Point { x: f64, y: f64 } +# struct TuplePoint(f64, f64); +# mod game { pub struct User<'a> { name: &'a str, age: uint, score: uint } } +# struct Cookie; fn some_fn<T>(t: T) {} +Point {x: 10.0, y: 20.0}; +TuplePoint(10.0, 20.0); +let u = game::User {name: "Joe", age: 35, score: 100_000}; +some_fn::<Cookie>(Cookie); +~~~~ + +A structure expression forms a new value of the named structure type. +Note that for a given *unit-like* structure type, this will always be the same value. + +A structure expression can terminate with the syntax `..` followed by an expression to denote a functional update. +The expression following `..` (the base) must have the same structure type as the new structure type being formed. +The entire expression denotes the result of allocating a new structure +(with the same type as the base expression) +with the given values for the fields that were explicitly specified +and the values in the base record for all other fields. + +~~~~ +# struct Point3d { x: int, y: int, z: int } +let base = Point3d {x: 1, y: 2, z: 3}; +Point3d {y: 0, z: 10, .. base}; +~~~~ + +### Block expressions + +~~~~ {.ebnf .gram} +block_expr : '{' [ view_item ] * + [ stmt ';' | item ] * + [ expr ] '}' +~~~~ + +A _block expression_ is similar to a module in terms of the declarations that +are possible. Each block conceptually introduces a new namespace scope. View +items can bring new names into scopes and declared items are in scope for only +the block itself. + +A block will execute each statement sequentially, and then execute the +expression (if given). If the final expression is omitted, the type and return +value of the block are `()`, but if it is provided, the type and return value +of the block are that of the expression itself. + +### Method-call expressions + +~~~~ {.ebnf .gram} +method_call_expr : expr '.' ident paren_expr_list ; +~~~~ + +A _method call_ consists of an expression followed by a single dot, an identifier, and a parenthesized expression-list. +Method calls are resolved to methods on specific traits, +either statically dispatching to a method if the exact `self`-type of the left-hand-side is known, +or dynamically dispatching if the left-hand-side expression is an indirect [object type](#object-types). + +### Field expressions + +~~~~ {.ebnf .gram} +field_expr : expr '.' ident +~~~~ + +A _field expression_ consists of an expression followed by a single dot and an identifier, +when not immediately followed by a parenthesized expression-list (the latter is a [method call expression](#method-call-expressions)). +A field expression denotes a field of a [structure](#structure-types). + +~~~~ {.field} +myrecord.myfield; +{a: 10, b: 20}.a; +~~~~ + +A field access on a record is an [lvalue](#lvalues-rvalues-and-temporaries) referring to the value of that field. +When the field is mutable, it can be [assigned](#assignment-expressions) to. + +When the type of the expression to the left of the dot is a pointer to a record or structure, +it is automatically dereferenced to make the field access possible. + +### Vector expressions + +~~~~ {.ebnf .gram} +vec_expr : '[' "mut" ? vec_elems? ']' + +vec_elems : [expr [',' expr]*] | [expr ',' ".." expr] +~~~~ + +A [_vector_](#vector-types) _expression_ is written by enclosing zero or +more comma-separated expressions of uniform type in square brackets. + +In the `[expr ',' ".." expr]` form, the expression after the `".."` +must be a constant expression that can be evaluated at compile time, such +as a [literal](#literals) or a [static item](#static-items). + +~~~~ +[1, 2, 3, 4]; +["a", "b", "c", "d"]; +[0, ..128]; // vector with 128 zeros +[0u8, 0u8, 0u8, 0u8]; +~~~~ + +### Index expressions + +~~~~ {.ebnf .gram} +idx_expr : expr '[' expr ']' +~~~~ + +[Vector](#vector-types)-typed expressions can be indexed by writing a +square-bracket-enclosed expression (the index) after them. When the +vector is mutable, the resulting [lvalue](#lvalues-rvalues-and-temporaries) can be assigned to. + +Indices are zero-based, and may be of any integral type. Vector access +is bounds-checked at run-time. When the check fails, it will put the +task in a _failing state_. + +~~~~ {.ignore} +# use std::task; +# do task::spawn { + +([1, 2, 3, 4])[0]; +(["a", "b"])[10]; // fails + +# } +~~~~ + +### Unary operator expressions + +Rust defines six symbolic unary operators. +They are all written as prefix operators, +before the expression they apply to. + +`-` + : Negation. May only be applied to numeric types. +`*` + : Dereference. When applied to a [pointer](#pointer-types) it denotes the pointed-to location. + For pointers to mutable locations, the resulting [lvalue](#lvalues-rvalues-and-temporaries) can be assigned to. + For [enums](#enumerated-types) that have only a single variant, containing a single parameter, + the dereference operator accesses this parameter. +`!` + : Logical negation. On the boolean type, this flips between `true` and + `false`. On integer types, this inverts the individual bits in the + two's complement representation of the value. +`@` and `~` + : [Boxing](#pointer-types) operators. Allocate a box to hold the value they are applied to, + and store the value in it. `@` creates a managed box, whereas `~` creates an owned box. +`&` + : Borrow operator. Returns a reference, pointing to its operand. + The operand of a borrow is statically proven to outlive the resulting pointer. + If the borrow-checker cannot prove this, it is a compilation error. + +### Binary operator expressions + +~~~~ {.ebnf .gram} +binop_expr : expr binop expr ; +~~~~ + +Binary operators expressions are given in terms of +[operator precedence](#operator-precedence). + +#### Arithmetic operators + +Binary arithmetic expressions are syntactic sugar for calls to built-in traits, +defined in the `std::ops` module of the `std` library. +This means that arithmetic operators can be overridden for user-defined types. +The default meaning of the operators on standard types is given here. + +`+` + : Addition and vector/string concatenation. + Calls the `add` method on the `std::ops::Add` trait. +`-` + : Subtraction. + Calls the `sub` method on the `std::ops::Sub` trait. +`*` + : Multiplication. + Calls the `mul` method on the `std::ops::Mul` trait. +`/` + : Quotient. + Calls the `div` method on the `std::ops::Div` trait. +`%` + : Remainder. + Calls the `rem` method on the `std::ops::Rem` trait. + +#### Bitwise operators + +Like the [arithmetic operators](#arithmetic-operators), bitwise operators +are syntactic sugar for calls to methods of built-in traits. +This means that bitwise operators can be overridden for user-defined types. +The default meaning of the operators on standard types is given here. + +`&` + : And. + Calls the `bitand` method of the `std::ops::BitAnd` trait. +`|` + : Inclusive or. + Calls the `bitor` method of the `std::ops::BitOr` trait. +`^` + : Exclusive or. + Calls the `bitxor` method of the `std::ops::BitXor` trait. +`<<` + : Logical left shift. + Calls the `shl` method of the `std::ops::Shl` trait. +`>>` + : Logical right shift. + Calls the `shr` method of the `std::ops::Shr` trait. + +#### Lazy boolean operators + +The operators `||` and `&&` may be applied to operands of boolean type. +The `||` operator denotes logical 'or', and the `&&` operator denotes logical 'and'. +They differ from `|` and `&` in that the right-hand operand is only evaluated +when the left-hand operand does not already determine the result of the expression. +That is, `||` only evaluates its right-hand operand +when the left-hand operand evaluates to `false`, and `&&` only when it evaluates to `true`. + +#### Comparison operators + +Comparison operators are, like the [arithmetic operators](#arithmetic-operators), +and [bitwise operators](#bitwise-operators), +syntactic sugar for calls to built-in traits. +This means that comparison operators can be overridden for user-defined types. +The default meaning of the operators on standard types is given here. + +`==` + : Equal to. + Calls the `eq` method on the `std::cmp::Eq` trait. +`!=` + : Unequal to. + Calls the `ne` method on the `std::cmp::Eq` trait. +`<` + : Less than. + Calls the `lt` method on the `std::cmp::Ord` trait. +`>` + : Greater than. + Calls the `gt` method on the `std::cmp::Ord` trait. +`<=` + : Less than or equal. + Calls the `le` method on the `std::cmp::Ord` trait. +`>=` + : Greater than or equal. + Calls the `ge` method on the `std::cmp::Ord` trait. + +#### Type cast expressions + +A type cast expression is denoted with the binary operator `as`. + +Executing an `as` expression casts the value on the left-hand side to the type +on the right-hand side. + +A numeric value can be cast to any numeric type. +A raw pointer value can be cast to or from any integral type or raw pointer type. +Any other cast is unsupported and will fail to compile. + +An example of an `as` expression: + +~~~~ +# fn sum(v: &[f64]) -> f64 { 0.0 } +# fn len(v: &[f64]) -> int { 0 } + +fn avg(v: &[f64]) -> f64 { + let sum: f64 = sum(v); + let sz: f64 = len(v) as f64; + return sum / sz; +} +~~~~ + +#### Assignment expressions + +An _assignment expression_ consists of an [lvalue](#lvalues-rvalues-and-temporaries) expression followed by an +equals sign (`=`) and an [rvalue](#lvalues-rvalues-and-temporaries) expression. + +Evaluating an assignment expression [either copies or moves](#moved-and-copied-types) its right-hand operand to its left-hand operand. + +~~~~ +# let mut x = 0; +# let y = 0; + +x = y; +~~~~ + +#### Compound assignment expressions + +The `+`, `-`, `*`, `/`, `%`, `&`, `|`, `^`, `<<`, and `>>` +operators may be composed with the `=` operator. The expression `lval +OP= val` is equivalent to `lval = lval OP val`. For example, `x = x + +1` may be written as `x += 1`. + +Any such expression always has the [`unit`](#primitive-types) type. + +#### Operator precedence + +The precedence of Rust binary operators is ordered as follows, going +from strong to weak: + +~~~~ {.precedence} +* / % +as ++ - +<< >> +& +^ +| +< > <= >= +== != +&& +|| += +~~~~ + +Operators at the same precedence level are evaluated left-to-right. [Unary operators](#unary-operator-expressions) +have the same precedence level and it is stronger than any of the binary operators'. + +### Grouped expressions + +An expression enclosed in parentheses evaluates to the result of the enclosed +expression. Parentheses can be used to explicitly specify evaluation order +within an expression. + +~~~~ {.ebnf .gram} +paren_expr : '(' expr ')' ; +~~~~ + +An example of a parenthesized expression: + +~~~~ +let x = (2 + 3) * 4; +~~~~ + + +### Call expressions + +~~~~ {.abnf .gram} +expr_list : [ expr [ ',' expr ]* ] ? ; +paren_expr_list : '(' expr_list ')' ; +call_expr : expr paren_expr_list ; +~~~~ + +A _call expression_ invokes a function, providing zero or more input slots and +an optional reference slot to serve as the function's output, bound to the +`lval` on the right hand side of the call. If the function eventually returns, +then the expression completes. + +Some examples of call expressions: + +~~~~ +# use std::from_str::FromStr; +# fn add(x: int, y: int) -> int { 0 } + +let x: int = add(1, 2); +let pi: Option<f32> = FromStr::from_str("3.14"); +~~~~ + +### Lambda expressions + +~~~~ {.abnf .gram} +ident_list : [ ident [ ',' ident ]* ] ? ; +lambda_expr : '|' ident_list '|' expr ; +~~~~ + +A _lambda expression_ (sometimes called an "anonymous function expression") defines a function and denotes it as a value, +in a single expression. +A lambda expression is a pipe-symbol-delimited (`|`) list of identifiers followed by an expression. + +A lambda expression denotes a function that maps a list of parameters (`ident_list`) +onto the expression that follows the `ident_list`. +The identifiers in the `ident_list` are the parameters to the function. +These parameters' types need not be specified, as the compiler infers them from context. + +Lambda expressions are most useful when passing functions as arguments to other functions, +as an abbreviation for defining and capturing a separate function. + +Significantly, lambda expressions _capture their environment_, +which regular [function definitions](#functions) do not. +The exact type of capture depends on the [function type](#function-types) inferred for the lambda expression. +In the simplest and least-expensive form (analogous to a ```|| { }``` expression), +the lambda expression captures its environment by reference, +effectively borrowing pointers to all outer variables mentioned inside the function. +Alternately, the compiler may infer that a lambda expression should copy or move values (depending on their type.) +from the environment into the lambda expression's captured environment. + +In this example, we define a function `ten_times` that takes a higher-order function argument, +and call it with a lambda expression as an argument. + +~~~~ +fn ten_times(f: |int|) { + let mut i = 0; + while i < 10 { + f(i); + i += 1; + } +} + +ten_times(|j| println!("hello, {}", j)); +~~~~ + +### While loops + +~~~~ {.ebnf .gram} +while_expr : "while" expr '{' block '}' ; +~~~~ + +A `while` loop begins by evaluating the boolean loop conditional expression. +If the loop conditional expression evaluates to `true`, the loop body block +executes and control returns to the loop conditional expression. If the loop +conditional expression evaluates to `false`, the `while` expression completes. + +An example: + +~~~~ +let mut i = 0; + +while i < 10 { + println!("hello"); + i = i + 1; +} +~~~~ + +### Infinite loops + +The keyword `loop` in Rust appears both in _loop expressions_ and in _continue expressions_. +A loop expression denotes an infinite loop; +see [Continue expressions](#continue-expressions) for continue expressions. + +~~~~ {.ebnf .gram} +loop_expr : [ lifetime ':' ] "loop" '{' block '}'; +~~~~ + +A `loop` expression may optionally have a _label_. +If a label is present, +then labeled `break` and `loop` expressions nested within this loop may exit out of this loop or return control to its head. +See [Break expressions](#break-expressions). + +### Break expressions + +~~~~ {.ebnf .gram} +break_expr : "break" [ lifetime ]; +~~~~ + +A `break` expression has an optional `label`. +If the label is absent, then executing a `break` expression immediately terminates the innermost loop enclosing it. +It is only permitted in the body of a loop. +If the label is present, then `break foo` terminates the loop with label `foo`, +which need not be the innermost label enclosing the `break` expression, +but must enclose it. + +### Continue expressions + +~~~~ {.ebnf .gram} +continue_expr : "loop" [ lifetime ]; +~~~~ + +A continue expression, written `loop`, also has an optional `label`. +If the label is absent, +then executing a `loop` expression immediately terminates the current iteration of the innermost loop enclosing it, +returning control to the loop *head*. +In the case of a `while` loop, +the head is the conditional expression controlling the loop. +In the case of a `for` loop, the head is the call-expression controlling the loop. +If the label is present, then `loop foo` returns control to the head of the loop with label `foo`, +which need not be the innermost label enclosing the `break` expression, +but must enclose it. + +A `loop` expression is only permitted in the body of a loop. + +### For expressions + +~~~~ {.ebnf .gram} +for_expr : "for" pat "in" expr '{' block '}' ; +~~~~ + +A `for` expression is a syntactic construct for looping over elements +provided by an implementation of `std::iter::Iterator`. + +An example of a for loop over the contents of a vector: + +~~~~ +# type foo = int; +# fn bar(f: foo) { } +# let a = 0; +# let b = 0; +# let c = 0; + +let v: &[foo] = &[a, b, c]; + +for e in v.iter() { + bar(*e); +} +~~~~ + +An example of a for loop over a series of integers: + +~~~~ +# fn bar(b:uint) { } +for i in range(0u, 256) { + bar(i); +} +~~~~ + +### If expressions + +~~~~ {.ebnf .gram} +if_expr : "if" expr '{' block '}' + else_tail ? ; + +else_tail : "else" [ if_expr + | '{' block '}' ] ; +~~~~ + +An `if` expression is a conditional branch in program control. The form of +an `if` expression is a condition expression, followed by a consequent +block, any number of `else if` conditions and blocks, and an optional +trailing `else` block. The condition expressions must have type +`bool`. If a condition expression evaluates to `true`, the +consequent block is executed and any subsequent `else if` or `else` +block is skipped. If a condition expression evaluates to `false`, the +consequent block is skipped and any subsequent `else if` condition is +evaluated. If all `if` and `else if` conditions evaluate to `false` +then any `else` block is executed. + +### Match expressions + +~~~~ {.ebnf .gram} +match_expr : "match" expr '{' match_arm [ '|' match_arm ] * '}' ; + +match_arm : match_pat '=>' [ expr "," | '{' block '}' ] ; + +match_pat : pat [ ".." pat ] ? [ "if" expr ] ; +~~~~ + +A `match` expression branches on a *pattern*. The exact form of matching that +occurs depends on the pattern. Patterns consist of some combination of +literals, destructured vectors or enum constructors, structures, records and +tuples, variable binding specifications, wildcards (`..`), and placeholders +(`_`). A `match` expression has a *head expression*, which is the value to +compare to the patterns. The type of the patterns must equal the type of the +head expression. + +In a pattern whose head expression has an `enum` type, a placeholder (`_`) +stands for a *single* data field, whereas a wildcard `..` stands for *all* the +fields of a particular variant. For example: + +~~~~ +enum List<X> { Nil, Cons(X, ~List<X>) } + +let x: List<int> = Cons(10, ~Cons(11, ~Nil)); + +match x { + Cons(_, ~Nil) => fail!("singleton list"), + Cons(..) => return, + Nil => fail!("empty list") +} +~~~~ + +The first pattern matches lists constructed by applying `Cons` to any head +value, and a tail value of `~Nil`. The second pattern matches _any_ list +constructed with `Cons`, ignoring the values of its arguments. The difference +between `_` and `..` is that the pattern `C(_)` is only type-correct if `C` has +exactly one argument, while the pattern `C(..)` is type-correct for any enum +variant `C`, regardless of how many arguments `C` has. + +Used inside a vector pattern, `..` stands for any number of elements. This +wildcard can be used at most once for a given vector, which implies that it +cannot be used to specifically match elements that are at an unknown distance +from both ends of a vector, like `[.., 42, ..]`. If followed by a variable name, +it will bind the corresponding slice to the variable. Example: + +~~~~ +fn is_symmetric(list: &[uint]) -> bool { + match list { + [] | [_] => true, + [x, ..inside, y] if x == y => is_symmetric(inside), + _ => false + } +} + +fn main() { + let sym = &[0, 1, 4, 2, 4, 1, 0]; + let not_sym = &[0, 1, 7, 2, 4, 1, 0]; + assert!(is_symmetric(sym)); + assert!(!is_symmetric(not_sym)); +} +~~~~ + +A `match` behaves differently depending on whether or not the head expression +is an [lvalue or an rvalue](#lvalues-rvalues-and-temporaries). +If the head expression is an rvalue, it is +first evaluated into a temporary location, and the resulting value +is sequentially compared to the patterns in the arms until a match +is found. The first arm with a matching pattern is chosen as the branch target +of the `match`, any variables bound by the pattern are assigned to local +variables in the arm's block, and control enters the block. + +When the head expression is an lvalue, the match does not allocate a +temporary location (however, a by-value binding may copy or move from +the lvalue). When possible, it is preferable to match on lvalues, as the +lifetime of these matches inherits the lifetime of the lvalue, rather +than being restricted to the inside of the match. + +An example of a `match` expression: + +~~~~ +# fn process_pair(a: int, b: int) { } +# fn process_ten() { } + +enum List<X> { Nil, Cons(X, ~List<X>) } + +let x: List<int> = Cons(10, ~Cons(11, ~Nil)); + +match x { + Cons(a, ~Cons(b, _)) => { + process_pair(a,b); + } + Cons(10, _) => { + process_ten(); + } + Nil => { + return; + } + _ => { + fail!(); + } +} +~~~~ + +Patterns that bind variables +default to binding to a copy or move of the matched value +(depending on the matched value's type). +This can be changed to bind to a reference by +using the `ref` keyword, +or to a mutable reference using `ref mut`. + +Subpatterns can also be bound to variables by the use of the syntax +`variable @ pattern`. +For example: + +~~~~ +enum List { Nil, Cons(uint, ~List) } + +fn is_sorted(list: &List) -> bool { + match *list { + Nil | Cons(_, ~Nil) => true, + Cons(x, ref r @ ~Cons(y, _)) => (x <= y) && is_sorted(*r) + } +} + +fn main() { + let a = Cons(6, ~Cons(7, ~Cons(42, ~Nil))); + assert!(is_sorted(&a)); +} + +~~~~ + +Patterns can also dereference pointers by using the `&`, +`~` or `@` symbols, as appropriate. For example, these two matches +on `x: &int` are equivalent: + +~~~~ +# let x = &3; +let y = match *x { 0 => "zero", _ => "some" }; +let z = match x { &0 => "zero", _ => "some" }; + +assert_eq!(y, z); +~~~~ + +A pattern that's just an identifier, like `Nil` in the previous example, +could either refer to an enum variant that's in scope, or bind a new variable. +The compiler resolves this ambiguity by forbidding variable bindings that occur +in `match` patterns from shadowing names of variants that are in scope. +For example, wherever `List` is in scope, +a `match` pattern would not be able to bind `Nil` as a new name. +The compiler interprets a variable pattern `x` as a binding _only_ if there is +no variant named `x` in scope. +A convention you can use to avoid conflicts is simply to name variants with +upper-case letters, and local variables with lower-case letters. + +Multiple match patterns may be joined with the `|` operator. +A range of values may be specified with `..`. +For example: + +~~~~ +# let x = 2; + +let message = match x { + 0 | 1 => "not many", + 2 .. 9 => "a few", + _ => "lots" +}; +~~~~ + +Range patterns only work on scalar types +(like integers and characters; not like vectors and structs, which have sub-components). +A range pattern may not be a sub-range of another range pattern inside the same `match`. + +Finally, match patterns can accept *pattern guards* to further refine the +criteria for matching a case. Pattern guards appear after the pattern and +consist of a bool-typed expression following the `if` keyword. A pattern +guard may refer to the variables bound within the pattern they follow. + +~~~~ +# let maybe_digit = Some(0); +# fn process_digit(i: int) { } +# fn process_other(i: int) { } + +let message = match maybe_digit { + Some(x) if x < 10 => process_digit(x), + Some(x) => process_other(x), + None => fail!() +}; +~~~~ + +### Return expressions + +~~~~ {.ebnf .gram} +return_expr : "return" expr ? ; +~~~~ + +Return expressions are denoted with the keyword `return`. Evaluating a `return` +expression moves its argument into the output slot of the current +function, destroys the current function activation frame, and transfers +control to the caller frame. + +An example of a `return` expression: + +~~~~ +fn max(a: int, b: int) -> int { + if a > b { + return a; + } + return b; +} +~~~~ + +# Type system + +## Types + +Every slot, item and value in a Rust program has a type. The _type_ of a *value* +defines the interpretation of the memory holding it. + +Built-in types and type-constructors are tightly integrated into the language, +in nontrivial ways that are not possible to emulate in user-defined +types. User-defined types have limited capabilities. + +### Primitive types + +The primitive types are the following: + +* The "unit" type `()`, having the single "unit" value `()` (occasionally called "nil"). + ^[The "unit" value `()` is *not* a sentinel "null pointer" value for reference slots; the "unit" type is the implicit return type from functions otherwise lacking a return type, and can be used in other contexts (such as message-sending or type-parametric code) as a zero-size type.] +* The boolean type `bool` with values `true` and `false`. +* The machine types. +* The machine-dependent integer and floating-point types. + +#### Machine types + +The machine types are the following: + +* The unsigned word types `u8`, `u16`, `u32` and `u64`, with values drawn from + the integer intervals $[0, 2^8 - 1]$, $[0, 2^{16} - 1]$, $[0, 2^{32} - 1]$ and + $[0, 2^{64} - 1]$ respectively. + +* The signed two's complement word types `i8`, `i16`, `i32` and `i64`, with + values drawn from the integer intervals $[-(2^7), 2^7 - 1]$, + $[-(2^{15}), 2^{15} - 1]$, $[-(2^{31}), 2^{31} - 1]$, $[-(2^{63}), 2^{63} - 1]$ + respectively. + +* The IEEE 754-2008 `binary32` and `binary64` floating-point types: `f32` and + `f64`, respectively. + +#### Machine-dependent integer types + +The Rust type `uint`^[A Rust `uint` is analogous to a C99 `uintptr_t`.] is an +unsigned integer type with target-machine-dependent size. Its size, in +bits, is equal to the number of bits required to hold any memory address on +the target machine. + +The Rust type `int`^[A Rust `int` is analogous to a C99 `intptr_t`.] is a +two's complement signed integer type with target-machine-dependent size. Its +size, in bits, is equal to the size of the rust type `uint` on the same target +machine. + +### Textual types + +The types `char` and `str` hold textual data. + +A value of type `char` is a Unicode character, +represented as a 32-bit unsigned word holding a UCS-4 codepoint. + +A value of type `str` is a Unicode string, +represented as a vector of 8-bit unsigned bytes holding a sequence of UTF-8 codepoints. +Since `str` is of unknown size, it is not a _first class_ type, +but can only be instantiated through a pointer type, +such as `&str` or `~str`. + +### Tuple types + +The tuple type-constructor forms a new heterogeneous product of values similar +to the record type-constructor. The differences are as follows: + +* tuple elements cannot be mutable, unlike record fields +* tuple elements are not named and can be accessed only by pattern-matching + +Tuple types and values are denoted by listing the types or values of their +elements, respectively, in a parenthesized, comma-separated +list. + +The members of a tuple are laid out in memory contiguously, like a record, in +order specified by the tuple type. + +An example of a tuple type and its use: + +~~~~ +type Pair<'a> = (int,&'a str); +let p: Pair<'static> = (10,"hello"); +let (a, b) = p; +assert!(b != "world"); +~~~~ + +### Vector types + +The vector type constructor represents a homogeneous array of values of a given type. +A vector has a fixed size. +(Operations like `vec.push` operate solely on owned vectors.) +A vector type can be annotated with a _definite_ size, such as `[int, ..10]`. +Such a definite-sized vector type is a first-class type, since its size is known statically. +A vector without such a size is said to be of _indefinite_ size, +and is therefore not a _first-class_ type. +An indefinite-size vector can only be instantiated through a pointer type, +such as `&[T]` or `~[T]`. +The kind of a vector type depends on the kind of its element type, +as with other simple structural types. + +Expressions producing vectors of definite size cannot be evaluated in a +context expecting a vector of indefinite size; one must copy the +definite-sized vector contents into a distinct vector of indefinite size. + +An example of a vector type and its use: + +~~~~ +let v: &[int] = &[7, 5, 3]; +let i: int = v[2]; +assert!(i == 3); +~~~~ + +All in-bounds elements of a vector are always initialized, +and access to a vector is always bounds-checked. + +### Structure types + +A `struct` *type* is a heterogeneous product of other types, called the *fields* of the type. +^[`struct` types are analogous `struct` types in C, +the *record* types of the ML family, +or the *structure* types of the Lisp family.] + +New instances of a `struct` can be constructed with a [struct expression](#structure-expressions). + +The memory order of fields in a `struct` is given by the item defining it. +Fields may be given in any order in a corresponding struct *expression*; +the resulting `struct` value will always be laid out in memory in the order specified by the corresponding *item*. + +The fields of a `struct` may be qualified by [visibility modifiers](#re-exporting-and-visibility), +to restrict access to implementation-private data in a structure. + +A _tuple struct_ type is just like a structure type, except that the fields are anonymous. + +A _unit-like struct_ type is like a structure type, except that it has no fields. +The one value constructed by the associated [structure expression](#structure-expressions) +is the only value that inhabits such a type. + +### Enumerated types + +An *enumerated type* is a nominal, heterogeneous disjoint union type, +denoted by the name of an [`enum` item](#enumerations). +^[The `enum` type is analogous to a `data` constructor declaration in ML, +or a *pick ADT* in Limbo.] + +An [`enum` item](#enumerations) declares both the type and a number of *variant constructors*, +each of which is independently named and takes an optional tuple of arguments. + +New instances of an `enum` can be constructed by calling one of the variant constructors, +in a [call expression](#call-expressions). + +Any `enum` value consumes as much memory as the largest variant constructor for its corresponding `enum` type. + +Enum types cannot be denoted *structurally* as types, +but must be denoted by named reference to an [`enum` item](#enumerations). + +### Recursive types + +Nominal types -- [enumerations](#enumerated-types) and [structures](#structure-types) -- may be recursive. +That is, each `enum` constructor or `struct` field may refer, directly or indirectly, to the enclosing `enum` or `struct` type itself. +Such recursion has restrictions: + +* Recursive types must include a nominal type in the recursion + (not mere [type definitions](#type-definitions), + or other structural types such as [vectors](#vector-types) or [tuples](#tuple-types)). +* A recursive `enum` item must have at least one non-recursive constructor + (in order to give the recursion a basis case). +* The size of a recursive type must be finite; + in other words the recursive fields of the type must be [pointer types](#pointer-types). +* Recursive type definitions can cross module boundaries, but not module *visibility* boundaries, + or crate boundaries (in order to simplify the module system and type checker). + +An example of a *recursive* type and its use: + +~~~~ +enum List<T> { + Nil, + Cons(T, @List<T>) +} + +let a: List<int> = Cons(7, @Cons(13, @Nil)); +~~~~ + +### Pointer types + +All pointers in Rust are explicit first-class values. +They can be copied, stored into data structures, and returned from functions. +There are four varieties of pointer in Rust: + +Managed pointers (`@`) + : These point to managed heap allocations (or "boxes") in the task-local, managed heap. + Managed pointers are written `@content`, + for example `@int` means a managed pointer to a managed box containing an integer. + Copying a managed pointer is a "shallow" operation: + it involves only copying the pointer itself + (as well as any reference-count or GC-barriers required by the managed heap). + Dropping a managed pointer does not necessarily release the box it points to; + the lifecycles of managed boxes are subject to an unspecified garbage collection algorithm. + +Owning pointers (`~`) + : These point to owned heap allocations (or "boxes") in the shared, inter-task heap. + Each owned box has a single owning pointer; pointer and pointee retain a 1:1 relationship at all times. + Owning pointers are written `~content`, + for example `~int` means an owning pointer to an owned box containing an integer. + Copying an owned box is a "deep" operation: + it involves allocating a new owned box and copying the contents of the old box into the new box. + Releasing an owning pointer immediately releases its corresponding owned box. + +References (`&`) + : These point to memory _owned by some other value_. + References arise by (automatic) conversion from owning pointers, managed pointers, + or by applying the borrowing operator `&` to some other value, + including [lvalues, rvalues or temporaries](#lvalues-rvalues-and-temporaries). + References are written `&content`, or in some cases `&'f content` for some lifetime-variable `f`, + for example `&int` means a reference to an integer. + Copying a reference is a "shallow" operation: + it involves only copying the pointer itself. + Releasing a reference typically has no effect on the value it points to, + with the exception of temporary values, + which are released when the last reference to them is released. + +Raw pointers (`*`) + : Raw pointers are pointers without safety or liveness guarantees. + Raw pointers are written `*content`, + for example `*int` means a raw pointer to an integer. + Copying or dropping a raw pointer has no effect on the lifecycle of any other value. + Dereferencing a raw pointer or converting it to any other pointer type is an [`unsafe` operation](#unsafe-functions). + Raw pointers are generally discouraged in Rust code; + they exist to support interoperability with foreign code, + and writing performance-critical or low-level functions. + +### Function types + +The function type constructor `fn` forms new function types. +A function type consists of a possibly-empty set of function-type modifiers +(such as `unsafe` or `extern`), a sequence of input types and an output type. + +An example of a `fn` type: + +~~~~ +fn add(x: int, y: int) -> int { + return x + y; +} + +let mut x = add(5,7); + +type Binop<'a> = 'a |int,int| -> int; +let bo: Binop = add; +x = bo(5,7); +~~~~ + +### Closure types + +The type of a closure mapping an input of type `A` to an output of type `B` is `|A| -> B`. A closure with no arguments or return values has type `||`. + + +An example of creating and calling a closure: + +```rust +let captured_var = 10; + +let closure_no_args = || println!("captured_var={}", captured_var); + +let closure_args = |arg: int| -> int { + println!("captured_var={}, arg={}", captured_var, arg); + arg // Note lack of semicolon after 'arg' +}; + +fn call_closure(c1: ||, c2: |int| -> int) { + c1(); + c2(2); +} + +call_closure(closure_no_args, closure_args); + +``` + +### Object types + +Every trait item (see [traits](#traits)) defines a type with the same name as the trait. +This type is called the _object type_ of the trait. +Object types permit "late binding" of methods, dispatched using _virtual method tables_ ("vtables"). +Whereas most calls to trait methods are "early bound" (statically resolved) to specific implementations at compile time, +a call to a method on an object type is only resolved to a vtable entry at compile time. +The actual implementation for each vtable entry can vary on an object-by-object basis. + +Given a pointer-typed expression `E` of type `&T`, `~T` or `@T`, where `T` implements trait `R`, +casting `E` to the corresponding pointer type `&R`, `~R` or `@R` results in a value of the _object type_ `R`. +This result is represented as a pair of pointers: +the vtable pointer for the `T` implementation of `R`, and the pointer value of `E`. + +An example of an object type: + +~~~~ +trait Printable { + fn to_string(&self) -> ~str; +} + +impl Printable for int { + fn to_string(&self) -> ~str { self.to_str() } +} + +fn print(a: @Printable) { + println!("{}", a.to_string()); +} + +fn main() { + print(@10 as @Printable); +} +~~~~ + +In this example, the trait `Printable` occurs as an object type in both the type signature of `print`, +and the cast expression in `main`. + +### Type parameters + +Within the body of an item that has type parameter declarations, the names of its type parameters are types: + +~~~~ +fn map<A: Clone, B: Clone>(f: |A| -> B, xs: &[A]) -> ~[B] { + if xs.len() == 0 { + return ~[]; + } + let first: B = f(xs[0].clone()); + let rest: ~[B] = map(f, xs.slice(1, xs.len())); + return ~[first] + rest; +} +~~~~ + +Here, `first` has type `B`, referring to `map`'s `B` type parameter; +and `rest` has type `~[B]`, a vector type with element type `B`. + +### Self types + +The special type `self` has a meaning within methods inside an +impl item. It refers to the type of the implicit `self` argument. For +example, in: + +~~~~ +trait Printable { + fn make_string(&self) -> ~str; +} + +impl Printable for ~str { + fn make_string(&self) -> ~str { + (*self).clone() + } +} +~~~~ + +`self` refers to the value of type `~str` that is the receiver for a +call to the method `make_string`. + +## Type kinds + +Types in Rust are categorized into kinds, based on various properties of the components of the type. +The kinds are: + +`Freeze` + : Types of this kind are deeply immutable; + they contain no mutable memory locations + directly or indirectly via pointers. +`Send` + : Types of this kind can be safely sent between tasks. + This kind includes scalars, owning pointers, owned closures, and + structural types containing only other owned types. + All `Send` types are `'static`. +`Pod` + : Types of this kind consist of "Plain Old Data" + which can be copied by simply moving bits. + All values of this kind can be implicitly copied. + This kind includes scalars and immutable references, + as well as structural types containing other `Pod` types. +`'static` + : Types of this kind do not contain any references; + this can be a useful guarantee for code + that breaks borrowing assumptions + using [`unsafe` operations](#unsafe-functions). +`Drop` + : This is not strictly a kind, + but its presence interacts with kinds: + the `Drop` trait provides a single method `drop` + that takes no parameters, + and is run when values of the type are dropped. + Such a method is called a "destructor", + and are always executed in "top-down" order: + a value is completely destroyed + before any of the values it owns run their destructors. + Only `Send` types can implement `Drop`. + +_Default_ + : Types with destructors, closure environments, + and various other _non-first-class_ types, + are not copyable at all. + Such types can usually only be accessed through pointers, + or in some cases, moved between mutable locations. + +Kinds can be supplied as _bounds_ on type parameters, like traits, +in which case the parameter is constrained to types satisfying that kind. + +By default, type parameters do not carry any assumed kind-bounds at all. +When instantiating a type parameter, +the kind bounds on the parameter are checked +to be the same or narrower than the kind +of the type that it is instantiated with. + +Sending operations are not part of the Rust language, +but are implemented in the library. +Generic functions that send values +bound the kind of these values to sendable. + +# Memory and concurrency models + +Rust has a memory model centered around concurrently-executing _tasks_. Thus +its memory model and its concurrency model are best discussed simultaneously, +as parts of each only make sense when considered from the perspective of the +other. + +When reading about the memory model, keep in mind that it is partitioned in +order to support tasks; and when reading about tasks, keep in mind that their +isolation and communication mechanisms are only possible due to the ownership +and lifetime semantics of the memory model. + +## Memory model + +A Rust program's memory consists of a static set of *items*, a set of +[tasks](#tasks) each with its own *stack*, and a *heap*. Immutable portions of +the heap may be shared between tasks, mutable portions may not. + +Allocations in the stack consist of *slots*, and allocations in the heap +consist of *boxes*. + +### Memory allocation and lifetime + +The _items_ of a program are those functions, modules and types +that have their value calculated at compile-time and stored uniquely in the +memory image of the rust process. Items are neither dynamically allocated nor +freed. + +A task's _stack_ consists of activation frames automatically allocated on +entry to each function as the task executes. A stack allocation is reclaimed +when control leaves the frame containing it. + +The _heap_ is a general term that describes two separate sets of boxes: +managed boxes -- which may be subject to garbage collection -- and owned +boxes. The lifetime of an allocation in the heap depends on the lifetime of +the box values pointing to it. Since box values may themselves be passed in +and out of frames, or stored in the heap, heap allocations may outlive the +frame they are allocated within. + +### Memory ownership + +A task owns all memory it can *safely* reach through local variables, +as well as managed, owned boxes and references. + +When a task sends a value that has the `Send` trait to another task, +it loses ownership of the value sent and can no longer refer to it. +This is statically guaranteed by the combined use of "move semantics", +and the compiler-checked _meaning_ of the `Send` trait: +it is only instantiated for (transitively) sendable kinds of data constructor and pointers, +never including managed boxes or references. + +When a stack frame is exited, its local allocations are all released, and its +references to boxes (both managed and owned) are dropped. + +A managed box may (in the case of a recursive, mutable managed type) be cyclic; +in this case the release of memory inside the managed structure may be deferred +until task-local garbage collection can reclaim it. Code can ensure no such +delayed deallocation occurs by restricting itself to owned boxes and similar +unmanaged kinds of data. + +When a task finishes, its stack is necessarily empty and it therefore has no +references to any boxes; the remainder of its heap is immediately freed. + +### Memory slots + +A task's stack contains slots. + +A _slot_ is a component of a stack frame, either a function parameter, +a [temporary](#lvalues-rvalues-and-temporaries), or a local variable. + +A _local variable_ (or *stack-local* allocation) holds a value directly, +allocated within the stack's memory. The value is a part of the stack frame. + +Local variables are immutable unless declared otherwise like: `let mut x = ...`. + +Function parameters are immutable unless declared with `mut`. The +`mut` keyword applies only to the following parameter (so `|mut x, y|` +and `fn f(mut x: ~int, y: ~int)` declare one mutable variable `x` and +one immutable variable `y`). + +Methods that take either `self` or `~self` can optionally place them in a +mutable slot by prefixing them with `mut` (similar to regular arguments): + +~~~ +trait Changer { + fn change(mut self) -> Self; + fn modify(mut ~self) -> ~Self; +} +~~~ + +Local variables are not initialized when allocated; the entire frame worth of +local variables are allocated at once, on frame-entry, in an uninitialized +state. Subsequent statements within a function may or may not initialize the +local variables. Local variables can be used only after they have been +initialized; this is enforced by the compiler. + +### Memory boxes + +A _box_ is a reference to a heap allocation holding another value. There +are two kinds of boxes: *managed boxes* and *owned boxes*. + +A _managed box_ type or value is constructed by the prefix *at* sigil `@`. + +An _owned box_ type or value is constructed by the prefix *tilde* sigil `~`. + +Multiple managed box values can point to the same heap allocation; copying a +managed box value makes a shallow copy of the pointer (optionally incrementing +a reference count, if the managed box is implemented through +reference-counting). + +Owned box values exist in 1:1 correspondence with their heap allocation. + +An example of constructing one managed box type and value, and one owned box +type and value: + +~~~~ +let x: @int = @10; +let x: ~int = ~10; +~~~~ + +Some operations (such as field selection) implicitly dereference boxes. An +example of an _implicit dereference_ operation performed on box values: + +~~~~ +struct Foo { y: int } +let x = @Foo{y: 10}; +assert!(x.y == 10); +~~~~ + +Other operations act on box values as single-word-sized address values. For +these operations, to access the value held in the box requires an explicit +dereference of the box value. Explicitly dereferencing a box is indicated with +the unary *star* operator `*`. Examples of such _explicit dereference_ +operations are: + +* copying box values (`x = y`) +* passing box values to functions (`f(x,y)`) + +An example of an explicit-dereference operation performed on box values: + +~~~~ +fn takes_boxed(b: @int) { +} + +fn takes_unboxed(b: int) { +} + +fn main() { + let x: @int = @10; + takes_boxed(x); + takes_unboxed(*x); +} +~~~~ + +## Tasks + +An executing Rust program consists of a tree of tasks. +A Rust _task_ consists of an entry function, a stack, +a set of outgoing communication channels and incoming communication ports, +and ownership of some portion of the heap of a single operating-system process. +(We expect that many programs will not use channels and ports directly, +but will instead use higher-level abstractions provided in standard libraries, +such as pipes.) + +Multiple Rust tasks may coexist in a single operating-system process. +The runtime scheduler maps tasks to a certain number of operating-system threads. +By default, the scheduler chooses the number of threads based on +the number of concurrent physical CPUs detected at startup. +It's also possible to override this choice at runtime. +When the number of tasks exceeds the number of threads -- which is likely -- +the scheduler multiplexes the tasks onto threads.^[ +This is an M:N scheduler, +which is known to give suboptimal results for CPU-bound concurrency problems. +In such cases, running with the same number of threads and tasks can yield better results. +Rust has M:N scheduling in order to support very large numbers of tasks +in contexts where threads are too resource-intensive to use in large number. +The cost of threads varies substantially per operating system, and is sometimes quite low, +so this flexibility is not always worth exploiting.] + +### Communication between tasks + +Rust tasks are isolated and generally unable to interfere with one another's memory directly, +except through [`unsafe` code](#unsafe-functions). +All contact between tasks is mediated by safe forms of ownership transfer, +and data races on memory are prohibited by the type system. + +Inter-task communication and co-ordination facilities are provided in the standard library. +These include: + + - synchronous and asynchronous communication channels with various communication topologies + - read-only and read-write shared variables with various safe mutual exclusion patterns + - simple locks and semaphores + +When such facilities carry values, the values are restricted to the [`Send` type-kind](#type-kinds). +Restricting communication interfaces to this kind ensures that no references or managed pointers move between tasks. +Thus access to an entire data structure can be mediated through its owning "root" value; +no further locking or copying is required to avoid data races within the substructure of such a value. + +### Task lifecycle + +The _lifecycle_ of a task consists of a finite set of states and events +that cause transitions between the states. The lifecycle states of a task are: + +* running +* blocked +* failing +* dead + +A task begins its lifecycle -- once it has been spawned -- in the *running* +state. In this state it executes the statements of its entry function, and any +functions called by the entry function. + +A task may transition from the *running* state to the *blocked* +state any time it makes a blocking communication call. When the +call can be completed -- when a message arrives at a sender, or a +buffer opens to receive a message -- then the blocked task will +unblock and transition back to *running*. + +A task may transition to the *failing* state at any time, due being +killed by some external event or internally, from the evaluation of a +`fail!()` macro. Once *failing*, a task unwinds its stack and +transitions to the *dead* state. Unwinding the stack of a task is done by +the task itself, on its own control stack. If a value with a destructor is +freed during unwinding, the code for the destructor is run, also on the task's +control stack. Running the destructor code causes a temporary transition to a +*running* state, and allows the destructor code to cause any subsequent +state transitions. The original task of unwinding and failing thereby may +suspend temporarily, and may involve (recursive) unwinding of the stack of a +failed destructor. Nonetheless, the outermost unwinding activity will continue +until the stack is unwound and the task transitions to the *dead* +state. There is no way to "recover" from task failure. Once a task has +temporarily suspended its unwinding in the *failing* state, failure +occurring from within this destructor results in *hard* failure. +A hard failure currently results in the process aborting. + +A task in the *dead* state cannot transition to other states; it exists +only to have its termination status inspected by other tasks, and/or to await +reclamation when the last reference to it drops. + +### Task scheduling + +The currently scheduled task is given a finite *time slice* in which to +execute, after which it is *descheduled* at a loop-edge or similar +preemption point, and another task within is scheduled, pseudo-randomly. + +An executing task can yield control at any time, by making a library call to +`std::task::yield`, which deschedules it immediately. Entering any other +non-executing state (blocked, dead) similarly deschedules the task. + +# Runtime services, linkage and debugging + +The Rust _runtime_ is a relatively compact collection of C++ and Rust code +that provides fundamental services and datatypes to all Rust tasks at +run-time. It is smaller and simpler than many modern language runtimes. It is +tightly integrated into the language's execution model of memory, tasks, +communication and logging. + +> **Note:** The runtime library will merge with the `std` library in future versions of Rust. + +### Memory allocation + +The runtime memory-management system is based on a _service-provider interface_, +through which the runtime requests blocks of memory from its environment +and releases them back to its environment when they are no longer needed. +The default implementation of the service-provider interface +consists of the C runtime functions `malloc` and `free`. + +The runtime memory-management system, in turn, supplies Rust tasks with +facilities for allocating releasing stacks, as well as allocating and freeing +heap data. + +### Built in types + +The runtime provides C and Rust code to assist with various built-in types, +such as vectors, strings, and the low level communication system (ports, +channels, tasks). + +Support for other built-in types such as simple types, tuples, records, and +enums is open-coded by the Rust compiler. + +### Task scheduling and communication + +The runtime provides code to manage inter-task communication. This includes +the system of task-lifecycle state transitions depending on the contents of +queues, as well as code to copy values between queues and their recipients and +to serialize values for transmission over operating-system inter-process +communication facilities. + +### Linkage + +The Rust compiler supports various methods to link crates together both +statically and dynamically. This section will explore the various methods to +link Rust crates together, and more information about native libraries can be +found in the [ffi tutorial][ffi]. + +In one session of compilation, the compiler can generate multiple artifacts +through the usage of command line flags and the `crate_type` attribute. + +* `--bin`, `#[crate_type = "bin"]` - A runnable executable will be produced. + This requires that there is a `main` function in the crate which will be run + when the program begins executing. This will link in all Rust and native + dependencies, producing a distributable binary. + +* `--lib`, `#[crate_type = "lib"]` - A Rust library will be produced. This is + an ambiguous concept as to what exactly is produced because a library can + manifest itself in several forms. The purpose of this generic `lib` option is + to generate the "compiler recommended" style of library. The output library + will always be usable by rustc, but the actual type of library may change + from time-to-time. The remaining output types are all different flavors of + libraries, and the `lib` type can be seen as an alias for one of them (but + the actual one is compiler-defined). + +* `--dylib`, `#[crate_type = "dylib"]` - A dynamic Rust library will be + produced. This is different from the `lib` output type in that this forces + dynamic library generation. The resulting dynamic library can be used as a + dependency for other libraries and/or executables. This output type will + create `*.so` files on linux, `*.dylib` files on osx, and `*.dll` files on + windows. + +* `--staticlib`, `#[crate_type = "staticlib"]` - A static system library will + be produced. This is different from other library outputs in that the Rust + compiler will never attempt to link to `staticlib` outputs. The purpose of + this output type is to create a static library containing all of the local + crate's code along with all upstream dependencies. The static library is + actually a `*.a` archive on linux and osx and a `*.lib` file on windows. This + format is recommended for use in situtations such as linking Rust code into an + existing non-Rust application because it will not have dynamic dependencies on + other Rust code. + +* `--rlib`, `#[crate_type = "rlib"]` - A "Rust library" file will be produced. + This is used as an intermediate artifact and can be thought of as a "static + Rust library". These `rlib` files, unlike `staticlib` files, are interpreted + by the Rust compiler in future linkage. This essentially means that `rustc` + will look for metadata in `rlib` files like it looks for metadata in dynamic + libraries. This form of output is used to produce statically linked + executables as well as `staticlib` outputs. + +Note that these outputs are stackable in the sense that if multiple are +specified, then the compiler will produce each form of output at once without +having to recompile. + +With all these different kinds of outputs, if crate A depends on crate B, then +the compiler could find B in various different forms throughout the system. The +only forms looked for by the compiler, however, are the `rlib` format and the +dynamic library format. With these two options for a dependent library, the +compiler must at some point make a choice between these two formats. With this +in mind, the compiler follows these rules when determining what format of +dependencies will be used: + +1. If a dynamic library is being produced, then it is required for all upstream + Rust dependencies to also be dynamic. This is a limitation of the current + implementation of the linkage model. The reason behind this limitation is to + prevent multiple copies of the same upstream library from showing up, and in + the future it is planned to support a mixture of dynamic and static linking. + + When producing a dynamic library, the compiler will generate an error if an + upstream dependency could not be found, and also if an upstream dependency + could only be found in an `rlib` format. Remember that `staticlib` formats + are always ignored by `rustc` for crate-linking purposes. + +2. If a static library is being produced, all upstream dependecies are + required to be available in `rlib` formats. This requirement stems from the + same reasons that a dynamic library must have all dynamic dependencies. + + Note that it is impossible to link in native dynamic dependencies to a static + library, and in this case warnings will be printed about all unlinked native + dynamic dependencies. + +3. If an `rlib` file is being produced, then there are no restrictions on what + format the upstream dependencies are available in. It is simply required that + all upstream dependencies be available for reading metadata from. + + The reason for this is that `rlib` files do not contain any of their upstream + dependencies. It wouldn't be very efficient for all `rlib` files to contain a + copy of `libstd.rlib`! + +4. If an executable is being produced, then things get a little interesting. As + with the above limitations in dynamic and static libraries, it is required + for all upstream dependencies to be in the same format. The next question is + whether to prefer a dynamic or a static format. The compiler currently favors + static linking over dynamic linking, but this can be inverted with the `-Z + prefer-dynamic` flag to the compiler. + + What this means is that first the compiler will attempt to find all upstream + dependencies as `rlib` files, and if successful, it will create a statically + linked executable. If an upstream dependency is missing as an `rlib` file, + then the compiler will force all dependencies to be dynamic and will generate + errors if dynamic versions could not be found. + +In general, `--bin` or `--lib` should be sufficient for all compilation needs, +and the other options are just available if more fine-grained control is desired +over the output format of a Rust crate. + +### Logging system + +The runtime contains a system for directing [logging +expressions](#logging-expressions) to a logging console and/or internal logging +buffers. Logging can be enabled per module. + +Logging output is enabled by setting the `RUST_LOG` environment +variable. `RUST_LOG` accepts a logging specification made up of a +comma-separated list of paths, with optional log levels. For each +module containing log expressions, if `RUST_LOG` contains the path to +that module or a parent of that module, then logs of the appropriate +level will be output to the console. + +The path to a module consists of the crate name, any parent modules, +then the module itself, all separated by double colons (`::`). The +optional log level can be appended to the module path with an equals +sign (`=`) followed by the log level, from 1 to 4, inclusive. Level 1 +is the error level, 2 is warning, 3 info, and 4 debug. You can also +use the symbolic constants `error`, `warn`, `info`, and `debug`. Any +logs less than or equal to the specified level will be output. If not +specified then log level 4 is assumed. Debug messages can be omitted +by passing `--cfg ndebug` to `rustc`. + +As an example, to see all the logs generated by the compiler, you would set +`RUST_LOG` to `rustc`, which is the crate name (as specified in its `crate_id` +[attribute](#attributes)). To narrow down the logs to just crate resolution, +you would set it to `rustc::metadata::creader`. To see just error logging +use `rustc=0`. + +Note that when compiling source files that don't specify a +crate name the crate is given a default name that matches the source file, +with the extension removed. In that case, to turn on logging for a program +compiled from, e.g. `helloworld.rs`, `RUST_LOG` should be set to `helloworld`. + +As a convenience, the logging spec can also be set to a special pseudo-crate, +`::help`. In this case, when the application starts, the runtime will +simply output a list of loaded modules containing log expressions, then exit. + +#### Logging Expressions + +Rust provides several macros to log information. Here's a simple Rust program +that demonstrates all four of them: + +~~~~ +fn main() { + error!("This is an error log") + warn!("This is a warn log") + info!("this is an info log") + debug!("This is a debug log") +} +~~~~ + +These four log levels correspond to levels 1-4, as controlled by `RUST_LOG`: + +```bash +$ RUST_LOG=rust=3 ./rust +This is an error log +This is a warn log +this is an info log +``` + +# Appendix: Rationales and design tradeoffs + +*TODO*. + +# Appendix: Influences and further references + +## Influences + +> The essential problem that must be solved in making a fault-tolerant +> software system is therefore that of fault-isolation. Different programmers +> will write different modules, some modules will be correct, others will have +> errors. We do not want the errors in one module to adversely affect the +> behaviour of a module which does not have any errors. +> +> — Joe Armstrong + +> In our approach, all data is private to some process, and processes can +> only communicate through communications channels. *Security*, as used +> in this paper, is the property which guarantees that processes in a system +> cannot affect each other except by explicit communication. +> +> When security is absent, nothing which can be proven about a single module +> in isolation can be guaranteed to hold when that module is embedded in a +> system [...] +> +> — Robert Strom and Shaula Yemini + +> Concurrent and applicative programming complement each other. The +> ability to send messages on channels provides I/O without side effects, +> while the avoidance of shared data helps keep concurrent processes from +> colliding. +> +> — Rob Pike + +Rust is not a particularly original language. It may however appear unusual +by contemporary standards, as its design elements are drawn from a number of +"historical" languages that have, with a few exceptions, fallen out of +favour. Five prominent lineages contribute the most, though their influences +have come and gone during the course of Rust's development: + +* The NIL (1981) and Hermes (1990) family. These languages were developed by + Robert Strom, Shaula Yemini, David Bacon and others in their group at IBM + Watson Research Center (Yorktown Heights, NY, USA). + +* The Erlang (1987) language, developed by Joe Armstrong, Robert Virding, Claes + Wikström, Mike Williams and others in their group at the Ericsson Computer + Science Laboratory (Älvsjö, Stockholm, Sweden) . + +* The Sather (1990) language, developed by Stephen Omohundro, Chu-Cheow Lim, + Heinz Schmidt and others in their group at The International Computer + Science Institute of the University of California, Berkeley (Berkeley, CA, + USA). + +* The Newsqueak (1988), Alef (1995), and Limbo (1996) family. These + languages were developed by Rob Pike, Phil Winterbottom, Sean Dorward and + others in their group at Bell Labs Computing Sciences Research Center + (Murray Hill, NJ, USA). + +* The Napier (1985) and Napier88 (1988) family. These languages were + developed by Malcolm Atkinson, Ron Morrison and others in their group at + the University of St. Andrews (St. Andrews, Fife, UK). + +Additional specific influences can be seen from the following languages: + +* The structural algebraic types and compilation manager of SML. +* The attribute and assembly systems of C#. +* The references and deterministic destructor system of C++. +* The memory region systems of the ML Kit and Cyclone. +* The typeclass system of Haskell. +* The lexical identifier rule of Python. +* The block syntax of Ruby. + +[ffi]: tutorial-ffi.html diff --git a/src/doc/rustdoc.md b/src/doc/rustdoc.md new file mode 100644 index 00000000000..72282030fb3 --- /dev/null +++ b/src/doc/rustdoc.md @@ -0,0 +1,182 @@ +% Rust Documentation + +`rustdoc` is the built-in tool for generating documentation. It integrates +with the compiler to provide accurate hyperlinking between usage of types and +their documentation. Furthermore, by not using a separate parser, it will +never reject your valid Rust code. + +# Creating Documentation + +Documenting Rust APIs is quite simple. To document a given item, we have "doc +comments": + +~~~ +// the "link" crate attribute is currently required for rustdoc, but normally +// isn't needed. +#[crate_id = "universe"]; +#[crate_type="lib"]; + +//! Tools for dealing with universes (this is a doc comment, and is shown on +//! the crate index page. The ! makes it apply to the parent of the comment, +//! rather than what follows). + +/// Widgets are very common (this is a doc comment, and will show up on +/// Widget's documentation). +pub struct Widget { + /// All widgets have a purpose (this is a doc comment, and will show up + /// the field's documentation). + purpose: ~str, + /// Humans are not allowed to understand some widgets + understandable: bool +} + +pub fn recalibrate() { + //! Recalibrate a pesky universe (this is also a doc comment, like above, + //! the documentation will be applied to the *parent* item, so + //! `recalibrate`). + /* ... */ +} +~~~ + +Doc comments are markdown, and are currently parsed with the +[sundown][sundown] library. rustdoc does not yet do any fanciness such as +referencing other items inline, like javadoc's `@see`. One exception to this +is that the first paragrah will be used as the "summary" of an item in the +generated documentation: + +~~~ +/// A whizbang. Does stuff. (this line is the summary) +/// +/// Whizbangs are ... +struct Whizbang; +~~~ + +To generate the docs, run `rustdoc universe.rs`. By default, it generates a +directory called `doc`, with the documentation for `universe` being in +`doc/universe/index.html`. If you are using other crates with `extern mod`, +rustdoc will even link to them when you use their types, as long as their +documentation has already been generated by a previous run of rustdoc, or the +crate advertises that its documentation is hosted at a given URL. + +The generated output can be controlled with the `doc` crate attribute, which +is how the above advertisement works. An example from the `libstd` +documentation: + +~~~ +#[doc(html_logo_url = "http://www.rust-lang.org/logos/rust-logo-128x128-blk.png", + html_favicon_url = "http://www.rust-lang.org/favicon.ico", + html_root_url = "http://static.rust-lang.org/doc/master")]; +~~~ + +The `html_root_url` is the prefix that rustdoc will apply to any references to +that crate's types etc. + +rustdoc can also generate JSON, for consumption by other tools, with +`rustdoc --output-format json`, and also consume already-generated JSON with +`rustdoc --input-format json`. + +# Using the Documentation + +The web pages generated by rustdoc present the same logical heirarchy that one +writes a library with. Every kind of item (function, struct, etc) has its own +color, and one can always click on a colored type to jump to its +documentation. There is a search bar at the top, which is powered by some +javascript and a statically-generated search index. No special web server is +required for the search. + +[sundown]: https://github.com/vmg/sundown/ + +# Testing the Documentation + +`rustdoc` has support for testing code examples which appear in the +documentation. This is helpful for keeping code examples up to date with the +source code. + +To test documentation, the `--test` argument is passed to rustdoc: + +~~~ +rustdoc --test crate.rs +~~~ + +## Defining tests + +Rust documentation currently uses the markdown format, and code blocks can refer +to any piece of code-related documentation, which isn't always rust. Because of +this, only code blocks with the language of "rust" will be considered for +testing. + +~~~ +```rust +// This is a testable code block +``` + +``` +// This is not a testable code block +``` + + // This is not a testable code block (4-space indent) +~~~ + +In addition to only testing "rust"-language code blocks, there are additional +specifiers that can be used to dictate how a code block is tested: + +~~~ +```rust,ignore +// This code block is ignored by rustdoc, but is passed through to the test +// harness +``` + +```rust,should_fail +// This code block is expected to generate a failure +``` +~~~ + +Rustdoc also supplies some extra sugar for helping with some tedious +documentation examples. If a line is prefixed with `# `, then the line +will not show up in the HTML documentation, but it will be used when +testing the code block (NB. the space after the `#` is required, so +that one can still write things like `#[deriving(Eq)]`). + +~~~ +```rust +# /!\ The three following lines are comments, which are usually stripped off by +# the doc-generating tool. In order to display them anyway in this particular +# case, the character following the leading '#' is not a usual space like in +# these first five lines but a non breakable one. +# +# // showing 'fib' in this documentation would just be tedious and detracts from +# // what's actualy being documented. +# fn fib(n: int) { n + 2 } + +do spawn { fib(200); } +``` +~~~ + +The documentation online would look like `do spawn { fib(200); }`, but when +testing this code, the `fib` function will be included (so it can compile). + +## Running tests (advanced) + +Running tests often requires some special configuration to filter tests, find +libraries, or try running ignored examples. The testing framework that rustdoc +uses is build on `extra::test`, which is also used when you compile crates with +rustc's `--test` flag. Extra arguments can be passed to rustdoc's test harness +with the `--test-args` flag. + +~~~ +// Only run tests containing 'foo' in their name +rustdoc --test lib.rs --test-args 'foo' + +// See what's possible when running tests +rustdoc --test lib.rs --test-args '--help' + +// Run all ignored tests +rustdoc --test lib.rs --test-args '--ignored' +~~~ + +When testing a library, code examples will often show how functions are used, +and this code often requires `use`-ing paths from the crate. To accomodate this, +rustdoc will implicitly add `extern mod <crate>;` where `<crate>` is the name of +the crate being tested to the top of each code example. This means that rustdoc +must be able to find a compiled version of the library crate being tested. Extra +search paths may be added via the `-L` flag to `rustdoc`. diff --git a/src/doc/tutorial.md b/src/doc/tutorial.md new file mode 100644 index 00000000000..5122ac35602 --- /dev/null +++ b/src/doc/tutorial.md @@ -0,0 +1,3275 @@ +% The Rust Language Tutorial + +# Introduction + +Rust is a programming language with a focus on type safety, memory +safety, concurrency and performance. It is intended for writing +large-scale, high-performance software that is free from several +classes of common errors. Rust has a sophisticated memory model that +encourages efficient data structures and safe concurrency patterns, +forbidding invalid memory accesses that would otherwise cause +segmentation faults. It is statically typed and compiled ahead of +time. + +As a multi-paradigm language, Rust supports writing code in +procedural, functional and object-oriented styles. Some of its +pleasant high-level features include: + +* **Type inference.** Type annotations on local variable declarations + are optional. +* **Safe task-based concurrency.** Rust's lightweight tasks do not share + memory, instead communicating through messages. +* **Higher-order functions.** Efficient and flexible closures provide + iteration and other control structures +* **Pattern matching and algebraic data types.** Pattern matching on + Rust's enumeration types (a more powerful version of C's enums, + similar to algebraic data types in functional languages) is a + compact and expressive way to encode program logic. +* **Polymorphism.** Rust has type-parametric functions and + types, type classes and OO-style interfaces. + +## Scope + +This is an introductory tutorial for the Rust programming language. It +covers the fundamentals of the language, including the syntax, the +type system and memory model, generics, and modules. [Additional +tutorials](#what-next) cover specific language features in greater +depth. + +This tutorial assumes that the reader is already familiar with one or +more languages in the C family. Understanding of pointers and general +memory management techniques will help. + +## Conventions + +Throughout the tutorial, language keywords and identifiers defined in +example code are displayed in `code font`. + +Code snippets are indented, and also shown in a monospaced font. Not +all snippets constitute whole programs. For brevity, we'll often show +fragments of programs that don't compile on their own. To try them +out, you might have to wrap them in `fn main() { ... }`, and make sure +they don't contain references to names that aren't actually defined. + +> ***Warning:*** Rust is a language under ongoing development. Notes +> about potential changes to the language, implementation +> deficiencies, and other caveats appear offset in blockquotes. + +# Getting started + +> **NOTE**: The tarball and installer links are for the most recent release, +> not master. + +The Rust compiler currently must be built from a [tarball] or [git], unless +you are on Windows, in which case using the [installer][win-exe] is +recommended. There is a list of community-maintained nightly builds and +packages [on the wiki][wiki-packages]. + +Since the Rust compiler is written in Rust, it must be built by +a precompiled "snapshot" version of itself (made in an earlier state +of development). The source build automatically fetches these snapshots +from the Internet on our supported platforms. + +Snapshot binaries are currently built and tested on several platforms: + +* Windows (7, 8, Server 2008 R2), x86 only +* Linux (2.6.18 or later, various distributions), x86 and x86-64 +* OSX 10.7 (Lion) or greater, x86 and x86-64 + +You may find that other platforms work, but these are our "tier 1" +supported build environments that are most likely to work. + +> ***Note:*** Windows users should read the detailed +> "[getting started][wiki-start]" notes on the wiki. Even when using +> the binary installer, the Windows build requires a MinGW installation, +> the precise details of which are not discussed here. Finally, `rustc` may +> need to be [referred to as `rustc.exe`][bug-3319]. It's a bummer, we +> know. + +[bug-3319]: https://github.com/mozilla/rust/issues/3319 +[wiki-start]: https://github.com/mozilla/rust/wiki/Note-getting-started-developing-Rust +[git]: https://github.com/mozilla/rust.git + +To build from source you will also need the following prerequisite +packages: + +* g++ 4.4 or clang++ 3.x +* python 2.6 or later (but not 3.x) +* perl 5.0 or later +* gnu make 3.81 or later +* curl + +If you've fulfilled those prerequisites, something along these lines +should work. + +~~~~ {.notrust} +$ curl -O http://static.rust-lang.org/dist/rust-0.9.tar.gz +$ tar -xzf rust-0.9.tar.gz +$ cd rust-0.9 +$ ./configure +$ make && make install +~~~~ + +You may need to use `sudo make install` if you do not normally have +permission to modify the destination directory. The install locations +can be adjusted by passing a `--prefix` argument to +`configure`. Various other options are also supported: pass `--help` +for more information on them. + +When complete, `make install` will place several programs into +`/usr/local/bin`: `rustc`, the Rust compiler, and `rustdoc`, the +API-documentation tool. + +[tarball]: http://static.rust-lang.org/dist/rust-0.9.tar.gz +[win-exe]: http://static.rust-lang.org/dist/rust-0.9-install.exe + +## Compiling your first program + +Rust program files are, by convention, given the extension `.rs`. Say +we have a file `hello.rs` containing this program: + +~~~~ +fn main() { + println!("hello?"); +} +~~~~ + +If the Rust compiler was installed successfully, running `rustc +hello.rs` will produce an executable called `hello` (or `hello.exe` on +Windows) which, upon running, will likely do exactly what you expect. + +The Rust compiler tries to provide useful information when it encounters an +error. If you introduce an error into the program (for example, by changing +`println!` to some nonexistent macro), and then compile it, you'll see +an error message like this: + +~~~~ {.notrust} +hello.rs:2:5: 2:24 error: macro undefined: 'print_with_unicorns' +hello.rs:2 print_with_unicorns!("hello?"); + ^~~~~~~~~~~~~~~~~~~ +~~~~ + +In its simplest form, a Rust program is a `.rs` file with some types +and functions defined in it. If it has a `main` function, it can be +compiled to an executable. Rust does not allow code that's not a +declaration to appear at the top level of the file: all statements must +live inside a function. Rust programs can also be compiled as +libraries, and included in other programs, even ones not written in Rust. + +## Editing Rust code + +There are vim highlighting and indentation scripts in the Rust source +distribution under `src/etc/vim/`. There is an emacs mode under +`src/etc/emacs/` called `rust-mode`, but do read the instructions +included in that directory. In particular, if you are running emacs +24, then using emacs's internal package manager to install `rust-mode` +is the easiest way to keep it up to date. There is also a package for +Sublime Text 2, available both [standalone][sublime] and through +[Sublime Package Control][sublime-pkg], and support for Kate +under `src/etc/kate`. + +A community-maintained list of available Rust tooling is [on the +wiki][wiki-packages]. + +There is ctags support via `src/etc/ctags.rust`, but many other +tools and editors are not yet supported. If you end up writing a Rust +mode for your favorite editor, let us know so that we can link to it. + +[sublime]: http://github.com/dbp/sublime-rust +[sublime-pkg]: http://wbond.net/sublime_packages/package_control + +# Syntax basics + +Assuming you've programmed in any C-family language (C++, Java, +JavaScript, C#, or PHP), Rust will feel familiar. Code is arranged +in blocks delineated by curly braces; there are control structures +for branching and looping, like the familiar `if` and `while`; function +calls are written `myfunc(arg1, arg2)`; operators are written the same +and mostly have the same precedence as in C; comments are again like C; +module names are separated with double-colon (`::`) as with C++. + +The main surface difference to be aware of is that the condition at +the head of control structures like `if` and `while` does not require +parentheses, while their bodies *must* be wrapped in +braces. Single-statement, unbraced bodies are not allowed. + +~~~~ +# mod universe { pub fn recalibrate() -> bool { true } } +fn main() { + /* A simple loop */ + loop { + // A tricky calculation + if universe::recalibrate() { + return; + } + } +} +~~~~ + +The `let` keyword introduces a local variable. Variables are immutable by +default. To introduce a local variable that you can re-assign later, use `let +mut` instead. + +~~~~ +let hi = "hi"; +let mut count = 0; + +while count < 10 { + println!("count is {}", count); + count += 1; +} +~~~~ + +Although Rust can almost always infer the types of local variables, you can +specify a variable's type by following it in the `let` with a colon, then the +type name. Static items, on the other hand, always require a type annotation. + + +~~~~ +static MONSTER_FACTOR: f64 = 57.8; +let monster_size = MONSTER_FACTOR * 10.0; +let monster_size: int = 50; +~~~~ + +Local variables may shadow earlier declarations, as in the previous example: +`monster_size` was first declared as a `f64`, and then a second +`monster_size` was declared as an `int`. If you were to actually compile this +example, though, the compiler would determine that the first `monster_size` is +unused and issue a warning (because this situation is likely to indicate a +programmer error). For occasions where unused variables are intentional, their +names may be prefixed with an underscore to silence the warning, like `let +_monster_size = 50;`. + +Rust identifiers start with an alphabetic +character or an underscore, and after that may contain any sequence of +alphabetic characters, numbers, or underscores. The preferred style is to +write function, variable, and module names with lowercase letters, using +underscores where they help readability, while writing types in camel case. + +~~~ +let my_variable = 100; +type MyType = int; // primitive types are _not_ camel case +~~~ + +## Expressions and semicolons + +Though it isn't apparent in all code, there is a fundamental +difference between Rust's syntax and predecessors like C. +Many constructs that are statements in C are expressions +in Rust, allowing code to be more concise. For example, you might +write a piece of code like this: + +~~~~ +# let item = "salad"; +let price; +if item == "salad" { + price = 3.50; +} else if item == "muffin" { + price = 2.25; +} else { + price = 2.00; +} +~~~~ + +But, in Rust, you don't have to repeat the name `price`: + +~~~~ +# let item = "salad"; +let price = + if item == "salad" { + 3.50 + } else if item == "muffin" { + 2.25 + } else { + 2.00 + }; +~~~~ + +Both pieces of code are exactly equivalent: they assign a value to +`price` depending on the condition that holds. Note that there +are no semicolons in the blocks of the second snippet. This is +important: the lack of a semicolon after the last statement in a +braced block gives the whole block the value of that last expression. + +Put another way, the semicolon in Rust *ignores the value of an expression*. +Thus, if the branches of the `if` had looked like `{ 4; }`, the above example +would simply assign `()` (nil or void) to `price`. But without the semicolon, each +branch has a different value, and `price` gets the value of the branch that +was taken. + +In short, everything that's not a declaration (declarations are `let` for +variables; `fn` for functions; and any top-level named items such as +[traits](#traits), [enum types](#enums), and static items) is an +expression, including function bodies. + +~~~~ +fn is_four(x: int) -> bool { + // No need for a return statement. The result of the expression + // is used as the return value. + x == 4 +} +~~~~ + +## Primitive types and literals + +There are general signed and unsigned integer types, `int` and `uint`, +as well as 8-, 16-, 32-, and 64-bit variants, `i8`, `u16`, etc. +Integers can be written in decimal (`144`), hexadecimal (`0x90`), octal (`0o70`), or +binary (`0b10010000`) base. Each integral type has a corresponding literal +suffix that can be used to indicate the type of a literal: `i` for `int`, +`u` for `uint`, `i8` for the `i8` type. + +In the absence of an integer literal suffix, Rust will infer the +integer type based on type annotations and function signatures in the +surrounding program. In the absence of any type information at all, +Rust will assume that an unsuffixed integer literal has type +`int`. + +~~~~ +let a = 1; // `a` is an `int` +let b = 10i; // `b` is an `int`, due to the `i` suffix +let c = 100u; // `c` is a `uint` +let d = 1000i32; // `d` is an `i32` +~~~~ + +There are two floating-point types: `f32`, and `f64`. +Floating-point numbers are written `0.0`, `1e6`, or `2.1e-4`. +Like integers, floating-point literals are inferred to the correct type. +Suffixes `f32`, and `f64` can be used to create literals of a specific type. + +The keywords `true` and `false` produce literals of type `bool`. + +Characters, the `char` type, are four-byte Unicode codepoints, +whose literals are written between single quotes, as in `'x'`. +Just like C, Rust understands a number of character escapes, using the backslash +character, such as `\n`, `\r`, and `\t`. String literals, +written between double quotes, allow the same escape sequences, and do no +other processing, unlike languages such as PHP or shell. + +On the other hand, raw string literals do not process any escape sequences. +They are written as `r##"blah"##`, with a matching number of zero or more `#` +before the opening and after the closing quote, and can contain any sequence of +characters except their closing delimiter. More on strings +[later](#vectors-and-strings). + +The nil type, written `()`, has a single value, also written `()`. + +## Operators + +Rust's set of operators contains very few surprises. Arithmetic is done with +`*`, `/`, `%`, `+`, and `-` (multiply, quotient, remainder, add, and subtract). `-` is +also a unary prefix operator that negates numbers. As in C, the bitwise operators +`>>`, `<<`, `&`, `|`, and `^` are also supported. + +Note that, if applied to an integer value, `!` flips all the bits (bitwise +NOT, like `~` in C). + +The comparison operators are the traditional `==`, `!=`, `<`, `>`, +`<=`, and `>=`. Short-circuiting (lazy) boolean operators are written +`&&` (and) and `||` (or). + +For compile-time type casting, Rust uses the binary `as` operator. It takes +an expression on the left side and a type on the right side and will, if a +meaningful conversion exists, convert the result of the expression to the +given type. Generally, `as` is only used with the primitive numeric types or +pointers, and is not overloadable. [`transmute`][transmute] can be used for +unsafe C-like casting of same-sized types. + +~~~~ +let x: f64 = 4.0; +let y: uint = x as uint; +assert!(y == 4u); +~~~~ + +[transmute]: http://static.rust-lang.org/doc/master/std/cast/fn.transmute.html + +## Syntax extensions + +*Syntax extensions* are special forms that are not built into the language, +but are instead provided by the libraries. To make it clear to the reader when +a name refers to a syntax extension, the names of all syntax extensions end +with `!`. The standard library defines a few syntax extensions, the most +useful of which is [`format!`][fmt], a `sprintf`-like text formatter that you +will often see in examples, and its related family of macros: `print!`, +`println!`, and `write!`. + +`format!` draws syntax from Python, but contains many of the same principles +that [printf][pf] has. Unlike printf, `format!` will give you a compile-time +error when the types of the directives don't match the types of the arguments. + +~~~~ +# let mystery_object = (); + +// `{}` will print the "default format" of a type +println!("{} is {}", "the answer", 43); + +// `{:?}` will conveniently print any type +println!("what is this thing: {:?}", mystery_object); +~~~~ + +[pf]: http://en.cppreference.com/w/cpp/io/c/fprintf +[fmt]: http://static.rust-lang.org/doc/master/std/fmt/index.html + +You can define your own syntax extensions with the macro system. For details, +see the [macro tutorial][macros]. Note that macro definition is currently +considered an unstable feature. + +# Control structures + +## Conditionals + +We've seen `if` expressions a few times already. To recap, braces are +compulsory, an `if` can have an optional `else` clause, and multiple +`if`/`else` constructs can be chained together: + +~~~~ +if false { + println!("that's odd"); +} else if true { + println!("right"); +} else { + println!("neither true nor false"); +} +~~~~ + +The condition given to an `if` construct *must* be of type `bool` (no +implicit conversion happens). If the arms are blocks that have a +value, this value must be of the same type for every arm in which +control reaches the end of the block: + +~~~~ +fn signum(x: int) -> int { + if x < 0 { -1 } + else if x > 0 { 1 } + else { 0 } +} +~~~~ + +## Pattern matching + +Rust's `match` construct is a generalized, cleaned-up version of C's +`switch` construct. You provide it with a value and a number of +*arms*, each labelled with a pattern, and the code compares the value +against each pattern in order until one matches. The matching pattern +executes its corresponding arm. + +~~~~ +# let my_number = 1; +match my_number { + 0 => println!("zero"), + 1 | 2 => println!("one or two"), + 3..10 => println!("three to ten"), + _ => println!("something else") +} +~~~~ + +Unlike in C, there is no "falling through" between arms: only one arm +executes, and it doesn't have to explicitly `break` out of the +construct when it is finished. + +A `match` arm consists of a *pattern*, then an arrow `=>`, followed by +an *action* (expression). Literals are valid patterns and match only +their own value. A single arm may match multiple different patterns by +combining them with the pipe operator (`|`), so long as every pattern +binds the same set of variables. Ranges of numeric literal patterns +can be expressed with two dots, as in `M..N`. The underscore (`_`) is +a wildcard pattern that matches any single value. (`..`) is a different +wildcard that can match one or more fields in an `enum` variant. + +The patterns in a match arm are followed by a fat arrow, `=>`, then an +expression to evaluate. Each case is separated by commas. It's often +convenient to use a block expression for each case, in which case the +commas are optional. + +~~~ +# let my_number = 1; +match my_number { + 0 => { println!("zero") } + _ => { println!("something else") } +} +~~~ + +`match` constructs must be *exhaustive*: they must have an arm +covering every possible case. For example, the typechecker would +reject the previous example if the arm with the wildcard pattern was +omitted. + +A powerful application of pattern matching is *destructuring*: +matching in order to bind names to the contents of data +types. + +> ***Note:*** The following code makes use of tuples (`(f64, f64)`) which +> are explained in section 5.3. For now you can think of tuples as a list of +> items. + +~~~~ +use std::f64; +use std::num::atan; +fn angle(vector: (f64, f64)) -> f64 { + let pi = f64::consts::PI; + match vector { + (0.0, y) if y < 0.0 => 1.5 * pi, + (0.0, y) => 0.5 * pi, + (x, y) => atan(y / x) + } +} +~~~~ + +A variable name in a pattern matches any value, *and* binds that name +to the value of the matched value inside of the arm's action. Thus, `(0.0, +y)` matches any tuple whose first element is zero, and binds `y` to +the second element. `(x, y)` matches any two-element tuple, and binds both +elements to variables. +A subpattern can also be bound to a variable, using `variable @ pattern`. For +example: + +~~~~ +# let age = 23; +match age { + a @ 0..20 => println!("{} years old", a), + _ => println!("older than 21") +} +~~~~ + +Any `match` arm can have a guard clause (written `if EXPR`), called a +*pattern guard*, which is an expression of type `bool` that +determines, after the pattern is found to match, whether the arm is +taken or not. The variables bound by the pattern are in scope in this +guard expression. The first arm in the `angle` example shows an +example of a pattern guard. + +You've already seen simple `let` bindings, but `let` is a little +fancier than you've been led to believe. It, too, supports destructuring +patterns. For example, you can write this to extract the fields from a +tuple, introducing two variables at once: `a` and `b`. + +~~~~ +# fn get_tuple_of_two_ints() -> (int, int) { (1, 1) } +let (a, b) = get_tuple_of_two_ints(); +~~~~ + +Let bindings only work with _irrefutable_ patterns: that is, patterns +that can never fail to match. This excludes `let` from matching +literals and most `enum` variants. + +## Loops + +`while` denotes a loop that iterates as long as its given condition +(which must have type `bool`) evaluates to `true`. Inside a loop, the +keyword `break` aborts the loop, and `continue` aborts the current +iteration and continues with the next. + +~~~~ +let mut cake_amount = 8; +while cake_amount > 0 { + cake_amount -= 1; +} +~~~~ + +`loop` denotes an infinite loop, and is the preferred way of writing `while true`: + +~~~~ +let mut x = 5u; +loop { + x += x - 3; + if x % 5 == 0 { break; } + println!("{}", x); +} +~~~~ + +This code prints out a weird sequence of numbers and stops as soon as +it finds one that can be divided by five. + +# Data structures + +## Structs + +Rust struct types must be declared before they are used using the `struct` +syntax: `struct Name { field1: T1, field2: T2 [, ...] }`, where `T1`, `T2`, +... denote types. To construct a struct, use the same syntax, but leave off +the `struct`: for example: `Point { x: 1.0, y: 2.0 }`. + +Structs are quite similar to C structs and are even laid out the same way in +memory (so you can read from a Rust struct in C, and vice-versa). Use the dot +operator to access struct fields, as in `mypoint.x`. + +~~~~ +struct Point { + x: f64, + y: f64 +} +~~~~ + +Structs have "inherited mutability", which means that any field of a struct +may be mutable, if the struct is in a mutable slot. + +With a value (say, `mypoint`) of such a type in a mutable location, you can do +`mypoint.y += 1.0`. But in an immutable location, such an assignment to a +struct without inherited mutability would result in a type error. + +~~~~ {.ignore} +# struct Point { x: f64, y: f64 } +let mut mypoint = Point { x: 1.0, y: 1.0 }; +let origin = Point { x: 0.0, y: 0.0 }; + +mypoint.y += 1.0; // `mypoint` is mutable, and its fields as well +origin.y += 1.0; // ERROR: assigning to immutable field +~~~~ + +`match` patterns destructure structs. The basic syntax is +`Name { fieldname: pattern, ... }`: + +~~~~ +# struct Point { x: f64, y: f64 } +# let mypoint = Point { x: 0.0, y: 0.0 }; +match mypoint { + Point { x: 0.0, y: yy } => println!("{}", yy), + Point { x: xx, y: yy } => println!("{} {}", xx, yy), +} +~~~~ + +In general, the field names of a struct do not have to appear in the same +order they appear in the type. When you are not interested in all +the fields of a struct, a struct pattern may end with `, ..` (as in +`Name { field1, .. }`) to indicate that you're ignoring all other fields. +Additionally, struct fields have a shorthand matching form that simply +reuses the field name as the binding name. + +~~~ +# struct Point { x: f64, y: f64 } +# let mypoint = Point { x: 0.0, y: 0.0 }; +match mypoint { + Point { x, .. } => println!("{}", x), +} +~~~ + +## Enums + +Enums are datatypes that have several alternate representations. For +example, consider the following type: + +~~~~ +# struct Point { x: f64, y: f64 } +enum Shape { + Circle(Point, f64), + Rectangle(Point, Point) +} +~~~~ + +A value of this type is either a `Circle`, in which case it contains a +`Point` struct and a f64, or a `Rectangle`, in which case it contains +two `Point` structs. The run-time representation of such a value +includes an identifier of the actual form that it holds, much like the +"tagged union" pattern in C, but with better static guarantees. + +The above declaration will define a type `Shape` that can refer to +such shapes, and two functions, `Circle` and `Rectangle`, which can be +used to construct values of the type (taking arguments of the +specified types). So `Circle(Point { x: 0.0, y: 0.0 }, 10.0)` is the way to +create a new circle. + +Enum variants need not have parameters. This `enum` declaration, +for example, is equivalent to a C enum: + +~~~~ +enum Direction { + North, + East, + South, + West +} +~~~~ + +This declaration defines `North`, `East`, `South`, and `West` as constants, +all of which have type `Direction`. + +When an enum is C-like (that is, when none of the variants have +parameters), it is possible to explicitly set the discriminator values +to a constant value: + +~~~~ +enum Color { + Red = 0xff0000, + Green = 0x00ff00, + Blue = 0x0000ff +} +~~~~ + +If an explicit discriminator is not specified for a variant, the value +defaults to the value of the previous variant plus one. If the first +variant does not have a discriminator, it defaults to 0. For example, +the value of `North` is 0, `East` is 1, `South` is 2, and `West` is 3. + +When an enum is C-like, you can apply the `as` cast operator to +convert it to its discriminator value as an `int`. + +For enum types with multiple variants, destructuring is the only way to +get at their contents. All variant constructors can be used as +patterns, as in this definition of `area`: + +~~~~ +use std::f64; +# struct Point {x: f64, y: f64} +# enum Shape { Circle(Point, f64), Rectangle(Point, Point) } +fn area(sh: Shape) -> f64 { + match sh { + Circle(_, size) => f64::consts::PI * size * size, + Rectangle(Point { x, y }, Point { x: x2, y: y2 }) => (x2 - x) * (y2 - y) + } +} +~~~~ + +You can write a lone `_` to ignore an individual field, and can +ignore all fields of a variant like: `Circle(..)`. As in their +introduction form, nullary enum patterns are written without +parentheses. + +~~~~ +# struct Point { x: f64, y: f64 } +# enum Direction { North, East, South, West } +fn point_from_direction(dir: Direction) -> Point { + match dir { + North => Point { x: 0.0, y: 1.0 }, + East => Point { x: 1.0, y: 0.0 }, + South => Point { x: 0.0, y: -1.0 }, + West => Point { x: -1.0, y: 0.0 } + } +} +~~~~ + +Enum variants may also be structs. For example: + +~~~~ +use std::f64; +# struct Point { x: f64, y: f64 } +# fn square(x: f64) -> f64 { x * x } +enum Shape { + Circle { center: Point, radius: f64 }, + Rectangle { top_left: Point, bottom_right: Point } +} +fn area(sh: Shape) -> f64 { + match sh { + Circle { radius: radius, .. } => f64::consts::PI * square(radius), + Rectangle { top_left: top_left, bottom_right: bottom_right } => { + (bottom_right.x - top_left.x) * (top_left.y - bottom_right.y) + } + } +} +~~~~ + +> ***Note:*** This feature of the compiler is currently gated behind the +> `#[feature(struct_variant)]` directive. More about these directives can be +> found in the manual. + +## Tuples + +Tuples in Rust behave exactly like structs, except that their fields do not +have names. Thus, you cannot access their fields with dot notation. Tuples +can have any arity (number of elements) except for 0 (though you may consider +unit, `()`, as the empty tuple if you like). + +~~~~ +let mytup: (int, int, f64) = (10, 20, 30.0); +match mytup { + (a, b, c) => info!("{}", a + b + (c as int)) +} +~~~~ + +## Tuple structs + +Rust also has _tuple structs_, which behave like both structs and tuples, +except that, unlike tuples, tuple structs have names (so `Foo(1, 2)` has a +different type from `Bar(1, 2)`), and tuple structs' _fields_ do not have +names. + +For example: + +~~~~ +struct MyTup(int, int, f64); +let mytup: MyTup = MyTup(10, 20, 30.0); +match mytup { + MyTup(a, b, c) => info!("{}", a + b + (c as int)) +} +~~~~ + +<a name="newtype"></a> + +There is a special case for tuple structs with a single field, which are +sometimes called "newtypes" (after Haskell's "newtype" feature). These are +used to define new types in such a way that the new name is not just a +synonym for an existing type but is rather its own distinct type. + +~~~~ +struct GizmoId(int); +~~~~ + +Types like this can be useful to differentiate between data that have +the same underlying type but must be used in different ways. + +~~~~ +struct Inches(int); +struct Centimeters(int); +~~~~ + +The above definitions allow for a simple way for programs to avoid +confusing numbers that correspond to different units. Their integer +values can be extracted with pattern matching: + +~~~ +# struct Inches(int); + +let length_with_unit = Inches(10); +let Inches(integer_length) = length_with_unit; +println!("length is {} inches", integer_length); +~~~ + +# Functions + +We've already seen several function definitions. Like all other static +declarations, such as `type`, functions can be declared both at the +top level and inside other functions (or in modules, which we'll come +back to [later](#crates-and-the-module-system)). The `fn` keyword introduces a +function. A function has an argument list, which is a parenthesized +list of `name: type` pairs separated by commas. An arrow `->` +separates the argument list and the function's return type. + +~~~~ +fn line(a: int, b: int, x: int) -> int { + return a * x + b; +} +~~~~ + +The `return` keyword immediately returns from the body of a function. It +is optionally followed by an expression to return. A function can +also return a value by having its top-level block produce an +expression. + +~~~~ +fn line(a: int, b: int, x: int) -> int { + a * x + b +} +~~~~ + +It's better Rust style to write a return value this way instead of +writing an explicit `return`. The utility of `return` comes in when +returning early from a function. Functions that do not return a value +are said to return nil, `()`, and both the return type and the return +value may be omitted from the definition. The following two functions +are equivalent. + +~~~~ +fn do_nothing_the_hard_way() -> () { return (); } + +fn do_nothing_the_easy_way() { } +~~~~ + +Ending the function with a semicolon like so is equivalent to returning `()`. + +~~~~ +fn line(a: int, b: int, x: int) -> int { a * x + b } +fn oops(a: int, b: int, x: int) -> () { a * x + b; } + +assert!(8 == line(5, 3, 1)); +assert!(() == oops(5, 3, 1)); +~~~~ + +As with `match` expressions and `let` bindings, function arguments support +pattern destructuring. Like `let`, argument patterns must be irrefutable, +as in this example that unpacks the first value from a tuple and returns it. + +~~~ +fn first((value, _): (int, f64)) -> int { value } +~~~ + +# Destructors + +A *destructor* is a function responsible for cleaning up the resources used by +an object when it is no longer accessible. Destructors can be defined to handle +the release of resources like files, sockets and heap memory. + +Objects are never accessible after their destructor has been called, so no +dynamic failures are possible from accessing freed resources. When a task +fails, destructors of all objects in the task are called. + +The `~` sigil represents a unique handle for a memory allocation on the heap: + +~~~~ +{ + // an integer allocated on the heap + let y = ~10; +} +// the destructor frees the heap memory as soon as `y` goes out of scope +~~~~ + +Rust includes syntax for heap memory allocation in the language since it's +commonly used, but the same semantics can be implemented by a type with a +custom destructor. + +# Ownership + +Rust formalizes the concept of object ownership to delegate management of an +object's lifetime to either a variable or a task-local garbage collector. An +object's owner is responsible for managing the lifetime of the object by +calling the destructor, and the owner determines whether the object is mutable. + +Ownership is recursive, so mutability is inherited recursively and a destructor +destroys the contained tree of owned objects. Variables are top-level owners +and destroy the contained object when they go out of scope. + +~~~~ +// the struct owns the objects contained in the `x` and `y` fields +struct Foo { x: int, y: ~int } + +{ + // `a` is the owner of the struct, and thus the owner of the struct's fields + let a = Foo { x: 5, y: ~10 }; +} +// when `a` goes out of scope, the destructor for the `~int` in the struct's +// field is called + +// `b` is mutable, and the mutability is inherited by the objects it owns +let mut b = Foo { x: 5, y: ~10 }; +b.x = 10; +~~~~ + +If an object doesn't contain any non-Send types, it consists of a single +ownership tree and is itself given the `Send` trait which allows it to be sent +between tasks. Custom destructors can only be implemented directly on types +that are `Send`, but non-`Send` types can still *contain* types with custom +destructors. Example of types which are not `Send` are [`Gc<T>`][gc] and +[`Rc<T>`][rc], the shared-ownership types. + +[gc]: http://static.rust-lang.org/doc/master/std/gc/struct.Gc.html +[rc]: http://static.rust-lang.org/doc/master/std/rc/struct.Rc.html + +# Implementing a linked list + +An `enum` is a natural fit for describing a linked list, because it can express +a `List` type as being *either* the end of the list (`Nil`) or another node +(`Cons`). The full definition of the `Cons` variant will require some thought. + +~~~ {.ignore} +enum List { + Cons(...), // an incomplete definition of the next element in a List + Nil // the end of a List +} +~~~ + +The obvious approach is to define `Cons` as containing an element in the list +along with the next `List` node. However, this will generate a compiler error. + +~~~ {.ignore} +// error: illegal recursive enum type; wrap the inner value in a box to make it representable +enum List { + Cons(u32, List), // an element (`u32`) and the next node in the list + Nil +} +~~~ + +This error message is related to Rust's precise control over memory layout, and +solving it will require introducing the concept of *boxing*. + +## Boxes + +A value in Rust is stored directly inside the owner. If a `struct` contains +four `u32` fields, it will be four times as large as a single `u32`. + +~~~ +use std::mem::size_of; // bring `size_of` into the current scope, for convenience + +struct Foo { + a: u32, + b: u32, + c: u32, + d: u32 +} + +assert_eq!(size_of::<Foo>(), size_of::<u32>() * 4); + +struct Bar { + a: Foo, + b: Foo, + c: Foo, + d: Foo +} + +assert_eq!(size_of::<Bar>(), size_of::<u32>() * 16); +~~~ + +Our previous attempt at defining the `List` type included an `u32` and a `List` +directly inside `Cons`, making it at least as big as the sum of both types. The +type was invalid because the size was infinite! + +An *owned box* (`~`) uses a dynamic memory allocation to provide the invariant +of always being the size of a pointer, regardless of the contained type. This +can be leverage to create a valid `List` definition: + +~~~ +enum List { + Cons(u32, ~List), + Nil +} +~~~ + +Defining a recursive data structure like this is the canonical example of an +owned box. Much like an unboxed value, an owned box has a single owner and is +therefore limited to expressing a tree-like data structure. + +Consider an instance of our `List` type: + +~~~ +# enum List { +# Cons(u32, ~List), +# Nil +# } +let list = Cons(1, ~Cons(2, ~Cons(3, ~Nil))); +~~~ + +It represents an owned tree of values, inheriting mutability down the tree and +being destroyed along with the owner. Since the `list` variable above is +immutable, the whole list is immutable. The memory allocation itself is the +box, while the owner holds onto a pointer to it: + + List box List box List box List box + +--------------+ +--------------+ +--------------+ +--------------+ + list -> | Cons | 1 | ~ | -> | Cons | 2 | ~ | -> | Cons | 3 | ~ | -> | Nil | + +--------------+ +--------------+ +--------------+ +--------------+ + +> Note: the above diagram shows the logical contents of the enum. The actual +> memory layout of the enum may vary. For example, for the `List` enum shown +> above, Rust guarantees that there will be no enum tag field in the actual +> structure. See the language reference for more details. + +An owned box is a common example of a type with a destructor. The allocated +memory is cleaned up when the box is destroyed. + +## Move semantics + +Rust uses a shallow copy for parameter passing, assignment and returning from +functions. Passing around the `List` will copy only as deep as the pointer to +the box rather than doing an implicit heap allocation. + +~~~ +# enum List { +# Cons(u32, ~List), +# Nil +# } +let xs = Cons(1, ~Cons(2, ~Cons(3, ~Nil))); +let ys = xs; // copies `Cons(u32, pointer)` shallowly +~~~ + +Rust will consider a shallow copy of a type with a destructor like `List` to +*move ownership* of the value. After a value has been moved, the source +location cannot be used unless it is reinitialized. + +~~~ +# enum List { +# Cons(u32, ~List), +# Nil +# } +let mut xs = Nil; +let ys = xs; + +// attempting to use `xs` will result in an error here + +xs = Nil; + +// `xs` can be used again +~~~ + +A destructor call will only occur for a variable that has not been moved from, +as it is only called a single time. + + +Avoiding a move can be done with the library-defined `clone` method: + +~~~~ +let x = ~5; +let y = x.clone(); // `y` is a newly allocated box +let z = x; // no new memory allocated, `x` can no longer be used +~~~~ + +The `clone` method is provided by the `Clone` trait, and can be derived for +our `List` type. Traits will be explained in detail later. + +~~~{.ignore} +#[deriving(Clone)] +enum List { + Cons(u32, ~List), + Nil +} + +let x = Cons(5, ~Nil); +let y = x.clone(); + +// `x` can still be used! + +let z = x; + +// and now, it can no longer be used since it has been moved +~~~ + +The mutability of a value may be changed by moving it to a new owner: + +~~~~ +let r = ~13; +let mut s = r; // box becomes mutable +*s += 1; +let t = s; // box becomes immutable +~~~~ + +A simple way to define a function prepending to the `List` type is to take +advantage of moves: + +~~~ +enum List { + Cons(u32, ~List), + Nil +} + +fn prepend(xs: List, value: u32) -> List { + Cons(value, ~xs) +} + +let mut xs = Nil; +xs = prepend(xs, 1); +xs = prepend(xs, 2); +xs = prepend(xs, 3); +~~~ + +However, this is not a very flexible definition of `prepend` as it requires +ownership of a list to be passed in rather than just mutating it in-place. + +## References + +The obvious signature for a `List` equality comparison is the following: + +~~~{.ignore} +fn eq(xs: List, ys: List) -> bool { ... } +~~~ + +However, this will cause both lists to be moved into the function. Ownership +isn't required to compare the lists, so the function should take *references* +(&T) instead. + +~~~{.ignore} +fn eq(xs: &List, ys: &List) -> bool { ... } +~~~ + +A reference is a *non-owning* view of a value. A reference can be obtained with the `&` (address-of) +operator. It can be dereferenced by using the `*` operator. In a pattern, such as `match` expression +branches, the `ref` keyword can be used to bind to a variable name by-reference rather than +by-value. A recursive definition of equality using references is as follows: + +~~~ +# enum List { +# Cons(u32, ~List), +# Nil +# } +fn eq(xs: &List, ys: &List) -> bool { + // Match on the next node in both lists. + match (xs, ys) { + // If we have reached the end of both lists, they are equal. + (&Nil, &Nil) => true, + // If the current element in both lists is equal, keep going. + (&Cons(x, ~ref next_xs), &Cons(y, ~ref next_ys)) if x == y => eq(next_xs, next_ys), + // If the current elements are not equal, the lists are not equal. + _ => false + } +} + +let xs = Cons(5, ~Cons(10, ~Nil)); +let ys = Cons(5, ~Cons(10, ~Nil)); +assert!(eq(&xs, &ys)); +~~~ + +Note that Rust doesn't guarantee [tail-call](http://en.wikipedia.org/wiki/Tail_call) optimization, +but LLVM is able to handle a simple case like this with optimizations enabled. + +## Lists of other types + +Our `List` type is currently always a list of 32-bit unsigned integers. By +leveraging Rust's support for generics, it can be extended to work for any +element type. + +The `u32` in the previous definition can be substituted with a type parameter: + +~~~ +enum List<T> { + Cons(T, ~List<T>), + Nil +} +~~~ + +The old `List` of `u32` is now available as `List<u32>`. The `prepend` +definition has to be updated too: + +~~~ +# enum List<T> { +# Cons(T, ~List<T>), +# Nil +# } +fn prepend<T>(xs: List<T>, value: T) -> List<T> { + Cons(value, ~xs) +} +~~~ + +Generic functions and types like this are equivalent to defining specialized +versions for each set of type parameters. + +Using the generic `List<T>` works much like before, thanks to type inference: + +~~~ +# enum List<T> { +# Cons(T, ~List<T>), +# Nil +# } +# fn prepend<T>(xs: List<T>, value: T) -> List<T> { +# Cons(value, ~xs) +# } +let mut xs = Nil; // Unknown type! This is a `List<T>`, but `T` can be anything. +xs = prepend(xs, 10); // The compiler infers the type of `xs` as `List<int>` from this. +xs = prepend(xs, 15); +xs = prepend(xs, 20); +~~~ + +The code sample above demonstrates type inference making most type annotations optional. It is +equivalent to the following type-annotated code: + +~~~ +# enum List<T> { +# Cons(T, ~List<T>), +# Nil +# } +# fn prepend<T>(xs: List<T>, value: T) -> List<T> { +# Cons(value, ~xs) +# } +let mut xs: List<int> = Nil::<int>; +xs = prepend::<int>(xs, 10); +xs = prepend::<int>(xs, 15); +xs = prepend::<int>(xs, 20); +~~~ + +In declarations, the language uses `Type<T, U, V>` to describe a list of type +parameters, but expressions use `identifier::<T, U, V>`, to disambiguate the +`<` operator. + +## Defining list equality with generics + +Generic functions are type-checked from the definition, so any necessary properties of the type must +be specified up-front. Our previous definition of list equality relied on the element type having +the `==` operator available, and took advantage of the lack of a destructor on `u32` to copy it +without a move of ownership. + +We can add a *trait bound* on the `Eq` trait to require that the type implement the `==` operator. +Two more `ref` annotations need to be added to avoid attempting to move out the element types: + +~~~ +# enum List<T> { +# Cons(T, ~List<T>), +# Nil +# } +fn eq<T: Eq>(xs: &List<T>, ys: &List<T>) -> bool { + // Match on the next node in both lists. + match (xs, ys) { + // If we have reached the end of both lists, they are equal. + (&Nil, &Nil) => true, + // If the current element in both lists is equal, keep going. + (&Cons(ref x, ~ref next_xs), &Cons(ref y, ~ref next_ys)) if x == y => eq(next_xs, next_ys), + // If the current elements are not equal, the lists are not equal. + _ => false + } +} + +let xs = Cons('c', ~Cons('a', ~Cons('t', ~Nil))); +let ys = Cons('c', ~Cons('a', ~Cons('t', ~Nil))); +assert!(eq(&xs, &ys)); +~~~ + +This would be a good opportunity to implement the `Eq` trait for our list type, making the `==` and +`!=` operators available. We'll need to provide an `impl` for the `Eq` trait and a definition of the +`eq` method. In a method, the `self` parameter refers to an instance of the type we're implementing +on. + +~~~ +# enum List<T> { +# Cons(T, ~List<T>), +# Nil +# } +impl<T: Eq> Eq for List<T> { + fn eq(&self, ys: &List<T>) -> bool { + // Match on the next node in both lists. + match (self, ys) { + // If we have reached the end of both lists, they are equal. + (&Nil, &Nil) => true, + // If the current element in both lists is equal, keep going. + (&Cons(ref x, ~ref next_xs), &Cons(ref y, ~ref next_ys)) if x == y => next_xs == next_ys, + // If the current elements are not equal, the lists are not equal. + _ => false + } + } +} + +let xs = Cons(5, ~Cons(10, ~Nil)); +let ys = Cons(5, ~Cons(10, ~Nil)); +assert!(xs.eq(&ys)); +assert!(xs == ys); +assert!(!xs.ne(&ys)); +assert!(!(xs != ys)); +~~~ + +# More on boxes + +The most common use case for owned boxes is creating recursive data structures +like a binary search tree. Rust's trait-based generics system (covered later in +the tutorial) is usually used for static dispatch, but also provides dynamic +dispatch via boxing. Values of different types may have different sizes, but a +box is able to *erase* the difference via the layer of indirection they +provide. + +In uncommon cases, the indirection can provide a performance gain or memory +reduction by making values smaller. However, unboxed values should almost +always be preferred when they are usable. + +Note that returning large unboxed values via boxes is unnecessary. 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: + +~~~~ +fn foo() -> (u64, u64, u64, u64, u64, u64) { + (5, 5, 5, 5, 5, 5) +} + +let x = ~foo(); // allocates a `~` box, and writes the integers directly to it +~~~~ + +Beyond the properties granted by the size, an owned box behaves as a regular +value by inheriting the mutability and lifetime of the owner: + +~~~~ +let x = 5; // immutable +let mut y = 5; // mutable +y += 2; + +let x = ~5; // immutable +let mut y = ~5; // mutable +*y += 2; // the `*` operator is needed to access the contained value +~~~~ + +# References + +In contrast with +owned boxes, where the holder of an owned box is the owner of the pointed-to +memory, references never imply ownership - they are "borrowed". +A reference can be borrowed to +any object, and the compiler verifies that it cannot outlive the lifetime of +the object. + +As an example, consider a simple struct type, `Point`: + +~~~ +struct Point { + x: f64, + y: f64 +} +~~~~ + +We can use this simple definition to allocate points in many different +ways. For example, in this code, each of these three local variables +contains a point, but allocated in a different location: + +~~~ +# struct Point { x: f64, y: f64 } +let on_the_stack : Point = Point { x: 3.0, y: 4.0 }; +let managed_box : @Point = @Point { x: 5.0, y: 1.0 }; +let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 }; +~~~ + +Suppose we want to write a procedure that computes the distance +between any two points, no matter where they are stored. For example, +we might like to compute the distance between `on_the_stack` and +`managed_box`, or between `managed_box` and `owned_box`. One option is +to define a function that takes two arguments of type point—that is, +it takes the points by value. But this will cause the points to be +copied when we call the function. For points, this is probably not so +bad, but often copies are expensive. So we’d like to define a function +that takes the points by pointer. We can use references to do this: + +~~~ +# struct Point { x: f64, y: f64 } +# fn sqrt(f: f64) -> f64 { 0.0 } +fn compute_distance(p1: &Point, p2: &Point) -> f64 { + let x_d = p1.x - p2.x; + let y_d = p1.y - p2.y; + sqrt(x_d * x_d + y_d * y_d) +} +~~~ + +Now we can call `compute_distance()` in various ways: + +~~~ +# struct Point{ x: f64, y: f64 }; +# let on_the_stack : Point = Point { x: 3.0, y: 4.0 }; +# let managed_box : @Point = @Point { x: 5.0, y: 1.0 }; +# let owned_box : ~Point = ~Point { x: 7.0, y: 9.0 }; +# fn compute_distance(p1: &Point, p2: &Point) -> f64 { 0.0 } +compute_distance(&on_the_stack, managed_box); +compute_distance(managed_box, owned_box); +~~~ + +Here the `&` operator is used to take the address of the variable +`on_the_stack`; this is because `on_the_stack` has the type `Point` +(that is, a struct value) and we have to take its address to get a +reference. We also call this _borrowing_ the local variable +`on_the_stack`, because we are creating an alias: that is, another +route to the same data. + +In the case of the boxes `managed_box` and `owned_box`, however, no +explicit action is necessary. The compiler will automatically convert +a box like `@point` or `~point` to a reference like +`&point`. This is another form of borrowing; in this case, the +contents of the managed/owned box are being lent out. + +Whenever a value is borrowed, there are some limitations on what you +can do with the original. For example, if the contents of a variable +have been lent out, you cannot send that variable to another task, nor +will you be permitted to take actions that might cause the borrowed +value to be freed or to change its type. This rule should make +intuitive sense: you must wait for a borrowed value to be returned +(that is, for the reference to go out of scope) before you can +make full use of it again. + +For a more in-depth explanation of references and lifetimes, read the +[references and lifetimes guide][lifetimes]. + +## Freezing + +Lending an immutable pointer to an object freezes it and prevents mutation. +`Freeze` objects have freezing enforced statically at compile-time. An example +of a non-`Freeze` type is [`RefCell<T>`][refcell]. + +~~~~ +let mut x = 5; +{ + let y = &x; // `x` is now frozen, it cannot be modified +} +// `x` is now unfrozen again +# x = 3; +~~~~ + +[refcell]: http://static.rust-lang.org/doc/master/std/cell/struct.RefCell.html + +# Dereferencing pointers + +Rust uses the unary star operator (`*`) to access the contents of a +box or pointer, similarly to C. + +~~~ +let managed = @10; +let owned = ~20; +let borrowed = &30; + +let sum = *managed + *owned + *borrowed; +~~~ + +Dereferenced mutable pointers may appear on the left hand side of +assignments. Such an assignment modifies the value that the pointer +points to. + +~~~ +let managed = @10; +let mut owned = ~20; + +let mut value = 30; +let borrowed = &mut value; + +*owned = *borrowed + 100; +*borrowed = *managed + 1000; +~~~ + +Pointers have high operator precedence, but lower precedence than the +dot operator used for field and method access. This precedence order +can sometimes make code awkward and parenthesis-filled. + +~~~ +# struct Point { x: f64, y: f64 } +# enum Shape { Rectangle(Point, Point) } +# impl Shape { fn area(&self) -> int { 0 } } +let start = @Point { x: 10.0, y: 20.0 }; +let end = ~Point { x: (*start).x + 100.0, y: (*start).y + 100.0 }; +let rect = &Rectangle(*start, *end); +let area = (*rect).area(); +~~~ + +To combat this ugliness the dot operator applies _automatic pointer +dereferencing_ to the receiver (the value on the left-hand side of the +dot), so in most cases, explicitly dereferencing the receiver is not necessary. + +~~~ +# struct Point { x: f64, y: f64 } +# enum Shape { Rectangle(Point, Point) } +# impl Shape { fn area(&self) -> int { 0 } } +let start = @Point { x: 10.0, y: 20.0 }; +let end = ~Point { x: start.x + 100.0, y: start.y + 100.0 }; +let rect = &Rectangle(*start, *end); +let area = rect.area(); +~~~ + +You can write an expression that dereferences any number of pointers +automatically. For example, if you feel inclined, you could write +something silly like + +~~~ +# struct Point { x: f64, y: f64 } +let point = &@~Point { x: 10.0, y: 20.0 }; +println!("{:f}", point.x); +~~~ + +The indexing operator (`[]`) also auto-dereferences. + +# Vectors and strings + +A vector is a contiguous block of memory containing zero or more values of the +same type. Rust also supports vector reference types, called slices, which are +a view into a block of memory represented as a pointer and a length. + +Strings are represented as vectors of `u8`, with the guarantee of containing a +valid UTF-8 sequence. + +Fixed-size vectors are an unboxed block of memory, with the element length as +part of the type. A fixed-size vector owns the elements it contains, so the +elements are mutable if the vector is mutable. Fixed-size strings do not exist. + +~~~ +// A fixed-size vector +let numbers = [1, 2, 3]; +let more_numbers = numbers; + +// The type of a fixed-size vector is written as `[Type, ..length]` +let five_zeroes: [int, ..5] = [0, ..5]; +~~~ + +A unique vector is dynamically sized, and has a destructor to clean up +allocated memory on the heap. A unique vector owns the elements it contains, so +the elements are mutable if the vector is mutable. + +~~~ +// A dynamically sized vector (unique vector) +let mut numbers = ~[1, 2, 3]; +numbers.push(4); +numbers.push(5); + +// The type of a unique vector is written as `~[int]` +let more_numbers: ~[int] = numbers; + +// The original `numbers` value can no longer be used, due to move semantics. + +let mut string = ~"fo"; +string.push_char('o'); +~~~ + +Slices are similar to fixed-size vectors, but the length is not part of the +type. They simply point into a block of memory and do not have ownership over +the elements. + +~~~ +// A slice +let xs = &[1, 2, 3]; + +// Slices have their type written as `&[int]` +let ys: &[int] = xs; + +// Other vector types coerce to slices +let three = [1, 2, 3]; +let zs: &[int] = three; + +// An unadorned string literal is an immutable string slice +let string = "foobar"; + +// A string slice type is written as `&str` +let view: &str = string.slice(0, 3); +~~~ + +Mutable slices also exist, just as there are mutable references. However, there +are no mutable string slices. Strings are a multi-byte encoding (UTF-8) of +Unicode code points, so they cannot be freely mutated without the ability to +alter the length. + +~~~ +let mut xs = [1, 2, 3]; +let view = xs.mut_slice(0, 2); +view[0] = 5; + +// The type of a mutable slice is written as `&mut [T]` +let ys: &mut [int] = &mut [1, 2, 3]; +~~~ + +Square brackets denote indexing into a vector: + +~~~~ +# enum Crayon { Almond, AntiqueBrass, Apricot, +# Aquamarine, Asparagus, AtomicTangerine, +# BananaMania, Beaver, Bittersweet }; +# fn draw_scene(c: Crayon) { } +let crayons: [Crayon, ..3] = [BananaMania, Beaver, Bittersweet]; +match crayons[0] { + Bittersweet => draw_scene(crayons[0]), + _ => () +} +~~~~ + +A vector can be destructured using pattern matching: + +~~~~ +let numbers: &[int] = &[1, 2, 3]; +let score = match numbers { + [] => 0, + [a] => a * 10, + [a, b] => a * 6 + b * 4, + [a, b, c, ..rest] => a * 5 + b * 3 + c * 2 + rest.len() as int +}; +~~~~ + +Both vectors and strings support a number of useful [methods](#methods), +defined in [`std::vec`] and [`std::str`]. + +[`std::vec`]: std/vec/index.html +[`std::str`]: std/str/index.html + +# Ownership escape hatches + +Ownership can cleanly describe tree-like data structures, and references provide non-owning pointers. However, more flexibility is often desired and Rust provides ways to escape from strict +single parent ownership. + +The standard library provides the `std::rc::Rc` pointer type to express *shared ownership* over a +reference counted box. As soon as all of the `Rc` pointers go out of scope, the box and the +contained value are destroyed. + +~~~ +use std::rc::Rc; + +// A fixed-size array allocated in a reference-counted box +let x = Rc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); +let y = x.clone(); // a new owner +let z = x; // this moves `x` into `z`, rather than creating a new owner + +assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); + +// the variable is mutable, but not the contents of the box +let mut a = Rc::new([10, 9, 8, 7, 6, 5, 4, 3, 2, 1]); +a = z; +~~~ + +A garbage collected pointer is provided via `std::gc::Gc`, with a task-local garbage collector +having ownership of the box. It allows the creation of cycles, and the individual `Gc` pointers do +not have a destructor. + +~~~ +use std::gc::Gc; + +// A fixed-size array allocated in a garbage-collected box +let x = Gc::new([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); +let y = x; // does not perform a move, unlike with `Rc` +let z = x; + +assert_eq!(*z.borrow(), [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); +~~~ + +With shared ownership, mutability cannot be inherited so the boxes are always immutable. However, +it's possible to use *dynamic* mutability via types like `std::cell::Cell` where freezing is handled +via dynamic checks and can fail at runtime. + +The `Rc` and `Gc` types are not sendable, so they cannot be used to share memory between tasks. Safe +immutable and mutable shared memory is provided by the `extra::arc` module. + +# Closures + +Named functions, like those we've seen so far, may not refer to local +variables declared outside the function: they do not close over their +environment (sometimes referred to as "capturing" variables in their +environment). For example, you couldn't write the following: + +~~~~ {.ignore} +let foo = 10; + +fn bar() -> int { + return foo; // `bar` cannot refer to `foo` +} +~~~~ + +Rust also supports _closures_, functions that can access variables in +the enclosing scope. + +~~~~ +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); +~~~~ + +Closures begin with the argument list between vertical bars and are followed by +a single expression. Remember that a block, `{ <expr1>; <expr2>; ... }`, is +considered a single expression: it evaluates to the result of the last +expression it contains if that expression is not followed by a semicolon, +otherwise the block evaluates to `()`. + +The types of the arguments are generally omitted, as is the return type, +because the compiler can almost always infer them. In the rare case where the +compiler needs assistance, though, the arguments and return types may be +annotated. + +~~~~ +let square = |x: int| -> uint { (x * x) as uint }; +~~~~ + +There are several forms of closure, each with its own role. The most +common, called a _stack closure_, has type `||` and can directly +access local variables in the enclosing scope. + +~~~~ +let mut max = 0; +[1, 2, 3].map(|x| if *x > max { max = *x }); +~~~~ + +Stack closures are very efficient because their environment is +allocated on the call stack and refers by pointer to captured +locals. To ensure that stack closures never outlive the local +variables to which they refer, stack closures are not +first-class. That is, they can only be used in argument position; they +cannot be stored in data structures or returned from +functions. Despite these limitations, stack closures are used +pervasively in Rust code. + +## Owned closures + +Owned closures, written `proc`, +hold on to things that can safely be sent between +processes. They copy the values they close over, much like managed +closures, but they also own them: that is, no other code can access +them. Owned closures are used in concurrent code, particularly +for spawning [tasks][tasks]. + +## Closure compatibility + +Rust closures have a convenient subtyping property: you can pass any kind of +closure (as long as the arguments and return types match) to functions +that expect a `||`. Thus, when writing a higher-order function that +only calls its function argument, and does nothing else with it, you +should almost always declare the type of that argument as `||`. That way, +callers may pass any kind of closure. + +~~~~ +fn call_twice(f: ||) { f(); f(); } +let closure = || { "I'm a closure, and it doesn't matter what type I am"; }; +fn function() { "I'm a normal function"; } +call_twice(closure); +call_twice(function); +~~~~ + +> ***Note:*** Both the syntax and the semantics will be changing +> in small ways. At the moment they can be unsound in some +> scenarios, particularly with non-copyable types. + +## Do syntax + +The `do` expression makes it easier to call functions that take procedures +as arguments. + +Consider this function that takes a procedure: + +~~~~ +fn call_it(op: proc(v: int)) { + op(10) +} +~~~~ + +As a caller, if we use a closure to provide the final operator +argument, we can write it in a way that has a pleasant, block-like +structure. + +~~~~ +# fn call_it(op: proc(v: int)) { } +call_it(proc(n) { + println!("{}", n); +}); +~~~~ + +A practical example of this pattern is found when using the `spawn` function, +which starts a new task. + +~~~~ +use std::task::spawn; +spawn(proc() { + debug!("I'm a new task") +}); +~~~~ + +If you want to see the output of `debug!` statements, you will need to turn on +`debug!` logging. To enable `debug!` logging, set the RUST_LOG environment +variable to the name of your crate, which, for a file named `foo.rs`, will be +`foo` (e.g., with bash, `export RUST_LOG=foo`). + +# Methods + +Methods are like functions except that they always begin with a special argument, +called `self`, +which has the type of the method's receiver. The +`self` argument is like `this` in C++ and many other languages. +Methods are called with dot notation, as in `my_vec.len()`. + +_Implementations_, written with the `impl` keyword, can define +methods on most Rust types, including structs and enums. +As an example, let's define a `draw` method on our `Shape` enum. + +~~~ +# fn draw_circle(p: Point, f: f64) { } +# fn draw_rectangle(p: Point, p: Point) { } +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(); +~~~ + +This defines an _implementation_ for `Shape` containing a single +method, `draw`. In most respects the `draw` method is defined +like any other function, except for the name `self`. + +The type of `self` is the type on which the method is implemented, +or a pointer thereof. As an argument it is written either `self`, +`&self`, `@self`, or `~self`. +A caller must in turn have a compatible pointer type to call the method. + +~~~ +# fn draw_circle(p: Point, f: f64) { } +# fn draw_rectangle(p: Point, p: Point) { } +# struct Point { x: f64, y: f64 } +# enum Shape { +# Circle(Point, f64), +# Rectangle(Point, Point) +# } +impl Shape { + fn draw_reference(&self) { ... } + fn draw_managed(@self) { ... } + fn draw_owned(~self) { ... } + fn draw_value(self) { ... } +} + +let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0); + +(@s).draw_managed(); +(~s).draw_owned(); +(&s).draw_reference(); +s.draw_value(); +~~~ + +Methods typically take a reference self type, +so the compiler will go to great lengths to convert a callee +to a reference. + +~~~ +# fn draw_circle(p: Point, f: f64) { } +# fn draw_rectangle(p: Point, p: Point) { } +# struct Point { x: f64, y: f64 } +# enum Shape { +# Circle(Point, f64), +# Rectangle(Point, Point) +# } +# impl Shape { +# fn draw_reference(&self) { ... } +# fn draw_managed(@self) { ... } +# fn draw_owned(~self) { ... } +# fn draw_value(self) { ... } +# } +# let s = Circle(Point { x: 1.0, y: 2.0 }, 3.0); +// As with typical function arguments, managed and owned pointers +// are automatically converted to references + +(@s).draw_reference(); +(~s).draw_reference(); + +// Unlike typical function arguments, the self value will +// automatically be referenced ... +s.draw_reference(); + +// ... and dereferenced +(& &s).draw_reference(); + +// ... and dereferenced and borrowed +(&@~s).draw_reference(); +~~~ + +Implementations may also define standalone (sometimes called "static") +methods. The absence of a `self` parameter distinguishes such methods. +These methods are the preferred way to define constructor functions. + +~~~~ {.ignore} +impl Circle { + fn area(&self) -> f64 { ... } + fn new(area: f64) -> Circle { ... } +} +~~~~ + +To call such a method, just prefix it with the type name and a double colon: + +~~~~ +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); +~~~~ + +# Generics + +Throughout this tutorial, we've been defining functions that act only +on specific data types. With type parameters we can also define +functions whose arguments have generic types, and which can be invoked +with a variety of types. Consider a generic `map` function, which +takes a function `function` and a vector `vector` and returns a new +vector consisting of the result of applying `function` to each element +of `vector`: + +~~~~ +fn map<T, U>(vector: &[T], function: |v: &T| -> U) -> ~[U] { + let mut accumulator = ~[]; + for element in vector.iter() { + accumulator.push(function(element)); + } + return accumulator; +} +~~~~ + +When defined with type parameters, as denoted by `<T, U>`, this +function can be applied to any type of vector, as long as the type of +`function`'s argument and the type of the vector's contents agree with +each other. + +Inside a generic function, the names of the type parameters +(capitalized by convention) stand for opaque types. All you can do +with instances of these types is pass them around: you can't apply any +operations to them or pattern-match on them. Note that instances of +generic types are often passed by pointer. For example, the parameter +`function()` is supplied with a pointer to a value of type `T` and not +a value of type `T` itself. This ensures that the function works with +the broadest set of types possible, since some types are expensive or +illegal to copy and pass by value. + +Generic `type`, `struct`, and `enum` declarations follow the same pattern: + +~~~~ +use std::hashmap::HashMap; +type Set<T> = HashMap<T, ()>; + +struct Stack<T> { + elements: ~[T] +} + +enum Option<T> { + Some(T), + None +} +~~~~ + +These declarations can be instantiated to valid types like `Set<int>`, +`Stack<int>`, and `Option<int>`. + +The last type in that example, `Option`, appears frequently in Rust code. +Because Rust does not have null pointers (except in unsafe code), we need +another way to write a function whose result isn't defined on every possible +combination of arguments of the appropriate types. The usual way is to write +a function that returns `Option<T>` instead of `T`. + +~~~~ +# struct Point { x: f64, y: f64 } +# enum Shape { Circle(Point, f64), Rectangle(Point, Point) } +fn radius(shape: Shape) -> Option<f64> { + match shape { + Circle(_, radius) => Some(radius), + Rectangle(..) => None + } +} +~~~~ + +The Rust compiler compiles generic functions very efficiently by +*monomorphizing* them. *Monomorphization* is a fancy name for a simple +idea: generate a separate copy of each generic function at each call site, +a copy that is specialized to the argument +types and can thus be optimized specifically for them. In this +respect, Rust's generics have similar performance characteristics to +C++ templates. + +## Traits + +Within a generic function -- that is, a function parameterized by a +type parameter, say, `T` -- the operations we can do on arguments of +type `T` are quite limited. After all, since we don't know what type +`T` will be instantiated with, we can't safely modify or query values +of type `T`. This is where _traits_ come into play. Traits are Rust's +most powerful tool for writing polymorphic code. Java developers will +see them as similar to Java interfaces, and Haskellers will notice +their similarities to type classes. Rust's traits give us a way to +express *bounded polymorphism*: by limiting the set of possible types +that a type parameter could refer to, they expand the number of +operations we can safely perform on arguments of that type. + +As motivation, let us consider copying of values in Rust. The `clone` +method is not defined for values of every type. One reason is +user-defined destructors: copying a value of a type that has a +destructor could result in the destructor running multiple times. +Therefore, values of types that have destructors cannot be copied +unless we explicitly implement `clone` for them. + +This complicates handling of generic functions. +If we have a function with a type parameter `T`, +can we copy values of type `T` inside that function? +In Rust, we can't, +and if we try to run the following code the compiler will complain. + +~~~~ {.ignore} +// This does not compile +fn head_bad<T>(v: &[T]) -> T { + v[0] // error: copying a non-copyable value +} +~~~~ + +However, we can tell the compiler +that the `head` function is only for copyable types. +In Rust, copyable types are those that _implement the `Clone` trait_. +We can then explicitly create a second copy of the value we are returning +by calling the `clone` method: + +~~~~ +// This does +fn head<T: Clone>(v: &[T]) -> T { + v[0].clone() +} +~~~~ + +The bounded type parameter `T: Clone` says that `head` +can be called on an argument of type `&[T]` for any `T`, +so long as there is an implementation of the +`Clone` trait for `T`. +When instantiating a generic function, +we can only instantiate it with types +that implement the correct trait, +so we could not apply `head` to a vector whose elements are of some type +that does not implement `Clone`. + +While most traits can be defined and implemented by user code, +three traits are automatically derived and implemented +for all applicable types by the compiler, +and may not be overridden: + +* `Send` - Sendable types. +Types are sendable +unless they contain managed boxes, managed closures, or references. + +* `Freeze` - Constant (immutable) types. +These are types that do not contain anything intrinsically mutable. +Intrinsically mutable values include `Cell` in the standard library. + +* `'static` - Non-borrowed types. +These are types that do not contain any data whose lifetime is bound to +a particular stack frame. These are types that do not contain any +references, or types where the only contained references +have the `'static` lifetime. + +> ***Note:*** These two traits were referred to as 'kinds' in earlier +> iterations of the language, and often still are. + +Additionally, the `Drop` trait is used to define destructors. This +trait provides one method called `drop`, which is automatically +called when a value of the type that implements this trait is +destroyed, either because the value went out of scope or because the +garbage collector reclaimed it. + +~~~ +struct TimeBomb { + explosivity: uint +} + +impl Drop for TimeBomb { + fn drop(&mut self) { + for _ in range(0, self.explosivity) { + println!("blam!"); + } + } +} +~~~ + +It is illegal to call `drop` directly. Only code inserted by the compiler +may call it. + +## Declaring and implementing traits + +At its simplest, a trait is a set of zero or more _method signatures_. +For example, we could declare the trait +`Printable` for things that can be printed to the console, +with a single method signature: + +~~~~ +trait Printable { + fn print(&self); +} +~~~~ + +We say that the `Printable` trait _provides_ a `print` method with the +given signature. This means that we can call `print` on an argument +of any type that implements the `Printable` trait. + +Rust's built-in `Send` and `Freeze` types are examples of traits that +don't provide any methods. + +Traits may be implemented for specific types with [impls]. An impl for +a particular trait gives an implementation of the methods that +trait provides. For instance, the following impls of +`Printable` for `int` and `~str` give implementations of the `print` +method. + +[impls]: #methods + +~~~~ +# trait Printable { fn print(&self); } +impl Printable for int { + fn print(&self) { println!("{:?}", *self) } +} + +impl Printable for ~str { + fn print(&self) { println!("{}", *self) } +} + +# 1.print(); +# (~"foo").print(); +~~~~ + +Methods defined in an impl for a trait may be called just like +any other method, using dot notation, as in `1.print()`. + +## Default method implementations in trait definitions + +Sometimes, a method that a trait provides will have the same +implementation for most or all of the types that implement that trait. +For instance, suppose that we wanted `bool`s and `f32`s to be +printable, and that we wanted the implementation of `print` for those +types to be exactly as it is for `int`, above: + +~~~~ +# trait Printable { fn print(&self); } +impl Printable for f32 { + fn print(&self) { println!("{:?}", *self) } +} + +impl Printable for bool { + fn print(&self) { println!("{:?}", *self) } +} + +# true.print(); +# 3.14159.print(); +~~~~ + +This works fine, but we've now repeated the same definition of `print` +in three places. Instead of doing that, we can simply include the +definition of `print` right in the trait definition, instead of just +giving its signature. That is, we can write the following: + +~~~~ +trait Printable { + // Default method implementation + fn print(&self) { println!("{:?}", *self) } +} + +impl Printable for int {} + +impl Printable for ~str { + fn print(&self) { println!("{}", *self) } +} + +impl Printable for bool {} + +impl Printable for f32 {} + +# 1.print(); +# (~"foo").print(); +# true.print(); +# 3.14159.print(); +~~~~ + +Here, the impls of `Printable` for `int`, `bool`, and `f32` don't +need to provide an implementation of `print`, because in the absence +of a specific implementation, Rust just uses the _default method_ +provided in the trait definition. Depending on the trait, default +methods can save a great deal of boilerplate code from having to be +written in impls. Of course, individual impls can still override the +default method for `print`, as is being done above in the impl for +`~str`. + +## Type-parameterized traits + +Traits may be parameterized by type variables. For example, a trait +for generalized sequence types might look like the following: + +~~~~ +trait Seq<T> { + fn length(&self) -> uint; +} + +impl<T> Seq<T> for ~[T] { + fn length(&self) -> uint { self.len() } +} +~~~~ + +The implementation has to explicitly declare the type parameter that +it binds, `T`, before using it to specify its trait type. Rust +requires this declaration because the `impl` could also, for example, +specify an implementation of `Seq<int>`. The trait type (appearing +between `impl` and `for`) *refers* to a type, rather than +defining one. + +The type parameters bound by a trait are in scope in each of the +method declarations. So, re-declaring the type parameter +`T` as an explicit type parameter for `len`, in either the trait or +the impl, would be a compile-time error. + +Within a trait definition, `Self` is a special type that you can think +of as a type parameter. An implementation of the trait for any given +type `T` replaces the `Self` type parameter with `T`. The following +trait describes types that support an equality operation: + +~~~~ +// In a trait, `self` refers to the self argument. +// `Self` refers to the type implementing the trait. +trait Eq { + fn equals(&self, other: &Self) -> bool; +} + +// In an impl, `self` refers just to the value of the receiver +impl Eq for int { + fn equals(&self, other: &int) -> bool { *other == *self } +} +~~~~ + +Notice that in the trait definition, `equals` takes a +second parameter of type `Self`. +In contrast, in the `impl`, `equals` takes a second parameter of +type `int`, only using `self` as the name of the receiver. + +Just as in type implementations, traits can define standalone (static) +methods. These methods are called by prefixing the method name with the trait +name and a double colon. The compiler uses type inference to decide which +implementation to use. + +~~~~ +use std::f64::consts::PI; +trait Shape { fn new(area: f64) -> Self; } +struct Circle { radius: f64 } +struct Square { length: f64 } + +impl Shape for Circle { + fn new(area: f64) -> Circle { Circle { radius: (area / PI).sqrt() } } +} +impl Shape for Square { + fn new(area: f64) -> Square { Square { length: (area).sqrt() } } +} + +let area = 42.5; +let c: Circle = Shape::new(area); +let s: Square = Shape::new(area); +~~~~ + +## Bounded type parameters and static method dispatch + +Traits give us a language for defining predicates on types, or +abstract properties that types can have. We can use this language to +define _bounds_ on type parameters, so that we can then operate on +generic types. + +~~~~ +# trait Printable { fn print(&self); } +fn print_all<T: Printable>(printable_things: ~[T]) { + for thing in printable_things.iter() { + thing.print(); + } +} +~~~~ + +Declaring `T` as conforming to the `Printable` trait (as we earlier +did with `Clone`) makes it possible to call methods from that trait +on values of type `T` inside the function. It will also cause a +compile-time error when anyone tries to call `print_all` on an array +whose element type does not have a `Printable` implementation. + +Type parameters can have multiple bounds by separating them with `+`, +as in this version of `print_all` that copies elements. + +~~~ +# trait Printable { fn print(&self); } +fn print_all<T: Printable + Clone>(printable_things: ~[T]) { + let mut i = 0; + while i < printable_things.len() { + let copy_of_thing = printable_things[i].clone(); + copy_of_thing.print(); + i += 1; + } +} +~~~ + +Method calls to bounded type parameters are _statically dispatched_, +imposing no more overhead than normal function invocation, so are +the preferred way to use traits polymorphically. + +This usage of traits is similar to Haskell type classes. + +## Trait objects and dynamic method dispatch + +The above allows us to define functions that polymorphically act on +values of a single unknown type that conforms to a given trait. +However, consider this function: + +~~~~ +# type Circle = int; type Rectangle = int; +# impl Drawable for int { fn draw(&self) {} } +# fn new_circle() -> int { 1 } +trait Drawable { fn draw(&self); } + +fn draw_all<T: Drawable>(shapes: ~[T]) { + for shape in shapes.iter() { shape.draw(); } +} +# let c: Circle = new_circle(); +# draw_all(~[c]); +~~~~ + +You can call that on an array of circles, or an array of rectangles +(assuming those have suitable `Drawable` traits defined), but not on +an array containing both circles and rectangles. When such behavior is +needed, a trait name can alternately be used as a type, called +an _object_. + +~~~~ +# trait Drawable { fn draw(&self); } +fn draw_all(shapes: &[@Drawable]) { + for shape in shapes.iter() { shape.draw(); } +} +~~~~ + +In this example, there is no type parameter. Instead, the `@Drawable` +type denotes any managed box value that implements the `Drawable` +trait. To construct such a value, you use the `as` operator to cast a +value to an object: + +~~~~ +# type Circle = int; type Rectangle = bool; +# trait Drawable { fn draw(&self); } +# fn new_circle() -> Circle { 1 } +# fn new_rectangle() -> Rectangle { true } +# fn draw_all(shapes: &[@Drawable]) {} + +impl Drawable for Circle { fn draw(&self) { ... } } +impl Drawable for Rectangle { fn draw(&self) { ... } } + +let c: @Circle = @new_circle(); +let r: @Rectangle = @new_rectangle(); +draw_all([c as @Drawable, r as @Drawable]); +~~~~ + +We omit the code for `new_circle` and `new_rectangle`; imagine that +these just return `Circle`s and `Rectangle`s with a default size. Note +that, like strings and vectors, objects have dynamic size and may +only be referred to via one of the pointer types. +Other pointer types work as well. +Casts to traits may only be done with compatible pointers so, +for example, an `@Circle` may not be cast to an `~Drawable`. + +~~~ +# type Circle = int; type Rectangle = int; +# trait Drawable { fn draw(&self); } +# impl Drawable for int { fn draw(&self) {} } +# fn new_circle() -> int { 1 } +# fn new_rectangle() -> int { 2 } +// A managed object +let boxy: @Drawable = @new_circle() as @Drawable; +// An owned object +let owny: ~Drawable = ~new_circle() as ~Drawable; +// A borrowed object +let stacky: &Drawable = &new_circle() as &Drawable; +~~~ + +Method calls to trait types are _dynamically dispatched_. Since the +compiler doesn't know specifically which functions to call at compile +time, it uses a lookup table (also known as a vtable or dictionary) to +select the method to call at runtime. + +This usage of traits is similar to Java interfaces. + +By default, each of the three storage classes for traits enforce a +particular set of built-in kinds that their contents must fulfill in +order to be packaged up in a trait object of that storage class. + +* The contents of owned traits (`~Trait`) must fulfill the `Send` bound. +* The contents of managed traits (`@Trait`) must fulfill the `'static` bound. +* The contents of reference traits (`&Trait`) are not constrained by any bound. + +Consequently, the trait objects themselves automatically fulfill their +respective kind bounds. However, this default behavior can be overridden by +specifying a list of bounds on the trait type, for example, by writing `~Trait:` +(which indicates that the contents of the owned trait need not fulfill any +bounds), or by writing `~Trait:Send+Freeze`, which indicates that in addition +to fulfilling `Send`, contents must also fulfill `Freeze`, and as a consequence, +the trait itself fulfills `Freeze`. + +* `~Trait:Send` is equivalent to `~Trait`. +* `@Trait:'static` is equivalent to `@Trait`. +* `&Trait:` is equivalent to `&Trait`. + +Builtin kind bounds can also be specified on closure types in the same way (for +example, by writing `fn:Freeze()`), and the default behaviours are the same as +for traits of the same storage class. + +## Trait inheritance + +We can write a trait declaration that _inherits_ from other traits, called _supertraits_. +Types that implement a trait must also implement its supertraits. +For example, +we can define a `Circle` trait that inherits from `Shape`. + +~~~~ +trait Shape { fn area(&self) -> f64; } +trait Circle : Shape { fn radius(&self) -> f64; } +~~~~ + +Now, we can implement `Circle` on a type only if we also implement `Shape`. + +~~~~ +use std::f64::consts::PI; +# trait Shape { fn area(&self) -> f64; } +# trait Circle : Shape { fn radius(&self) -> f64; } +# struct Point { x: f64, y: f64 } +# fn square(x: f64) -> f64 { x * x } +struct CircleStruct { center: Point, radius: f64 } +impl Circle for CircleStruct { + fn radius(&self) -> f64 { (self.area() / PI).sqrt() } +} +impl Shape for CircleStruct { + fn area(&self) -> f64 { PI * square(self.radius) } +} +~~~~ + +Notice that methods of `Circle` can call methods on `Shape`, as our +`radius` implementation calls the `area` method. +This is a silly way to compute the radius of a circle +(since we could just return the `radius` field), but you get the idea. + +In type-parameterized functions, +methods of the supertrait may be called on values of subtrait-bound type parameters. +Refering to the previous example of `trait Circle : Shape`: + +~~~ +# trait Shape { fn area(&self) -> f64; } +# trait Circle : Shape { fn radius(&self) -> f64; } +fn radius_times_area<T: Circle>(c: T) -> f64 { + // `c` is both a Circle and a Shape + c.radius() * c.area() +} +~~~ + +Likewise, supertrait methods may also be called on trait objects. + +~~~ {.ignore} +use std::f64::consts::PI; +# trait Shape { fn area(&self) -> f64; } +# trait Circle : Shape { fn radius(&self) -> f64; } +# struct Point { x: f64, y: f64 } +# struct CircleStruct { center: Point, radius: f64 } +# impl Circle for CircleStruct { fn radius(&self) -> f64 { (self.area() / PI).sqrt() } } +# impl Shape for CircleStruct { fn area(&self) -> f64 { PI * square(self.radius) } } + +let concrete = @CircleStruct{center:Point{x:3f,y:4f},radius:5f}; +let mycircle: @Circle = concrete as @Circle; +let nonsense = mycircle.radius() * mycircle.area(); +~~~ + +> ***Note:*** Trait inheritance does not actually work with objects yet + +## Deriving implementations for traits + +A small number of traits in `std` and `extra` can have implementations +that can be automatically derived. These instances are specified by +placing the `deriving` attribute on a data type declaration. For +example, the following will mean that `Circle` has an implementation +for `Eq` and can be used with the equality operators, and that a value +of type `ABC` can be randomly generated and converted to a string: + +~~~ +#[deriving(Eq)] +struct Circle { radius: f64 } + +#[deriving(Rand, ToStr)] +enum ABC { A, B, C } +~~~ + +The full list of derivable traits is `Eq`, `TotalEq`, `Ord`, +`TotalOrd`, `Encodable` `Decodable`, `Clone`, `DeepClone`, +`IterBytes`, `Rand`, `Default`, `Zero`, and `ToStr`. + +# Crates and the module system + +Rust's module system is very powerful, but because of that also somewhat complex. +Nevertheless, this section will try to explain every important aspect of it. + +## Crates + +In order to speak about the module system, we first need to define the medium it exists in: + +Let's say you've written a program or a library, compiled it, and got the resulting binary. +In Rust, the content of all source code that the compiler directly had to compile in order to end up with +that binary is collectively called a 'crate'. + +For example, for a simple hello world program your crate only consists of this code: + +~~~~ +// `main.rs` +fn main() { + println!("Hello world!"); +} +~~~~ + +A crate is also the unit of independent compilation in Rust: `rustc` always compiles a single crate at a time, +from which it produces either a library or an executable. + +Note that merely using an already compiled library in your code does not make it part of your crate. + +## The module hierarchy + +For every crate, all the code in it is arranged in a hierarchy of modules starting with a single +root module. That root module is called the 'crate root'. + +All modules in a crate below the crate root are declared with the `mod` keyword: + +~~~~ +// This is the crate root + +mod farm { + // This is the body of module 'farm' declared in the crate root. + + fn chicken() { println!("cluck cluck"); } + fn cow() { println!("mooo"); } + + mod barn { + // Body of module 'barn' + + fn hay() { println!("..."); } + } +} + +fn main() { + println!("Hello farm!"); +} +~~~~ + +As you can see, your module hierarchy is now three modules deep: There is the crate root, which contains your `main()` +function, and the module `farm`. The module `farm` also contains two functions and a third module `barn`, +which contains a function `hay`. + +(In case you already stumbled over `extern mod`: It isn't directly related to a bare `mod`, we'll get to it later. ) + +## Paths and visibility + +We've now defined a nice module hierarchy. But how do we access the items in it from our `main` function? +One way to do it is to simply fully qualifying it: + +~~~~ {.ignore} +mod farm { + fn chicken() { println!("cluck cluck"); } + // ... +} + +fn main() { + println!("Hello chicken!"); + + ::farm::chicken(); // Won't compile yet, see further down +} +~~~~ + +The `::farm::chicken` construct is what we call a 'path'. + +Because it's starting with a `::`, it's also a 'global path', which qualifies +an item by its full path in the module hierarchy relative to the crate root. + +If the path were to start with a regular identifier, like `farm::chicken`, it +would be a 'local path' instead. We'll get to them later. + +Now, if you actually tried to compile this code example, you'll notice that you +get a `function 'chicken' is private` error. That's because by default, items +(`fn`, `struct`, `static`, `mod`, ...) are private. + +To make them visible outside their containing modules, you need to mark them +_public_ with `pub`: + +~~~~ +mod farm { + pub fn chicken() { println!("cluck cluck"); } + pub fn cow() { println!("mooo"); } + // ... +} + +fn main() { + println!("Hello chicken!"); + ::farm::chicken(); // This compiles now +} +~~~~ + +Visibility restrictions in Rust exist only at module boundaries. This +is quite different from most object-oriented languages that also +enforce restrictions on objects themselves. That's not to say that +Rust doesn't support encapsulation: both struct fields and methods can +be private. But this encapsulation is at the module level, not the +struct level. + +For convenience, fields are _public_ by default, and can be made _private_ with +the `priv` keyword: + +~~~ +mod farm { +# pub type Chicken = int; +# struct Human(int); +# impl Human { pub fn rest(&self) { } } +# pub fn make_me_a_farm() -> Farm { Farm { chickens: ~[], farmer: Human(0) } } + pub struct Farm { + priv chickens: ~[Chicken], + farmer: Human + } + + impl Farm { + fn feed_chickens(&self) { ... } + pub fn add_chicken(&self, c: Chicken) { ... } + } + + pub fn feed_animals(farm: &Farm) { + farm.feed_chickens(); + } +} + +fn main() { + let f = make_me_a_farm(); + f.add_chicken(make_me_a_chicken()); + farm::feed_animals(&f); + f.farmer.rest(); + + // This wouldn't compile because both are private: + // `f.feed_chickens();` + // `let chicken_counter = f.chickens.len();` +} +# fn make_me_a_farm() -> farm::Farm { farm::make_me_a_farm() } +# fn make_me_a_chicken() -> farm::Chicken { 0 } +~~~ + +Exact details and specifications about visibility rules can be found in the Rust +manual. + +## Files and modules + +One important aspect about Rusts module system is that source files are not important: +You define a module hierarchy, populate it with all your definitions, define visibility, +maybe put in a `fn main()`, and that's it: No need to think about source files. + +The only file that's relevant is the one that contains the body of your crate root, +and it's only relevant because you have to pass that file to `rustc` to compile your crate. + +And in principle, that's all you need: You can write any Rust program as one giant source file that contains your +crate root and everything below it in `mod ... { ... }` declarations. + +However, in practice you usually want to split you code up into multiple source files to make it more manageable. +In order to do that, Rust allows you to move the body of any module into it's own source file, which works like this: + +If you declare a module without its body, like `mod foo;`, the compiler will look for the +files `foo.rs` and `foo/mod.rs` inside some directory (usually the same as of the source file containing +the `mod foo;`). If it finds either, it uses the content of that file as the body of the module. +If it finds both, that's a compile error. + +So, if we want to move the content of `mod farm` into it's own file, it would look like this: + +~~~~ {.ignore} +// `main.rs` - contains body of the crate root +mod farm; // Compiler will look for `farm.rs` and `farm/mod.rs` + +fn main() { + println!("Hello farm!"); + ::farm::cow(); +} +~~~~ + +~~~~ +// `farm.rs` - contains body of module 'farm' in the crate root +pub fn chicken() { println!("cluck cluck"); } +pub fn cow() { println!("mooo"); } + +pub mod barn { + pub fn hay() { println!("..."); } +} +# fn main() { } +~~~~ + +In short, `mod foo;` is just syntactic sugar for `mod foo { /* content of <...>/foo.rs or <...>/foo/mod.rs */ }`. + +This also means that having two or more identical `mod foo;` somewhere +in your crate hierarchy is generally a bad idea, +just like copy-and-paste-ing a module into two or more places is one. +Both will result in duplicate and mutually incompatible definitions. + +The directory the compiler looks in for those two files is determined by starting with +the same directory as the source file that contains the `mod foo;` declaration, and concatenating to that a +path equivalent to the relative path of all nested `mod { ... }` declarations the `mod foo;` +is contained in, if any. + +For example, given a file with this module body: + +~~~ {.ignore} +// `src/main.rs` +mod plants; +mod animals { + mod fish; + mod mammals { + mod humans; + } +} +~~~ + +The compiler would then try all these files: + +~~~ {.notrust} +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 +~~~ + +Keep in mind that identical module hierachies can still lead to different path lookups +depending on how and where you've moved a module body to its own file. +For example, if we move the `animals` module above into its own file... + +~~~ {.ignore} +// `src/main.rs` +mod plants; +mod animals; +~~~ + +~~~ {.ignore} +// `src/animals.rs` or `src/animals/mod.rs` +mod fish; +mod mammals { + mod humans; +} +~~~ + +...then the source files of `mod animals`'s submodules can +either be placed right next to that of its parents, or in a subdirectory if `animals` source file is: + +~~~ {.notrust} +src/plants.rs +src/plants/mod.rs + +src/animals.rs - if file sits next to that of parent module's: + src/fish.rs + src/fish/mod.rs + + src/mammals/humans.rs + src/mammals/humans/mod.rs + +src/animals/mod.rs - if file is in it's own subdirectory: + src/animals/fish.rs + src/animals/fish/mod.rs + + src/animals/mammals/humans.rs + src/animals/mammals/humans/mod.rs + +~~~ + +These rules allow you to have both small modules that only need +to consist of one source file each and can be conveniently placed right next to each other, +and big complicated modules that group the source files of submodules in subdirectories. + +If you need to circumvent the defaults, you can also overwrite the path a `mod foo;` would take: + +~~~ {.ignore} +#[path="../../area51/alien.rs"] +mod classified; +~~~ + +## Importing names into the local scope + +Always referring to definitions in other modules with their global +path gets old really fast, so Rust has a way to import +them into the local scope of your module: `use`-statements. + +They work like this: At the beginning of any module body, `fn` body, or any other block +you can write a list of `use`-statements, consisting of the keyword `use` and a __global path__ to an item +without the `::` prefix. For example, this imports `cow` into the local scope: + +~~~ +use farm::cow; +# mod farm { pub fn cow() { println!("I'm a hidden ninja cow!") } } +# fn main() { cow() } +~~~ + +The path you give to `use` is per default global, meaning relative to the crate root, +no matter how deep the module hierarchy is, or whether the module body it's written in +is contained in its own file (remember: files are irrelevant). + +This is different to other languages, where you often only find a single import construct that combines the semantic +of `mod foo;` and `use`-statements, and which tend to work relative to the source file or use an absolute file path +- Rubys `require` or C/C++'s `#include` come to mind. + +However, it's also possible to import things relative to the module of the `use`-statement: +Adding a `super::` in front of the path will start in the parent module, +while adding a `self::` prefix will start in the current module: + +~~~ +# mod workaround { +# pub fn some_parent_item(){ println!("...") } +# mod foo { +use super::some_parent_item; +use self::some_child_module::some_item; +# pub fn bar() { some_parent_item(); some_item() } +# pub mod some_child_module { pub fn some_item() {} } +# } +# } +~~~ + +Again - relative to the module, not to the file. + +Imports are also shadowed by local definitions: +For each name you mention in a module/block, `rust` +will first look at all items that are defined locally, +and only if that results in no match look at items you brought in +scope with corresponding `use` statements. + +~~~ {.ignore} +# // FIXME: Allow unused import in doc test +use farm::cow; +// ... +# mod farm { pub fn cow() { println!("Hidden ninja cow is hidden.") } } +fn cow() { println!("Mooo!") } + +fn main() { + cow() // resolves to the locally defined `cow()` function +} +~~~ + +To make this behavior more obvious, the rule has been made that `use`-statement always need to be written +before any declaration, like in the example above. This is a purely artificial rule introduced +because people always assumed they shadowed each other based on order, despite the fact that all items in rust are +mutually recursive, order independent definitions. + +One odd consequence of that rule is that `use` statements also go in front of any `mod` declaration, +even if they refer to things inside them: + +~~~ +use farm::cow; +mod farm { + pub fn cow() { println!("Moooooo?") } +} + +fn main() { cow() } +~~~ + +This is what our `farm` example looks like with `use` statements: + +~~~~ +use farm::chicken; +use farm::cow; +use farm::barn; + +mod farm { + pub fn chicken() { println!("cluck cluck"); } + pub fn cow() { println!("mooo"); } + + pub mod barn { + pub fn hay() { println!("..."); } + } +} + +fn main() { + println!("Hello farm!"); + + // Can now refer to those names directly: + chicken(); + cow(); + barn::hay(); +} +~~~~ + +And here an example with multiple files: + +~~~{.ignore} +// `a.rs` - crate root +use b::foo; +mod b; +fn main() { foo(); } +~~~ + +~~~{.ignore} +// `b.rs` +use b::c::bar; +pub mod c; +pub fn foo() { bar(); } +~~~ + +~~~ +// `c.rs` +pub fn bar() { println!("Baz!"); } +# fn main() {} +~~~ + +There also exist two short forms for importing multiple names at once: + +1. Explicit mention multiple names as the last element of an `use` path: + +~~~ +use farm::{chicken, cow}; +# mod farm { +# pub fn cow() { println!("Did I already mention how hidden and ninja I am?") } +# pub fn chicken() { println!("I'm Bat-chicken, guardian of the hidden tutorial code.") } +# } +# fn main() { cow(); chicken() } +~~~ + +2. Import everything in a module with a wildcard: + +~~~ +use farm::*; +# mod farm { +# pub fn cow() { println!("Bat-chicken? What a stupid name!") } +# pub fn chicken() { println!("Says the 'hidden ninja' cow.") } +# } +# fn main() { cow(); chicken() } +~~~ + +> ***Note:*** This feature of the compiler is currently gated behind the +> `#[feature(globs)]` directive. More about these directives can be found in +> the manual. + +However, that's not all. You can also rename an item while you're bringing it into scope: + +~~~ +use egg_layer = farm::chicken; +# mod farm { pub fn chicken() { println!("Laying eggs is fun!") } } +// ... + +fn main() { + egg_layer(); +} +~~~ + +In general, `use` creates an local alias: +An alternate path and a possibly different name to access the same item, +without touching the original, and with both being interchangeable. + +## Reexporting names + +It is also possible to reexport items to be accessible under your module. + +For that, you write `pub use`: + +~~~ +mod farm { + pub use self::barn::hay; + + pub fn chicken() { println!("cluck cluck"); } + pub fn cow() { println!("mooo"); } + + mod barn { + pub fn hay() { println!("..."); } + } +} + +fn main() { + farm::chicken(); + farm::cow(); + farm::hay(); +} +~~~ + +Just like in normal `use` statements, the exported names +merely represent an alias to the same thing and can also be renamed. + +The above example also demonstrate what you can use `pub use` for: +The nested `barn` module is private, but the `pub use` allows users +of the module `farm` to access a function from `barn` without needing +to know that `barn` exists. + +In other words, you can use them to decouple an public api from their internal implementation. + +## Using libraries + +So far we've only talked about how to define and structure your own crate. + +However, most code out there will want to use preexisting libraries, +as there really is no reason to start from scratch each time you start a new project. + +In Rust terminology, we need a way to refer to other crates. + +For that, Rust offers you the `extern mod` declaration: + +~~~ +extern mod extra; +// extra ships with Rust, you'll find more details further down. + +fn main() { + // The rational number '1/2': + let one_half = ::extra::rational::Ratio::new(1, 2); +} +~~~ + +Despite its name, `extern mod` is a distinct construct from regular `mod` declarations: +A statement of the form `extern mod foo;` will cause `rustc` to search for the crate `foo`, +and if it finds a matching binary it lets you use it from inside your crate. + +The effect it has on your module hierarchy mirrors aspects of both `mod` and `use`: + +- Like `mod`, it causes `rustc` to actually emit code: + The linkage information the binary needs to use the library `foo`. + +- But like `use`, all `extern mod` statements that refer to the same library are interchangeable, + as each one really just presents an alias to an external module (the crate root of the library + you're linking against). + +Remember how `use`-statements have to go before local declarations because the latter shadows the former? +Well, `extern mod` statements also have their own rules in that regard: +Both `use` and local declarations can shadow them, so the rule is that `extern mod` has to go in front +of both `use` and local declarations. + +Which can result in something like this: + +~~~ +extern mod extra; + +use farm::dog; +use extra::rational::Ratio; + +mod farm { + pub fn dog() { println!("woof"); } +} + +fn main() { + farm::dog(); + let a_third = Ratio::new(1, 3); +} +~~~ + +It's a bit weird, but it's the result of shadowing rules that have been set that way because +they model most closely what people expect to shadow. + +## Package ids + +If you use `extern mod`, per default `rustc` will look for libraries in the library search path (which you can +extend with the `-L` switch). + +## Crate metadata and settings + +For every crate you can define a number of metadata items, such as link name, version or author. +You can also toggle settings that have crate-global consequences. Both mechanism +work by providing attributes in the crate root. + +For example, Rust uniquely identifies crates by their link metadata, which includes +the link name and the version. It also hashes the filename and the symbols in a binary +based on the link metadata, allowing you to use two different versions of the same library in a crate +without conflict. + +Therefore, if you plan to compile your crate as a library, you should annotate it with that information: + +~~~~ +// `lib.rs` + +# #[crate_type = "lib"]; +// Package ID +#[crate_id = "farm#2.5"]; + +// ... +# fn farm() {} +~~~~ + +You can also specify package ID information in a `extern mod` statement. For +example, these `extern mod` statements would both accept and select the +crate define above: + +~~~~ {.ignore} +extern mod farm; +extern mod farm = "farm#2.5"; +extern mod my_farm = "farm"; +~~~~ + +Other crate settings and metadata include things like enabling/disabling certain errors or warnings, +or setting the crate type (library or executable) explicitly: + +~~~~ +// `lib.rs` +// ... + +// This crate is a library ("bin" is the default) +#[crate_id = "farm#2.5"]; +#[crate_type = "lib"]; + +// Turn on a warning +#[warn(non_camel_case_types)] +# fn farm() {} +~~~~ + +## A minimal example + +Now for something that you can actually compile yourself. + +We define two crates, and use one of them as a library in the other. + +~~~~ +// `world.rs` +#[crate_id = "world#0.42"]; +# extern mod extra; +pub fn explore() -> &'static str { "world" } +# fn main() {} +~~~~ + +~~~~ {.ignore} +// `main.rs` +extern mod world; +fn main() { println!("hello {}", world::explore()); } +~~~~ + +Now compile and run like this (adjust to your platform if necessary): + +~~~~ {.notrust} +> rustc --lib world.rs # compiles libworld-<HASH>-0.42.so +> rustc main.rs -L . # compiles main +> ./main +"hello world" +~~~~ + +Notice that the library produced contains the version in the file name +as well as an inscrutable string of alphanumerics. As explained in the previous paragraph, +these are both part of Rust's library versioning scheme. The alphanumerics are +a hash representing the crates package ID. + +## The standard library and the prelude + +While reading the examples in this tutorial, you might have asked yourself where all +those magical predefined items like `range` are coming from. + +The truth is, there's nothing magical about them: They are all defined normally +in the `std` library, which is a crate that ships with Rust. + +The only magical thing that happens is that `rustc` automatically inserts this line into your crate root: + +~~~ {.ignore} +extern mod std; +~~~ + +As well as this line into every module body: + +~~~ {.ignore} +use std::prelude::*; +~~~ + +The role of the `prelude` module is to re-export common definitions from `std`. + +This allows you to use common types and functions like `Option<T>` or `range` +without needing to import them. And if you need something from `std` that's not in the prelude, +you just have to import it with an `use` statement. + +For example, it re-exports `range` which is defined in `std::iter::range`: + +~~~ +use iter_range = std::iter::range; + +fn main() { + // `range` is imported by default + for _ in range(0, 10) {} + + // Doesn't hinder you from importing it under a different name yourself + for _ in iter_range(0, 10) {} + + // Or from not using the automatic import. + for _ in ::std::iter::range(0, 10) {} +} +~~~ + +Both auto-insertions can be disabled with an attribute if necessary: + +~~~ +// In the crate root: +#[no_std]; +~~~ + +~~~ +// In any module: +#[no_implicit_prelude]; +~~~ + +See the [API documentation][stddoc] for details. + +[stddoc]: std/index.html + +## The extra library + +Rust also ships with the [extra library], an accumulation of useful things, +that are however not important enough to deserve a place in the standard +library. You can use them by linking to `extra` with an `extern mod extra;`. + +[extra library]: extra/index.html + +Right now `extra` contains those definitions directly, but in the future it will likely just +re-export a bunch of 'officially blessed' crates that get managed with a +package manager. + +# What next? + +Now that you know the essentials, check out any of the additional +guides on individual topics. + +* [Pointers][pointers] +* [Lifetimes][lifetimes] +* [Tasks and communication][tasks] +* [Macros][macros] +* [The foreign function interface][ffi] +* [Containers and iterators][container] +* [Error-handling and Conditions][conditions] +* [Documenting Rust code][rustdoc] +* [Testing Rust code][testing] +* [The Rust Runtime][runtime] + +There is further documentation on the [wiki], however those tend to be even more out of date as this document. + +[pointers]: guide-pointers.html +[lifetimes]: guide-lifetimes.html +[tasks]: guide-tasks.html +[macros]: guide-macros.html +[ffi]: guide-ffi.html +[container]: guide-container.html +[conditions]: guide-conditions.html +[testing]: guide-testing.html +[runtime]: guide-runtime.html +[rustdoc]: rustdoc.html +[wiki]: https://github.com/mozilla/rust/wiki/Docs + +[wiki-packages]: https://github.com/mozilla/rust/wiki/Doc-packages,-editors,-and-other-tools diff --git a/src/doc/version_info.html.template b/src/doc/version_info.html.template new file mode 100644 index 00000000000..858e5a35f87 --- /dev/null +++ b/src/doc/version_info.html.template @@ -0,0 +1,6 @@ +<div id="versioninfo"> + <img src="http://www.rust-lang.org/logos/rust-logo-32x32-blk.png" width="32" height="32" alt><br> + <span class="white-sticker"><a href="http://rust-lang.org">Rust</a> VERSION</span><br> + <a href="http://github.com/mozilla/rust/commit/STAMP" + class="hash white-sticker">SHORT_HASH</a> +</div> \ No newline at end of file |