@@ -32,9 +32,8 @@
3232--
3333-- To use an extended and very rich family of functions for working
3434-- with Unicode text (including normalization, regular expressions,
35−-- non-standard encodings, text breaking, and locales), see the
36−-- <http://hackage.haskell.org/package/text-icu text-icu package >.
37−--
35+-- non-standard encodings, text breaking, and locales), see
36+-- <http://hackage.haskell.org/package/text-icu the text-icu package >.
3837
3938module Data.Text
4039 (
@@ -44,9 +43,6 @@ module Data.Text
4443 -- * Acceptable data
4544 -- $replacement
4645
47− -- * Definition of character
48− -- $character_definition
49−
5046 -- * Fusion
5147 -- $fusion
5248
@@ -64,7 +60,6 @@ module Data.Text
6460 , snoc
6561 , append
6662 , uncons
67− , unsnoc
6863 , head
6964 , last
7065 , tail
@@ -251,18 +246,6 @@ import qualified GHC.Exts as Exts
251246import Text.Printf (PrintfArg, formatArg, formatString)
252247#endif
253248
254−-- $character_definition
255−--
256−-- This package uses the term /character/ to denote Unicode /code points/.
257−--
258−-- Note that this is not the same thing as a grapheme (e.g. a
259−-- composition of code points that form one visual symbol). For
260−-- instance, consider the grapheme \"ä\". This symbol has two
261−-- Unicode representations: a single code-point representation
262−-- @U+00E4@ (the @LATIN SMALL LETTER A WITH DIAERESIS@ code point),
263−-- and a two code point representation @U+0061@ (the \"@A@\" code
264−-- point) and @U+0308@ (the @COMBINING DIAERESIS@ code point).
265−
266249-- $strict
267250--
268251-- This package provides both strict and lazy 'Text' types. The
@@ -351,13 +334,9 @@ instance Read Text where
351334 readsPrec p str = [(pack x,y) | (x,y) <- readsPrec p str]
352335
353336#if MIN_VERSION_base(4,9,0)
354−-- | Non-orphan 'Semigroup' instance only defined for
355−-- @base-4.9.0.0@ and later; orphan instances for older GHCs are
356−-- provided by
357−-- the [semigroups](http://hackage.haskell.org/package/semigroups)
358−-- package
359−--
360−-- @since 1.2.2.0
337+-- Semigroup orphan instances for older GHCs are provided by
338+-- 'semigroups` package
339+
361340instance Semigroup Text where
362341 (<>) = append
363342#endif
@@ -375,7 +354,6 @@ instance IsString Text where
375354 fromString = pack
376355
377356#if __GLASGOW_HASKELL__ >= 708
378−-- | @since 1.2.0.0
379357instance Exts.IsList Text where
380358 type Item Text = Char
381359 fromList = pack
@@ -386,7 +364,6 @@ instance Exts.IsList Text where
386364instance NFData Text where rnf !_ = ()
387365#endif
388366
389−-- | @since 1.2.1.0
390367instance Binary Text where
391368 put t = put (encodeUtf8 t)
392369 get = do
@@ -420,8 +397,6 @@ instance Data Text where
420397
421398#if MIN_VERSION_base(4,7,0)
422399-- | Only defined for @base-4.7.0.0@ and later
423−--
424−-- @since 1.2.2.0
425400instance PrintfArg Text where
426401 formatArg txt = formatString $ unpack txt
427402#endif
@@ -570,19 +545,6 @@ init (Text arr off len) | len <= 0 = emptyError "init"
570545 unstream (S.init (stream t)) = init t
571546 #-}
572547
573−-- | /O(1)/ Returns all but the last character and the last character of a
574−-- 'Text', or 'Nothing' if empty.
575−--
576−-- @since 1.2.3.0
577−unsnoc :: Text -> Maybe (Text, Char)
578−unsnoc (Text arr off len)
579− | len <= 0 = Nothing
580− | n < 0xDC00 || n > 0xDFFF = Just (text arr off (len-1), unsafeChr n)
581− | otherwise = Just (text arr off (len-2), U16.chr2 n0 n)
582− where n = A.unsafeIndex arr (off+len-1)
583− n0 = A.unsafeIndex arr (off+len-2)
584−{-# INLINE [1] unsnoc #-}
585−
586548-- | /O(1)/ Tests whether a 'Text' is empty or not. Subject to
587549-- fusion.
588550null :: Text -> Bool
@@ -662,15 +624,8 @@ compareLength t n = S.compareLengthI (stream t) n
662624-- -----------------------------------------------------------------------------
663625-- * Transformations
664626-- | /O(n)/ 'map' @f@ @t@ is the 'Text' obtained by applying @f@ to
665−-- each element of @t@.
666−--
667−-- Example:
668−--
669−-- >>> let message = pack "I am not angry. Not at all."
670−-- >>> T.map (\c -> if c == '.' then '!' else c) message
671−-- "I am not angry! Not at all!"
672−--
673−-- Subject to fusion. Performs replacement on invalid scalar values.
627+-- each element of @t@. Subject to fusion. Performs replacement on
628+-- invalid scalar values.
674629map :: (Char -> Char) -> Text -> Text
675630map f t = unstream (S.map (safe . f) (stream t))
676631{-# INLINE [1] map #-}
@@ -678,36 +633,18 @@ map f t = unstream (S.map (safe . f) (stream t))
678633-- | /O(n)/ The 'intercalate' function takes a 'Text' and a list of
679634-- 'Text's and concatenates the list after interspersing the first
680635-- argument between each element of the list.
681−--
682−-- Example:
683−--
684−-- >>> T.intercalate "NI!" ["We", "seek", "the", "Holy", "Grail"]
685−-- "WeNI!seekNI!theNI!HolyNI!Grail"
686636intercalate :: Text -> [Text] -> Text
687637intercalate t = concat . (F.intersperse t)
688638{-# INLINE intercalate #-}
689639
690640-- | /O(n)/ The 'intersperse' function takes a character and places it
691−-- between the characters of a 'Text'.
692−--
693−-- Example:
694−--
695−-- >>> T.intersperse '.' "SHIELD"
696−-- "S.H.I.E.L.D"
697−--
698−-- Subject to fusion. Performs replacement on invalid scalar values.
641+-- between the characters of a 'Text'. Subject to fusion. Performs
642+-- replacement on invalid scalar values.
699643intersperse :: Char -> Text -> Text
700644intersperse c t = unstream (S.intersperse (safe c) (stream t))
701645{-# INLINE intersperse #-}
702646
703−-- | /O(n)/ Reverse the characters of a string.
704−--
705−-- Example:
706−--
707−-- >>> T.reverse "desrever"
708−-- "reversed"
709−--
710−-- Subject to fusion.
647+-- | /O(n)/ Reverse the characters of a string. Subject to fusion.
711648reverse :: Text -> Text
712649reverse t = S.reverse (stream t)
713650{-# INLINE reverse #-}
@@ -726,14 +663,12 @@ reverse t = S.reverse (stream t)
726663-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
727664-- be replaced recursively:
728665--
729−-- >>> replace "oo" "foo" "oo"
730−-- "foo"
666+-- > replace "oo" "foo" "oo" == "foo"
731667--
732668-- In cases where several instances of @needle@ overlap, only the
733669-- first one will be replaced:
734670--
735−-- >>> replace "ofo" "bar" "ofofo"
736−-- "barfo"
671+-- > replace "ofo" "bar" "ofofo" == "barfo"
737672--
738673-- In (unlikely) bad cases, this function's time complexity degrades
739674-- towards /O(n*m)/.
@@ -847,8 +782,6 @@ toUpper t = unstream (S.toUpper (stream t))
847782-- guides disagree on whether the book name \"The Hill of the Red
848783-- Fox\" is correctly title cased—but this function will
849784-- capitalize /every/ word.
850−--
851−-- @since 1.0.0.0
852785toTitle :: Text -> Text
853786toTitle t = unstream (S.toTitle (stream t))
854787{-# INLINE toTitle #-}
@@ -859,11 +792,8 @@ toTitle t = unstream (S.toTitle (stream t))
859792--
860793-- Examples:
861794--
862−-- >>> justifyLeft 7 'x' "foo"
863−-- "fooxxxx"
864−--
865−-- >>> justifyLeft 3 'x' "foobar"
866−-- "foobar"
795+-- > justifyLeft 7 'x' "foo" == "fooxxxx"
796+-- > justifyLeft 3 'x' "foobar" == "foobar"
867797justifyLeft :: Int -> Char -> Text -> Text
868798justifyLeft k c t
869799 | len >= k = t
@@ -884,11 +814,8 @@ justifyLeft k c t
884814--
885815-- Examples:
886816--
887−-- >>> justifyRight 7 'x' "bar"
888−-- "xxxxbar"
889−--
890−-- >>> justifyRight 3 'x' "foobar"
891−-- "foobar"
817+-- > justifyRight 7 'x' "bar" == "xxxxbar"
818+-- > justifyRight 3 'x' "foobar" == "foobar"
892819justifyRight :: Int -> Char -> Text -> Text
893820justifyRight k c t
894821 | len >= k = t
@@ -902,8 +829,7 @@ justifyRight k c t
902829--
903830-- Examples:
904831--
905−-- >>> center 8 'x' "HS"
906−-- "xxxHSxxx"
832+-- > center 8 'x' "HS" = "xxxHSxxx"
907833center :: Int -> Char -> Text -> Text
908834center k c t
909835 | len >= k = t
@@ -918,14 +844,6 @@ center k c t
918844-- of its 'Text' argument. Note that this function uses 'pack',
919845-- 'unpack', and the list version of transpose, and is thus not very
920846-- efficient.
921−--
922−-- Examples:
923−--
924−-- >>> transpose ["green","orange"]
925−-- ["go","rr","ea","en","ng","e"]
926−--
927−-- >>> transpose ["blue","red"]
928−-- ["br","le","ud","e"]
929847transpose :: [Text] -> [Text]
930848transpose ts = P.map pack (L.transpose (P.map unpack ts))
931849
@@ -1170,10 +1088,7 @@ iterN n t@(Text _arr _off len) = loop 0 0
11701088--
11711089-- Examples:
11721090--
1173−-- >>> takeEnd 3 "foobar"
1174−-- "bar"
1175−--
1176−-- @since 1.1.1.0
1091+-- > takeEnd 3 "foobar" == "bar"
11771092takeEnd :: Int -> Text -> Text
11781093takeEnd n t@(Text arr off len)
11791094 | n <= 0 = empty
@@ -1184,8 +1099,8 @@ takeEnd n t@(Text arr off len)
11841099iterNEnd :: Int -> Text -> Int
11851100iterNEnd n t@(Text _arr _off len) = loop (len-1) n
11861101 where loop i !m
1187− | m <= 0 = i+1
11881102 | i <= 0 = 0
1103+ | m <= 1 = i
11891104 | otherwise = loop (i+d) (m-1)
11901105 where d = reverseIter_ t i
11911106
@@ -1212,10 +1127,7 @@ drop n t@(Text arr off len)
12121127--
12131128-- Examples:
12141129--
1215−-- >>> dropEnd 3 "foobar"
1216−-- "foo"
1217−--
1218−-- @since 1.1.1.0
1130+-- > dropEnd 3 "foobar" == "foo"
12191131dropEnd :: Int -> Text -> Text
12201132dropEnd n t@(Text arr off len)
12211133 | n <= 0 = t
@@ -1245,10 +1157,7 @@ takeWhile p t@(Text arr off len) = loop 0
12451157-- satisfy @p@. Subject to fusion.
12461158-- Examples:
12471159--
1248−-- >>> takeWhileEnd (=='o') "foo"
1249−-- "oo"
1250−--
1251−-- @since 1.2.2.0
1160+-- > takeWhileEnd (=='o') "foo" == "oo"
12521161takeWhileEnd :: (Char -> Bool) -> Text -> Text
12531162takeWhileEnd p t@(Text arr off len) = loop (len-1) len
12541163 where loop !i !l | l <= 0 = t
@@ -1287,8 +1196,7 @@ dropWhile p t@(Text arr off len) = loop 0 0
12871196--
12881197-- Examples:
12891198--
1290−-- >>> dropWhileEnd (=='.') "foo..."
1291−-- "foo"
1199+-- > dropWhileEnd (=='.') "foo..." == "foo"
12921200dropWhileEnd :: (Char -> Bool) -> Text -> Text
12931201dropWhileEnd p t@(Text arr off len) = loop (len-1) len
12941202 where loop !i !l | l <= 0 = empty
@@ -1406,14 +1314,9 @@ tails t | null t = [empty]
14061314--
14071315-- Examples:
14081316--
1409−-- >>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"
1410−-- ["a","b","d","e"]
1411−--
1412−-- >>> splitOn "aaa" "aaaXaaaXaaaXaaa"
1413−-- ["","X","X","X",""]
1414−--
1415−-- >>> splitOn "x" "x"
1416−-- ["",""]
1317+-- > splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
1318+-- > splitOn "aaa" "aaaXaaaXaaaXaaa" == ["","X","X","X",""]
1319+-- > splitOn "x" "x" == ["",""]
14171320--
14181321-- and
14191322--
@@ -1449,11 +1352,8 @@ splitOn pat@(Text _ _ l) src@(Text arr off len)
14491352-- resulting components do not contain the separators. Two adjacent
14501353-- separators result in an empty component in the output. eg.
14511354--
1452−-- >>> split (=='a') "aabbaca"
1453−-- ["","","bb","c",""]
1454−--
1455−-- >>> split (=='a') ""
1456−-- [""]
1355+-- > split (=='a') "aabbaca" == ["","","bb","c",""]
1356+-- > split (=='a') "" == [""]
14571357split :: (Char -> Bool) -> Text -> [Text]
14581358split _ t@(Text _off _arr 0) = [t]
14591359split p t = loop t
@@ -1466,11 +1366,8 @@ split p t = loop t
14661366-- element may be shorter than the other chunks, depending on the
14671367-- length of the input. Examples:
14681368--
1469−-- >>> chunksOf 3 "foobarbaz"
1470−-- ["foo","bar","baz"]
1471−--
1472−-- >>> chunksOf 4 "haskell.org"
1473−-- ["hask","ell.","org"]
1369+-- > chunksOf 3 "foobarbaz" == ["foo","bar","baz"]
1370+-- > chunksOf 4 "haskell.org" == ["hask","ell.","org"]
14741371chunksOf :: Int -> Text -> [Text]
14751372chunksOf k = go
14761373 where
@@ -1515,11 +1412,8 @@ filter p t = unstream (S.filter p (stream t))
15151412--
15161413-- Examples:
15171414--
1518−-- >>> breakOn "::" "a::b::c"
1519−-- ("a","::b::c")
1520−--
1521−-- >>> breakOn "/" "foobar"
1522−-- ("foobar","")
1415+-- > breakOn "::" "a::b::c" ==> ("a", "::b::c")
1416+-- > breakOn "/" "foobar" ==> ("foobar", "")
15231417--
15241418-- Laws:
15251419--
@@ -1547,8 +1441,7 @@ breakOn pat src@(Text arr off len)
15471441-- up to and including the last match of @needle@. The second is the
15481442-- remainder of @haystack@, following the match.
15491443--
1550−-- >>> breakOnEnd "::" "a::b::c"
1551−-- ("a::b::","c")
1444+-- > breakOnEnd "::" "a::b::c" ==> ("a::b::", "c")
15521445breakOnEnd :: Text -> Text -> (Text, Text)
15531446breakOnEnd pat src = (reverse b, reverse a)
15541447 where (a,b) = breakOn (reverse pat) (reverse src)
@@ -1563,11 +1456,10 @@ breakOnEnd pat src = (reverse b, reverse a)
15631456--
15641457-- Examples:
15651458--
1566−-- >>> breakOnAll "::" ""
1567−-- []
1568−--
1569−-- >>> breakOnAll "/" "a/b/c/"
1570−-- [("a","/b/c/"),("a/b","/c/"),("a/b/c","/")]
1459+-- > breakOnAll "::" ""
1460+-- > ==> []
1461+-- > breakOnAll "/" "a/b/c/"
1462+-- > ==> [("a", "/b/c/"), ("a/b", "/c/"), ("a/b/c", "/")]
15711463--
15721464-- In (unlikely) bad cases, this function's time complexity degrades
15731465-- towards /O(n*m)/.
@@ -1766,14 +1658,9 @@ isInfixOf needle haystack
17661658--
17671659-- Examples:
17681660--
1769−-- >>> stripPrefix "foo" "foobar"
1770−-- Just "bar"
1771−--
1772−-- >>> stripPrefix "" "baz"
1773−-- Just "baz"
1774−--
1775−-- >>> stripPrefix "foo" "quux"
1776−-- Nothing
1661+-- > stripPrefix "foo" "foobar" == Just "bar"
1662+-- > stripPrefix "" "baz" == Just "baz"
1663+-- > stripPrefix "foo" "quux" == Nothing
17771664--
17781665-- This is particularly useful with the @ViewPatterns@ extension to
17791666-- GHC, as follows:
@@ -1798,14 +1685,9 @@ stripPrefix p@(Text _arr _off plen) t@(Text arr off len)
17981685--
17991686-- Examples:
18001687--
1801−-- >>> commonPrefixes "foobar" "fooquux"
1802−-- Just ("foo","bar","quux")
1803−--
1804−-- >>> commonPrefixes "veeble" "fetzer"
1805−-- Nothing
1806−--
1807−-- >>> commonPrefixes "" "baz"
1808−-- Nothing
1688+-- > commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
1689+-- > commonPrefixes "veeble" "fetzer" == Nothing
1690+-- > commonPrefixes "" "baz" == Nothing
18091691commonPrefixes :: Text -> Text -> Maybe (Text,Text,Text)
18101692commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
18111693 where
@@ -1822,14 +1704,9 @@ commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
18221704--
18231705-- Examples:
18241706--
1825−-- >>> stripSuffix "bar" "foobar"
1826−-- Just "foo"
1827−--
1828−-- >>> stripSuffix "" "baz"
1829−-- Just "baz"
1830−--
1831−-- >>> stripSuffix "foo" "quux"
1832−-- Nothing
1707+-- > stripSuffix "bar" "foobar" == Just "foo"
1708+-- > stripSuffix "" "baz" == Just "baz"
1709+-- > stripSuffix "foo" "quux" == Nothing
18331710--
18341711-- This is particularly useful with the @ViewPatterns@ extension to
18351712-- GHC, as follows:
@@ -1876,12 +1753,3 @@ copy (Text arr off len) = Text (A.run go) 0 len
18761753 marr <- A.new len
18771754 A.copyI marr 0 arr off len
18781755 return marr
1879−
1880−
1881−-------------------------------------------------
1882−-- NOTE: the named chunk below used by doctest;
1883−-- verify the doctests via `doctest -fobject-code Data/Text.hs`
1884−
1885−-- $setup
1886−-- >>> :set -XOverloadedStrings
1887−-- >>> import qualified Data.Text as T