@@ -34,6 +34,7 @@
34-- with Unicode text (including normalization, regular expressions,
34-- with Unicode text (including normalization, regular expressions,
35-- non-standard encodings, text breaking, and locales), see
35-- non-standard encodings, text breaking, and locales), see
36-- <http://hackage.haskell.org/package/text-icu the text-icu package >.
36-- <http://hackage.haskell.org/package/text-icu the text-icu package >.
38module Data.Text
39module Data.Text
@@ -43,6 +44,9 @@ module Data.Text
43 -- * Acceptable data
44 -- * Acceptable data
44 -- $replacement
45 -- $replacement
47+ -- * Definition of character
48+ -- $character_definition
46 -- * Fusion
50 -- * Fusion
47 -- $fusion
51 -- $fusion
@@ -60,6 +64,7 @@ module Data.Text
@@ -246,6 +251,17 @@ import qualified GHC.Exts as Exts
246import Text.Printf (PrintfArg, formatArg, formatString)
251import Text.Printf (PrintfArg, formatArg, formatString)
254+-- $character-definition
256+-- This package uses the word /character/ to denote Unicode code points.
258+-- Note that this is not the same thing as a grapheme (e.g. a composition of
259+-- code points that form one visual symbol). For instance, consider the grapheme
260+-- @ä@. This symbol has two Unicode representations: a single code-point
261+-- representation @U+00E4@ (the @LATIN SMALL LETTER A WITH DIAERESIS@ code
262+-- point), and a two code point representation @U+0061@ (the @A@ code point) and
263+-- @U+0308@ (the @COMBINING DIAERESIS@ code point).
249-- $strict
265-- $strict
251-- This package provides both strict and lazy 'Text' types. The
267-- This package provides both strict and lazy 'Text' types. The
@@ -334,9 +350,13 @@ instance Read Text where
334 readsPrec p str = [(pack x,y) | (x,y) <- readsPrec p str]
350 readsPrec p str = [(pack x,y) | (x,y) <- readsPrec p str]
336#if MIN_VERSION_base(4,9,0)
352#if MIN_VERSION_base(4,9,0)
353+-- | Non-orphan 'Semigroup' instance only defined for
337−-- Semigroup orphan instances for older GHCs are provided by
354+-- @base-4.9.0.0@ and later; orphan instances for older GHCs are
356+-- the [semigroups](http://hackage.haskell.org/package/semigroups)
338−-- 'semigroups` package
357+-- package
340instance Semigroup Text where
360instance Semigroup Text where
341 (<>) = append
361 (<>) = append
@@ -354,6 +374,7 @@ instance IsString Text where
354 fromString = pack
374 fromString = pack
356#if __GLASGOW_HASKELL__ >= 708
376#if __GLASGOW_HASKELL__ >= 708
357instance Exts.IsList Text where
378instance Exts.IsList Text where
358 type Item Text = Char
379 type Item Text = Char
359 fromList = pack
380 fromList = pack
@@ -364,6 +385,7 @@ instance Exts.IsList Text where
364instance NFData Text where rnf !_ = ()
385instance NFData Text where rnf !_ = ()
367instance Binary Text where
389instance Binary Text where
368 put t = put (encodeUtf8 t)
390 put t = put (encodeUtf8 t)
@@ -397,6 +419,8 @@ instance Data Text where
398#if MIN_VERSION_base(4,7,0)
420#if MIN_VERSION_base(4,7,0)
399-- | Only defined for @base-4.7.0.0@ and later
421-- | Only defined for @base-4.7.0.0@ and later
400instance PrintfArg Text where
424instance PrintfArg Text where
401 formatArg txt = formatString $ unpack txt
425 formatArg txt = formatString $ unpack txt
@@ -545,6 +569,19 @@ init (Text arr off len) | len <= 0 = emptyError "init"
545 unstream (S.init (stream t)) = init t
569 unstream (S.init (stream t)) = init t
572+-- | /O(1)/ Returns all but the last character and the last character of a
573+-- 'Text', or 'Nothing' if empty.
576+unsnoc :: Text -> Maybe (Text, Char)
577+unsnoc (Text arr off len)
578+ | len <= 0 = Nothing
579+ | n < 0xDC00 || n > 0xDFFF = Just (text arr off (len-1), unsafeChr n)
580+ | otherwise = Just (text arr off (len-2), U16.chr2 n0 n)
581+ where n = A.unsafeIndex arr (off+len-1)
582+ n0 = A.unsafeIndex arr (off+len-2)
583+{-# INLINE [1] unsnoc #-}
548-- | /O(1)/ Tests whether a 'Text' is empty or not. Subject to
585-- | /O(1)/ Tests whether a 'Text' is empty or not. Subject to
549-- fusion.
586-- fusion.
550null :: Text -> Bool
587null :: Text -> Bool
@@ -624,8 +661,15 @@ compareLength t n = S.compareLengthI (stream t) n
624-- -----------------------------------------------------------------------------
661-- -----------------------------------------------------------------------------
625-- * Transformations
662-- * Transformations
626-- | /O(n)/ 'map' @f@ @t@ is the 'Text' obtained by applying @f@ to
663-- | /O(n)/ 'map' @f@ @t@ is the 'Text' obtained by applying @f@ to
664+-- each element of @t@.
668+-- >>> let message = pack "I am not angry. Not at all."
669+-- >>> T.map (\c -> if c == '.' then '!' else c) message
670+-- "I am not angry! Not at all!"
627−-- each element of @t@. Subject to fusion. Performs replacement on
672+-- Subject to fusion. Performs replacement on invalid scalar values.
628−-- invalid scalar values.
629map :: (Char -> Char) -> Text -> Text
673map :: (Char -> Char) -> Text -> Text
630map f t = unstream (S.map (safe . f) (stream t))
674map f t = unstream (S.map (safe . f) (stream t))
631{-# INLINE [1] map #-}
675{-# INLINE [1] map #-}
@@ -633,18 +677,36 @@ map f t = unstream (S.map (safe . f) (stream t))
633-- | /O(n)/ The 'intercalate' function takes a 'Text' and a list of
677-- | /O(n)/ The 'intercalate' function takes a 'Text' and a list of
634-- 'Text's and concatenates the list after interspersing the first
678-- 'Text's and concatenates the list after interspersing the first
635-- argument between each element of the list.
679-- argument between each element of the list.
683+-- >>> T.intercalate "NI!" ["We", "seek", "the", "Holy", "Grail"]
684+-- "WeNI!seekNI!theNI!HolyNI!Grail"
636intercalate :: Text -> [Text] -> Text
685intercalate :: Text -> [Text] -> Text
637intercalate t = concat . (F.intersperse t)
686intercalate t = concat . (F.intersperse t)
638{-# INLINE intercalate #-}
687{-# INLINE intercalate #-}
640-- | /O(n)/ The 'intersperse' function takes a character and places it
689-- | /O(n)/ The 'intersperse' function takes a character and places it
641−-- between the characters of a 'Text'. Subject to fusion. Performs
690+-- between the characters of a 'Text'.
694+-- >>> T.intersperse '.' "SHIELD"
642−-- replacement on invalid scalar values.
697+-- Subject to fusion. Performs replacement on invalid scalar values.
643intersperse :: Char -> Text -> Text
698intersperse :: Char -> Text -> Text
644intersperse c t = unstream (S.intersperse (safe c) (stream t))
699intersperse c t = unstream (S.intersperse (safe c) (stream t))
645{-# INLINE intersperse #-}
700{-# INLINE intersperse #-}
647−-- | /O(n)/ Reverse the characters of a string. Subject to fusion.
702+-- | /O(n)/ Reverse the characters of a string.
706+-- >>> T.reverse "desrever"
709+-- Subject to fusion.
648reverse :: Text -> Text
710reverse :: Text -> Text
649reverse t = S.reverse (stream t)
711reverse t = S.reverse (stream t)
650{-# INLINE reverse #-}
712{-# INLINE reverse #-}
@@ -663,12 +725,14 @@ reverse t = S.reverse (stream t)
663-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
725-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
664-- be replaced recursively:
726-- be replaced recursively:
666−-- > replace "oo" "foo" "oo" == "foo"
728+-- >>> replace "oo" "foo" "oo"
668-- In cases where several instances of @needle@ overlap, only the
731-- In cases where several instances of @needle@ overlap, only the
669-- first one will be replaced:
732-- first one will be replaced:
671−-- > replace "ofo" "bar" "ofofo" == "barfo"
734+-- >>> replace "ofo" "bar" "ofofo"
673-- In (unlikely) bad cases, this function's time complexity degrades
737-- In (unlikely) bad cases, this function's time complexity degrades
674-- towards /O(n*m)/.
738-- towards /O(n*m)/.
@@ -782,6 +846,8 @@ toUpper t = unstream (S.toUpper (stream t))
782-- guides disagree on whether the book name \"The Hill of the Red
846-- guides disagree on whether the book name \"The Hill of the Red
783-- Fox\" is correctly title cased—but this function will
847-- Fox\" is correctly title cased—but this function will
784-- capitalize /every/ word.
848-- capitalize /every/ word.
785toTitle :: Text -> Text
851toTitle :: Text -> Text
786toTitle t = unstream (S.toTitle (stream t))
852toTitle t = unstream (S.toTitle (stream t))
787{-# INLINE toTitle #-}
853{-# INLINE toTitle #-}
@@ -792,8 +858,11 @@ toTitle t = unstream (S.toTitle (stream t))
793-- Examples:
859-- Examples:
795−-- > justifyLeft 7 'x' "foo" == "fooxxxx"
861+-- >>> justifyLeft 7 'x' "foo"
796−-- > justifyLeft 3 'x' "foobar" == "foobar"
864+-- >>> justifyLeft 3 'x' "foobar"
797justifyLeft :: Int -> Char -> Text -> Text
866justifyLeft :: Int -> Char -> Text -> Text
798justifyLeft k c t
867justifyLeft k c t
799 | len >= k = t
868 | len >= k = t
@@ -814,8 +883,11 @@ justifyLeft k c t
815-- Examples:
884-- Examples:
817−-- > justifyRight 7 'x' "bar" == "xxxxbar"
886+-- >>> justifyRight 7 'x' "bar"
818−-- > justifyRight 3 'x' "foobar" == "foobar"
889+-- >>> justifyRight 3 'x' "foobar"
819justifyRight :: Int -> Char -> Text -> Text
891justifyRight :: Int -> Char -> Text -> Text
820justifyRight k c t
892justifyRight k c t
821 | len >= k = t
893 | len >= k = t
@@ -829,7 +901,8 @@ justifyRight k c t
830-- Examples:
902-- Examples:
832−-- > center 8 'x' "HS" = "xxxHSxxx"
904+-- >>> center 8 'x' "HS"
833center :: Int -> Char -> Text -> Text
906center :: Int -> Char -> Text -> Text
834center k c t
907center k c t
835 | len >= k = t
908 | len >= k = t
@@ -844,6 +917,14 @@ center k c t
844-- of its 'Text' argument. Note that this function uses 'pack',
917-- of its 'Text' argument. Note that this function uses 'pack',
845-- 'unpack', and the list version of transpose, and is thus not very
918-- 'unpack', and the list version of transpose, and is thus not very
846-- efficient.
919-- efficient.
923+-- >>> transpose ["green","orange"]
924+-- ["go","rr","ea","en","ng","e"]
926+-- >>> transpose ["blue","red"]
927+-- ["br","le","ud","e"]
847transpose :: [Text] -> [Text]
928transpose :: [Text] -> [Text]
848transpose ts = P.map pack (L.transpose (P.map unpack ts))
929transpose ts = P.map pack (L.transpose (P.map unpack ts))
@@ -1088,7 +1169,10 @@ iterN n t@(Text _arr _off len) = loop 0 0
1089-- Examples:
1170-- Examples:
1091−-- > takeEnd 3 "foobar" == "bar"
1172+-- >>> takeEnd 3 "foobar"
1092takeEnd :: Int -> Text -> Text
1176takeEnd :: Int -> Text -> Text
1093takeEnd n t@(Text arr off len)
1177takeEnd n t@(Text arr off len)
1094 | n <= 0 = empty
1178 | n <= 0 = empty
@@ -1099,8 +1183,8 @@ takeEnd n t@(Text arr off len)
1099iterNEnd :: Int -> Text -> Int
1183iterNEnd :: Int -> Text -> Int
1100iterNEnd n t@(Text _arr _off len) = loop (len-1) n
1184iterNEnd n t@(Text _arr _off len) = loop (len-1) n
1101 where loop i !m
1185 where loop i !m
1102 | i <= 0 = 0
1187 | i <= 0 = 0
1104 | otherwise = loop (i+d) (m-1)
1188 | otherwise = loop (i+d) (m-1)
1105 where d = reverseIter_ t i
1189 where d = reverseIter_ t i
@@ -1127,7 +1211,10 @@ drop n t@(Text arr off len)
1128-- Examples:
1212-- Examples:
1130−-- > dropEnd 3 "foobar" == "foo"
1214+-- >>> dropEnd 3 "foobar"
1131dropEnd :: Int -> Text -> Text
1218dropEnd :: Int -> Text -> Text
1132dropEnd n t@(Text arr off len)
1219dropEnd n t@(Text arr off len)
1133 | n <= 0 = t
1220 | n <= 0 = t
@@ -1157,7 +1244,10 @@ takeWhile p t@(Text arr off len) = loop 0
1157-- satisfy @p@. Subject to fusion.
1244-- satisfy @p@. Subject to fusion.
1158-- Examples:
1245-- Examples:
1160−-- > takeWhileEnd (=='o') "foo" == "oo"
1247+-- >>> takeWhileEnd (=='o') "foo"
1161takeWhileEnd :: (Char -> Bool) -> Text -> Text
1251takeWhileEnd :: (Char -> Bool) -> Text -> Text
1162takeWhileEnd p t@(Text arr off len) = loop (len-1) len
1252takeWhileEnd p t@(Text arr off len) = loop (len-1) len
1163 where loop !i !l | l <= 0 = t
1253 where loop !i !l | l <= 0 = t
@@ -1196,7 +1286,8 @@ dropWhile p t@(Text arr off len) = loop 0 0
1197-- Examples:
1287-- Examples:
1199−-- > dropWhileEnd (=='.') "foo..." == "foo"
1289+-- >>> dropWhileEnd (=='.') "foo..."
1200dropWhileEnd :: (Char -> Bool) -> Text -> Text
1291dropWhileEnd :: (Char -> Bool) -> Text -> Text
1201dropWhileEnd p t@(Text arr off len) = loop (len-1) len
1292dropWhileEnd p t@(Text arr off len) = loop (len-1) len
1202 where loop !i !l | l <= 0 = empty
1293 where loop !i !l | l <= 0 = empty
@@ -1314,9 +1405,14 @@ tails t | null t = [empty]
1315-- Examples:
1406-- Examples:
1317−-- > splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
1408+-- >>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"
1409+-- ["a","b","d","e"]
1318−-- > splitOn "aaa" "aaaXaaaXaaaXaaa" == ["","X","X","X",""]
1411+-- >>> splitOn "aaa" "aaaXaaaXaaaXaaa"
1412+-- ["","X","X","X",""]
1319−-- > splitOn "x" "x" == ["",""]
1414+-- >>> splitOn "x" "x"
@@ -1352,8 +1448,11 @@ splitOn pat@(Text _ _ l) src@(Text arr off len)
1352-- resulting components do not contain the separators. Two adjacent
1448-- resulting components do not contain the separators. Two adjacent
1353-- separators result in an empty component in the output. eg.
1449-- separators result in an empty component in the output. eg.
1355−-- > split (=='a') "aabbaca" == ["","","bb","c",""]
1451+-- >>> split (=='a') "aabbaca"
1452+-- ["","","bb","c",""]
1356−-- > split (=='a') "" == [""]
1454+-- >>> split (=='a') ""
1357split :: (Char -> Bool) -> Text -> [Text]
1456split :: (Char -> Bool) -> Text -> [Text]
1358split _ t@(Text _off _arr 0) = [t]
1457split _ t@(Text _off _arr 0) = [t]
1359split p t = loop t
1458split p t = loop t
@@ -1366,8 +1465,11 @@ split p t = loop t
1366-- element may be shorter than the other chunks, depending on the
1465-- element may be shorter than the other chunks, depending on the
1367-- length of the input. Examples:
1466-- length of the input. Examples:
1369−-- > chunksOf 3 "foobarbaz" == ["foo","bar","baz"]
1468+-- >>> chunksOf 3 "foobarbaz"
1469+-- ["foo","bar","baz"]
1370−-- > chunksOf 4 "haskell.org" == ["hask","ell.","org"]
1471+-- >>> chunksOf 4 "haskell.org"
1472+-- ["hask","ell.","org"]
1371chunksOf :: Int -> Text -> [Text]
1473chunksOf :: Int -> Text -> [Text]
1372chunksOf k = go
1474chunksOf k = go
@@ -1412,8 +1514,11 @@ filter p t = unstream (S.filter p (stream t))
1413-- Examples:
1515-- Examples:
1415−-- > breakOn "::" "a::b::c" ==> ("a", "::b::c")
1517+-- >>> breakOn "::" "a::b::c"
1416−-- > breakOn "/" "foobar" ==> ("foobar", "")
1520+-- >>> breakOn "/" "foobar"
@@ -1441,7 +1546,8 @@ breakOn pat src@(Text arr off len)
1441-- up to and including the last match of @needle@. The second is the
1546-- up to and including the last match of @needle@. The second is the
1442-- remainder of @haystack@, following the match.
1547-- remainder of @haystack@, following the match.
1444−-- > breakOnEnd "::" "a::b::c" ==> ("a::b::", "c")
1549+-- >>> breakOnEnd "::" "a::b::c"
1445breakOnEnd :: Text -> Text -> (Text, Text)
1551breakOnEnd :: Text -> Text -> (Text, Text)
1446breakOnEnd pat src = (reverse b, reverse a)
1552breakOnEnd pat src = (reverse b, reverse a)
1447 where (a,b) = breakOn (reverse pat) (reverse src)
1553 where (a,b) = breakOn (reverse pat) (reverse src)
@@ -1456,10 +1562,11 @@ breakOnEnd pat src = (reverse b, reverse a)
1457-- Examples:
1563-- Examples:
1459−-- > breakOnAll "::" ""
1565+-- >>> breakOnAll "::" ""
1460−-- > ==> []
1566+-- []
1461−-- > breakOnAll "/" "a/b/c/"
1568+-- >>> breakOnAll "/" "a/b/c/"
1462−-- > ==> [("a", "/b/c/"), ("a/b", "/c/"), ("a/b/c", "/")]
1569+-- [("a","/b/c/"),("a/b","/c/"),("a/b/c","/")]
1464-- In (unlikely) bad cases, this function's time complexity degrades
1571-- In (unlikely) bad cases, this function's time complexity degrades
1465-- towards /O(n*m)/.
1572-- towards /O(n*m)/.
@@ -1658,9 +1765,14 @@ isInfixOf needle haystack
1659-- Examples:
1766-- Examples:
1661−-- > stripPrefix "foo" "foobar" == Just "bar"
1768+-- >>> stripPrefix "foo" "foobar"
1662−-- > stripPrefix "" "baz" == Just "baz"
1771+-- >>> stripPrefix "" "baz"
1663−-- > stripPrefix "foo" "quux" == Nothing
1774+-- >>> stripPrefix "foo" "quux"
1665-- This is particularly useful with the @ViewPatterns@ extension to
1777-- This is particularly useful with the @ViewPatterns@ extension to
1666-- GHC, as follows:
1778-- GHC, as follows:
@@ -1685,9 +1797,14 @@ stripPrefix p@(Text _arr _off plen) t@(Text arr off len)
1686-- Examples:
1798-- Examples:
1688−-- > commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
1800+-- >>> commonPrefixes "foobar" "fooquux"
1801+-- Just ("foo","bar","quux")
1689−-- > commonPrefixes "veeble" "fetzer" == Nothing
1803+-- >>> commonPrefixes "veeble" "fetzer"
1690−-- > commonPrefixes "" "baz" == Nothing
1806+-- >>> commonPrefixes "" "baz"
1691commonPrefixes :: Text -> Text -> Maybe (Text,Text,Text)
1808commonPrefixes :: Text -> Text -> Maybe (Text,Text,Text)
1692commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
1809commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
@@ -1704,9 +1821,14 @@ commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
1705-- Examples:
1822-- Examples:
1707−-- > stripSuffix "bar" "foobar" == Just "foo"
1824+-- >>> stripSuffix "bar" "foobar"
1708−-- > stripSuffix "" "baz" == Just "baz"
1827+-- >>> stripSuffix "" "baz"
1709−-- > stripSuffix "foo" "quux" == Nothing
1830+-- >>> stripSuffix "foo" "quux"
1711-- This is particularly useful with the @ViewPatterns@ extension to
1833-- This is particularly useful with the @ViewPatterns@ extension to
1712-- GHC, as follows:
1834-- GHC, as follows:
@@ -1753,3 +1875,12 @@ copy (Text arr off len) = Text (A.run go) 0 len
1753 marr <- A.new len
1875 marr <- A.new len
1754 A.copyI marr 0 arr off len
1876 A.copyI marr 0 arr off len
1755 return marr
1877 return marr
1880+-------------------------------------------------
1881+-- NOTE: the named chunk below used by doctest;
1882+-- verify the doctests via `doctest -fobject-code Data/Text.hs`
1885+-- >>> :set -XOverloadedStrings
1886+-- >>> import qualified Data.Text as T