@@ -24,6 +24,9 @@
2424
2525module Data.Text
2626 (
27+ -- * Strict vs lazy types
28+ -- $strict
29+
2730 -- * Fusion
2831 -- $fusion
2932
@@ -203,8 +206,30 @@ import qualified Data.Text.Encoding.Utf16 as U16
203206import Data.Text.Search (indices)
204207#if defined(__HADDOCK__)
205208import Data.ByteString (ByteString)
209+import qualified Data.Text.Lazy as L
210+import Data.Int (Int64)
206211#endif
207212
213+-- $strict
214+--
215+-- This package provides both strict and lazy 'Text' types. The
216+-- strict type is provided by the 'Data.Text' package, while the lazy
217+-- type is provided by the 'Data.Text.Lazy' package. Internally, the
218+-- lazy @Text@ type consists of a list of strict chunks.
219+--
220+-- The strict 'Text' type requires that an entire string fit into
221+-- memory at once. The lazy @Text@ type is capable of streaming
222+-- strings that are larger than memory using a small memory footprint.
223+-- In many cases, the overhead of chunked streaming makes the lazy
224+-- @Text@ type slower than its strict counterpart, but this is not
225+-- always the case. Sometimes, the time complexity of a function in
226+-- one module may be different from the other, due to their differing
227+-- internal structures.
228+--
229+-- Each module provides an almost identical API, with the main
230+-- difference being that the strict module uses 'Int' values for
231+-- lengths and counts, while the lazy module uses 'Int64' lengths.
232+
208233-- $fusion
209234--
210235-- Most of the functions in this module are subject to /fusion/,