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