diff --git a/src/doc/book/ownership.md b/src/doc/book/ownership.md index 70d71c14ddf16..7f7f7d4c8ebdb 100644 --- a/src/doc/book/ownership.md +++ b/src/doc/book/ownership.md @@ -51,7 +51,7 @@ fn foo() { } ``` -When `v` comes into scope, a new [vector] is created on [the stack][stack], +When `v` comes into scope, a new [vector][vectors] is created on [the stack][stack], and it allocates space on [the heap][heap] for its elements. When `v` goes out of scope at the end of `foo()`, Rust will clean up everything related to the vector, even the heap-allocated memory. This happens deterministically, at the diff --git a/src/doc/book/references-and-borrowing.md b/src/doc/book/references-and-borrowing.md index 0a4e09ed00ab6..7be5cc442dd5f 100644 --- a/src/doc/book/references-and-borrowing.md +++ b/src/doc/book/references-and-borrowing.md @@ -23,7 +23,7 @@ Before we get to the details, two important notes about the ownership system. Rust has a focus on safety and speed. It accomplishes these goals through many ‘zero-cost abstractions’, which means that in Rust, abstractions cost as little as possible in order to make them work. The ownership system is a prime example -of a zero cost abstraction. All of the analysis we’ll talk about in this guide +of a zero-cost abstraction. All of the analysis we’ll talk about in this guide is _done at compile time_. You do not pay any run-time cost for any of these features. diff --git a/src/doc/book/syntax-index.md b/src/doc/book/syntax-index.md index 53f38cd77e4a4..3e889f51f542d 100644 --- a/src/doc/book/syntax-index.md +++ b/src/doc/book/syntax-index.md @@ -43,23 +43,23 @@ * `!` (`!expr`): bitwise or logical complement. Overloadable (`Not`). * `!=` (`var != expr`): nonequality comparison. Overloadable (`PartialEq`). * `%` (`expr % expr`): arithmetic remainder. Overloadable (`Rem`). -* `%=` (`var %= expr`): arithmetic remainder & assignment. +* `%=` (`var %= expr`): arithmetic remainder & assignment. Overloadable (`RemAssign`). * `&` (`expr & expr`): bitwise and. Overloadable (`BitAnd`). * `&` (`&expr`): borrow. See [References and Borrowing]. * `&` (`&type`, `&mut type`, `&'a type`, `&'a mut type`): borrowed pointer type. See [References and Borrowing]. -* `&=` (`var &= expr`): bitwise and & assignment. +* `&=` (`var &= expr`): bitwise and & assignment. Overloadable (`BitAndAssign`). * `&&` (`expr && expr`): logical and. * `*` (`expr * expr`): arithmetic multiplication. Overloadable (`Mul`). * `*` (`*expr`): dereference. * `*` (`*const type`, `*mut type`): raw pointer. See [Raw Pointers]. -* `*=` (`var *= expr`): arithmetic multiplication & assignment. +* `*=` (`var *= expr`): arithmetic multiplication & assignment. Overloadable (`MulAssign`). * `+` (`expr + expr`): arithmetic addition. Overloadable (`Add`). * `+` (`trait + trait`, `'a + trait`): compound type constraint. See [Traits (Multiple Trait Bounds)]. -* `+=` (`var += expr`): arithmetic addition & assignment. +* `+=` (`var += expr`): arithmetic addition & assignment. Overloadable (`AddAssign`). * `,`: argument and element separator. See [Attributes], [Functions], [Structs], [Generics], [Match], [Closures], [Crates and Modules (Importing Modules with `use`)]. * `-` (`expr - expr`): arithmetic subtraction. Overloadable (`Sub`). * `-` (`- expr`): arithmetic negation. Overloadable (`Neg`). -* `-=` (`var -= expr`): arithmetic subtraction & assignment. +* `-=` (`var -= expr`): arithmetic subtraction & assignment. Overloadable (`SubAssign`). * `->` (`fn(…) -> type`, `|…| -> type`): function and closure return type. See [Functions], [Closures]. * `-> !` (`fn(…) -> !`, `|…| -> !`): diverging function or closure. See [Diverging Functions]. * `.` (`expr.ident`): member access. See [Structs], [Method Syntax]. @@ -69,14 +69,14 @@ * `...` (`...expr`, `expr...expr`) *in an expression*: inclusive range expression. See [Iterators]. * `...` (`expr...expr`) *in a pattern*: inclusive range pattern. See [Patterns (Ranges)]. * `/` (`expr / expr`): arithmetic division. Overloadable (`Div`). -* `/=` (`var /= expr`): arithmetic division & assignment. +* `/=` (`var /= expr`): arithmetic division & assignment. Overloadable (`DivAssign`). * `:` (`pat: type`, `ident: type`): constraints. See [Variable Bindings], [Functions], [Structs], [Traits]. * `:` (`ident: expr`): struct field initializer. See [Structs]. * `:` (`'a: loop {…}`): loop label. See [Loops (Loops Labels)]. * `;`: statement and item terminator. * `;` (`[…; len]`): part of fixed-size array syntax. See [Primitive Types (Arrays)]. * `<<` (`expr << expr`): left-shift. Overloadable (`Shl`). -* `<<=` (`var <<= expr`): left-shift & assignment. +* `<<=` (`var <<= expr`): left-shift & assignment. Overloadable (`ShlAssign`). * `<` (`expr < expr`): less-than comparison. Overloadable (`PartialOrd`). * `<=` (`var <= expr`): less-than or equal-to comparison. Overloadable (`PartialOrd`). * `=` (`var = expr`, `ident = type`): assignment/equivalence. See [Variable Bindings], [`type` Aliases], generic parameter defaults. @@ -85,14 +85,14 @@ * `>` (`expr > expr`): greater-than comparison. Overloadable (`PartialOrd`). * `>=` (`var >= expr`): greater-than or equal-to comparison. Overloadable (`PartialOrd`). * `>>` (`expr >> expr`): right-shift. Overloadable (`Shr`). -* `>>=` (`var >>= expr`): right-shift & assignment. +* `>>=` (`var >>= expr`): right-shift & assignment. Overloadable (`ShrAssign`). * `@` (`ident @ pat`): pattern binding. See [Patterns (Bindings)]. * `^` (`expr ^ expr`): bitwise exclusive or. Overloadable (`BitXor`). -* `^=` (`var ^= expr`): bitwise exclusive or & assignment. +* `^=` (`var ^= expr`): bitwise exclusive or & assignment. Overloadable (`BitXorAssign`). * `|` (`expr | expr`): bitwise or. Overloadable (`BitOr`). * `|` (`pat | pat`): pattern alternatives. See [Patterns (Multiple patterns)]. * `|` (`|…| expr`): closures. See [Closures]. -* `|=` (`var |= expr`): bitwise or & assignment. +* `|=` (`var |= expr`): bitwise or & assignment. Overloadable (`BitOrAssign`). * `||` (`expr || expr`): logical or. * `_`: "ignored" pattern binding. See [Patterns (Ignoring bindings)]. diff --git a/src/doc/reference.md b/src/doc/reference.md index a94609a8b0cc1..8e655ee22e302 100644 --- a/src/doc/reference.md +++ b/src/doc/reference.md @@ -1118,6 +1118,16 @@ type Point = (u8, u8); let p: Point = (41, 68); ``` +Currently a type alias to an enum type cannot be used to qualify the +constructors: + +``` +enum E { A } +type F = E; +let _: F = E::A; // OK +// let _: F = F::A; // Doesn't work +``` + ### Structs A _struct_ is a nominal [struct type](#struct-types) defined with the @@ -1195,7 +1205,8 @@ a = Animal::Cat { name: "Spotty".to_string(), weight: 2.7 }; In this example, `Cat` is a _struct-like enum variant_, whereas `Dog` is simply called an enum variant. -Enums have a discriminant. You can assign them explicitly: +Each enum value has a _discriminant_ which is an integer associated to it. You +can specify it explicitly: ``` enum Foo { @@ -1203,10 +1214,15 @@ enum Foo { } ``` -If a discriminant isn't assigned, they start at zero, and add one for each +The right hand side of the specification is interpreted as an `isize` value, +but the compiler is allowed to use a smaller type in the actual memory layout. +The [`repr` attribute](#ffi-attributes) can be added in order to change +the type of the right hand side and specify the memory layout. + +If a discriminant isn't specified, they start at zero, and add one for each variant, in order. -You can cast an enum to get this value: +You can cast an enum to get its discriminant: ``` # enum Foo { Bar = 123 } diff --git a/src/libcollections/fmt.rs b/src/libcollections/fmt.rs index 97b01a607f5e6..435c9f0e9f4c3 100644 --- a/src/libcollections/fmt.rs +++ b/src/libcollections/fmt.rs @@ -429,20 +429,20 @@ //! For example, these: //! //! ``` -//! // Hello {arg 0 (x)} is {arg 1 (0.01} with precision specified inline (5)} +//! // Hello {arg 0 (x)} is {arg 1 (0.01) with precision specified inline (5)} //! println!("Hello {0} is {1:.5}", "x", 0.01); //! -//! // Hello {arg 1 (x)} is {arg 2 (0.01} with precision specified in arg 0 (5)} +//! // Hello {arg 1 (x)} is {arg 2 (0.01) with precision specified in arg 0 (5)} //! println!("Hello {1} is {2:.0$}", 5, "x", 0.01); //! -//! // Hello {arg 0 (x)} is {arg 2 (0.01} with precision specified in arg 1 (5)} +//! // Hello {arg 0 (x)} is {arg 2 (0.01) with precision specified in arg 1 (5)} //! println!("Hello {0} is {2:.1$}", "x", 5, 0.01); //! -//! // Hello {next arg (x)} is {second of next two args (0.01} with precision +//! // Hello {next arg (x)} is {second of next two args (0.01) with precision //! // specified in first of next two args (5)} //! println!("Hello {} is {:.*}", "x", 5, 0.01); //! -//! // Hello {next arg (x)} is {arg 2 (0.01} with precision +//! // Hello {next arg (x)} is {arg 2 (0.01) with precision //! // specified in its predecessor (5)} //! println!("Hello {} is {2:.*}", "x", 5, 0.01); //! ``` diff --git a/src/libcore/str/mod.rs b/src/libcore/str/mod.rs index 79f925aaab0ae..f5abdf65a5b4f 100644 --- a/src/libcore/str/mod.rs +++ b/src/libcore/str/mod.rs @@ -1311,13 +1311,19 @@ mod traits { } } + /// Implements substring slicing with syntax `&self[begin .. end]`. + /// /// Returns a slice of the given string from the byte range /// [`begin`..`end`). /// /// This operation is `O(1)`. /// - /// Panics when `begin` and `end` do not point to valid characters - /// or point beyond the last character of the string. + /// # Panics + /// + /// Panics if `begin` or `end` does not point to the starting + /// byte offset of a character (as defined by `is_char_boundary`). + /// Requires that `begin <= end` and `end <= len` where `len` is the + /// length of the string. /// /// # Examples /// @@ -1353,8 +1359,20 @@ mod traits { } } + /// Implements mutable substring slicing with syntax + /// `&mut self[begin .. end]`. + /// /// Returns a mutable slice of the given string from the byte range /// [`begin`..`end`). + /// + /// This operation is `O(1)`. + /// + /// # Panics + /// + /// Panics if `begin` or `end` does not point to the starting + /// byte offset of a character (as defined by `is_char_boundary`). + /// Requires that `begin <= end` and `end <= len` where `len` is the + /// length of the string. #[stable(feature = "derefmut_for_string", since = "1.2.0")] impl ops::IndexMut> for str { #[inline] @@ -1370,13 +1388,12 @@ mod traits { } } - /// Returns a slice of the string from the beginning to byte - /// `end`. + /// Implements substring slicing with syntax `&self[.. end]`. /// - /// Equivalent to `self[0 .. end]`. + /// Returns a slice of the string from the beginning to byte offset + /// `end`. /// - /// Panics when `end` does not point to a valid character, or is - /// out of bounds. + /// Equivalent to `&self[0 .. end]`. #[stable(feature = "rust1", since = "1.0.0")] impl ops::Index> for str { type Output = str; @@ -1392,8 +1409,12 @@ mod traits { } } - /// Returns a mutable slice of the string from the beginning to byte + /// Implements mutable substring slicing with syntax `&mut self[.. end]`. + /// + /// Returns a mutable slice of the string from the beginning to byte offset /// `end`. + /// + /// Equivalent to `&mut self[0 .. end]`. #[stable(feature = "derefmut_for_string", since = "1.2.0")] impl ops::IndexMut> for str { #[inline] @@ -1407,12 +1428,12 @@ mod traits { } } - /// Returns a slice of the string from `begin` to its end. + /// Implements substring slicing with syntax `&self[begin ..]`. /// - /// Equivalent to `self[begin .. self.len()]`. + /// Returns a slice of the string from byte offset `begin` + /// to the end of the string. /// - /// Panics when `begin` does not point to a valid character, or is - /// out of bounds. + /// Equivalent to `&self[begin .. len]`. #[stable(feature = "rust1", since = "1.0.0")] impl ops::Index> for str { type Output = str; @@ -1428,7 +1449,12 @@ mod traits { } } - /// Returns a slice of the string from `begin` to its end. + /// Implements mutable substring slicing with syntax `&mut self[begin ..]`. + /// + /// Returns a mutable slice of the string from byte offset `begin` + /// to the end of the string. + /// + /// Equivalent to `&mut self[begin .. len]`. #[stable(feature = "derefmut_for_string", since = "1.2.0")] impl ops::IndexMut> for str { #[inline] @@ -1443,6 +1469,12 @@ mod traits { } } + /// Implements substring slicing with syntax `&self[..]`. + /// + /// Returns a slice of the whole string. This operation can + /// never panic. + /// + /// Equivalent to `&self[0 .. len]`. #[stable(feature = "rust1", since = "1.0.0")] impl ops::Index for str { type Output = str; @@ -1453,6 +1485,12 @@ mod traits { } } + /// Implements mutable substring slicing with syntax `&mut self[..]`. + /// + /// Returns a mutable slice of the whole string. This operation can + /// never panic. + /// + /// Equivalent to `&mut self[0 .. len]`. #[stable(feature = "derefmut_for_string", since = "1.2.0")] impl ops::IndexMut for str { #[inline] diff --git a/src/librustc_typeck/diagnostics.rs b/src/librustc_typeck/diagnostics.rs index 01f7d6b456582..cfe76206b0290 100644 --- a/src/librustc_typeck/diagnostics.rs +++ b/src/librustc_typeck/diagnostics.rs @@ -1133,15 +1133,16 @@ enum Bad { } ``` -Here `X` will have already been assigned the discriminant 0 by the time `Y` is +Here `X` will have already been specified the discriminant 0 by the time `Y` is encountered, so a conflict occurs. "##, E0082: r##" -The default type for enum discriminants is `isize`, but it can be adjusted by -adding the `repr` attribute to the enum declaration. This error indicates that -an integer literal given as a discriminant is not a member of the discriminant -type. For example: +When you specify enum discriminants with `=`, the compiler expects `isize` +values by default. Or you can add the `repr` attibute to the enum declaration +for an explicit choice of the discriminant type. In either cases, the +discriminant values must fall within a valid range for the expected type; +otherwise this error is raised. For example: ```compile_fail #[repr(u8)] @@ -1152,11 +1153,19 @@ enum Thing { ``` Here, 1024 lies outside the valid range for `u8`, so the discriminant for `A` is -invalid. You may want to change representation types to fix this, or else change -invalid discriminant values so that they fit within the existing type. +invalid. Here is another, more subtle example which depends on target word size: -Note also that without a representation manually defined, the compiler will -optimize by using the smallest integer type possible. +```compile_fail +enum DependsOnPointerSize { + A = 1 << 32 +} +``` + +Here, `1 << 32` is interpreted as an `isize` value. So it is invalid for 32 bit +target (`target_pointer_width = "32"`) but valid for 64 bit target. + +You may want to change representation types to fix this, or else change invalid +discriminant values so that they fit within the existing type. "##, E0084: r##"