From b76172b412116356ebef05b884a6e4def63a4d17 Mon Sep 17 00:00:00 2001 From: aviac Date: Wed, 25 Oct 2023 21:02:17 +0200 Subject: [PATCH] chore: adjust docs to reflect discussion in the PR --- src/lib.rs | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 2a450bd8f..11b624d48 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2499,8 +2499,18 @@ pub trait Itertools: Iterator { /// └─f─f─f─f─f─f /// ``` /// - /// If `f` is non-associative, prefer the normal [`Iterator::reduce`] instead to prevent - /// unexpected behavior unless you know what you're doing. + /// If `f` is associative you should also decide carefully: + /// + /// - if `f` is a trivial operation like `u32::wrapping_add`, prefer the normal + /// [`Iterator::reduce`] instead since it will most likely result in the generation of simpler + /// code because the compiler is able to optimize it + /// - otherwise if `f` is non-trivial like `format!`, you should use `tree_fold1` since it + /// reduces the number of operations from `O(n)` to `O(ln(n))` + /// + /// Here "non-trivial" means: + /// + /// - any allocating operation + /// - any function that is a composition of many operations /// /// ``` /// use itertools::Itertools;