@@ -665,7 +665,9 @@ compareLength t n = S.compareLengthI (stream t) n
666-- Example:
666-- Example:
668+-- >>> let message = pack "I am not angry. Not at all."
669+-- >>> T.map (\c -> if c == '.' then '!' else c) message
668−-- > map (\c -> if c == '.' then '!' else c) $ pack "I am not angry. Not at all." ==> "I am not angry! Not at all!"
670+-- "I am not angry! Not at all!"
670-- Subject to fusion. Performs replacement on invalid scalar values.
672-- Subject to fusion. Performs replacement on invalid scalar values.
671map :: (Char -> Char) -> Text -> Text
673map :: (Char -> Char) -> Text -> Text
@@ -678,9 +680,8 @@ map f t = unstream (S.map (safe . f) (stream t))
679-- Example:
681-- Example:
681−-- > let ni = pack "NI!"
682−-- > let sentence = fmap pack ["We", "seek", "the", "Holy", "Grail"]
683+-- >>> T.intercalate "NI!" ["We", "seek", "the", "Holy", "Grail"]
683−-- > intercalate ni sentence ==> ""WeNI!seekNI!theNI!HolyNI!Grail""
684+-- "WeNI!seekNI!theNI!HolyNI!Grail"
684intercalate :: Text -> [Text] -> Text
685intercalate :: Text -> [Text] -> Text
685intercalate t = concat . (F.intersperse t)
686intercalate t = concat . (F.intersperse t)
686{-# INLINE intercalate #-}
687{-# INLINE intercalate #-}
@@ -690,7 +691,8 @@ intercalate t = concat . (F.intersperse t)
691-- Example:
692-- Example:
693−-- > intersperse '.' $ pack "SHIELD" ==> "S.H.I.E.L.D"
694+-- >>> T.intersperse '.' "SHIELD"
695-- Subject to fusion. Performs replacement on invalid scalar values.
697-- Subject to fusion. Performs replacement on invalid scalar values.
696intersperse :: Char -> Text -> Text
698intersperse :: Char -> Text -> Text
@@ -701,7 +703,8 @@ intersperse c t = unstream (S.intersperse (safe c) (stream t))
702-- Example:
704-- Example:
704−-- > reverse $ pack "desrever" ==> "reversed"
706+-- >>> T.reverse "desrever"
706-- Subject to fusion.
709-- Subject to fusion.
707reverse :: Text -> Text
710reverse :: Text -> Text
@@ -722,12 +725,14 @@ reverse t = S.reverse (stream t)
722-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
725-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
723-- be replaced recursively:
726-- be replaced recursively:
725−-- > replace "oo" "foo" "oo" == "foo"
728+-- >>> replace "oo" "foo" "oo"
727-- In cases where several instances of @needle@ overlap, only the
731-- In cases where several instances of @needle@ overlap, only the
728-- first one will be replaced:
732-- first one will be replaced:
730−-- > replace "ofo" "bar" "ofofo" == "barfo"
734+-- >>> replace "ofo" "bar" "ofofo"
732-- In (unlikely) bad cases, this function's time complexity degrades
737-- In (unlikely) bad cases, this function's time complexity degrades
733-- towards /O(n*m)/.
738-- towards /O(n*m)/.
@@ -853,8 +858,11 @@ toTitle t = unstream (S.toTitle (stream t))
854-- Examples:
859-- Examples:
856−-- > justifyLeft 7 'x' "foo" == "fooxxxx"
861+-- >>> justifyLeft 7 'x' "foo"
857−-- > justifyLeft 3 'x' "foobar" == "foobar"
864+-- >>> justifyLeft 3 'x' "foobar"
858justifyLeft :: Int -> Char -> Text -> Text
866justifyLeft :: Int -> Char -> Text -> Text
859justifyLeft k c t
867justifyLeft k c t
860 | len >= k = t
868 | len >= k = t
@@ -875,8 +883,11 @@ justifyLeft k c t
876-- Examples:
884-- Examples:
878−-- > justifyRight 7 'x' "bar" == "xxxxbar"
886+-- >>> justifyRight 7 'x' "bar"
879−-- > justifyRight 3 'x' "foobar" == "foobar"
889+-- >>> justifyRight 3 'x' "foobar"
880justifyRight :: Int -> Char -> Text -> Text
891justifyRight :: Int -> Char -> Text -> Text
881justifyRight k c t
892justifyRight k c t
882 | len >= k = t
893 | len >= k = t
@@ -890,7 +901,8 @@ justifyRight k c t
891-- Examples:
902-- Examples:
893−-- > center 8 'x' "HS" = "xxxHSxxx"
904+-- >>> center 8 'x' "HS"
894center :: Int -> Char -> Text -> Text
906center :: Int -> Char -> Text -> Text
895center k c t
907center k c t
896 | len >= k = t
908 | len >= k = t
@@ -908,8 +920,11 @@ center k c t
909-- Examples:
921-- Examples:
911−-- > transpose [pack "green", pack "orange"] ==> ["go","rr","ea","en","ng","e"]
923+-- >>> transpose ["green","orange"]
924+-- ["go","rr","ea","en","ng","e"]
912−-- > transpose [pack "blue", pack "red"] ==> ["br","le","ud","e"]
926+-- >>> transpose ["blue","red"]
927+-- ["br","le","ud","e"]
913transpose :: [Text] -> [Text]
928transpose :: [Text] -> [Text]
914transpose ts = P.map pack (L.transpose (P.map unpack ts))
929transpose ts = P.map pack (L.transpose (P.map unpack ts))
@@ -1154,7 +1169,8 @@ iterN n t@(Text _arr _off len) = loop 0 0
1155-- Examples:
1170-- Examples:
1157−-- > takeEnd 3 "foobar" == "bar"
1172+-- >>> takeEnd 3 "foobar"
1159-- @since 1.1.1.0
1175-- @since 1.1.1.0
1160takeEnd :: Int -> Text -> Text
1176takeEnd :: Int -> Text -> Text
@@ -1195,7 +1211,8 @@ drop n t@(Text arr off len)
1196-- Examples:
1212-- Examples:
1198−-- > dropEnd 3 "foobar" == "foo"
1214+-- >>> dropEnd 3 "foobar"
1200-- @since 1.1.1.0
1217-- @since 1.1.1.0
1201dropEnd :: Int -> Text -> Text
1218dropEnd :: Int -> Text -> Text
@@ -1227,7 +1244,8 @@ takeWhile p t@(Text arr off len) = loop 0
1227-- satisfy @p@. Subject to fusion.
1244-- satisfy @p@. Subject to fusion.
1228-- Examples:
1245-- Examples:
1230−-- > takeWhileEnd (=='o') "foo" == "oo"
1247+-- >>> takeWhileEnd (=='o') "foo"
1232-- @since 1.2.2.0
1250-- @since 1.2.2.0
1233takeWhileEnd :: (Char -> Bool) -> Text -> Text
1251takeWhileEnd :: (Char -> Bool) -> Text -> Text
@@ -1268,7 +1286,8 @@ dropWhile p t@(Text arr off len) = loop 0 0
1269-- Examples:
1287-- Examples:
1271−-- > dropWhileEnd (=='.') "foo..." == "foo"
1289+-- >>> dropWhileEnd (=='.') "foo..."
1272dropWhileEnd :: (Char -> Bool) -> Text -> Text
1291dropWhileEnd :: (Char -> Bool) -> Text -> Text
1273dropWhileEnd p t@(Text arr off len) = loop (len-1) len
1292dropWhileEnd p t@(Text arr off len) = loop (len-1) len
1274 where loop !i !l | l <= 0 = empty
1293 where loop !i !l | l <= 0 = empty
@@ -1386,9 +1405,14 @@ tails t | null t = [empty]
1387-- Examples:
1406-- Examples:
1389−-- > 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"]
1390−-- > splitOn "aaa" "aaaXaaaXaaaXaaa" == ["","X","X","X",""]
1411+-- >>> splitOn "aaa" "aaaXaaaXaaaXaaa"
1412+-- ["","X","X","X",""]
1391−-- > splitOn "x" "x" == ["",""]
1414+-- >>> splitOn "x" "x"
@@ -1424,8 +1448,11 @@ splitOn pat@(Text _ _ l) src@(Text arr off len)
1424-- resulting components do not contain the separators. Two adjacent
1448-- resulting components do not contain the separators. Two adjacent
1425-- separators result in an empty component in the output. eg.
1449-- separators result in an empty component in the output. eg.
1427−-- > split (=='a') "aabbaca" == ["","","bb","c",""]
1451+-- >>> split (=='a') "aabbaca"
1452+-- ["","","bb","c",""]
1428−-- > split (=='a') "" == [""]
1454+-- >>> split (=='a') ""
1429split :: (Char -> Bool) -> Text -> [Text]
1456split :: (Char -> Bool) -> Text -> [Text]
1430split _ t@(Text _off _arr 0) = [t]
1457split _ t@(Text _off _arr 0) = [t]
1431split p t = loop t
1458split p t = loop t
@@ -1438,8 +1465,11 @@ split p t = loop t
1438-- element may be shorter than the other chunks, depending on the
1465-- element may be shorter than the other chunks, depending on the
1439-- length of the input. Examples:
1466-- length of the input. Examples:
1441−-- > chunksOf 3 "foobarbaz" == ["foo","bar","baz"]
1468+-- >>> chunksOf 3 "foobarbaz"
1469+-- ["foo","bar","baz"]
1442−-- > chunksOf 4 "haskell.org" == ["hask","ell.","org"]
1471+-- >>> chunksOf 4 "haskell.org"
1472+-- ["hask","ell.","org"]
1443chunksOf :: Int -> Text -> [Text]
1473chunksOf :: Int -> Text -> [Text]
1444chunksOf k = go
1474chunksOf k = go
@@ -1484,8 +1514,11 @@ filter p t = unstream (S.filter p (stream t))
1485-- Examples:
1515-- Examples:
1487−-- > breakOn "::" "a::b::c" ==> ("a", "::b::c")
1517+-- >>> breakOn "::" "a::b::c"
1488−-- > breakOn "/" "foobar" ==> ("foobar", "")
1520+-- >>> breakOn "/" "foobar"
@@ -1513,7 +1546,8 @@ breakOn pat src@(Text arr off len)
1513-- 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
1514-- remainder of @haystack@, following the match.
1547-- remainder of @haystack@, following the match.
1516−-- > breakOnEnd "::" "a::b::c" ==> ("a::b::", "c")
1549+-- >>> breakOnEnd "::" "a::b::c"
1517breakOnEnd :: Text -> Text -> (Text, Text)
1551breakOnEnd :: Text -> Text -> (Text, Text)
1518breakOnEnd pat src = (reverse b, reverse a)
1552breakOnEnd pat src = (reverse b, reverse a)
1519 where (a,b) = breakOn (reverse pat) (reverse src)
1553 where (a,b) = breakOn (reverse pat) (reverse src)
@@ -1528,10 +1562,11 @@ breakOnEnd pat src = (reverse b, reverse a)
1529-- Examples:
1563-- Examples:
1531−-- > breakOnAll "::" ""
1565+-- >>> breakOnAll "::" ""
1532−-- > ==> []
1566+-- []
1533−-- > breakOnAll "/" "a/b/c/"
1568+-- >>> breakOnAll "/" "a/b/c/"
1534−-- > ==> [("a", "/b/c/"), ("a/b", "/c/"), ("a/b/c", "/")]
1569+-- [("a","/b/c/"),("a/b","/c/"),("a/b/c","/")]
1536-- In (unlikely) bad cases, this function's time complexity degrades
1571-- In (unlikely) bad cases, this function's time complexity degrades
1537-- towards /O(n*m)/.
1572-- towards /O(n*m)/.
@@ -1730,9 +1765,14 @@ isInfixOf needle haystack
1731-- Examples:
1766-- Examples:
1733−-- > stripPrefix "foo" "foobar" == Just "bar"
1768+-- >>> stripPrefix "foo" "foobar"
1734−-- > stripPrefix "" "baz" == Just "baz"
1771+-- >>> stripPrefix "" "baz"
1735−-- > stripPrefix "foo" "quux" == Nothing
1774+-- >>> stripPrefix "foo" "quux"
1737-- This is particularly useful with the @ViewPatterns@ extension to
1777-- This is particularly useful with the @ViewPatterns@ extension to
1738-- GHC, as follows:
1778-- GHC, as follows:
@@ -1757,9 +1797,14 @@ stripPrefix p@(Text _arr _off plen) t@(Text arr off len)
1758-- Examples:
1798-- Examples:
1760−-- > commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
1800+-- >>> commonPrefixes "foobar" "fooquux"
1801+-- Just ("foo","bar","quux")
1761−-- > commonPrefixes "veeble" "fetzer" == Nothing
1803+-- >>> commonPrefixes "veeble" "fetzer"
1762−-- > commonPrefixes "" "baz" == Nothing
1806+-- >>> commonPrefixes "" "baz"
1763commonPrefixes :: Text -> Text -> Maybe (Text,Text,Text)
1808commonPrefixes :: Text -> Text -> Maybe (Text,Text,Text)
1764commonPrefixes 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
@@ -1776,9 +1821,14 @@ commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
1777-- Examples:
1822-- Examples:
1779−-- > stripSuffix "bar" "foobar" == Just "foo"
1824+-- >>> stripSuffix "bar" "foobar"
1780−-- > stripSuffix "" "baz" == Just "baz"
1827+-- >>> stripSuffix "" "baz"
1781−-- > stripSuffix "foo" "quux" == Nothing
1830+-- >>> stripSuffix "foo" "quux"
1783-- This is particularly useful with the @ViewPatterns@ extension to
1833-- This is particularly useful with the @ViewPatterns@ extension to
1784-- GHC, as follows:
1834-- GHC, as follows:
@@ -1825,3 +1875,12 @@ copy (Text arr off len) = Text (A.run go) 0 len
1825 marr <- A.new len
1875 marr <- A.new len
1826 A.copyI marr 0 arr off len
1876 A.copyI marr 0 arr off len
1827 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