@@ -661,8 +661,13 @@ compareLength t n = S.compareLengthI (stream t) n
661-- -----------------------------------------------------------------------------
661-- -----------------------------------------------------------------------------
662-- * Transformations
662-- * Transformations
663-- | /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+-- > map (\c -> if c == '.' then '!' else c) $ pack "I am not angry. Not at all." ==> "I am not angry! Not at all!"
664−-- each element of @t@. Subject to fusion. Performs replacement on
670+-- Subject to fusion. Performs replacement on invalid scalar values.
665−-- invalid scalar values.
666map :: (Char -> Char) -> Text -> Text
671map :: (Char -> Char) -> Text -> Text
667map f t = unstream (S.map (safe . f) (stream t))
672map f t = unstream (S.map (safe . f) (stream t))
668{-# INLINE [1] map #-}
673{-# INLINE [1] map #-}
@@ -670,18 +675,35 @@ map f t = unstream (S.map (safe . f) (stream t))
670-- | /O(n)/ The 'intercalate' function takes a 'Text' and a list of
675-- | /O(n)/ The 'intercalate' function takes a 'Text' and a list of
671-- 'Text's and concatenates the list after interspersing the first
676-- 'Text's and concatenates the list after interspersing the first
672-- argument between each element of the list.
677-- argument between each element of the list.
681+-- > let ni = pack "NI!"
682+-- > let sentence = fmap pack ["We", "seek", "the", "Holy", "Grail"]
683+-- > intercalate ni sentence ==> ""WeNI!seekNI!theNI!HolyNI!Grail""
673intercalate :: Text -> [Text] -> Text
684intercalate :: Text -> [Text] -> Text
674intercalate t = concat . (F.intersperse t)
685intercalate t = concat . (F.intersperse t)
675{-# INLINE intercalate #-}
686{-# INLINE intercalate #-}
677-- | /O(n)/ The 'intersperse' function takes a character and places it
688-- | /O(n)/ The 'intersperse' function takes a character and places it
678−-- between the characters of a 'Text'. Subject to fusion. Performs
689+-- between the characters of a 'Text'.
693+-- > intersperse '.' $ pack "SHIELD" ==> "S.H.I.E.L.D"
679−-- replacement on invalid scalar values.
695+-- Subject to fusion. Performs replacement on invalid scalar values.
680intersperse :: Char -> Text -> Text
696intersperse :: Char -> Text -> Text
681intersperse c t = unstream (S.intersperse (safe c) (stream t))
697intersperse c t = unstream (S.intersperse (safe c) (stream t))
682{-# INLINE intersperse #-}
698{-# INLINE intersperse #-}
684−-- | /O(n)/ Reverse the characters of a string. Subject to fusion.
700+-- | /O(n)/ Reverse the characters of a string.
704+-- > reverse $ pack "desrever" ==> "reversed"
706+-- Subject to fusion.
685reverse :: Text -> Text
707reverse :: Text -> Text
686reverse t = S.reverse (stream t)
708reverse t = S.reverse (stream t)
687{-# INLINE reverse #-}
709{-# INLINE reverse #-}
@@ -883,6 +905,11 @@ center k c t
883-- of its 'Text' argument. Note that this function uses 'pack',
905-- of its 'Text' argument. Note that this function uses 'pack',
884-- 'unpack', and the list version of transpose, and is thus not very
906-- 'unpack', and the list version of transpose, and is thus not very
885-- efficient.
907-- efficient.
911+-- > transpose [pack "green", pack "orange"] ==> ["go","rr","ea","en","ng","e"]
912+-- > transpose [pack "blue", pack "red"] ==> ["br","le","ud","e"]
886transpose :: [Text] -> [Text]
913transpose :: [Text] -> [Text]
887transpose ts = P.map pack (L.transpose (P.map unpack ts))
914transpose ts = P.map pack (L.transpose (P.map unpack ts))