collections: Reorder slice methods to improve API docs

[bluss]

collections: Reorder slice methods to improve API docs

We have an evolutionary history whose traces are still visible in the
slice docs today.

Some heuristics:

• Group method and method_mut together

• Group method and method_by together

• Group by use case, here we have roughly:

  Basic interrogators (len)
  Mutation (swap)
  Iterators (iter)
  Segmentation (split)
  Searching (contains)
  Permutations (permutations)
  Misc (clone_from_slice)

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @brson (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. The way Github handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see CONTRIBUTING.md for more information.

[Gankra]

New order (since the patch makes this inscrutable):

https://etherpad.mozilla.org/7Do38wW2iz

[Gankra]

Actually let's just inline it:

// basic interrogators
fn len(&self) -> usize
fn is_empty(&self) -> bool
fn first(&self) -> Option<&T>
fn first_mut(&mut self) -> Option<&mut T>
fn tail(&self) -> &[T]
fn tail_mut(&mut self) -> &mut [T]
fn init(&self) -> &[T]
fn init_mut(&mut self) -> &mut [T]
fn last(&self) -> Option<&T>
fn last_mut(&mut self) -> Option<&mut T>
fn get(&self, index: usize) -> Option<&T>
fn get_mut(&mut self, index: usize) -> Option<&mut T>
unsafe fn get_unchecked(&self, index: usize) -> &T
unsafe fn get_unchecked_mut(&mut self, index: usize) -> &mut T
fn as_ptr(&self) -> *const T
fn as_mut_ptr(&mut self) -> *mut T

// mutation
fn swap(&mut self, a: usize, b: usize)
fn reverse(&mut self)

// iterators
fn iter(&self) -> Iter<T>
fn iter_mut(&mut self) -> IterMut<T>
fn windows(&self, size: usize) -> Windows<T>
fn chunks(&self, size: usize) -> Chunks<T>
fn chunks_mut(&mut self, chunk_size: usize) -> ChunksMut<T>

// segmentation
fn split_at(&self, mid: usize) -> (&[T], &[T])
fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T])

fn split<F>(&self, pred: F) -> Split<T, F> where F: FnMut(&T) -> bool
fn split_mut<F>(&mut self, pred: F) -> SplitMut<T, F> where F: FnMut(&T) -> bool
fn splitn<F>(&self, n: usize, pred: F) -> SplitN<T, F> where F: FnMut(&T) -> bool
fn splitn_mut<F>(&mut self, n: usize, pred: F) -> SplitNMut<T, F> where F: FnMut(&T) -> bool
fn rsplitn<F>(&self, n: usize, pred: F) -> RSplitN<T, F> where F: FnMut(&T) -> bool
fn rsplitn_mut<F>(&mut self, n: usize, pred: F) -> RSplitNMut<T, F> where F: FnMut(&T) -> bool

// sorting and searching
fn contains(&self, x: &T) -> bool where T: PartialEq<T>
fn starts_with(&self, needle: &[T]) -> bool where T: PartialEq<T>
fn ends_with(&self, needle: &[T]) -> bool where T: PartialEq<T>
fn position_elem(&self, t: &T) -> Option<usize> where T: PartialEq<T>
fn rposition_elem(&self, t: &T) -> Option<usize> where T: PartialEq<T>
fn binary_search(&self, x: &T) -> Result<usize, usize> where T: Ord
fn binary_search_by<F>(&self, f: F) -> Result<usize, usize> where F: FnMut(&T) -> Ordering
fn sort(&mut self) where T: Ord
fn sort_by<F>(&mut self, compare: F) where F: FnMut(&T, &T) -> Ordering

// permut
fn permutations(&self) -> Permutations<T> where T: Clone
fn next_permutation(&mut self) -> bool where T: Ord
fn prev_permutation(&mut self) -> bool where T: Ord

// misc
fn clone_from_slice(&mut self, src: &[T]) -> usize where T: Clone
fn move_from(&mut self, src: Vec<T>, start: usize, end: usize) -> usize
fn to_vec(&self) -> Vec<T> where T: Clone
fn into_vec(self: Box<[T]>) -> Vec<T>

[Gankra]

Seems to be basically an improvement, though I don't like the clobber to history.

@bors r+

[bors]

📌 Commit 7b89fe0 has been approved by Gankro

[bluss]

None of the methods have their real implementation inline anyway, this is just the façade.

[bors]

☔ The latest upstream changes (presumably #25588) made this pull request unmergeable. Please resolve the merge conflicts.

[bluss]

Rebased!

[Gankra]

@bors r+

[bors]

📌 Commit 77dcaa5 has been approved by Gankro

[bors]

⌛ Testing commit 77dcaa5 with merge b287254...

[bors]

💔 Test failed - auto-mac-64-opt

[bluss]

Looks like failure is unrelated and retry is needed :(

[Gankra]

@bors retry

[bors]

⌛ Testing commit 77dcaa5 with merge 667a634...

[bors]

💔 Test failed - auto-linux-32-opt

[bluss]

Argh, no idea why this keeps happening.

[Gankra]

Sometimes it's just stubborn 💢

@bors retry

[bors]

⌛ Testing commit 77dcaa5 with merge c575885...

[bluss]

come on bors! 🎱

[bors]

☀️ Test successful - auto-linux-32-nopt-t, auto-linux-32-opt, auto-linux-64-nopt-t, auto-linux-64-opt, auto-linux-64-x-android-t, auto-mac-32-opt, auto-mac-64-nopt-t, auto-mac-64-opt, auto-win-gnu-32-nopt-t, auto-win-gnu-32-opt, auto-win-gnu-64-nopt-t, auto-win-gnu-64-opt