This commit performs a pass over the implementations of the new `String` trait
in the formatting module. Some implementations were removed as a conservative
move pending an upcoming convention about `String` implementations, and some
were added in order to retain consistency across the libraries. Specifically:
* All "smart pointers" implement `String` now, adding missing implementations
for `Arc` and `Rc`.
* The `Vec<T>` and `[T]` types no longer implement `String`.
* The `*const T` and `*mut T` type no longer implement `String`.
* The `()` type no longer implements `String`.
* The `Path` type's `Show` implementation does not surround itself with `Path
{}` (a minor tweak).
All implementations of `String` in this PR were also marked `#[stable]` to
indicate that the types will continue to implement the `String` trait regardless
of what it looks like.
fmt::Show is for debugging, and can and should be implemented for
all public types. This trait is used with `{:?}` syntax. There still
exists #[derive(Show)].
fmt::String is for types that faithfully be represented as a String.
Because of this, there is no way to derive fmt::String, all
implementations must be purposeful. It is used by the default format
syntax, `{}`.
This will break most instances of `{}`, since that now requires the type
to impl fmt::String. In most cases, replacing `{}` with `{:?}` is the
correct fix. Types that were being printed specifically for users should
receive a fmt::String implementation to fix this.
Part of #20013
[breaking-change]
- the self type includes some local type; and,
- type parameters in the self type must be constrained by a local type.
A type parameter is called *constrained* if it appears in some type-parameter of a local type.
Here are some examples that are accepted. In all of these examples, I
assume that `Foo` is a trait defined in another crate. If `Foo` were
defined in the local crate, then all the examples would be legal.
- `impl Foo for LocalType`
- `impl<T> Foo<T> for LocalType` -- T does not appear in Self, so it is OK
- `impl<T> Foo<T> for LocalType<T>` -- T here is constrained by LocalType
- `impl<T> Foo<T> for (LocalType<T>, T)` -- T here is constrained by LocalType
Here are some illegal examples (again, these examples assume that
`Foo` is not local to the current crate):
- `impl Foo for int` -- the Self type is not local
- `impl<T> Foo for T` -- T appears in Self unconstrained by a local type
- `impl<T> Foo for (LocalType, T)` -- T appears in Self unconstrained by a local type
This is a [breaking-change]. For the time being, you can opt out of
the new rules by placing `#[old_orphan_check]` on the trait (and
enabling the feature gate where the trait is defined). Longer term,
you should restructure your traits to avoid the problem. Usually this
means changing the order of parameters so that the "central" type
parameter is in the `Self` position.
As an example of that refactoring, consider the `BorrowFrom` trait:
```rust
pub trait BorrowFrom<Sized? Owned> for Sized? {
fn borrow_from(owned: &Owned) -> &Self;
}
```
As defined, this trait is commonly implemented for custom pointer
types, such as `Arc`. Those impls follow the pattern:
```rust
impl<T> BorrowFrom<Arc<T>> for T {...}
```
Unfortunately, this impl is illegal because the self type `T` is not
local to the current crate. Therefore, we are going to change the order of the parameters,
so that `BorrowFrom` becomes `Borrow`:
```rust
pub trait Borrow<Sized? Borrowed> for Sized? {
fn borrow_from(owned: &Self) -> &Borrowed;
}
```
Now the `Arc` impl is written:
```rust
impl<T> Borrow<T> for Arc<T> { ... }
```
This impl is legal because the self type (`Arc<T>`) is local.
This patch marks `PartialEq`, `Eq`, `PartialOrd`, and `Ord` as
`#[stable]`, as well as the majorify of manual implementaitons of these
traits. The traits match the [reform
RFC](https://github.com/rust-lang/rfcs/pull/439).
Along the way, two changes are made:
* The recently-added type parameters for `Ord` and `Eq` are
removed. These were mistakenly added while adding them to `PartialOrd`
and `PartialEq`, but they don't make sense given the laws that are
required for (and use cases for) `Ord` and `Eq`.
* More explicit laws are added for `PartialEq` and `PartialOrd`,
connecting them to their associated mathematical concepts.
In the future, many of the impls should be generalized; see
since generalizing later is not a breaking change.
[breaking-change]
This patch marks `clone` stable, as well as the `Clone` trait, but
leaves `clone_from` unstable. The latter will be decided by the beta.
The patch also marks most manual implementations of `Clone` as stable,
except where the APIs are otherwise deprecated or where there is
uncertainty about providing `Clone`.
This commit makes `Cow` more usable by allowing it to be applied to
unsized types (as was intended) and providing some basic `ToOwned`
implementations on slice types. It also corrects the documentation for
`Cow` to no longer mention `DerefMut`, and adds an example.
Closes#19123
This commit makes `Cow` more usable by allowing it to be applied to
unsized types (as was intended) and providing some basic `ToOwned`
implementations on slice types. It also corrects the documentation for
`Cow` to no longer mention `DerefMut`, and adds an example.
Following [the collections reform
RFC](https://github.com/rust-lang/rfcs/pull/235),
this commit adds a new `borrow` module to libcore.
The module contains traits for borrowing data (`BorrowFrom` and
`BorrowFromMut`),
generalized cloning (`ToOwned`), and a clone-on-write smartpointer (`Cow`).
