Deprecate [T]::rotate in favor of [T]::rotate_{left,right}.
Background
==========
Slices currently have an **unstable** [`rotate`] method which rotates
elements in the slice to the _left_ N positions. [Here][tracking] is the
tracking issue for this unstable feature.
```rust
let mut a = ['a', 'b' ,'c', 'd', 'e', 'f'];
a.rotate(2);
assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);
```
Proposal
========
Deprecate the [`rotate`] method and introduce `rotate_left` and
`rotate_right` methods.
```rust
let mut a = ['a', 'b' ,'c', 'd', 'e', 'f'];
a.rotate_left(2);
assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);
```
```rust
let mut a = ['a', 'b' ,'c', 'd', 'e', 'f'];
a.rotate_right(2);
assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']);
```
Justification
=============
I used this method today for my first time and (probably because I’m a
naive westerner who reads LTR) was surprised when the docs mentioned that
elements get rotated in a left-ward direction. I was in a situation
where I needed to shift elements in a right-ward direction and had to
context switch from the main problem I was working on and think how much
to rotate left in order to accomplish the right-ward rotation I needed.
Ruby’s `Array.rotate` shifts left-ward, Python’s `deque.rotate` shifts
right-ward. Both of their implementations allow passing negative numbers
to shift in the opposite direction respectively. The current `rotate`
implementation takes an unsigned integer argument which doesn't allow
the negative number behavior.
Introducing `rotate_left` and `rotate_right` would:
- remove ambiguity about direction (alleviating need to read docs 😉)
- make it easier for people who need to rotate right
[`rotate`]: https://doc.rust-lang.org/std/primitive.slice.html#method.rotate
[tracking]: https://github.com/rust-lang/rust/issues/41891
Mention SliceConcatExt's stability in its docs
Just saw someone in IRC mention there being no stable way to join string slices! It isn't entirely clear from the rust documentation that `SliceConcatExt` is usable. While this is mentioned in https://doc.rust-lang.org/std/prelude/, the trait has nothing to indicate that it's currently usable if found via a documentation search.
The wording on this could probably be improved, but I'm hoping its better than nothing.
SliceConcatExt's status as an unstable trait with stable methods is
documented in the compiler error for using it, and in
https://doc.rust-lang.org/std/prelude/, but it is not mentioned in the
trait itself.
Mentioning the methods can be used in stable rust today should help
users who are looking for a `join` method while working on stable rust.
Add a tidy check for missing or too many trailing newlines.
I've noticed recently there are lots of review comments requesting to fix trailing newlines. If this is going to be an official style here, it's better to let the CI do this repetitive check.
update char_indices example to highlight big chars
There was a comment today in IRC where someone thought `char_indices()` and `chars().enumerate()` were equivalent, so i wanted to put an example in the docs where that wasn't true.
r? @rust-lang/docs
Background
==========
Slices currently have an unstable [`rotate`] method which rotates
elements in the slice to the _left_ N positions. [Here][tracking] is the
tracking issue for this unstable feature.
```rust
let mut a = ['a', 'b' ,'c', 'd', 'e', 'f'];
a.rotate(2);
assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);
```
Proposal
========
Deprecate the [`rotate`] method and introduce `rotate_left` and
`rotate_right` methods.
```rust
let mut a = ['a', 'b' ,'c', 'd', 'e', 'f'];
a.rotate_left(2);
assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']);
```
```rust
let mut a = ['a', 'b' ,'c', 'd', 'e', 'f'];
a.rotate_right(2);
assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']);
```
Justification
=============
I used this method today for my first time and (probably because I’m a
naive westerner who reads LTR) was surprised when the docs mentioned that
elements get rotated in a left-ward direction. I was in a situation
where I needed to shift elements in a right-ward direction and had to
context switch from the main problem I was working on and think how much
to rotate left in order to accomplish the right-ward rotation I needed.
Ruby’s `Array.rotate` shifts left-ward, Python’s `deque.rotate` shifts
right-ward. Both of their implementations allow passing negative numbers
to shift in the opposite direction respectively.
Introducing `rotate_left` and `rotate_right` would:
- remove ambiguity about direction (alleviating need to read docs 😉)
- make it easier for people who need to rotate right
[`rotate`]: https://doc.rust-lang.org/std/primitive.slice.html#method.rotate
[tracking]: https://github.com/rust-lang/rust/issues/41891
After discussing [1] today with @pnkfelix and @Gankro,
we concluded that it’s ok for drop checking not to be much smarter
than the current `#[may_dangle]` design which requires an explicit
unsafe opt-in.
[1] https://github.com/rust-lang/rust/issues/27730#issuecomment-316432083
Mark ascii methods on primitive types stable in 1.23.0 not 1.21.0.
The ascii_methods_on_intrinsics feature stabilization
didn't land in time for 1.21.0. Update the annotation
so the documentation is correct about when these
methods became available.
The ascii_methods_on_intrinsics feature stabilization
didn't land in time for 1.21.0. Update the annotation
so the documentation is correct about when these
methods became available.
Improve documentation for slice swap/copy/clone operations.
Fixes#45636.
- Demonstrate how to use these operations with slices of differing
lengths
- Demonstrate how to swap/copy/clone sub-slices of a slice using
`split_at_mut`
Stabilize some `ascii_ctype` methods
As discussed in #39658, this PR stabilizes those methods for `u8` and `char`. All inherent `ascii_ctype` for `[u8]` and `str` are removed as we prefer the more explicit version `s.chars().all(|c| c.is_ascii_())`.
This PR doesn't modify the `AsciiExt` trait. There, the `ascii_ctype` methods are still unstable. It is planned to remove those in the future (I think). I had to modify some code in `ascii.rs` to properly implement `AsciiExt` for all types.
Fixes#39658.
Introduce LinkedList::drain_filter
This introduces `LinkedList::remove_if`.
This operation embodies one of the use-cases where `LinkedList` would typically be preferred over `Vec`: random removal and retrieval.
There are a number of considerations with this:
Should there be two `remove_if` methods? One where elements are only removed, one which returns a collection of removed elements.
Should this be implemented using a draining iterator pattern that covers both cases? I suspect that would incur a bit of overhead (moving the element into the iterator, then into a new collection). But I'm not sure. Maybe that's an acceptable compromise to maximize flexibility.
I don't feel I've had enough exposure to unsafe programming in rust to be certain the implementation is correct. This relies quite heavily on moving around copies of Shared pointers to make the code reasonable. Please help me out :).
Relates to rust-lang/rfcs#2140 - drain_filter for all collections
`drain_filter` is implemented instead of `LinkedList::remove_if` based
on review feedback.
Fixes#45636.
- Demonstrate how to use these operations with slices of differing
lengths
- Demonstrate how to swap/copy/clone sub-slices of a slice using
`split_at_mut`
Rename param in `[T]::swap_with_slice` from `src` to `other`.
The idea of ‘source’ and ‘destination’ aren’t very applicable for this
operation since both slices can both be considered sources and
destinations.
Add Box::leak<'a>(Box<T>) -> &'a mut T where T: 'a
Adds:
```rust
impl<T: ?Sized> Box<T> {
pub fn leak<'a>(b: Box<T>) -> &'a mut T where T: 'a {
unsafe { &mut *Box::into_raw(b) }
}
}
```
which is useful for when you just want to put some stuff on the heap and then have a reference to it for the remainder of the program.
r? @sfackler
cc @durka
