@@ -201,12 +201,33 @@ import Data.Text.UnsafeChar (unsafeChr)
201201import qualified Data.Text.Util as U
202202import qualified Data.Text.Encoding.Utf16 as U16
203203import Data.Text.Search (indices)
204+#if defined(__HADDOCK__)
205+import Data.ByteString (ByteString)
206+#endif
204207
205208-- $fusion
206209--
207210-- Most of the functions in this module are subject to /fusion/,
208211-- meaning that a pipeline of such functions will usually allocate at
209212-- most one 'Text' value.
213+--
214+-- As an example, consider the following pipeline:
215+--
216+-- > import Data.Text as T
217+-- > import Data.Text.Encoding as E
218+-- >
219+-- > countChars :: ByteString -> Int
220+-- > countChars = T.length . T.toUpper . E.decodeUtf8
221+--
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
227+-- 'ByteString'.
228+--
229+-- Functions that can be fused by the compiler are marked with the
230+-- phrase \"Subject to fusion\".
210231
211232instance Eq Text where
212233 t1 == t2 = stream t1 == stream t2