@@ -113,6 +113,7 @@ module Data.Text
113113 , tails
114114
115115 -- ** Breaking into many substrings
116+ -- $split
116117 , split
117118 , splitTimes
118119 , splitChar
@@ -405,12 +406,12 @@ replace s d = intercalate d . split s
405406
406407-- $case
407408--
408−-- With Unicode text, it is incorrect to use combinators like @map
409−-- toUpper@ to case convert each character of a string individually.
410−-- Instead, use the whole-string case conversion functions from this
411−-- module. For correctness in different writing systems, these
412−-- functions may map one input character to two or three output
413−-- characters.
409+-- When case converting Unicode text, it is incorrect to use
410+-- combinators like @map toUpper@ to case convert each character of a
411+-- string individually. Instead, use the whole-string case conversion
412+-- functions from this module. For correctness in different writing
413+-- systems, these functions may map one input character to two or
414+-- three output characters.
414415
415416-- | /O(n)/ Convert a string to folded case. This function is mainly
416417-- useful for performing caseless (or case insensitive) string
@@ -422,27 +423,28 @@ replace s d = intercalate d . split s
422423--
423424-- The result string may be longer than the input string, and may
424425-- differ from applying 'toLower' to the input string. For instance,
425−-- the Armenian small ligature men now (U+FB13) is case folded to the
426−-- bigram men now (U+0574 U+0576), while the micro sign (U+00B5) is
427−-- case folded to the Greek small letter letter mu (U+03BC) instead of
428−-- itself.
426+-- the Armenian small ligature \"ﬓ\" (men now, U+FB13) is case
427+-- folded to the sequence \"մ\" (men, U+0574) followed by
428+-- \"ն\" (now, U+0576), while the Greek \"µ\" (micro sign,
429+-- U+00B5) is case folded to \"μ\" (small letter mu, U+03BC)
430+-- instead of itself.
429431toCaseFold :: Text -> Text
430432toCaseFold t = unstream (S.toCaseFold (stream t))
431433{-# INLINE [0] toCaseFold #-}
432434
433435-- | /O(n)/ Convert a string to lower case, using simple case
434436-- conversion. The result string may be longer than the input string.
435−-- For instance, the Latin capital letter I with dot above (U+0130)
436−-- maps to the bigram Latin small letter i (U+0069) followed by
437−-- combining dot above (U+0307).
437+-- For instance, \"İ\" (Latin capital letter I with dot above,
438+-- U+0130) maps to the sequence \"i\" (Latin small letter i, U+0069) followed
439+-- by \" ̇\" (combining dot above, U+0307).
438440toLower :: Text -> Text
439441toLower t = unstream (S.toLower (stream t))
440442{-# INLINE toLower #-}
441443
442444-- | /O(n)/ Convert a string to upper case, using simple case
443445-- conversion. The result string may be longer than the input string.
444−-- For instance, the German eszett (U+00DF) maps to the two-letter
445−-- sequence SS.
446+-- For instance, the German \"ß\" (eszett, U+00DF) maps to the
447+-- two-letter sequence \"SS\".
446448toUpper :: Text -> Text
447449toUpper t = unstream (S.toUpper (stream t))
448450{-# INLINE toUpper #-}
@@ -824,17 +826,19 @@ tails t | null t = [empty]
824826-- and
825827--
826828-- > intercalate (singleton c) . splitChar c == id
827−-- > splitChar == splitWith . (==)
828−--
829−-- As with all splitting functions in this library, this function does
830−-- not copy the substrings, it just constructs new 'Text's that are
831−-- slices of the original.
829+-- > splitChar == splitWith . (==)
832830splitChar :: Char -> Text -> [Text]
833831splitChar c = splitWith (==c)
834832{-# INLINE splitChar #-}
835833
836−-- | /O(m)*O(n)/ Break a 'Text' into pieces separated by the 'Text'
837−-- argument, consuming the delimiter. I.e.
834+-- $split
835+--
836+-- Splitting functions in this library do not perform character-wise
837+-- copies to create substrings; they just construct new 'Text's that
838+-- are slices of the original.
839+
840+-- | /O(m)*O(n)/ Break a 'Text' into pieces separated by the first
841+-- 'Text' argument, consuming the delimiter. Examples:
838842--
839843-- > split "\r\n" "a\r\nb\r\nd\r\ne" == ["a","b","d","e"]
840844-- > split "aaa" "aaaXaaaXaaaXaaa" == ["","X","X","X",""]
@@ -842,17 +846,15 @@ splitChar c = splitWith (==c)
842846--
843847-- and
844848--
845−-- > intercalate s . split s == id
846−--
847−-- As with all splitting functions in this library, this function does
848−-- not copy the substrings, it just constructs new 'Text's that are
849−-- slices of the original.
850−split :: Text -> Text -> [Text]
849+-- > intercalate s . split s == id
850+split :: Text -- ^ Text to split on
851+ -> Text -- ^ Input text
852+ -> [Text]
851853split pat src0
852854 | l == 0 = [src0]
853855 | otherwise = go src0
854856 where
855− l = length pat
857+ l = length pat
856858 go src = search 0 src
857859 where
858860 search !n !s