@@ -201,12 +201,33 @@ import Data.Text.UnsafeChar (unsafeChr)
201import qualified Data.Text.Util as U
201import qualified Data.Text.Util as U
202import qualified Data.Text.Encoding.Utf16 as U16
202import qualified Data.Text.Encoding.Utf16 as U16
203import Data.Text.Search (indices)
203import Data.Text.Search (indices)
204+#if defined(__HADDOCK__)
205+import Data.ByteString (ByteString)
205-- $fusion
208-- $fusion
207-- Most of the functions in this module are subject to /fusion/,
210-- Most of the functions in this module are subject to /fusion/,
208-- meaning that a pipeline of such functions will usually allocate at
211-- meaning that a pipeline of such functions will usually allocate at
209-- most one 'Text' value.
212-- most one 'Text' value.
214+-- As an example, consider the following pipeline:
216+-- > import Data.Text as T
217+-- > import Data.Text.Encoding as E
219+-- > countChars :: ByteString -> Int
220+-- > countChars = T.length . T.toUpper . E.decodeUtf8
222+-- From the type signatures involved, this looks like it should
223+-- allocate one 'ByteString' value, and two 'Text' values. However,
224+-- when a module is compiled with optimisation enabled under GHC, the
225+-- two intermediate 'Text' values will be optimised away, and the
226+-- function will be compiled down to a single loop over the source
229+-- Functions that can be fused by the compiler are marked with the
230+-- phrase \"Subject to fusion\".
211instance Eq Text where
232instance Eq Text where
212 t1 == t2 = stream t1 == stream t2
233 t1 == t2 = stream t1 == stream t2