@@ -661,8 +661,13 @@ compareLength t n = S.compareLengthI (stream t) n
661661-- -----------------------------------------------------------------------------
662662-- * Transformations
663663-- | /O(n)/ 'map' @f@ @t@ is the 'Text' obtained by applying @f@ to
664−-- each element of @t@. Subject to fusion. Performs replacement on
665−-- invalid scalar values.
664+-- each element of @t@.
665+--
666+-- Example:
667+--
668+-- > map (\c -> if c == '.' then '!' else c) $ pack "I am not angry. Not at all." ==> "I am not angry! Not at all!"
669+--
670+-- Subject to fusion. Performs replacement on invalid scalar values.
666671map :: (Char -> Char) -> Text -> Text
667672map f t = unstream (S.map (safe . f) (stream t))
668673{-# INLINE [1] map #-}
@@ -670,18 +675,35 @@ map f t = unstream (S.map (safe . f) (stream t))
670675-- | /O(n)/ The 'intercalate' function takes a 'Text' and a list of
671676-- 'Text's and concatenates the list after interspersing the first
672677-- argument between each element of the list.
678+--
679+-- Example:
680+--
681+-- > let ni = pack "NI!"
682+-- > let sentence = fmap pack ["We", "seek", "the", "Holy", "Grail"]
683+-- > intercalate ni sentence ==> ""WeNI!seekNI!theNI!HolyNI!Grail""
673684intercalate :: Text -> [Text] -> Text
674685intercalate t = concat . (F.intersperse t)
675686{-# INLINE intercalate #-}
676687
677688-- | /O(n)/ The 'intersperse' function takes a character and places it
678−-- between the characters of a 'Text'. Subject to fusion. Performs
679−-- replacement on invalid scalar values.
689+-- between the characters of a 'Text'.
690+--
691+-- Example:
692+--
693+-- > intersperse '.' $ pack "SHIELD" ==> "S.H.I.E.L.D"
694+--
695+-- Subject to fusion. Performs replacement on invalid scalar values.
680696intersperse :: Char -> Text -> Text
681697intersperse c t = unstream (S.intersperse (safe c) (stream t))
682698{-# INLINE intersperse #-}
683699
684−-- | /O(n)/ Reverse the characters of a string. Subject to fusion.
700+-- | /O(n)/ Reverse the characters of a string.
701+--
702+-- Example:
703+--
704+-- > reverse $ pack "desrever" ==> "reversed"
705+--
706+-- Subject to fusion.
685707reverse :: Text -> Text
686708reverse t = S.reverse (stream t)
687709{-# INLINE reverse #-}
@@ -883,6 +905,11 @@ center k c t
883905-- of its 'Text' argument. Note that this function uses 'pack',
884906-- 'unpack', and the list version of transpose, and is thus not very
885907-- efficient.
908+--
909+-- Examples:
910+--
911+-- > transpose [pack "green", pack "orange"] ==> ["go","rr","ea","en","ng","e"]
912+-- > transpose [pack "blue", pack "red"] ==> ["br","le","ud","e"]
886913transpose :: [Text] -> [Text]
887914transpose ts = P.map pack (L.transpose (P.map unpack ts))
888915