@@ -665,7 +665,9 @@ compareLength t n = S.compareLengthI (stream t) n
665665--
666666-- Example:
667667--
668−-- > map (\c -> if c == '.' then '!' else c) $ pack "I am not angry. Not at all." ==> "I am not angry! Not at all!"
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!"
669671--
670672-- Subject to fusion. Performs replacement on invalid scalar values.
671673map :: (Char -> Char) -> Text -> Text
@@ -678,9 +680,8 @@ map f t = unstream (S.map (safe . f) (stream t))
678680--
679681-- Example:
680682--
681−-- > let ni = pack "NI!"
682−-- > let sentence = fmap pack ["We", "seek", "the", "Holy", "Grail"]
683−-- > intercalate ni sentence ==> ""WeNI!seekNI!theNI!HolyNI!Grail""
683+-- >>> T.intercalate "NI!" ["We", "seek", "the", "Holy", "Grail"]
684+-- "WeNI!seekNI!theNI!HolyNI!Grail"
684685intercalate :: Text -> [Text] -> Text
685686intercalate t = concat . (F.intersperse t)
686687{-# INLINE intercalate #-}
@@ -690,7 +691,8 @@ intercalate t = concat . (F.intersperse t)
690691--
691692-- Example:
692693--
693−-- > intersperse '.' $ pack "SHIELD" ==> "S.H.I.E.L.D"
694+-- >>> T.intersperse '.' "SHIELD"
695+-- "S.H.I.E.L.D"
694696--
695697-- Subject to fusion. Performs replacement on invalid scalar values.
696698intersperse :: Char -> Text -> Text
@@ -701,7 +703,8 @@ intersperse c t = unstream (S.intersperse (safe c) (stream t))
701703--
702704-- Example:
703705--
704−-- > reverse $ pack "desrever" ==> "reversed"
706+-- >>> T.reverse "desrever"
707+-- "reversed"
705708--
706709-- Subject to fusion.
707710reverse :: Text -> Text
@@ -722,12 +725,14 @@ reverse t = S.reverse (stream t)
722725-- @needle@ occurs in @replacement@, that occurrence will /not/ itself
723726-- be replaced recursively:
724727--
725−-- > replace "oo" "foo" "oo" == "foo"
728+-- >>> replace "oo" "foo" "oo"
729+-- "foo"
726730--
727731-- In cases where several instances of @needle@ overlap, only the
728732-- first one will be replaced:
729733--
730−-- > replace "ofo" "bar" "ofofo" == "barfo"
734+-- >>> replace "ofo" "bar" "ofofo"
735+-- "barfo"
731736--
732737-- In (unlikely) bad cases, this function's time complexity degrades
733738-- towards /O(n*m)/.
@@ -853,8 +858,11 @@ toTitle t = unstream (S.toTitle (stream t))
853858--
854859-- Examples:
855860--
856−-- > justifyLeft 7 'x' "foo" == "fooxxxx"
857−-- > justifyLeft 3 'x' "foobar" == "foobar"
861+-- >>> justifyLeft 7 'x' "foo"
862+-- "fooxxxx"
863+--
864+-- >>> justifyLeft 3 'x' "foobar"
865+-- "foobar"
858866justifyLeft :: Int -> Char -> Text -> Text
859867justifyLeft k c t
860868 | len >= k = t
@@ -875,8 +883,11 @@ justifyLeft k c t
875883--
876884-- Examples:
877885--
878−-- > justifyRight 7 'x' "bar" == "xxxxbar"
879−-- > justifyRight 3 'x' "foobar" == "foobar"
886+-- >>> justifyRight 7 'x' "bar"
887+-- "xxxxbar"
888+--
889+-- >>> justifyRight 3 'x' "foobar"
890+-- "foobar"
880891justifyRight :: Int -> Char -> Text -> Text
881892justifyRight k c t
882893 | len >= k = t
@@ -890,7 +901,8 @@ justifyRight k c t
890901--
891902-- Examples:
892903--
893−-- > center 8 'x' "HS" = "xxxHSxxx"
904+-- >>> center 8 'x' "HS"
905+-- "xxxHSxxx"
894906center :: Int -> Char -> Text -> Text
895907center k c t
896908 | len >= k = t
@@ -908,8 +920,11 @@ center k c t
908920--
909921-- Examples:
910922--
911−-- > transpose [pack "green", pack "orange"] ==> ["go","rr","ea","en","ng","e"]
912−-- > transpose [pack "blue", pack "red"] ==> ["br","le","ud","e"]
923+-- >>> transpose ["green","orange"]
924+-- ["go","rr","ea","en","ng","e"]
925+--
926+-- >>> transpose ["blue","red"]
927+-- ["br","le","ud","e"]
913928transpose :: [Text] -> [Text]
914929transpose ts = P.map pack (L.transpose (P.map unpack ts))
915930
@@ -1154,7 +1169,8 @@ iterN n t@(Text _arr _off len) = loop 0 0
11541169--
11551170-- Examples:
11561171--
1157−-- > takeEnd 3 "foobar" == "bar"
1172+-- >>> takeEnd 3 "foobar"
1173+-- "bar"
11581174--
11591175-- @since 1.1.1.0
11601176takeEnd :: Int -> Text -> Text
@@ -1195,7 +1211,8 @@ drop n t@(Text arr off len)
11951211--
11961212-- Examples:
11971213--
1198−-- > dropEnd 3 "foobar" == "foo"
1214+-- >>> dropEnd 3 "foobar"
1215+-- "foo"
11991216--
12001217-- @since 1.1.1.0
12011218dropEnd :: Int -> Text -> Text
@@ -1227,7 +1244,8 @@ takeWhile p t@(Text arr off len) = loop 0
12271244-- satisfy @p@. Subject to fusion.
12281245-- Examples:
12291246--
1230−-- > takeWhileEnd (=='o') "foo" == "oo"
1247+-- >>> takeWhileEnd (=='o') "foo"
1248+-- "oo"
12311249--
12321250-- @since 1.2.2.0
12331251takeWhileEnd :: (Char -> Bool) -> Text -> Text
@@ -1268,7 +1286,8 @@ dropWhile p t@(Text arr off len) = loop 0 0
12681286--
12691287-- Examples:
12701288--
1271−-- > dropWhileEnd (=='.') "foo..." == "foo"
1289+-- >>> dropWhileEnd (=='.') "foo..."
1290+-- "foo"
12721291dropWhileEnd :: (Char -> Bool) -> Text -> Text
12731292dropWhileEnd p t@(Text arr off len) = loop (len-1) len
12741293 where loop !i !l | l <= 0 = empty
@@ -1386,9 +1405,14 @@ tails t | null t = [empty]
13861405--
13871406-- Examples:
13881407--
1389−-- > splitOn "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
1390−-- > splitOn "aaa" "aaaXaaaXaaaXaaa" == ["","X","X","X",""]
1391−-- > splitOn "x" "x" == ["",""]
1408+-- >>> splitOn "\r\n" "a\r\nb\r\nd\r\ne"
1409+-- ["a","b","d","e"]
1410+--
1411+-- >>> splitOn "aaa" "aaaXaaaXaaaXaaa"
1412+-- ["","X","X","X",""]
1413+--
1414+-- >>> splitOn "x" "x"
1415+-- ["",""]
13921416--
13931417-- and
13941418--
@@ -1424,8 +1448,11 @@ splitOn pat@(Text _ _ l) src@(Text arr off len)
14241448-- resulting components do not contain the separators. Two adjacent
14251449-- separators result in an empty component in the output. eg.
14261450--
1427−-- > split (=='a') "aabbaca" == ["","","bb","c",""]
1428−-- > split (=='a') "" == [""]
1451+-- >>> split (=='a') "aabbaca"
1452+-- ["","","bb","c",""]
1453+--
1454+-- >>> split (=='a') ""
1455+-- [""]
14291456split :: (Char -> Bool) -> Text -> [Text]
14301457split _ t@(Text _off _arr 0) = [t]
14311458split p t = loop t
@@ -1438,8 +1465,11 @@ split p t = loop t
14381465-- element may be shorter than the other chunks, depending on the
14391466-- length of the input. Examples:
14401467--
1441−-- > chunksOf 3 "foobarbaz" == ["foo","bar","baz"]
1442−-- > chunksOf 4 "haskell.org" == ["hask","ell.","org"]
1468+-- >>> chunksOf 3 "foobarbaz"
1469+-- ["foo","bar","baz"]
1470+--
1471+-- >>> chunksOf 4 "haskell.org"
1472+-- ["hask","ell.","org"]
14431473chunksOf :: Int -> Text -> [Text]
14441474chunksOf k = go
14451475 where
@@ -1484,8 +1514,11 @@ filter p t = unstream (S.filter p (stream t))
14841514--
14851515-- Examples:
14861516--
1487−-- > breakOn "::" "a::b::c" ==> ("a", "::b::c")
1488−-- > breakOn "/" "foobar" ==> ("foobar", "")
1517+-- >>> breakOn "::" "a::b::c"
1518+-- ("a","::b::c")
1519+--
1520+-- >>> breakOn "/" "foobar"
1521+-- ("foobar","")
14891522--
14901523-- Laws:
14911524--
@@ -1513,7 +1546,8 @@ breakOn pat src@(Text arr off len)
15131546-- up to and including the last match of @needle@. The second is the
15141547-- remainder of @haystack@, following the match.
15151548--
1516−-- > breakOnEnd "::" "a::b::c" ==> ("a::b::", "c")
1549+-- >>> breakOnEnd "::" "a::b::c"
1550+-- ("a::b::","c")
15171551breakOnEnd :: Text -> Text -> (Text, Text)
15181552breakOnEnd pat src = (reverse b, reverse a)
15191553 where (a,b) = breakOn (reverse pat) (reverse src)
@@ -1528,10 +1562,11 @@ breakOnEnd pat src = (reverse b, reverse a)
15281562--
15291563-- Examples:
15301564--
1531−-- > breakOnAll "::" ""
1532−-- > ==> []
1533−-- > breakOnAll "/" "a/b/c/"
1534−-- > ==> [("a", "/b/c/"), ("a/b", "/c/"), ("a/b/c", "/")]
1565+-- >>> breakOnAll "::" ""
1566+-- []
1567+--
1568+-- >>> breakOnAll "/" "a/b/c/"
1569+-- [("a","/b/c/"),("a/b","/c/"),("a/b/c","/")]
15351570--
15361571-- In (unlikely) bad cases, this function's time complexity degrades
15371572-- towards /O(n*m)/.
@@ -1730,9 +1765,14 @@ isInfixOf needle haystack
17301765--
17311766-- Examples:
17321767--
1733−-- > stripPrefix "foo" "foobar" == Just "bar"
1734−-- > stripPrefix "" "baz" == Just "baz"
1735−-- > stripPrefix "foo" "quux" == Nothing
1768+-- >>> stripPrefix "foo" "foobar"
1769+-- Just "bar"
1770+--
1771+-- >>> stripPrefix "" "baz"
1772+-- Just "baz"
1773+--
1774+-- >>> stripPrefix "foo" "quux"
1775+-- Nothing
17361776--
17371777-- This is particularly useful with the @ViewPatterns@ extension to
17381778-- GHC, as follows:
@@ -1757,9 +1797,14 @@ stripPrefix p@(Text _arr _off plen) t@(Text arr off len)
17571797--
17581798-- Examples:
17591799--
1760−-- > commonPrefixes "foobar" "fooquux" == Just ("foo","bar","quux")
1761−-- > commonPrefixes "veeble" "fetzer" == Nothing
1762−-- > commonPrefixes "" "baz" == Nothing
1800+-- >>> commonPrefixes "foobar" "fooquux"
1801+-- Just ("foo","bar","quux")
1802+--
1803+-- >>> commonPrefixes "veeble" "fetzer"
1804+-- Nothing
1805+--
1806+-- >>> commonPrefixes "" "baz"
1807+-- Nothing
17631808commonPrefixes :: Text -> Text -> Maybe (Text,Text,Text)
17641809commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
17651810 where
@@ -1776,9 +1821,14 @@ commonPrefixes t0@(Text arr0 off0 len0) t1@(Text arr1 off1 len1) = go 0 0
17761821--
17771822-- Examples:
17781823--
1779−-- > stripSuffix "bar" "foobar" == Just "foo"
1780−-- > stripSuffix "" "baz" == Just "baz"
1781−-- > stripSuffix "foo" "quux" == Nothing
1824+-- >>> stripSuffix "bar" "foobar"
1825+-- Just "foo"
1826+--
1827+-- >>> stripSuffix "" "baz"
1828+-- Just "baz"
1829+--
1830+-- >>> stripSuffix "foo" "quux"
1831+-- Nothing
17821832--
17831833-- This is particularly useful with the @ViewPatterns@ extension to
17841834-- GHC, as follows:
@@ -1825,3 +1875,12 @@ copy (Text arr off len) = Text (A.run go) 0 len
18251875 marr <- A.new len
18261876 A.copyI marr 0 arr off len
18271877 return marr
1878+
1879+
1880+-------------------------------------------------
1881+-- NOTE: the named chunk below used by doctest;
1882+-- verify the doctests via `doctest -fobject-code Data/Text.hs`
1883+
1884+-- $setup
1885+-- >>> :set -XOverloadedStrings
1886+-- >>> import qualified Data.Text as T