diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4870aa6a8980..609bf03fb6c91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -131,8 +131,12 @@ Some common make targets are: & everything builds in the correct manner. - `make check-stage1-std NO_REBUILD=1` - test the standard library without rebuilding the entire compiler -- `make check TESTNAME=.rs` - Run a single test file -- `make check-stage1-rpass TESTNAME=.rs` - Run a single +- `make check TESTNAME=` - Run a matching set of tests. + - `TESTNAME` should be a substring of the tests to match against e.g. it could + be the fully qualified test name, or just a part of it. + `TESTNAME=collections::hash::map::test_map::test_capacity_not_less_than_len` + or `TESTNAME=test_capacity_not_less_than_len`. +- `make check-stage1-rpass TESTNAME=` - Run a single rpass test with the stage1 compiler (this will be quicker than running the command above as we only build the stage1 compiler, not the entire thing). You can also leave off the `-rpass` to run all stage1 test types. diff --git a/src/doc/book/documentation.md b/src/doc/book/documentation.md index 4053e5776e39f..ede3100194e5b 100644 --- a/src/doc/book/documentation.md +++ b/src/doc/book/documentation.md @@ -118,7 +118,7 @@ least. If your function has a non-trivial contract like this, that is detected/enforced by panics, documenting it is very important. ```rust -/// # Failures +/// # Errors # fn foo() {} ``` diff --git a/src/doc/book/error-handling.md b/src/doc/book/error-handling.md index 78527c21d1067..73875704ecaf7 100644 --- a/src/doc/book/error-handling.md +++ b/src/doc/book/error-handling.md @@ -356,11 +356,28 @@ fn file_name(file_path: &str) -> Option<&str> { ``` You might think that we could use the `map` combinator to reduce the case -analysis, but its type doesn't quite fit. Namely, `map` takes a function that -does something only with the inner value. The result of that function is then -*always* [rewrapped with `Some`](#code-option-map). Instead, we need something -like `map`, but which allows the caller to return another `Option`. Its generic -implementation is even simpler than `map`: +analysis, but its type doesn't quite fit... + +```rust,ignore +fn file_path_ext(file_path: &str) -> Option<&str> { + file_name(file_path).map(|x| extension(x)) //Compilation error +} +``` + +The `map` function here wraps the value returned by the `extension` function +inside an `Option<_>` and since the `extension` function itself returns an +`Option<&str>` the expression `file_name(file_path).map(|x| extension(x))` +actually returns an `Option>`. + +But since `file_path_ext` just returns `Option<&str>` (and not +`Option>`) we get a compilation error. + +The result of the function taken by map as input is *always* [rewrapped with +`Some`](#code-option-map). Instead, we need something like `map`, but which +allows the caller to return a `Option<_>` directly without wrapping it in +another `Option<_>`. + +Its generic implementation is even simpler than `map`: ```rust fn and_then(option: Option, f: F) -> Option @@ -382,6 +399,10 @@ fn file_path_ext(file_path: &str) -> Option<&str> { } ``` +Side note: Since `and_then` essentially works like `map` but returns an +`Option<_>` instead of an `Option>` it is known as `flatmap` in some +other languages. + The `Option` type has many other combinators [defined in the standard library][5]. It is a good idea to skim this list and familiarize yourself with what's available—they can often reduce case analysis diff --git a/src/doc/book/getting-started.md b/src/doc/book/getting-started.md index d7b6e15794ef4..31ee385a928d6 100644 --- a/src/doc/book/getting-started.md +++ b/src/doc/book/getting-started.md @@ -39,6 +39,7 @@ Specifically they will each satisfy the following requirements: | Target | std |rustc|cargo| notes | |-------------------------------|-----|-----|-----|----------------------------| +| `i686-pc-windows-msvc` | ✓ | ✓ | ✓ | 32-bit MSVC (Windows 7+) | | `x86_64-pc-windows-msvc` | ✓ | ✓ | ✓ | 64-bit MSVC (Windows 7+) | | `i686-pc-windows-gnu` | ✓ | ✓ | ✓ | 32-bit MinGW (Windows 7+) | | `x86_64-pc-windows-gnu` | ✓ | ✓ | ✓ | 64-bit MinGW (Windows 7+) | @@ -62,7 +63,6 @@ these platforms are required to have each of the following: | Target | std |rustc|cargo| notes | |-------------------------------|-----|-----|-----|----------------------------| -| `i686-pc-windows-msvc` | ✓ | ✓ | ✓ | 32-bit MSVC (Windows 7+) | | `x86_64-unknown-linux-musl` | ✓ | | | 64-bit Linux with MUSL | | `arm-linux-androideabi` | ✓ | | | ARM Android | | `arm-unknown-linux-gnueabi` | ✓ | ✓ | | ARM Linux (2.6.18+) | @@ -85,6 +85,9 @@ unofficial locations. | `i686-linux-android` | ✓ | | | 32-bit x86 Android | | `aarch64-linux-android` | ✓ | | | ARM64 Android | | `powerpc-unknown-linux-gnu` | ✓ | | | PowerPC Linux (2.6.18+) | +| `powerpc64-unknown-linux-gnu` | ✓ | | | PPC64 Linux (2.6.18+) | +|`powerpc64le-unknown-linux-gnu`| ✓ | | | PPC64LE Linux (2.6.18+) | +|`armv7-unknown-linux-gnueabihf`| ✓ | | | ARMv7 Linux (2.6.18+) | | `i386-apple-ios` | ✓ | | | 32-bit x86 iOS | | `x86_64-apple-ios` | ✓ | | | 64-bit x86 iOS | | `armv7-apple-ios` | ✓ | | | ARM iOS | @@ -97,6 +100,7 @@ unofficial locations. | `x86_64-unknown-bitrig` | ✓ | ✓ | | 64-bit Bitrig | | `x86_64-unknown-dragonfly` | ✓ | ✓ | | 64-bit DragonFlyBSD | | `x86_64-rumprun-netbsd` | ✓ | | | 64-bit NetBSD Rump Kernel | +| `x86_64-sun-solaris` | ✓ | ✓ | | 64-bit Solaris/SunOS | | `i686-pc-windows-msvc` (XP) | ✓ | | | Windows XP support | | `x86_64-pc-windows-msvc` (XP) | ✓ | | | Windows XP support | @@ -569,7 +573,7 @@ executable application, as opposed to a library. Executables are often called *binaries* (as in `/usr/bin`, if you’re on a Unix system). Cargo has generated two files and one directory for us: a `Cargo.toml` and a -*src* directory with a *main.rs* file inside. These should look familliar, +*src* directory with a *main.rs* file inside. These should look familiar, they’re exactly what we created by hand, above. This output is all you need to get started. First, open `Cargo.toml`. It should diff --git a/src/doc/book/loops.md b/src/doc/book/loops.md index 5b08c2fb04dbd..b5dde9be17fcb 100644 --- a/src/doc/book/loops.md +++ b/src/doc/book/loops.md @@ -125,7 +125,8 @@ Don't forget to add the parentheses around the range. #### On iterators: ```rust -# let lines = "hello\nworld".lines(); +let lines = "hello\nworld".lines(); + for (linenumber, line) in lines.enumerate() { println!("{}: {}", linenumber, line); } @@ -134,10 +135,8 @@ for (linenumber, line) in lines.enumerate() { Outputs: ```text -0: Content of line one -1: Content of line two -2: Content of line three -3: Content of line four +0: hello +1: world ``` ## Ending iteration early diff --git a/src/libcollections/str.rs b/src/libcollections/str.rs index 094b7f1d03453..20a7c651350cb 100644 --- a/src/libcollections/str.rs +++ b/src/libcollections/str.rs @@ -1511,6 +1511,13 @@ impl str { /// 'Whitespace' is defined according to the terms of the Unicode Derived /// Core Property `White_Space`. /// + /// # Text directionality + /// + /// A string is a sequence of bytes. 'Left' in this context means the first + /// position of that byte string; for a language like Arabic or Hebrew + /// which are 'right to left' rather than 'left to right', this will be + /// the _right_ side, not the left. + /// /// # Examples /// /// Basic usage: @@ -1520,6 +1527,16 @@ impl str { /// /// assert_eq!("Hello\tworld\t", s.trim_left()); /// ``` + /// + /// Directionality: + /// + /// ``` + /// let s = " English"; + /// assert!(Some('E') == s.trim_left().chars().next()); + /// + /// let s = " עברית"; + /// assert!(Some('ע') == s.trim_left().chars().next()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn trim_left(&self) -> &str { UnicodeStr::trim_left(self) @@ -1530,6 +1547,13 @@ impl str { /// 'Whitespace' is defined according to the terms of the Unicode Derived /// Core Property `White_Space`. /// + /// # Text directionality + /// + /// A string is a sequence of bytes. 'Right' in this context means the last + /// position of that byte string; for a language like Arabic or Hebrew + /// which are 'right to left' rather than 'left to right', this will be + /// the _left_ side, not the right. + /// /// # Examples /// /// Basic usage: @@ -1539,6 +1563,16 @@ impl str { /// /// assert_eq!(" Hello\tworld", s.trim_right()); /// ``` + /// + /// Directionality: + /// + /// ``` + /// let s = "English "; + /// assert!(Some('h') == s.trim_right().chars().rev().next()); + /// + /// let s = "עברית "; + /// assert!(Some('ת') == s.trim_right().chars().rev().next()); + /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub fn trim_right(&self) -> &str { UnicodeStr::trim_right(self) @@ -1584,6 +1618,13 @@ impl str { /// /// [`char`]: primitive.char.html /// + /// # Text directionality + /// + /// A string is a sequence of bytes. 'Left' in this context means the first + /// position of that byte string; for a language like Arabic or Hebrew + /// which are 'right to left' rather than 'left to right', this will be + /// the _right_ side, not the left. + /// /// # Examples /// /// Basic usage: @@ -1608,6 +1649,13 @@ impl str { /// /// [`char`]: primitive.char.html /// + /// # Text directionality + /// + /// A string is a sequence of bytes. 'Right' in this context means the last + /// position of that byte string; for a language like Arabic or Hebrew + /// which are 'right to left' rather than 'left to right', this will be + /// the _left_ side, not the right. + /// /// # Examples /// /// Simple patterns: @@ -1644,7 +1692,7 @@ impl str { /// /// [`FromStr`]: str/trait.FromStr.html /// - /// # Failure + /// # Errors /// /// Will return `Err` if it's not possible to parse this string slice into /// the desired type. diff --git a/src/libcollections/string.rs b/src/libcollections/string.rs index 97c12043e7634..b1242ba6d4df2 100644 --- a/src/libcollections/string.rs +++ b/src/libcollections/string.rs @@ -433,7 +433,7 @@ impl String { /// /// [`str::from_utf8()`]: ../str/fn.from_utf8.html /// - /// # Failure + /// # Errors /// /// Returns `Err` if the slice is not UTF-8 with a description as to why the /// provided bytes are not UTF-8. The vector you moved in is also included. diff --git a/src/libcore/iter.rs b/src/libcore/iter.rs index 3f1c0f6a5492a..93514dbd6bb2f 100644 --- a/src/libcore/iter.rs +++ b/src/libcore/iter.rs @@ -2756,20 +2756,11 @@ pub trait Extend { /// /// let mut iter = numbers.iter(); /// -/// let n = iter.next(); -/// assert_eq!(Some(&1), n); -/// -/// let n = iter.next_back(); -/// assert_eq!(Some(&3), n); -/// -/// let n = iter.next_back(); -/// assert_eq!(Some(&2), n); -/// -/// let n = iter.next(); -/// assert_eq!(None, n); -/// -/// let n = iter.next_back(); -/// assert_eq!(None, n); +/// assert_eq!(Some(&1), iter.next()); +/// assert_eq!(Some(&3), iter.next_back()); +/// assert_eq!(Some(&2), iter.next_back()); +/// assert_eq!(None, iter.next()); +/// assert_eq!(None, iter.next_back()); /// ``` #[stable(feature = "rust1", since = "1.0.0")] pub trait DoubleEndedIterator: Iterator { @@ -2789,20 +2780,11 @@ pub trait DoubleEndedIterator: Iterator { /// /// let mut iter = numbers.iter(); /// - /// let n = iter.next(); - /// assert_eq!(Some(&1), n); - /// - /// let n = iter.next_back(); - /// assert_eq!(Some(&3), n); - /// - /// let n = iter.next_back(); - /// assert_eq!(Some(&2), n); - /// - /// let n = iter.next(); - /// assert_eq!(None, n); - /// - /// let n = iter.next_back(); - /// assert_eq!(None, n); + /// assert_eq!(Some(&1), iter.next()); + /// assert_eq!(Some(&3), iter.next_back()); + /// assert_eq!(Some(&2), iter.next_back()); + /// assert_eq!(None, iter.next()); + /// assert_eq!(None, iter.next_back()); /// ``` #[stable(feature = "rust1", since = "1.0.0")] fn next_back(&mut self) -> Option; diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 3892455395f76..f19970546d79b 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -188,7 +188,7 @@ impl Utf8Error { /// it, this function is one way to have a stack-allocated string. There is /// an example of this in the examples section below. /// -/// # Failure +/// # Errors /// /// Returns `Err` if the slice is not UTF-8 with a description as to why the /// provided slice is not UTF-8. diff --git a/src/libcore/sync/atomic.rs b/src/libcore/sync/atomic.rs index 21b76c1f4bec1..700a577e20c92 100644 --- a/src/libcore/sync/atomic.rs +++ b/src/libcore/sync/atomic.rs @@ -711,7 +711,7 @@ impl AtomicUsize { /// ``` /// use std::sync::atomic::{AtomicUsize, Ordering}; /// - /// let some_usize= AtomicUsize::new(5); + /// let some_usize = AtomicUsize::new(5); /// /// assert_eq!(some_usize.swap(10, Ordering::Relaxed), 5); /// assert_eq!(some_usize.load(Ordering::Relaxed), 10); diff --git a/src/librustc_borrowck/diagnostics.rs b/src/librustc_borrowck/diagnostics.rs index 7ad4d3ca70898..6cbea1abbb5bb 100644 --- a/src/librustc_borrowck/diagnostics.rs +++ b/src/librustc_borrowck/diagnostics.rs @@ -377,6 +377,33 @@ fn main() { } ``` +Moving out of a member of a mutably borrowed struct is fine if you put something +back. `mem::replace` can be used for that: + +``` +struct TheDarkKnight; + +impl TheDarkKnight { + fn nothing_is_true(self) {} +} + +struct Batcave { + knight: TheDarkKnight +} + +fn main() { + use std::mem; + + let mut cave = Batcave { + knight: TheDarkKnight + }; + let borrowed = &mut cave; + + borrowed.knight.nothing_is_true(); // E0507 + mem::replace(&mut borrowed.knight, TheDarkKnight).nothing_is_true(); // ok! +} +``` + You can find more information about borrowing in the rust-book: http://doc.rust-lang.org/stable/book/references-and-borrowing.html "##, diff --git a/src/librustc_unicode/char.rs b/src/librustc_unicode/char.rs index 46ecd3a80b5d1..9386453d660d2 100644 --- a/src/librustc_unicode/char.rs +++ b/src/librustc_unicode/char.rs @@ -194,7 +194,7 @@ impl char { /// * `a-z` /// * `A-Z` /// - /// # Failure + /// # Errors /// /// Returns `None` if the `char` does not refer to a digit in the given radix. /// diff --git a/src/libstd/fs.rs b/src/libstd/fs.rs index e40a3d06f7753..d12cfa6183a24 100644 --- a/src/libstd/fs.rs +++ b/src/libstd/fs.rs @@ -70,7 +70,7 @@ pub struct Metadata(fs_imp::FileAttr); /// information like the entry's path and possibly other metadata can be /// learned. /// -/// # Failure +/// # Errors /// /// This `io::Result` will be an `Err` if there's some sort of intermittent /// IO error during iteration. diff --git a/src/libstd/process.rs b/src/libstd/process.rs index 7197dfa8b2d47..5e0a54392d23d 100644 --- a/src/libstd/process.rs +++ b/src/libstd/process.rs @@ -47,6 +47,16 @@ use thread::{self, JoinHandle}; /// /// assert!(ecode.success()); /// ``` +/// +/// # Note +/// +/// Take note that there is no implementation of +/// [`Drop`](../../core/ops/trait.Drop.html) for child processes, so if you +/// do not ensure the `Child` has exited then it will continue to run, even +/// after the `Child` handle to the child process has gone out of scope. +/// +/// Calling `wait` (or other functions that wrap around it) will make the +/// parent process wait until the child has actually exited before continuing. #[stable(feature = "process", since = "1.0.0")] pub struct Child { handle: imp::Process, diff --git a/src/libstd/sync/condvar.rs b/src/libstd/sync/condvar.rs index 1f7fe820bf86a..9a786752365f1 100644 --- a/src/libstd/sync/condvar.rs +++ b/src/libstd/sync/condvar.rs @@ -129,7 +129,7 @@ impl Condvar { /// the predicate must always be checked each time this function returns to /// protect against spurious wakeups. /// - /// # Failure + /// # Errors /// /// This function will return an error if the mutex being waited on is /// poisoned when this thread re-acquires the lock. For more information, diff --git a/src/libstd/sync/mutex.rs b/src/libstd/sync/mutex.rs index 6b20e51967d88..fe9f0371abd5d 100644 --- a/src/libstd/sync/mutex.rs +++ b/src/libstd/sync/mutex.rs @@ -205,7 +205,7 @@ impl Mutex { /// held. An RAII guard is returned to allow scoped unlock of the lock. When /// the guard goes out of scope, the mutex will be unlocked. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return an error once the mutex is acquired. @@ -223,7 +223,7 @@ impl Mutex { /// /// This function does not block. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return failure if the mutex would otherwise be @@ -250,7 +250,7 @@ impl Mutex { /// Consumes this mutex, returning the underlying data. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return an error instead. @@ -280,7 +280,7 @@ impl Mutex { /// Since this call borrows the `Mutex` mutably, no actual locking needs to /// take place---the mutable borrow statically guarantees no locks exist. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return an error instead. diff --git a/src/libstd/sync/rwlock.rs b/src/libstd/sync/rwlock.rs index 3dbef43548136..63ef7732ad650 100644 --- a/src/libstd/sync/rwlock.rs +++ b/src/libstd/sync/rwlock.rs @@ -169,7 +169,7 @@ impl RwLock { /// Returns an RAII guard which will release this thread's shared access /// once it is dropped. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. @@ -192,7 +192,7 @@ impl RwLock { /// This function does not provide any guarantees with respect to the ordering /// of whether contentious readers or writers will acquire the lock first. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An @@ -217,7 +217,7 @@ impl RwLock { /// Returns an RAII guard which will drop the write access of this rwlock /// when dropped. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. @@ -240,7 +240,7 @@ impl RwLock { /// This function does not provide any guarantees with respect to the ordering /// of whether contentious readers or writers will acquire the lock first. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An @@ -269,7 +269,7 @@ impl RwLock { /// Consumes this `RwLock`, returning the underlying data. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An @@ -301,7 +301,7 @@ impl RwLock { /// Since this call borrows the `RwLock` mutably, no actual locking needs to /// take place---the mutable borrow statically guarantees no locks exist. /// - /// # Failure + /// # Errors /// /// This function will return an error if the RwLock is poisoned. An RwLock /// is poisoned whenever a writer panics while holding an exclusive lock. An diff --git a/src/libstd/sys/common/remutex.rs b/src/libstd/sys/common/remutex.rs index 31caa68c4b7ea..2e2be63c3cb5b 100644 --- a/src/libstd/sys/common/remutex.rs +++ b/src/libstd/sys/common/remutex.rs @@ -78,7 +78,7 @@ impl ReentrantMutex { /// calling this method already holds the lock, the call shall succeed without /// blocking. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return failure if the mutex would otherwise be @@ -95,7 +95,7 @@ impl ReentrantMutex { /// /// This function does not block. /// - /// # Failure + /// # Errors /// /// If another user of this mutex panicked while holding the mutex, then /// this call will return failure if the mutex would otherwise be diff --git a/src/libsyntax/ast.rs b/src/libsyntax/ast.rs index e327adfaf892c..19bedab9d3054 100644 --- a/src/libsyntax/ast.rs +++ b/src/libsyntax/ast.rs @@ -70,9 +70,9 @@ pub struct Name(pub u32); /// A SyntaxContext represents a chain of macro-expandings /// and renamings. Each macro expansion corresponds to /// a fresh u32. This u32 is a reference to a table stored -// in thread-local storage. -// The special value EMPTY_CTXT is used to indicate an empty -// syntax context. +/// in thread-local storage. +/// The special value EMPTY_CTXT is used to indicate an empty +/// syntax context. #[derive(Clone, Copy, PartialEq, Eq, Hash, Debug, RustcEncodable, RustcDecodable)] pub struct SyntaxContext(pub u32); diff --git a/src/libsyntax/errors/emitter.rs b/src/libsyntax/errors/emitter.rs index 7e0e17423de8c..94bbd1bd12816 100644 --- a/src/libsyntax/errors/emitter.rs +++ b/src/libsyntax/errors/emitter.rs @@ -516,7 +516,7 @@ impl EmitterWriter { }; let lo = self.cm.lookup_char_pos(sp.lo); let hi = self.cm.lookup_char_pos(sp.hi); - let elide_sp = (lo.line - hi.line) > MAX_SP_LINES; + let elide_sp = (hi.line - lo.line) >= MAX_SP_LINES; let line_num = line.line_index + 1; if !(lo.line <= line_num && hi.line >= line_num) { @@ -1024,7 +1024,7 @@ mod test { \x20 ^ ^\n"; let expect0_end = "dummy.txt: 5 ccccc\n\ - \x20 ...\n\ + dummy.txt: 6 xxxxx\n\ dummy.txt: 7 yyyyy\n\ \x20 ^\n\ \x20 ...\n\