f97e59a · text · git.iko.soy

git.iko.soy/text

Many small documentation improvements.

commitf97e59a983936e1d8ae41a598c66ad4e84a84042 authorBryan O'Sullivan <bos@serpentine.com> dateMon 29 Nov 2010, 16:40 (16 years ago) parent8fa25cb

7 files changed+128−10

compare with master

unifiedsplit

Data/Text.hs+2−1 Data/Text/Encoding.hs+38−2 Data/Text/IO.hs+22 Data/Text/Lazy/Encoding.hs+36−2 Data/Text/Lazy/IO.hs+21 Data/Text/Lazy/Read.hs+4−2 Data/Text/Read.hs+5−3

Data/Text.hs+2−1

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

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

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

577577-- 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>

579580

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

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

Data/Text/Encoding.hs+38−2

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

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

1515-- using several standard encodings.

1616--

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

18−-- package.

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

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

1919

2020module Data.Text.Encoding

2121 (

2222 -- * Decoding ByteStrings to Text

23+ -- $strict

2324 decodeASCII

2425 , decodeUtf8

2526 , decodeUtf16LE

2627 , decodeUtf16BE

2728 , decodeUtf32LE

2829 , decodeUtf32BE

30+

2931 -- ** Controllable error handling

3032 , decodeUtf8With

3133 , decodeUtf16LEWith

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

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

6163import qualified Data.Text.Fusion as F

6264

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+

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

6479decodeASCII :: ByteString -> Text

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

6681{-# INLINE decodeASCII #-}

6782

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

6884decodeUtf8With :: OnDecodeError -> ByteString -> Text

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

7086 where

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

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

102118

103119-- | 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'.

104124decodeUtf8 :: ByteString -> Text

105125decodeUtf8 = decodeUtf8With strictDecode

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

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

156176{-# INLINE decodeUtf16LEWith #-}

157177

158178-- | 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'.

159183decodeUtf16LE :: ByteString -> Text

160184decodeUtf16LE = decodeUtf16LEWith strictDecode

161185{-# INLINE decodeUtf16LE #-}

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

166190{-# INLINE decodeUtf16BEWith #-}

167191

168192-- | 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'.

169197decodeUtf16BE :: ByteString -> Text

170198decodeUtf16BE = decodeUtf16BEWith strictDecode

171199{-# INLINE decodeUtf16BE #-}

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

186214{-# INLINE decodeUtf32LEWith #-}

187215

188216-- | 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'.

189221decodeUtf32LE :: ByteString -> Text

190222decodeUtf32LE = decodeUtf32LEWith strictDecode

191223{-# INLINE decodeUtf32LE #-}

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

196228{-# INLINE decodeUtf32BEWith #-}

197229

198230-- | 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'.

199235decodeUtf32BE :: ByteString -> Text

200236decodeUtf32BE = decodeUtf32BEWith strictDecode

201237{-# INLINE decodeUtf32BE #-}

Data/Text/IO.hs+22

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

99-- Portability : GHC

1010--

1111-- 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.

1215

1316module Data.Text.IO

1417 (

18+ -- * Performance

19+ -- $performance

20+

1521 -- * Locale support

1622 -- $locale

1723 -- * File-at-a-time operations

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

6066import System.IO.Error (isEOFError)

6167#endif

6268

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+

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

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

6587-- 'getContents'.

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

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

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

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

1414--

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

16−-- package.

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

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

1717

1818module Data.Text.Lazy.Encoding

1919 (

2020 -- * Decoding ByteStrings to Text

21+ -- $strict

2122 decodeASCII

2223 , decodeUtf8

2324 , decodeUtf16LE

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

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

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

5354

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+

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

5569decodeASCII :: B.ByteString -> Text

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

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

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

96110

97111-- | 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'.

98116decodeUtf8 :: B.ByteString -> Text

99117decodeUtf8 = decodeUtf8With strictDecode

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

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

113131{-# INLINE decodeUtf16LEWith #-}

114132

115133-- | 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'.

116138decodeUtf16LE :: B.ByteString -> Text

117139decodeUtf16LE = decodeUtf16LEWith strictDecode

118140{-# INLINE decodeUtf16LE #-}

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

123145{-# INLINE decodeUtf16BEWith #-}

124146

125147-- | 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'.

126152decodeUtf16BE :: B.ByteString -> Text

127153decodeUtf16BE = decodeUtf16BEWith strictDecode

128154{-# INLINE decodeUtf16BE #-}

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

143169{-# INLINE decodeUtf32LEWith #-}

144170

145171-- | 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'.

146176decodeUtf32LE :: B.ByteString -> Text

147177decodeUtf32LE = decodeUtf32LEWith strictDecode

148178{-# INLINE decodeUtf32LE #-}

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

153183{-# INLINE decodeUtf32BEWith #-}

154184

155185-- | 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'.

156190decodeUtf32BE :: B.ByteString -> Text

157191decodeUtf32BE = decodeUtf32BEWith strictDecode

158192{-# INLINE decodeUtf32BE #-}

Data/Text/Lazy/IO.hs+21

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

99-- Portability : GHC

1010--

1111-- 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.

1215

1316module Data.Text.Lazy.IO

1417 (

18+ -- * Performance

19+ -- $performance

20+

1521 -- * Locale support

1622 -- $locale

1723 -- * File-at-a-time operations

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

5864import System.IO.Unsafe (unsafeInterleaveIO)

5965#endif

6066

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+

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

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

6384readFile :: FilePath -> IO Text

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

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

3939--

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

4141-- 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.

4344decimal :: Integral a => Reader a

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

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

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

5960--

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

6162-- 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.

6365hexadecimal :: Integral a => Reader a

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

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

Data/Text/Read.hs+5−3

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

3939--

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

4141-- 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.

4344decimal :: Integral a => Reader a

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

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

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

5960--

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

6162-- 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.

6365hexadecimal :: Integral a => Reader a

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

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

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

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

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

101103--

102−-- Examples:

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

103105--

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

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