From 3eb87dbe2ddd99c5334d5282e6a4d3de6d9fa6c0 Mon Sep 17 00:00:00 2001 From: Mario Carneiro Date: Thu, 7 Oct 2021 03:33:00 -0700 Subject: [PATCH] doc: guarantee call order for sort_by_cached_key `slice::sort_by_cached_key` takes a caching function `f: impl FnMut(&T) -> K`, which means that the order that calls to the caching function are made is user-visible. This adds a clause to the documentation to promise the current behavior, which is that `f` is called on all elements of the slice from left to right, unless the slice has len < 2 in which case `f` is not called. --- library/alloc/src/slice.rs | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/library/alloc/src/slice.rs b/library/alloc/src/slice.rs index 4c8ea6902ff..58c35dfa361 100644 --- a/library/alloc/src/slice.rs +++ b/library/alloc/src/slice.rs @@ -374,7 +374,8 @@ impl [T] { /// During sorting, the key function is called only once per element. /// /// This sort is stable (i.e., does not reorder equal elements) and *O*(*m* \* *n* + *n* \* log(*n*)) - /// worst-case, where the key function is *O*(*m*). + /// worst-case, where the key function is *O*(*m*). If the slice requires sorting, + /// the key function is called on all elements of the slice in the original order. /// /// For simple key functions (e.g., functions that are property accesses or /// basic operations), [`sort_by_key`](slice::sort_by_key) is likely to be