8dd9bee · text · git.iko.soy

git.iko.soy/text

on master help sign in

Make phrasing of fusion documentation more uniform.

8dd9beeBryan O'Sullivan16 years ago

Data/Text.hs+3−3

compare with master

unifiedsplit

@@ -278,6 +278,7 @@ import Data.Int (Int64)

278--

279-- > import Data.Text as T

280-- > import Data.Text.Encoding as E

281+-- > import Data.ByteString (ByteString)

281-- >

282-- >

282-- > countChars :: ByteString -> Int

283-- > countChars :: ByteString -> Int

283-- > countChars = T.length . T.toUpper . E.decodeUtf8

284-- > countChars = T.length . T.toUpper . E.decodeUtf8

@@ -289,7 +290,7 @@ import Data.Int (Int64)

289-- function will be compiled down to a single loop over the source

290-- function will be compiled down to a single loop over the source

290-- 'ByteString'.

291-- 'ByteString'.

291--

292--

292−-- Functions that can be fused by the compiler are marked with the

293+-- Functions that can be fused by the compiler are documented with the

293-- phrase \"Subject to fusion\".

294-- phrase \"Subject to fusion\".

294

295

295instance Eq Text where

296instance Eq Text where

@@ -1428,8 +1429,7 @@ unwords = intercalate (singleton ' ')

1428{-# INLINE unwords #-}

1429{-# INLINE unwords #-}

1429

1430

1430-- | /O(n)/ The 'isPrefixOf' function takes two 'Text's and returns

1431-- | /O(n)/ The 'isPrefixOf' function takes two 'Text's and returns

1431−-- 'True' iff the first is a prefix of the second. This function is

1432+-- 'True' iff the first is a prefix of the second. Subject to fusion.

1432−-- subject to fusion.

1433isPrefixOf :: Text -> Text -> Bool

1434isPrefixOf a@(Text _ _ alen) b@(Text _ _ blen) =

1435 alen <= blen && S.isPrefixOf (stream a) (stream b)

Data/Text/Lazy.hs+35−39

@@ -22,12 +22,12 @@

22-- requiring that the entire content be resident in memory.

23--

24-- Some operations, such as 'concat', 'append', 'reverse' and 'cons',

25−-- have better complexity than their "Data.Text" equivalents, due to

25+-- have better time complexity than their "Data.Text" equivalents, due

26−-- optimisations resulting from the list spine structure. And for

26+-- to the underlying representation being a list of chunks. For other

27−-- other operations lazy 'Text's are usually within a few percent of

27+-- operations, lazy 'Text's are usually within a few percent of strict

28−-- strict ones, but with better heap usage. For data larger than

28+-- ones, but often with better heap usage if used in a streaming

29−-- available memory, or if you have tight memory constraints, this

29+-- fashion. For data larger than available memory, or if you have

30−-- module will be the only option.

30+-- tight memory constraints, this module will be the only option.

31--

32-- This module is intended to be imported @qualified@, to avoid name

33-- clashes with "Prelude" functions. eg.

@@ -345,7 +345,7 @@ pack = unstream . S.streamList . L.map safe

345{-# INLINE [1] pack #-}

346

347-- | /O(n)/ Convert a 'Text' into a 'String'.

348−-- Subject to array fusion.

348+-- Subject to fusion.

349unpack :: Text -> String

350unpack t = S.unstreamList (stream t)

351{-# INLINE [1] unpack #-}

@@ -411,8 +411,7 @@ snoc t c = foldrChunks Chunk (singleton c) t

411 unstream (S.snoc (stream t) c) = snoc t c

412 #-}

413

414−-- | /O(n\/c)/ Appends one 'Text' to another. Subject to array

414+-- | /O(n\/c)/ Appends one 'Text' to another. Subject to fusion.

415−-- fusion.

416append :: Text -> Text -> Text

415append :: Text -> Text -> Text

417append xs ys = foldrChunks Chunk ys xs

416append xs ys = foldrChunks Chunk ys xs

418{-# INLINE [1] append #-}

417{-# INLINE [1] append #-}

@@ -425,7 +424,7 @@ append xs ys = foldrChunks Chunk ys xs

425 #-}

424 #-}

426

425

427-- | /O(1)/ Returns the first character and rest of a 'Text', or

426-- | /O(1)/ Returns the first character and rest of a 'Text', or

428−-- 'Nothing' if empty. Subject to array fusion.

427+-- 'Nothing' if empty. Subject to fusion.

429uncons :: Text -> Maybe (Char, Text)

428uncons :: Text -> Maybe (Char, Text)

430uncons Empty = Nothing

429uncons Empty = Nothing

431uncons (Chunk t ts) = Just (T.unsafeHead t, ts')

430uncons (Chunk t ts) = Just (T.unsafeHead t, ts')

@@ -434,13 +433,13 @@ uncons (Chunk t ts) = Just (T.unsafeHead t, ts')

434{-# INLINE uncons #-}

433{-# INLINE uncons #-}

435

434

436-- | /O(1)/ Returns the first character of a 'Text', which must be

435-- | /O(1)/ Returns the first character of a 'Text', which must be

437−-- non-empty. Subject to array fusion.

436+-- non-empty. Subject to fusion.

438head :: Text -> Char

437head :: Text -> Char

439head t = S.head (stream t)

438head t = S.head (stream t)

440{-# INLINE head #-}

439{-# INLINE head #-}

441

440

442-- | /O(1)/ Returns all characters after the head of a 'Text', which

441-- | /O(1)/ Returns all characters after the head of a 'Text', which

443−-- must be non-empty. Subject to array fusion.

442+-- must be non-empty. Subject to fusion.

444tail :: Text -> Text

443tail :: Text -> Text

445tail (Chunk t ts) = chunk (T.tail t) ts

444tail (Chunk t ts) = chunk (T.tail t) ts

446tail Empty = emptyError "tail"

445tail Empty = emptyError "tail"

@@ -454,7 +453,7 @@ tail Empty = emptyError "tail"

454 #-}

453 #-}

455

454

456-- | /O(1)/ Returns all but the last character of a 'Text', which must

455-- | /O(1)/ Returns all but the last character of a 'Text', which must

457−-- be non-empty. Subject to array fusion.

456+-- be non-empty. Subject to fusion.

458init :: Text -> Text

457init :: Text -> Text

459init (Chunk t0 ts0) = go t0 ts0

458init (Chunk t0 ts0) = go t0 ts0

460 where go t (Chunk t' ts) = Chunk t (go t' ts)

459 where go t (Chunk t' ts) = Chunk t (go t' ts)

@@ -469,7 +468,7 @@ init Empty = emptyError "init"

469 unstream (S.init (stream t)) = init t

468 unstream (S.init (stream t)) = init t

470 #-}

469 #-}

471

470

472−-- | /O(1)/ Tests whether a 'Text' is empty or not. Subject to array

471+-- | /O(1)/ Tests whether a 'Text' is empty or not. Subject to

473-- fusion.

472-- fusion.

474null :: Text -> Bool

473null :: Text -> Bool

475null Empty = True

474null Empty = True

@@ -490,7 +489,7 @@ isSingleton = S.isSingleton . stream

490{-# INLINE isSingleton #-}

489{-# INLINE isSingleton #-}

491

490

492-- | /O(1)/ Returns the last character of a 'Text', which must be

491-- | /O(1)/ Returns the last character of a 'Text', which must be

493−-- non-empty. Subject to array fusion.

492+-- non-empty. Subject to fusion.

494last :: Text -> Char

493last :: Text -> Char

495last Empty = emptyError "last"

494last Empty = emptyError "last"

496last (Chunk t ts) = go t ts

495last (Chunk t ts) = go t ts

@@ -548,9 +547,10 @@ intercalate t = concat . (U.intersperse t)

548{-# INLINE intercalate #-}

547{-# INLINE intercalate #-}

549

548

550-- | /O(n)/ The 'intersperse' function takes a character and places it

549-- | /O(n)/ The 'intersperse' function takes a character and places it

551−-- between the characters of a 'Text'. Subject to array fusion.

550+-- between the characters of a 'Text'. Subject to fusion. Performs

551+-- replacement on invalid scalar values.

552−intersperse :: Char -> Text -> Text

552+intersperse :: Char -> Text -> Text

553−intersperse c t = unstream (S.intersperse c (stream t))

553+intersperse c t = unstream (S.intersperse (safe c) (stream t))

554{-# INLINE intersperse #-}

555

556-- | /O(n)/ Left-justify a string to the given length, using the

@@ -683,26 +683,24 @@ toUpper t = unstream (S.toUpper (stream t))

683-- | /O(n)/ 'foldl', applied to a binary operator, a starting value

684-- (typically the left-identity of the operator), and a 'Text',

685-- reduces the 'Text' using the binary operator, from left to right.

686−-- Subject to array fusion.

686+-- Subject to fusion.

687foldl :: (a -> Char -> a) -> a -> Text -> a

688foldl f z t = S.foldl f z (stream t)

689{-# INLINE foldl #-}

690

691-- | /O(n)/ A strict version of 'foldl'.

692−-- Subject to array fusion.

692+-- Subject to fusion.

693foldl' :: (a -> Char -> a) -> a -> Text -> a

694foldl' f z t = S.foldl' f z (stream t)

695{-# INLINE foldl' #-}

696

697-- | /O(n)/ A variant of 'foldl' that has no starting value argument,

698−-- and thus must be applied to a non-empty 'Text'. Subject to array

698+-- and thus must be applied to a non-empty 'Text'. Subject to fusion.

699−-- fusion.

700foldl1 :: (Char -> Char -> Char) -> Text -> Char

699foldl1 :: (Char -> Char -> Char) -> Text -> Char

701foldl1 f t = S.foldl1 f (stream t)

700foldl1 f t = S.foldl1 f (stream t)

702{-# INLINE foldl1 #-}

701{-# INLINE foldl1 #-}

703

702

704−-- | /O(n)/ A strict version of 'foldl1'.

703+-- | /O(n)/ A strict version of 'foldl1'. Subject to fusion.

705−-- Subject to array fusion.

706foldl1' :: (Char -> Char -> Char) -> Text -> Char

704foldl1' :: (Char -> Char -> Char) -> Text -> Char

707foldl1' f t = S.foldl1' f (stream t)

705foldl1' f t = S.foldl1' f (stream t)

708{-# INLINE foldl1' #-}

706{-# INLINE foldl1' #-}

@@ -710,13 +708,13 @@ foldl1' f t = S.foldl1' f (stream t)

710-- | /O(n)/ 'foldr', applied to a binary operator, a starting value

708-- | /O(n)/ 'foldr', applied to a binary operator, a starting value

711-- (typically the right-identity of the operator), and a 'Text',

709-- (typically the right-identity of the operator), and a 'Text',

712-- reduces the 'Text' using the binary operator, from right to left.

710-- reduces the 'Text' using the binary operator, from right to left.

713−-- Subject to array fusion.

711+-- Subject to fusion.

714foldr :: (Char -> a -> a) -> a -> Text -> a

712foldr :: (Char -> a -> a) -> a -> Text -> a

715foldr f z t = S.foldr f z (stream t)

713foldr f z t = S.foldr f z (stream t)

716{-# INLINE foldr #-}

714{-# INLINE foldr #-}

717

715

718−-- | /O(n)/ A variant of 'foldr' that has no starting value argument, and

716+-- | /O(n)/ A variant of 'foldr' that has no starting value argument,

719−-- thust must be applied to a non-empty 'Text'. Subject to array

717+-- and thust must be applied to a non-empty 'Text'. Subject to

720-- fusion.

718-- fusion.

721foldr1 :: (Char -> Char -> Char) -> Text -> Char

719foldr1 :: (Char -> Char -> Char) -> Text -> Char

722foldr1 f t = S.foldr1 f (stream t)

720foldr1 f t = S.foldr1 f (stream t)

@@ -739,25 +737,25 @@ concatMap f = concat . foldr ((:) . f) []

739{-# INLINE concatMap #-}

737{-# INLINE concatMap #-}

740

738

741-- | /O(n)/ 'any' @p@ @t@ determines whether any character in the

739-- | /O(n)/ 'any' @p@ @t@ determines whether any character in the

742−-- 'Text' @t@ satisifes the predicate @p@. Subject to array fusion.

740+-- 'Text' @t@ satisifes the predicate @p@. Subject to fusion.

743any :: (Char -> Bool) -> Text -> Bool

741any :: (Char -> Bool) -> Text -> Bool

744any p t = S.any p (stream t)

742any p t = S.any p (stream t)

745{-# INLINE any #-}

743{-# INLINE any #-}

746

744

747-- | /O(n)/ 'all' @p@ @t@ determines whether all characters in the

745-- | /O(n)/ 'all' @p@ @t@ determines whether all characters in the

748−-- 'Text' @t@ satisify the predicate @p@. Subject to array fusion.

746+-- 'Text' @t@ satisify the predicate @p@. Subject to fusion.

749all :: (Char -> Bool) -> Text -> Bool

747all :: (Char -> Bool) -> Text -> Bool

750all p t = S.all p (stream t)

748all p t = S.all p (stream t)

751{-# INLINE all #-}

749{-# INLINE all #-}

752

750

753-- | /O(n)/ 'maximum' returns the maximum value from a 'Text', which

751-- | /O(n)/ 'maximum' returns the maximum value from a 'Text', which

754−-- must be non-empty. Subject to array fusion.

752+-- must be non-empty. Subject to fusion.

755maximum :: Text -> Char

753maximum :: Text -> Char

756maximum t = S.maximum (stream t)

754maximum t = S.maximum (stream t)

757{-# INLINE maximum #-}

755{-# INLINE maximum #-}

758

756

759-- | /O(n)/ 'minimum' returns the minimum value from a 'Text', which

757-- | /O(n)/ 'minimum' returns the minimum value from a 'Text', which

760−-- must be non-empty. Subject to array fusion.

758+-- must be non-empty. Subject to fusion.

761minimum :: Text -> Char

759minimum :: Text -> Char

762minimum t = S.minimum (stream t)

760minimum t = S.minimum (stream t)

763{-# INLINE minimum #-}

761{-# INLINE minimum #-}

@@ -929,9 +927,9 @@ dropWords i t0

929 where len' = fromIntegral len

927 where len' = fromIntegral len

930 n' = fromIntegral n

928 n' = fromIntegral n

931

929

932−-- | /O(n)/ 'takeWhile', applied to a predicate @p@ and a 'Text', returns

930+-- | /O(n)/ 'takeWhile', applied to a predicate @p@ and a 'Text',

933−-- the longest prefix (possibly empty) of elements that satisfy @p@.

931+-- returns the longest prefix (possibly empty) of elements that

934−-- This function is subject to array fusion.

932+-- satisfy @p@. Subject to fusion.

935takeWhile :: (Char -> Bool) -> Text -> Text

933takeWhile :: (Char -> Bool) -> Text -> Text

936takeWhile p t0 = takeWhile' t0

934takeWhile p t0 = takeWhile' t0

937 where takeWhile' Empty = Empty

935 where takeWhile' Empty = Empty

@@ -950,7 +948,7 @@ takeWhile p t0 = takeWhile' t0

950 #-}

948 #-}

951

949

952-- | /O(n)/ 'dropWhile' @p@ @t@ returns the suffix remaining after

950-- | /O(n)/ 'dropWhile' @p@ @t@ returns the suffix remaining after

953−-- 'takeWhile' @p@ @t@. This function is subject to array fusion.

951+-- 'takeWhile' @p@ @t@. Subject to fusion.

954dropWhile :: (Char -> Bool) -> Text -> Text

952dropWhile :: (Char -> Bool) -> Text -> Text

955dropWhile p t0 = dropWhile' t0

953dropWhile p t0 = dropWhile' t0

956 where dropWhile' Empty = Empty

954 where dropWhile' Empty = Empty

@@ -1275,8 +1273,7 @@ unwords = intercalate (singleton ' ')

1275{-# INLINE unwords #-}

1273{-# INLINE unwords #-}

1276

1274

1277-- | /O(n)/ The 'isPrefixOf' function takes two 'Text's and returns

1275-- | /O(n)/ The 'isPrefixOf' function takes two 'Text's and returns

1278−-- 'True' iff the first is a prefix of the second. This function is

1276+-- 'True' iff the first is a prefix of the second. Subject to fusion.

1279−-- subject to fusion.

1280isPrefixOf :: Text -> Text -> Bool

1277isPrefixOf :: Text -> Text -> Bool

1281isPrefixOf Empty _ = True

1278isPrefixOf Empty _ = True

1282isPrefixOf _ Empty = False

1279isPrefixOf _ Empty = False

@@ -1422,8 +1419,7 @@ count pat src

1422 #-}

1419 #-}

1423

1420

1424-- | /O(n)/ The 'countChar' function returns the number of times the

1421-- | /O(n)/ The 'countChar' function returns the number of times the

1425−-- query element appears in the given 'Text'. This function is subject

1422+-- query element appears in the given 'Text'. Subject to fusion.

1426−-- to fusion.

1427countChar :: Char -> Text -> Int64

1423countChar :: Char -> Text -> Int64

1428countChar c t = S.countChar c (stream t)

1424countChar c t = S.countChar c (stream t)

1429

1425