Merge branch 'master' of https://github.com/rust-lang/rfcs

Author: nrc

README.md

@@ -29,28 +29,20 @@ the direction the language is evolving in.
 * [0141-lifetime-elision.md](text/0141-lifetime-elision.md)
 * [0195-associated-items.md](text/0195-associated-items.md)
 * [0213-defaulted-type-params.md](text/0213-defaulted-type-params.md)
-* [0235-collections-conventions.md](text/0235-collections-conventions.md)
 * [0320-nonzeroing-dynamic-drop.md](text/0320-nonzeroing-dynamic-drop.md)
 * [0339-statically-sized-literals.md](text/0339-statically-sized-literals.md)
-* [0369-num-reform.md](text/0369-num-reform.md)
 * [0385-module-system-cleanup.md](text/0385-module-system-cleanup.md)
 * [0401-coercions.md](text/0401-coercions.md)
 * [0447-no-unused-impl-parameters.md](text/0447-no-unused-impl-parameters.md)
-* [0458-send-improvements.md](text/0458-send-improvements.md)
 * [0495-array-pattern-changes.md](text/0495-array-pattern-changes.md)
 * [0501-consistent_no_prelude_attributes.md](text/0501-consistent_no_prelude_attributes.md)
-* [0505-api-comment-conventions.md](text/0505-api-comment-conventions.md)
 * [0509-collections-reform-part-2.md](text/0509-collections-reform-part-2.md)
 * [0517-io-os-reform.md](text/0517-io-os-reform.md)
-* [0544-rename-int-uint.md](text/0544-rename-int-uint.md)
 * [0560-integer-overflow.md](text/0560-integer-overflow.md)
-* [0563-remove-ndebug.md](text/0563-remove-ndebug.md)
-* [0572-rustc-attribute.md](text/0572-rustc-attribute.md)
-* [0640-debug-improvements.md](text/0640-debug-improvements.md)
-* [0702-rangefull-expression.md](text/0702-rangefull-expression.md)
-* [0738-variance.md](text/0738-variance.md)
 * [0769-sound-generic-drop.md](text/0769-sound-generic-drop.md)
+* [0803-type-ascription.md](text/0803-type-ascription.md)
 * [0809-box-and-in-for-stdlib.md](text/0809-box-and-in-for-stdlib.md)
+* [0968-closure-return-type-syntax.md](text/0968-closure-return-type-syntax.md)
 
 ## Table of Contents
 [Table of Contents]: #table-of-contents

text/0517-io-os-reform.md

@@ -1016,10 +1016,11 @@ strings) and is usually what you want when working with iterators.
 
 The `BufReader`, `BufWriter` and `BufStream` types stay
 essentially as they are today, except that for streams and writers the
-`into_inner` method yields the structure back in the case of a flush error:
-
+`into_inner` method yields the structure back in the case of a write error,
+and its behavior is clarified to writing out the buffered data without
+flushing the underlying reader:
 ```rust
-// If flushing fails, you get the unflushed data back
+// If writing fails, you get the unwritten data back
 fn into_inner(self) -> Result<W, IntoInnerError<Self>>;
 
 pub struct IntoInnerError<W>(W, Error);
@@ -1540,6 +1541,59 @@ The contents of `std::io::net` submodules `tcp`, `udp`, `ip` and
 the other modules are being moved or removed and are described
 elsewhere.
 
+#### SocketAddr
+
+This structure will represent either a `sockaddr_in` or `sockaddr_in6` which is
+commonly just a pairing of an IP address and a port.
+
+```rust
+enum SocketAddr {
+    V4(SocketAddrV4),
+    V6(SocketAddrV6),
+}
+
+impl SocketAddrV4 {
+    fn new(addr: Ipv4Addr, port: u16) -> SocketAddrV4;
+    fn ip(&self) -> &Ipv4Addr;
+    fn port(&self) -> u16;
+}
+
+impl SocketAddrV6 {
+    fn new(addr: Ipv6Addr, port: u16, flowinfo: u32, scope_id: u32) -> SocketAddrV6;
+    fn ip(&self) -> &Ipv6Addr;
+    fn port(&self) -> u16;
+    fn flowinfo(&self) -> u32;
+    fn scope_id(&self) -> u32;
+}
+```
+
+#### Ipv4Addr
+
+Represents a version 4 IP address. It has the following interface:
+
+```rust
+impl Ipv4Addr {
+    fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr;
+    fn any() -> Ipv4Addr;
+    fn octets(&self) -> [u8; 4];
+    fn to_ipv6_compatible(&self) -> Ipv6Addr;
+    fn to_ipv6_mapped(&self) -> Ipv6Addr;
+}
+```
+
+#### Ipv6Addr
+
+Represents a version 6 IP address. It has the following interface:
+
+```rust
+impl Ipv6Addr {
+    fn new(a: u16, b: u16, c: u16, d: u16, e: u16, f: u16, g: u16, h: u16) -> Ipv6Addr;
+    fn any() -> Ipv6Addr;
+    fn segments(&self) -> [u16; 8]
+    fn to_ipv4(&self) -> Option<Ipv4Addr>;
+}
+```
+
 #### TCP
 [TCP]: #tcp
 
@@ -1552,7 +1606,7 @@ following interface:
 impl TcpStream {
     fn connect<A: ToSocketAddrs>(addr: &A) -> io::Result<TcpStream>;
     fn peer_addr(&self) -> io::Result<SocketAddr>;
-    fn socket_addr(&self) -> io::Result<SocketAddr>;
+    fn local_addr(&self) -> io::Result<SocketAddr>;
     fn shutdown(&self, how: Shutdown) -> io::Result<()>;
     fn duplicate(&self) -> io::Result<TcpStream>;
 }
@@ -1591,7 +1645,7 @@ into the `TcpListener` structure. Specifically, this will be the resulting API:
 ```rust
 impl TcpListener {
     fn bind<A: ToSocketAddrs>(addr: &A) -> io::Result<TcpListener>;
-    fn socket_addr(&self) -> io::Result<SocketAddr>;
+    fn local_addr(&self) -> io::Result<SocketAddr>;
     fn duplicate(&self) -> io::Result<TcpListener>;
     fn accept(&self) -> io::Result<(TcpStream, SocketAddr)>;
     fn incoming(&self) -> Incoming;
@@ -1635,7 +1689,7 @@ impl UdpSocket {
     fn bind<A: ToSocketAddrs>(addr: &A) -> io::Result<UdpSocket>;
     fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)>;
     fn send_to<A: ToSocketAddrs>(&self, buf: &[u8], addr: &A) -> io::Result<usize>;
-    fn socket_addr(&self) -> io::Result<SocketAddr>;
+    fn local_addr(&self) -> io::Result<SocketAddr>;
     fn duplicate(&self) -> io::Result<UdpSocket>;
 }
 
@@ -1687,8 +1741,18 @@ For the current `ip` module:
 * The `ToSocketAddr` trait should become `ToSocketAddrs`
 * The default `to_socket_addr_all` method should be removed.
 
-The actual address structures could use some scrutiny, but any
-revisions there are left as an unresolved question.
+The following implementations of `ToSocketAddrs` will be available:
+
+```rust
+impl ToSocketAddrs for SocketAddr { ... }
+impl ToSocketAddrs for SocketAddrV4 { ... }
+impl ToSocketAddrs for SocketAddrV6 { ... }
+impl ToSocketAddrs for (Ipv4Addr, u16) { ... }
+impl ToSocketAddrs for (Ipv6Addr, u16) { ... }
+impl ToSocketAddrs for (&str, u16) { ... }
+impl ToSocketAddrs for str { ... }
+impl<T: ToSocketAddrs> ToSocketAddrs for &T { ... }
+```
 
 ### `std::process`
 [std::process]: #stdprocess

text/0640-debug-improvements.md

@@ -4,7 +4,7 @@
 
 # Summary
 
-The `Debug` trait is intended to be implemented by every trait and display
+The `Debug` trait is intended to be implemented by every type and display
 useful runtime information to help with debugging. This RFC proposes two
 additions to the fmt API, one of which aids implementors of `Debug`, and one
 which aids consumers of the output of `Debug`. Specifically, the `#` format

text/0803-type-ascription.md

@@ -0,0 +1,228 @@
+- Start Date: 2015-2-3
+- RFC PR: [rust-lang/rfcs#803](https://github.com/rust-lang/rfcs/pull/803)
+- Rust Issue: [rust-lang/rust#23416](https://github.com/rust-lang/rust/issues/23416)
+- Feature: `ascription`
+
+# Summary
+
+Add type ascription to expressions. (An earlier version of this RFC covered type
+ascription in patterns too, that has been postponed).
+
+Type ascription on expression has already been implemented.
+
+See also discussion on [#354](https://github.com/rust-lang/rfcs/issues/354) and
+[rust issue 10502](https://github.com/rust-lang/rust/issues/10502).
+
+
+# Motivation
+
+Type inference is imperfect. It is often useful to help type inference by
+annotating a sub-expression with a type. Currently, this is only possible by
+extracting the sub-expression into a variable using a `let` statement and/or
+giving a type for a whole expression or pattern. This is un- ergonomic, and
+sometimes impossible due to lifetime issues. Specifically, where a variable has
+lifetime of its enclosing scope, but a sub-expression's lifetime is typically
+limited to the nearest semi-colon.
+
+Typical use cases are where a function's return type is generic (e.g., collect)
+and where we want to force a coercion.
+
+Type ascription can also be used for documentation and debugging - where it is
+unclear from the code which type will be inferred, type ascription can be used
+to precisely communicate expectations to the compiler or other programmers.
+
+By allowing type ascription in more places, we remove the inconsistency that
+type ascription is currently only allowed on top-level patterns.
+
+## Examples:
+
+(Somewhat simplified examples, in these cases there are sometimes better
+solutions with the current syntax).
+
+Generic return type:
+
+```
+// Current.
+let z = if ... {
+    let x: Vec<_> = foo.enumerate().collect();
+    x
+} else {
+    ...
+};
+
+// With type ascription.
+let z = if ... {
+    foo.enumerate().collect(): Vec<_>
+} else {
+    ...
+};
+```
+
+Coercion:
+
+```
+fn foo<T>(a: T, b: T) { ... }
+
+// Current.
+let x = [1u32, 2, 4];
+let y = [3u32];
+...
+let x: &[_] = &x;
+let y: &[_] = &y;
+foo(x, y);
+
+// With type ascription.
+let x = [1u32, 2, 4];
+let y = [3u32];
+...
+foo(x: &[_], y: &[_]);
+```
+
+Generic return type and coercion:
+
+```
+// Current.
+let x: T = {
+    let temp: U<_> = foo();
+    temp
+};
+
+// With type ascription.
+let x: T = foo(): U<_>;
+```
+
+
+# Detailed design
+
+The syntax of expressions is extended with type ascription:
+
+```
+e ::= ... | e: T
+```
+
+where `e` is an expression and `T` is a type. Type ascription has the same
+precedence as explicit coercions using `as`.
+
+When type checking `e: T`, `e` must have type `T`. The `must have type` test
+includes implicit coercions and subtyping, but not explicit coercions. `T` may
+be any well-formed type.
+
+At runtime, type ascription is a no-op, unless an implicit coercion was used in
+type checking, in which case the dynamic semantics of a type ascription
+expression are exactly those of the implicit coercion.
+
+@eddyb has implemented the expressions part of this RFC,
+[PR](https://github.com/rust-lang/rust/pull/21836).
+
+This feature should land behind the `ascription` feature gate.
+
+
+### coercion and `as` vs `:`
+
+A downside of type ascription is the overlap with explicit coercions (aka casts,
+the `as` operator). To the programmer, type ascription makes implicit coercions
+explicit (however, the compiler makes no distinction between coercions due to
+type ascription and other coercions). In RFC 401, it is proposed that all valid
+implicit coercions are valid explicit coercions. However, that may be too
+confusing for users, since there is no reason to use type ascription rather than
+`as` (if there is some coercion). Furthermore, if programmers do opt to use `as`
+as the default whether or not it is required, then it loses its function as a
+warning sign for programmers to beware of.
+
+To address this I propose two lints which check for: trivial casts and trivial
+numeric casts. Other than these lints we stick with the proposal from #401 that
+unnecessary casts will no longer be an error.
+
+A trivial cast is a cast `x as T` where `x` has type `U` and `x` can be
+implicitly coerced to `T` or is already a subtype of `T`.
+
+A trivial numeric cast is a cast `x as T` where `x` has type `U` and `x` is
+implicitly coercible to `T` or `U` is a subtype of `T`, and both `U` and `T` are
+numeric types.
+
+Like any lints, these can be customised per-crate by the programmer. Both lints
+are 'warn' by default.
+
+Although this is a somewhat complex scheme, it allows code that works today to
+work with only minor adjustment, it allows for a backwards compatible path to
+'promoting' type conversions from explicit casts to implicit coercions, and it
+allows customisation of a contentious kind of error (especially so in the
+context of cross-platform programming).
+
+
+### Type ascription and temporaries
+
+There is an implementation choice between treating `x: T` as an lvalue or
+rvalue. Note that when a rvalue is used in lvalue context (e.g., the subject of
+a reference operation), then the compiler introduces a temporary variable.
+Neither option is satisfactory, if we treat an ascription expression as an
+lvalue (i.e., no new temporary), then there is potential for unsoundness:
+
+```
+let mut foo: S = ...;
+{
+    let bar = &mut (foo: T);  // S <: T, no coercion required
+    *bar = ... : T;
+}
+// Whoops, foo has type T, but the compiler thinks it has type S, where potentially T </: S
+```
+
+If we treat ascription expressions as rvalues (i.e., create a temporary in
+lvalue position), then we don't have the soundness problem, but we do get the
+unexpected result that `&(x: T)` is not in fact a reference to `x`, but a
+reference to a temporary copy of `x`.
+
+The proposed solution is that type ascription expressions are rvalues, but
+taking a reference of such an expression is forbidden. I.e., type asciption is
+forbidden in the following contexts (where `<expr>` is a type ascription
+expression):
+
+```
+&[mut] <expr>
+let ref [mut] x = <expr>
+match <expr> { .. ref [mut] x .. => { .. } .. }
+<expr>.foo() // due to autoref
+```
+
+Like other rvalues, type ascription would not be allowed as the lhs of assignment.
+
+Note that, if type asciption is required in such a context, an lvalue can be
+forced by using `{}`, e.g., write `&mut { foo: T }`, rather than `&mut (foo: T)`.
+
+
+# Drawbacks
+
+More syntax, another feature in the language.
+
+Interacts poorly with struct initialisers (changing the syntax for struct
+literals has been [discussed and rejected](https://github.com/rust-lang/rfcs/pull/65)
+and again in [discuss](http://internals.rust-lang.org/t/replace-point-x-3-y-5-with-point-x-3-y-5/198)).
+
+If we introduce named arguments in the future, then it would make it more
+difficult to support the same syntax as field initialisers.
+
+
+# Alternatives
+
+We could do nothing and force programmers to use temporary variables to specify
+a type. However, this is less ergonomic and has problems with scopes/lifetimes.
+
+Rely on explicit coercions - the current plan [RFC 401](https://github.com/rust-lang/rfcs/blob/master/text/0401-coercions.md)
+is to allow explicit coercion to any valid type and to use a customisable lint
+for trivial casts (that is, those given by subtyping, including the identity
+case). If we allow trivial casts, then we could always use explicit coercions
+instead of type ascription. However, we would then lose the distinction between
+implicit coercions which are safe and explicit coercions, such as narrowing,
+which require more programmer attention. This also does not help with patterns.
+
+We could use a different symbol or keyword instead of `:`, e.g., `is`.
+
+
+# Unresolved questions
+
+Is the suggested precedence correct?
+
+Should we remove integer suffixes in favour of type ascription?
+
+Style guidelines - should we recommend spacing or parenthesis to make type
+ascription syntax more easily recognisable?