f97e59a · text · git.iko.soy

git.iko.soy/text

on master help sign in

Many small documentation improvements.

f97e59aBryan O'Sullivan16 years ago

Data/Text.hs+2−1

compare with master

unifiedsplit

@@ -575,7 +575,8 @@ replace s d = intercalate d . splitOn s

575-- context-dependent operation. The case conversion functions in this

576-- module are /not/ locale sensitive. Programs that require locale

577-- sensitivity should use appropriate versions of the case mapping

578−-- functions from the @text-icu@ package.

578+-- functions from the @text-icu@ package:

579+-- <http://hackage.haskell.org/package/text-icu>

579

580

580-- | /O(n)/ Convert a string to folded case. This function is mainly

581-- | /O(n)/ Convert a string to folded case. This function is mainly

581-- useful for performing caseless (also known as case insensitive)

582-- useful for performing caseless (also known as case insensitive)

Data/Text/Encoding.hs+38−2

@@ -14,18 +14,20 @@

14-- Functions for converting 'Text' values to and from 'ByteString',

15-- using several standard encodings.

16--

17−-- To make use of a much larger variety of encodings, use the @text-icu@

17+-- To gain access to a much larger family of encodings, use the

18−-- package.

18+-- @text-icu@ package: <http://hackage.haskell.org/package/text-icu>

20module Data.Text.Encoding

21 (

22 -- * Decoding ByteStrings to Text

23+ -- $strict

23 decodeASCII

24 decodeASCII

24 , decodeUtf8

25 , decodeUtf8

25 , decodeUtf16LE

26 , decodeUtf16LE

26 , decodeUtf16BE

27 , decodeUtf16BE

27 , decodeUtf32LE

28 , decodeUtf32LE

28 , decodeUtf32BE

29 , decodeUtf32BE

30+

29 -- ** Controllable error handling

31 -- ** Controllable error handling

30 , decodeUtf8With

32 , decodeUtf8With

31 , decodeUtf16LEWith

33 , decodeUtf16LEWith

@@ -60,11 +62,25 @@ import qualified Data.Text.Encoding.Utf16 as U16

60import qualified Data.Text.Encoding.Utf8 as U8

62import qualified Data.Text.Encoding.Utf8 as U8

61import qualified Data.Text.Fusion as F

63import qualified Data.Text.Fusion as F

65+-- $strict

66+--

67+-- All of the single-parameter functions for decoding bytestrings

68+-- encoded in one of the Unicode Transformation Formats (UTF) operate

69+-- in a /strict/ mode: each will throw an exception if given invalid

70+-- input.

71+--

72+-- Each function has a variant, whose name is suffixed with -'With',

73+-- that gives greater control over the handling of decoding errors.

74+-- For instance, 'decodeUtf8' will throw an exception, but

75+-- 'decodeUtf8With' allows the programmer to determine what to do on a

76+-- decoding error.

77+

63-- | Decode a 'ByteString' containing 7-bit ASCII encoded text.

78-- | Decode a 'ByteString' containing 7-bit ASCII encoded text.

64decodeASCII :: ByteString -> Text

79decodeASCII :: ByteString -> Text

65decodeASCII bs = F.unstream (E.streamASCII bs)

80decodeASCII bs = F.unstream (E.streamASCII bs)

66{-# INLINE decodeASCII #-}

81{-# INLINE decodeASCII #-}

83+-- | Decode a 'ByteString' containing UTF-8 encoded text.

68decodeUtf8With :: OnDecodeError -> ByteString -> Text

84decodeUtf8With :: OnDecodeError -> ByteString -> Text

69decodeUtf8With onErr bs = textP (fst a) 0 (snd a)

85decodeUtf8With onErr bs = textP (fst a) 0 (snd a)

70 where

86 where

@@ -101,6 +117,10 @@ decodeUtf8With onErr bs = textP (fst a) 0 (snd a)

101{-# INLINE[0] decodeUtf8With #-}

117{-# INLINE[0] decodeUtf8With #-}

102

118

103-- | Decode a 'ByteString' containing UTF-8 encoded text.

119-- | Decode a 'ByteString' containing UTF-8 encoded text.

120+--

121+-- If the input contains any invalid UTF-8 data, an exception will be

122+-- thrown. For more control over the handling of invalid data, use

123+-- 'decodeUtf8With'.

104decodeUtf8 :: ByteString -> Text

124decodeUtf8 :: ByteString -> Text

105decodeUtf8 = decodeUtf8With strictDecode

125decodeUtf8 = decodeUtf8With strictDecode

106{-# INLINE[0] decodeUtf8 #-}

126{-# INLINE[0] decodeUtf8 #-}

@@ -156,6 +176,10 @@ decodeUtf16LEWith onErr bs = F.unstream (E.streamUtf16LE onErr bs)

156{-# INLINE decodeUtf16LEWith #-}

176{-# INLINE decodeUtf16LEWith #-}

157

177

158-- | Decode text from little endian UTF-16 encoding.

178-- | Decode text from little endian UTF-16 encoding.

179+--

180+-- If the input contains any invalid little endian UTF-16 data, an

181+-- exception will be thrown. For more control over the handling of

182+-- invalid data, use 'decodeUtf16LEWith'.

159decodeUtf16LE :: ByteString -> Text

183decodeUtf16LE :: ByteString -> Text

160decodeUtf16LE = decodeUtf16LEWith strictDecode

184decodeUtf16LE = decodeUtf16LEWith strictDecode

161{-# INLINE decodeUtf16LE #-}

185{-# INLINE decodeUtf16LE #-}

@@ -166,6 +190,10 @@ decodeUtf16BEWith onErr bs = F.unstream (E.streamUtf16BE onErr bs)

166{-# INLINE decodeUtf16BEWith #-}

190{-# INLINE decodeUtf16BEWith #-}

167

191

168-- | Decode text from big endian UTF-16 encoding.

192-- | Decode text from big endian UTF-16 encoding.

193+--

194+-- If the input contains any invalid big endian UTF-16 data, an

195+-- exception will be thrown. For more control over the handling of

196+-- invalid data, use 'decodeUtf16BEWith'.

169decodeUtf16BE :: ByteString -> Text

197decodeUtf16BE :: ByteString -> Text

170decodeUtf16BE = decodeUtf16BEWith strictDecode

198decodeUtf16BE = decodeUtf16BEWith strictDecode

171{-# INLINE decodeUtf16BE #-}

199{-# INLINE decodeUtf16BE #-}

@@ -186,6 +214,10 @@ decodeUtf32LEWith onErr bs = F.unstream (E.streamUtf32LE onErr bs)

186{-# INLINE decodeUtf32LEWith #-}

214{-# INLINE decodeUtf32LEWith #-}

187

215

188-- | Decode text from little endian UTF-32 encoding.

216-- | Decode text from little endian UTF-32 encoding.

217+--

218+-- If the input contains any invalid little endian UTF-32 data, an

219+-- exception will be thrown. For more control over the handling of

220+-- invalid data, use 'decodeUtf32LEWith'.

189decodeUtf32LE :: ByteString -> Text

221decodeUtf32LE :: ByteString -> Text

190decodeUtf32LE = decodeUtf32LEWith strictDecode

222decodeUtf32LE = decodeUtf32LEWith strictDecode

191{-# INLINE decodeUtf32LE #-}

223{-# INLINE decodeUtf32LE #-}

@@ -196,6 +228,10 @@ decodeUtf32BEWith onErr bs = F.unstream (E.streamUtf32BE onErr bs)

196{-# INLINE decodeUtf32BEWith #-}

228{-# INLINE decodeUtf32BEWith #-}

197

229

198-- | Decode text from big endian UTF-32 encoding.

230-- | Decode text from big endian UTF-32 encoding.

231+--

232+-- If the input contains any invalid big endian UTF-32 data, an

233+-- exception will be thrown. For more control over the handling of

234+-- invalid data, use 'decodeUtf32BEWith'.

199decodeUtf32BE :: ByteString -> Text

235decodeUtf32BE :: ByteString -> Text

200decodeUtf32BE = decodeUtf32BEWith strictDecode

236decodeUtf32BE = decodeUtf32BEWith strictDecode

201{-# INLINE decodeUtf32BE #-}

237{-# INLINE decodeUtf32BE #-}

Data/Text/IO.hs+22

@@ -9,9 +9,15 @@

9-- Portability : GHC

10--

11-- Efficient locale-sensitive support for text I\/O.

12+--

13+-- Skip past the synopsis for some important notes on performance and

14+-- portability across different versions of GHC.

13module Data.Text.IO

16module Data.Text.IO

14 (

17 (

18+ -- * Performance

19+ -- $performance

20+

15 -- * Locale support

21 -- * Locale support

16 -- $locale

22 -- $locale

17 -- * File-at-a-time operations

23 -- * File-at-a-time operations

@@ -60,6 +66,22 @@ import System.IO (hGetBuffering, hFileSize, hSetBuffering, hTell)

60import System.IO.Error (isEOFError)

66import System.IO.Error (isEOFError)

61#endif

67#endif

69+-- $performance

70+-- #performance#

71+--

72+-- The functions in this module obey the runtime system's locale,

73+-- character set encoding, and line ending conversion settings.

74+--

75+-- If you know in advance that you will be working with data that has

76+-- a specific encoding (e.g. UTF-8), and your application is highly

77+-- performance sensitive, you may find that it is faster to perform

78+-- I\/O with bytestrings and to encode and decode yourself than to use

79+-- the functions in this module.

80+--

81+-- Whether this will hold depends on the version of GHC you are using,

82+-- the platform you are working on, the data you are working with, and

83+-- the encodings you are using, so be sure to test for yourself.

84+

63-- | The 'readFile' function reads a file and returns the contents of

85-- | The 'readFile' function reads a file and returns the contents of

64-- the file as a string. The entire file is read strictly, as with

86-- the file as a string. The entire file is read strictly, as with

65-- 'getContents'.

87-- 'getContents'.

Data/Text/Lazy/Encoding.hs+36−2

@@ -12,12 +12,13 @@

12-- Functions for converting lazy 'Text' values to and from lazy

13-- 'ByteString', using several standard encodings.

14--

15−-- To make use of a much larger variety of encodings, use the @text-icu@

15+-- To gain access to a much larger variety of encodings, use the

16−-- package.

16+-- @text-icu@ package: <http://hackage.haskell.org/package/text-icu>

18module Data.Text.Lazy.Encoding

19 (

20 -- * Decoding ByteStrings to Text

21+ -- $strict

21 decodeASCII

22 decodeASCII

22 , decodeUtf8

23 , decodeUtf8

23 , decodeUtf16LE

24 , decodeUtf16LE

@@ -51,6 +52,19 @@ import qualified Data.Text.Encoding as TE

51import qualified Data.Text.Lazy.Encoding.Fusion as E

52import qualified Data.Text.Lazy.Encoding.Fusion as E

52import qualified Data.Text.Lazy.Fusion as F

53import qualified Data.Text.Lazy.Fusion as F

55+-- $strict

56+--

57+-- All of the single-parameter functions for decoding bytestrings

58+-- encoded in one of the Unicode Transformation Formats (UTF) operate

59+-- in a /strict/ mode: each will throw an exception if given invalid

60+-- input.

61+--

62+-- Each function has a variant, whose name is suffixed with -'With',

63+-- that gives greater control over the handling of decoding errors.

64+-- For instance, 'decodeUtf8' will throw an exception, but

65+-- 'decodeUtf8With' allows the programmer to determine what to do on a

66+-- decoding error.

67+

54-- | Decode a 'ByteString' containing 7-bit ASCII encoded text.

68-- | Decode a 'ByteString' containing 7-bit ASCII encoded text.

55decodeASCII :: B.ByteString -> Text

69decodeASCII :: B.ByteString -> Text

56decodeASCII bs = foldr (chunk . TE.decodeASCII) empty (B.toChunks bs)

70decodeASCII bs = foldr (chunk . TE.decodeASCII) empty (B.toChunks bs)

@@ -95,6 +109,10 @@ decodeUtf8With onErr bs0 = fast bs0

95{-# INLINE[0] decodeUtf8With #-}

109{-# INLINE[0] decodeUtf8With #-}

110

97-- | Decode a 'ByteString' containing UTF-8 encoded text.

111-- | Decode a 'ByteString' containing UTF-8 encoded text.

112+--

113+-- If the input contains any invalid UTF-8 data, an exception will be

114+-- thrown. For more control over the handling of invalid data, use

115+-- 'decodeUtf8With'.

98decodeUtf8 :: B.ByteString -> Text

116decodeUtf8 :: B.ByteString -> Text

99decodeUtf8 = decodeUtf8With strictDecode

117decodeUtf8 = decodeUtf8With strictDecode

100{-# INLINE[0] decodeUtf8 #-}

118{-# INLINE[0] decodeUtf8 #-}

@@ -113,6 +131,10 @@ decodeUtf16LEWith onErr bs = F.unstream (E.streamUtf16LE onErr bs)

113{-# INLINE decodeUtf16LEWith #-}

131{-# INLINE decodeUtf16LEWith #-}

114

132

115-- | Decode text from little endian UTF-16 encoding.

133-- | Decode text from little endian UTF-16 encoding.

134+--

135+-- If the input contains any invalid little endian UTF-16 data, an

136+-- exception will be thrown. For more control over the handling of

137+-- invalid data, use 'decodeUtf16LEWith'.

116decodeUtf16LE :: B.ByteString -> Text

138decodeUtf16LE :: B.ByteString -> Text

117decodeUtf16LE = decodeUtf16LEWith strictDecode

139decodeUtf16LE = decodeUtf16LEWith strictDecode

118{-# INLINE decodeUtf16LE #-}

140{-# INLINE decodeUtf16LE #-}

@@ -123,6 +145,10 @@ decodeUtf16BEWith onErr bs = F.unstream (E.streamUtf16BE onErr bs)

123{-# INLINE decodeUtf16BEWith #-}

145{-# INLINE decodeUtf16BEWith #-}

124

146

125-- | Decode text from big endian UTF-16 encoding.

147-- | Decode text from big endian UTF-16 encoding.

148+--

149+-- If the input contains any invalid big endian UTF-16 data, an

150+-- exception will be thrown. For more control over the handling of

151+-- invalid data, use 'decodeUtf16BEWith'.

126decodeUtf16BE :: B.ByteString -> Text

152decodeUtf16BE :: B.ByteString -> Text

127decodeUtf16BE = decodeUtf16BEWith strictDecode

153decodeUtf16BE = decodeUtf16BEWith strictDecode

128{-# INLINE decodeUtf16BE #-}

154{-# INLINE decodeUtf16BE #-}

@@ -143,6 +169,10 @@ decodeUtf32LEWith onErr bs = F.unstream (E.streamUtf32LE onErr bs)

143{-# INLINE decodeUtf32LEWith #-}

169{-# INLINE decodeUtf32LEWith #-}

144

170

145-- | Decode text from little endian UTF-32 encoding.

171-- | Decode text from little endian UTF-32 encoding.

172+--

173+-- If the input contains any invalid little endian UTF-32 data, an

174+-- exception will be thrown. For more control over the handling of

175+-- invalid data, use 'decodeUtf32LEWith'.

146decodeUtf32LE :: B.ByteString -> Text

176decodeUtf32LE :: B.ByteString -> Text

147decodeUtf32LE = decodeUtf32LEWith strictDecode

177decodeUtf32LE = decodeUtf32LEWith strictDecode

148{-# INLINE decodeUtf32LE #-}

178{-# INLINE decodeUtf32LE #-}

@@ -153,6 +183,10 @@ decodeUtf32BEWith onErr bs = F.unstream (E.streamUtf32BE onErr bs)

153{-# INLINE decodeUtf32BEWith #-}

183{-# INLINE decodeUtf32BEWith #-}

154

184

155-- | Decode text from big endian UTF-32 encoding.

185-- | Decode text from big endian UTF-32 encoding.

186+--

187+-- If the input contains any invalid big endian UTF-32 data, an

188+-- exception will be thrown. For more control over the handling of

189+-- invalid data, use 'decodeUtf32BEWith'.

156decodeUtf32BE :: B.ByteString -> Text

190decodeUtf32BE :: B.ByteString -> Text

157decodeUtf32BE = decodeUtf32BEWith strictDecode

191decodeUtf32BE = decodeUtf32BEWith strictDecode

158{-# INLINE decodeUtf32BE #-}

192{-# INLINE decodeUtf32BE #-}

Data/Text/Lazy/IO.hs+21

@@ -9,9 +9,15 @@

9-- Portability : GHC

10--

11-- Efficient locale-sensitive support for lazy text I\/O.

12+--

13+-- Skip past the synopsis for some important notes on performance and

14+-- portability across different versions of GHC.

13module Data.Text.Lazy.IO

16module Data.Text.Lazy.IO

14 (

17 (

18+ -- * Performance

19+ -- $performance

20+

15 -- * Locale support

21 -- * Locale support

16 -- $locale

22 -- $locale

17 -- * File-at-a-time operations

23 -- * File-at-a-time operations

@@ -58,6 +64,21 @@ import System.IO.Error (isEOFError)

58import System.IO.Unsafe (unsafeInterleaveIO)

64import System.IO.Unsafe (unsafeInterleaveIO)

59#endif

65#endif

67+-- $performance

68+--

69+-- The functions in this module obey the runtime system's locale,

70+-- character set encoding, and line ending conversion settings.

71+--

72+-- If you know in advance that you will be working with data that has

73+-- a specific encoding (e.g. UTF-8), and your application is highly

74+-- performance sensitive, you may find that it is faster to perform

75+-- I\/O with bytestrings and to encode and decode yourself than to use

76+-- the functions in this module.

77+--

78+-- Whether this will hold depends on the version of GHC you are using,

79+-- the platform you are working on, the data you are working with, and

80+-- the encodings you are using, so be sure to test for yourself.

81+

61-- | Read a file and return its contents as a string. The file is

82-- | Read a file and return its contents as a string. The file is

62-- read lazily, as with 'getContents'.

83-- read lazily, as with 'getContents'.

63readFile :: FilePath -> IO Text

84readFile :: FilePath -> IO Text

Data/Text/Lazy/Read.hs+4−2

@@ -39,7 +39,8 @@ type Reader a = Text -> Either String (a,Text)

39--

40-- /Note/: For fixed-width integer types, this function does not

41-- attempt to detect overflow, so a sufficiently long input may give

42−-- incorrect results.

42+-- incorrect results. If you are worried about overflow, use

43+-- 'Integer' for your result type.

43decimal :: Integral a => Reader a

44decimal :: Integral a => Reader a

44{-# SPECIALIZE decimal :: Reader Int #-}

45{-# SPECIALIZE decimal :: Reader Int #-}

45{-# SPECIALIZE decimal :: Reader Integer #-}

46{-# SPECIALIZE decimal :: Reader Integer #-}

@@ -59,7 +60,8 @@ decimal txt

59--

60--

60-- /Note/: For fixed-width integer types, this function does not

61-- /Note/: For fixed-width integer types, this function does not

61-- attempt to detect overflow, so a sufficiently long input may give

62-- attempt to detect overflow, so a sufficiently long input may give

62−-- incorrect results.

63+-- incorrect results. If you are worried about overflow, use

64+-- 'Integer' for your result type.

63hexadecimal :: Integral a => Reader a

65hexadecimal :: Integral a => Reader a

64{-# SPECIALIZE hexadecimal :: Reader Int #-}

66{-# SPECIALIZE hexadecimal :: Reader Int #-}

65{-# SPECIALIZE hexadecimal :: Reader Integer #-}

67{-# SPECIALIZE hexadecimal :: Reader Integer #-}

Data/Text/Read.hs+5−3

@@ -39,7 +39,8 @@ type Reader a = Text -> Either String (a,Text)

39--

40-- /Note/: For fixed-width integer types, this function does not

41-- attempt to detect overflow, so a sufficiently long input may give

42−-- incorrect results.

42+-- incorrect results. If you are worried about overflow, use

43+-- 'Integer' for your result type.

43decimal :: Integral a => Reader a

44decimal :: Integral a => Reader a

44{-# SPECIALIZE decimal :: Reader Int #-}

45{-# SPECIALIZE decimal :: Reader Int #-}

45{-# SPECIALIZE decimal :: Reader Integer #-}

46{-# SPECIALIZE decimal :: Reader Integer #-}

@@ -59,7 +60,8 @@ decimal txt

59--

60--

60-- /Note/: For fixed-width integer types, this function does not

61-- /Note/: For fixed-width integer types, this function does not

61-- attempt to detect overflow, so a sufficiently long input may give

62-- attempt to detect overflow, so a sufficiently long input may give

62−-- incorrect results.

63+-- incorrect results. If you are worried about overflow, use

64+-- 'Integer' for your result type.

63hexadecimal :: Integral a => Reader a

65hexadecimal :: Integral a => Reader a

64{-# SPECIALIZE hexadecimal :: Reader Int #-}

66{-# SPECIALIZE hexadecimal :: Reader Int #-}

65{-# SPECIALIZE hexadecimal :: Reader Integer #-}

67{-# SPECIALIZE hexadecimal :: Reader Integer #-}

@@ -99,7 +101,7 @@ signed f = runP (signa (P f))

99-- by the 'read' function, with the exception that a trailing @\'.\'@

101-- by the 'read' function, with the exception that a trailing @\'.\'@

100-- or @\'e\'@ /not/ followed by a number is not consumed.

102-- or @\'e\'@ /not/ followed by a number is not consumed.

101--

103--

102−-- Examples:

104+-- Examples (with behaviour identical to 'read'):

103--

105--

104-- >rational "3" == Right (3.0, "")

106-- >rational "3" == Right (3.0, "")

105-- >rational "3.1" == Right (3.1, "")

107-- >rational "3.1" == Right (3.1, "")