@@ -29,8 +29,8 @@
2929--
3030-- To use an extended and very rich family of functions for working
3131-- with Unicode text (including normalization, regular expressions,
32−-- non-standard encodings, text breaking, and locales), see the
33−-- @text-icu@ package: <http://hackage.haskell.org/package/text-icu>
32+-- non-standard encodings, text breaking, and locales), see
33+-- <http://hackage.haskell.org/package/text-icu the text-icu package >.
3434
3535module Data.Text
3636 (
@@ -241,29 +241,32 @@ import GHC.Prim (Addr#)
241241-- lazy @Text@ type consists of a list of strict chunks.
242242--
243243-- The strict 'Text' type requires that an entire string fit into
244−-- memory at once. The lazy @Text@ type is capable of streaming
245−-- strings that are larger than memory using a small memory footprint.
246−-- In many cases, the overhead of chunked streaming makes the lazy
247−-- @Text@ type slower than its strict counterpart, but this is not
248−-- always the case. Sometimes, the time complexity of a function in
249−-- one module may be different from the other, due to their differing
250−-- internal structures.
244+-- memory at once. The lazy 'Data.Text.Lazy.Text' type is capable of
245+-- streaming strings that are larger than memory using a small memory
246+-- footprint. In many cases, the overhead of chunked streaming makes
247+-- the lazy 'Data.Text.Lazy.Text' type slower than its strict
248+-- counterpart, but this is not always the case. Sometimes, the time
249+-- complexity of a function in one module may be different from the
250+-- other, due to their differing internal structures.
251251--
252252-- Each module provides an almost identical API, with the main
253253-- difference being that the strict module uses 'Int' values for
254−-- lengths and counts, while the lazy module uses 'Int64' lengths.
254+-- lengths and counts, while the lazy module uses 'Data.Int.Int64'
255+-- lengths.
255256
256257-- $replacement
257258--
258259-- A 'Text' value is a sequence of Unicode scalar values, as defined
259−-- in §3.9, definition D76 of the Unicode 5.2 standard:
260−-- <http://www.unicode.org/versions/Unicode5.2.0/ch03.pdf#page=35>. As
261−-- such, a 'Text' cannot contain values in the range U+D800 to U+DFFF
262−-- inclusive. Haskell implementations admit all Unicode code points
263−-- (§3.4, definition D10) as 'Char' values, including code points
264−-- from this invalid range. This means that there are some 'Char'
265−-- values that are not valid Unicode scalar values, and the functions
266−-- in this module must handle those cases.
260+-- in
261+-- <http://www.unicode.org/versions/Unicode5.2.0/ch03.pdf#page=35 §3.9, definition D76 of the Unicode 5.2 standard >.
262+-- As such, a 'Text' cannot contain values in the range U+D800 to
263+-- U+DFFF inclusive. Haskell implementations admit all Unicode code
264+-- points
265+-- (<http://www.unicode.org/versions/Unicode5.2.0/ch03.pdf#page=13 §3.4, definition D10 >)
266+-- as 'Char' values, including code points from this invalid range.
267+-- This means that there are some 'Char' values that are not valid
268+-- Unicode scalar values, and the functions in this module must handle
269+-- those cases.
267270--
268271-- Within this module, many functions construct a 'Text' from one or
269272-- more 'Char' values. Those functions will substitute 'Char' values
@@ -277,8 +280,8 @@ import GHC.Prim (Addr#)
277280-- range U+D800 through U+DFFF are used by UTF-16 to denote surrogate
278281-- code points, and so cannot be represented. The functions replace
279282-- invalid scalar values, instead of dropping them, as a security
280−-- measure. For details, see Unicode Technical Report 36, §3.5:
281−-- <http://unicode.org/reports/tr36/#Deletion_of_Noncharacters>)
283+-- measure. For details, see
284+-- <http://unicode.org/reports/tr36/#Deletion_of_Noncharacters Unicode Technical Report 36, §3.5 >.)
282285
283286-- $fusion
284287--
@@ -296,11 +299,11 @@ import GHC.Prim (Addr#)
296299-- > countChars = T.length . T.toUpper . E.decodeUtf8
297300--
298301-- From the type signatures involved, this looks like it should
299−-- allocate one 'ByteString' value, and two 'Text' values. However,
300−-- when a module is compiled with optimisation enabled under GHC, the
301−-- two intermediate 'Text' values will be optimised away, and the
302−-- function will be compiled down to a single loop over the source
303−-- 'ByteString'.
302+-- allocate one 'Data.ByteString.ByteString' value, and two 'Text'
303+-- values. However, when a module is compiled with optimisation
304+-- enabled under GHC, the two intermediate 'Text' values will be
305+-- optimised away, and the function will be compiled down to a single
306+-- loop over the source 'Data.ByteString.ByteString'.
304307--
305308-- Functions that can be fused by the compiler are documented with the
306309-- phrase \"Subject to fusion\".
@@ -335,17 +338,17 @@ instance NFData Text
335338-- | This instance preserves data abstraction at the cost of inefficiency.
336339-- We omit reflection services for the sake of data abstraction.
337340--
338−-- This instance was created by copying the updated behavior of @Data.Set@ and
339−-- @Data.Map@. If you feel a mistake has been made, please feel free to
340−-- submit improvements.
341+-- This instance was created by copying the updated behavior of
342+-- @"Data.Set".@'Data.Set.Set' and @"Data.Map".@'Data.Map.Map'. If you
343+-- feel a mistake has been made, please feel free to submit
344+-- improvements.
341345--
342−-- Original discussion is archived here:
346+-- The original discussion is archived here:
347+-- <http://groups.google.com/group/haskell-cafe/browse_thread/thread/b5bbb1b28a7e525d/0639d46852575b93 could we get a Data instance for Data.Text.Text? >
343348--
344−-- <http://groups.google.com/group/haskell-cafe/browse_thread/thread/b5bbb1b28a7e525d/0639d46852575b93 could we get a Data instance for Data.Text.Text?>
345−--
346−-- The followup discussion that changed the behavior of @Data.Set@ and @Data.Map@ is archived here
347−--
348−-- <http://markmail.org/message/trovdc6zkphyi3cr#query:+page:1+mid:a46der3iacwjcf6n+state:results Proposal: Allow gunfold for Data.Map, ...>
349+-- The followup discussion that changed the behavior of 'Data.Set.Set'
350+-- and 'Data.Map.Map' is archived here:
351+-- <http://markmail.org/message/trovdc6zkphyi3cr#query:+page:1+mid:a46der3iacwjcf6n+state:results Proposal: Allow gunfold for Data.Map, ... >
349352
350353instance Data Text where
351354 gfoldl f z txt = z pack `f` (unpack txt)
@@ -669,9 +672,8 @@ replace needle@(Text _ _ neeLen)
669672-- /Note/: In some languages, case conversion is a locale- and
670673-- context-dependent operation. The case conversion functions in this
671674-- module are /not/ locale sensitive. Programs that require locale
672−-- sensitivity should use appropriate versions of the case mapping
673−-- functions from the @text-icu@ package:
674−-- <http://hackage.haskell.org/package/text-icu>
675+-- sensitivity should use appropriate versions of the
676+-- <http://hackage.haskell.org/package/text-icu-0.6.3.7/docs/Data-Text-ICU.html#g:4 case mapping functions from the text-icu package >.
675677
676678-- | /O(n)/ Convert a string to folded case. Subject to fusion.
677679--