From 3eb87dbe2ddd99c5334d5282e6a4d3de6d9fa6c0 Mon Sep 17 00:00:00 2001 From: Mario Carneiro Date: Thu, 7 Oct 2021 03:33:00 -0700 Subject: [PATCH 1/3] 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 4c8ea6902ff14..58c35dfa3611e 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 From b9f008b1eeed6055eb36e0fae11b30e8ffc2ebfa Mon Sep 17 00:00:00 2001 From: Mario Carneiro Date: Tue, 4 Jan 2022 12:18:54 -0800 Subject: [PATCH 2/3] Update wording --- library/alloc/src/slice.rs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/library/alloc/src/slice.rs b/library/alloc/src/slice.rs index 58c35dfa3611e..020dfcbaac684 100644 --- a/library/alloc/src/slice.rs +++ b/library/alloc/src/slice.rs @@ -371,11 +371,11 @@ impl [T] { /// Sorts the slice with a key extraction function. /// - /// During sorting, the key function is called only once per element. + /// During sorting, the key function is called at most once per element, by using + /// temporary storage to remember the results of key evaluation. /// /// 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*). If the slice requires sorting, - /// the key function is called on all elements of the slice in the original order. + /// worst-case, where the key function is *O*(*m*). /// /// 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 From 06b17a21813c2869ee50cbc4c8a92a04e40d2959 Mon Sep 17 00:00:00 2001 From: Mario Carneiro Date: Tue, 4 Jan 2022 21:32:20 -0800 Subject: [PATCH 3/3] Clarify that ordering is unspecified --- library/alloc/src/slice.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/library/alloc/src/slice.rs b/library/alloc/src/slice.rs index 020dfcbaac684..d03ae2d5c1519 100644 --- a/library/alloc/src/slice.rs +++ b/library/alloc/src/slice.rs @@ -373,6 +373,8 @@ impl [T] { /// /// During sorting, the key function is called at most once per element, by using /// temporary storage to remember the results of key evaluation. + /// The order of calls to the key function is unspecified and may change in future versions + /// of the standard library. /// /// 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*).