From 7b2e012efed8d0da7d8fee1ce78500c7bc17d5a8 Mon Sep 17 00:00:00 2001 From: Alex Rutar Date: Mon, 20 Jan 2025 19:42:20 +0200 Subject: [PATCH] Fix a doc typo and clarify the render performance considerations --- src/lib.rs | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index eac4367..6ce5270 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -179,18 +179,22 @@ pub use nucleo; /// ``` /// /// ## Performance considerations -/// Generally speaking, this crate assumes that the [`Render`] implementation is quite -/// fast. For each item, the [`Render`] implementation is first called to generate the match -/// objects, and then if the item is not ASCII, [`Render`] is called again in order to render -/// the interactive picker screen with the relevant matches. -/// -/// In particular, very slow [`Render`] implementations which output non-ASCII will reduce -/// interactivity of the terminal interface. A crude rule of thumb is that rendering a single +/// In the majority of situations, performance of the [`Render`] implementation is only relevant +/// when sending the items to the picker, and not for generating the match list interactively. In +/// particular, in the majority of situations, [`Render::render`] is called exactly once per item +/// when it is sent to the picker. +/// +/// The **only** exception to this rule occurs the value returned by [`Render::render`] contains +/// non-ASCII characters. In this situation, it can happen that *exceptionally slow* [`Render`] +/// implementations will reduce interactivity. A crude rule of thumb is that rendering a single /// item should take (in the worst case) at most 100μs. For comparison, display formatting a /// `f64` takes around 100ns. /// -/// If this is not the case for your type, it is highly recommended to cache the render -/// computation: +/// 100μs is an extremely large amount of time in the vast majority of situations. If after +/// benchmarking you determine that this is not the case for your [`Render`] implementation, +/// and moreover your [`Render`] implementation outputs (in the majority of cases) non-ASCII +/// Unicode, you can internally cache the render computation (at the cost of increased memory +/// overhead): /// ``` /// # use nucleo_picker::Render; /// pub struct Item { @@ -506,7 +510,7 @@ impl> Picker { } /// Returns an [`Observer`] containing up-to-date [`Injector`]s for this picker. For example, - /// this is the channel to which new injectors will be sent when the picker process a + /// this is the channel to which new injectors will be sent when the picker processes a /// [restart event](Event::Restart). See the [`Event`] documentation for more detail. /// /// Restart events are not generated by this library. You only need this channel if you