From 4d5a34bf75097085adddb3ca2ac226d5882874e1 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Sat, 18 Nov 2023 15:55:00 +0100 Subject: [PATCH 1/6] Improve `sizehint!` docstring about `shrink` arg --- base/array.jl | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/base/array.jl b/base/array.jl index e90723957afdb..11b9d00b91cc5 100644 --- a/base/array.jl +++ b/base/array.jl @@ -1434,7 +1434,7 @@ end """ sizehint!(s, n; first::Bool=false, shrink::Bool=true) -> s -Suggest that collection `s` reserve capacity for at least `n` elements. That is, if +Suggest that collection `s` reserve capacity for `n` elements. That is, if you expect that you're going to have to push a lot of values onto `s`, you can avoid the cost of incremental reallocation by doing it once up front; this can improve performance. @@ -1443,6 +1443,10 @@ If `first` is true, then the reserved space is from the start of the collection, collections. Supplying this keyword may result in an error if the collection is nor ordered or if `pushfirst!` is not supported for this collection. +If `shrink` is `true` (the default), the reserved space may be reduced if it is +larger than `n`. Passing `shrink=false` will ensure that the existing space is preserved +even if it is larger than requested. + See also [`resize!`](@ref). # Notes on the performance model @@ -1458,8 +1462,6 @@ For types that support `sizehint!`, 3. `empty!` is nearly costless (and O(1)) for types that support this kind of preallocation. -4. `shrink` controls if the collection can be shrunk. - !!! compat "Julia 1.11" The `shrink` and `first` arguments were added in Julia 1.11. """ From 7ad6cbdba63d773040977151afd4cae764f5e4b2 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Tue, 21 Nov 2023 21:24:24 +0100 Subject: [PATCH 2/6] Review fixes --- base/array.jl | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/base/array.jl b/base/array.jl index 11b9d00b91cc5..47e631fbe2017 100644 --- a/base/array.jl +++ b/base/array.jl @@ -1434,18 +1434,19 @@ end """ sizehint!(s, n; first::Bool=false, shrink::Bool=true) -> s -Suggest that collection `s` reserve capacity for `n` elements. That is, if +Suggest that collection `s` reserve capacity for at least `n` elements. That is, if you expect that you're going to have to push a lot of values onto `s`, you can avoid the cost of incremental reallocation by doing it once up front; this can improve performance. -If `first` is true, then the reserved space is from the start of the collection, for ordered -collections. Supplying this keyword may result in an error if the collection is nor ordered +If the collection is ordered and `first` is `true`, then any additional space is reserved +before the start of the collection rather than after the end. This way, subsequent calls +to `pushfirst!` (instead of `push!`) may become faster. +Supplying this keyword may result in an error if the collection is nor ordered or if `pushfirst!` is not supported for this collection. -If `shrink` is `true` (the default), the reserved space may be reduced if it is -larger than `n`. Passing `shrink=false` will ensure that the existing space is preserved -even if it is larger than requested. +If `shrink=true` (the default), the collection's capacity may be reduced if its current +capacity is greater than `n` See also [`resize!`](@ref). From 11fcb4c93d06fe1f98c5c6557a4afaf102d3b1fd Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Tue, 21 Nov 2023 21:25:14 +0100 Subject: [PATCH 3/6] Fix typo --- base/array.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/base/array.jl b/base/array.jl index 47e631fbe2017..28845e4e6e124 100644 --- a/base/array.jl +++ b/base/array.jl @@ -1442,7 +1442,7 @@ performance. If the collection is ordered and `first` is `true`, then any additional space is reserved before the start of the collection rather than after the end. This way, subsequent calls to `pushfirst!` (instead of `push!`) may become faster. -Supplying this keyword may result in an error if the collection is nor ordered +Supplying this keyword may result in an error if the collection is not ordered or if `pushfirst!` is not supported for this collection. If `shrink=true` (the default), the collection's capacity may be reduced if its current From aff1a0b6527f9411df52f43d8096eb593ac52e9b Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Sun, 10 Dec 2023 18:21:45 +0100 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Petr Vana --- base/array.jl | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/base/array.jl b/base/array.jl index 28845e4e6e124..fd22995946419 100644 --- a/base/array.jl +++ b/base/array.jl @@ -1439,14 +1439,14 @@ you expect that you're going to have to push a lot of values onto `s`, you can a the cost of incremental reallocation by doing it once up front; this can improve performance. -If the collection is ordered and `first` is `true`, then any additional space is reserved +If `first` is `true`, then any additional space is reserved before the start of the collection. This way, subsequent calls to `pushfirst!` (instead of `push!`) may become faster. before the start of the collection rather than after the end. This way, subsequent calls to `pushfirst!` (instead of `push!`) may become faster. Supplying this keyword may result in an error if the collection is not ordered or if `pushfirst!` is not supported for this collection. If `shrink=true` (the default), the collection's capacity may be reduced if its current -capacity is greater than `n` +capacity is greater than `n`. See also [`resize!`](@ref). From 343f51a3ab3b1c8f395c946fb286bd5ddd2a0a76 Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Sun, 10 Dec 2023 18:22:47 +0100 Subject: [PATCH 5/6] Break line --- base/array.jl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/base/array.jl b/base/array.jl index fd22995946419..4bb4b441d0030 100644 --- a/base/array.jl +++ b/base/array.jl @@ -1439,7 +1439,8 @@ you expect that you're going to have to push a lot of values onto `s`, you can a the cost of incremental reallocation by doing it once up front; this can improve performance. -If `first` is `true`, then any additional space is reserved before the start of the collection. This way, subsequent calls to `pushfirst!` (instead of `push!`) may become faster. +If `first` is `true`, then any additional space is reserved before the start of the collection. +This way, subsequent calls to `pushfirst!` (instead of `push!`) may become faster. before the start of the collection rather than after the end. This way, subsequent calls to `pushfirst!` (instead of `push!`) may become faster. Supplying this keyword may result in an error if the collection is not ordered From a9c1b5f8b4dbc7d0e3d108f6d60ecceeb7ad14be Mon Sep 17 00:00:00 2001 From: Milan Bouchet-Valat Date: Sun, 10 Dec 2023 22:07:36 +0100 Subject: [PATCH 6/6] Remove duplicate lines --- base/array.jl | 2 -- 1 file changed, 2 deletions(-) diff --git a/base/array.jl b/base/array.jl index 4bb4b441d0030..e5e2d2c07c71f 100644 --- a/base/array.jl +++ b/base/array.jl @@ -1441,8 +1441,6 @@ performance. If `first` is `true`, then any additional space is reserved before the start of the collection. This way, subsequent calls to `pushfirst!` (instead of `push!`) may become faster. -before the start of the collection rather than after the end. This way, subsequent calls -to `pushfirst!` (instead of `push!`) may become faster. Supplying this keyword may result in an error if the collection is not ordered or if `pushfirst!` is not supported for this collection.