Bryan O'Sullivan avatar Bryan O'Sullivan committed 6d549dc

Many small documentation improvements.

Comments (0)

Files changed (7)

 -- context-dependent operation. The case conversion functions in this
 -- module are /not/ locale sensitive. Programs that require locale
 -- sensitivity should use appropriate versions of the case mapping
--- functions from the @text-icu@ package.
+-- functions from the @text-icu@ package:
+-- <http://hackage.haskell.org/package/text-icu>
 
 -- | /O(n)/ Convert a string to folded case.  This function is mainly
 -- useful for performing caseless (also known as case insensitive)

Data/Text/Encoding.hs

 -- Functions for converting 'Text' values to and from 'ByteString',
 -- using several standard encodings.
 --
--- To make use of a much larger variety of encodings, use the @text-icu@
--- package.
+-- To gain access to a much larger family of encodings, use the
+-- @text-icu@ package: <http://hackage.haskell.org/package/text-icu>
 
 module Data.Text.Encoding
     (
     -- * Decoding ByteStrings to Text
+    -- $strict
       decodeASCII
     , decodeUtf8
     , decodeUtf16LE
     , decodeUtf16BE
     , decodeUtf32LE
     , decodeUtf32BE
+
     -- ** Controllable error handling
     , decodeUtf8With
     , decodeUtf16LEWith
 import qualified Data.Text.Encoding.Utf8 as U8
 import qualified Data.Text.Fusion as F
 
+-- $strict
+--
+-- All of the single-parameter functions for decoding bytestrings
+-- encoded in one of the Unicode Transformation Formats (UTF) operate
+-- in a /strict/ mode: each will throw an exception if given invalid
+-- input.
+--
+-- Each function has a variant, whose name is suffixed with -'With',
+-- that gives greater control over the handling of decoding errors.
+-- For instance, 'decodeUtf8' will throw an exception, but
+-- 'decodeUtf8With' allows the programmer to determine what to do on a
+-- decoding error.
+
 -- | Decode a 'ByteString' containing 7-bit ASCII encoded text.
 decodeASCII :: ByteString -> Text
 decodeASCII bs = F.unstream (E.streamASCII bs)
 {-# INLINE decodeASCII #-}
 
+-- | Decode a 'ByteString' containing UTF-8 encoded text.
 decodeUtf8With :: OnDecodeError -> ByteString -> Text
 decodeUtf8With onErr bs = textP (fst a) 0 (snd a)
  where
 {-# INLINE[0] decodeUtf8With #-}
 
 -- | Decode a 'ByteString' containing UTF-8 encoded text.
+--
+-- If the input contains any invalid UTF-8 data, an exception will be
+-- thrown.  For more control over the handling of invalid data, use
+-- 'decodeUtf8With'.
 decodeUtf8 :: ByteString -> Text
 decodeUtf8 = decodeUtf8With strictDecode
 {-# INLINE[0] decodeUtf8 #-}
 {-# INLINE decodeUtf16LEWith #-}
 
 -- | Decode text from little endian UTF-16 encoding.
+--
+-- If the input contains any invalid little endian UTF-16 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf16LEWith'.
 decodeUtf16LE :: ByteString -> Text
 decodeUtf16LE = decodeUtf16LEWith strictDecode
 {-# INLINE decodeUtf16LE #-}
 {-# INLINE decodeUtf16BEWith #-}
 
 -- | Decode text from big endian UTF-16 encoding.
+--
+-- If the input contains any invalid big endian UTF-16 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf16BEWith'.
 decodeUtf16BE :: ByteString -> Text
 decodeUtf16BE = decodeUtf16BEWith strictDecode
 {-# INLINE decodeUtf16BE #-}
 {-# INLINE decodeUtf32LEWith #-}
 
 -- | Decode text from little endian UTF-32 encoding.
+--
+-- If the input contains any invalid little endian UTF-32 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf32LEWith'.
 decodeUtf32LE :: ByteString -> Text
 decodeUtf32LE = decodeUtf32LEWith strictDecode
 {-# INLINE decodeUtf32LE #-}
 {-# INLINE decodeUtf32BEWith #-}
 
 -- | Decode text from big endian UTF-32 encoding.
+--
+-- If the input contains any invalid big endian UTF-32 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf32BEWith'.
 decodeUtf32BE :: ByteString -> Text
 decodeUtf32BE = decodeUtf32BEWith strictDecode
 {-# INLINE decodeUtf32BE #-}
 -- Portability : GHC
 --
 -- Efficient locale-sensitive support for text I\/O.
+--
+-- Skip past the synopsis for some important notes on performance and
+-- portability across different versions of GHC.
 
 module Data.Text.IO
     (
+    -- * Performance
+    -- $performance 
+
     -- * Locale support
     -- $locale
     -- * File-at-a-time operations
 import System.IO.Error (isEOFError)
 #endif
 
+-- $performance
+-- #performance#
+--
+-- The functions in this module obey the runtime system's locale,
+-- character set encoding, and line ending conversion settings.
+--
+-- If you know in advance that you will be working with data that has
+-- a specific encoding (e.g. UTF-8), and your application is highly
+-- performance sensitive, you may find that it is faster to perform
+-- I\/O with bytestrings and to encode and decode yourself than to use
+-- the functions in this module.
+--
+-- Whether this will hold depends on the version of GHC you are using,
+-- the platform you are working on, the data you are working with, and
+-- the encodings you are using, so be sure to test for yourself.
+
 -- | The 'readFile' function reads a file and returns the contents of
 -- the file as a string.  The entire file is read strictly, as with
 -- 'getContents'.

Data/Text/Lazy/Encoding.hs

 -- Functions for converting lazy 'Text' values to and from lazy
 -- 'ByteString', using several standard encodings.
 --
--- To make use of a much larger variety of encodings, use the @text-icu@
--- package.
+-- To gain access to a much larger variety of encodings, use the
+-- @text-icu@ package: <http://hackage.haskell.org/package/text-icu>
 
 module Data.Text.Lazy.Encoding
     (
     -- * Decoding ByteStrings to Text
+    -- $strict
       decodeASCII
     , decodeUtf8
     , decodeUtf16LE
 import qualified Data.Text.Lazy.Encoding.Fusion as E
 import qualified Data.Text.Lazy.Fusion as F
 
+-- $strict
+--
+-- All of the single-parameter functions for decoding bytestrings
+-- encoded in one of the Unicode Transformation Formats (UTF) operate
+-- in a /strict/ mode: each will throw an exception if given invalid
+-- input.
+--
+-- Each function has a variant, whose name is suffixed with -'With',
+-- that gives greater control over the handling of decoding errors.
+-- For instance, 'decodeUtf8' will throw an exception, but
+-- 'decodeUtf8With' allows the programmer to determine what to do on a
+-- decoding error.
+
 -- | Decode a 'ByteString' containing 7-bit ASCII encoded text.
 decodeASCII :: B.ByteString -> Text
 decodeASCII bs = foldr (chunk . TE.decodeASCII) empty (B.toChunks bs)
 {-# INLINE[0] decodeUtf8With #-}
 
 -- | Decode a 'ByteString' containing UTF-8 encoded text.
+--
+-- If the input contains any invalid UTF-8 data, an exception will be
+-- thrown.  For more control over the handling of invalid data, use
+-- 'decodeUtf8With'.
 decodeUtf8 :: B.ByteString -> Text
 decodeUtf8 = decodeUtf8With strictDecode
 {-# INLINE[0] decodeUtf8 #-}
 {-# INLINE decodeUtf16LEWith #-}
 
 -- | Decode text from little endian UTF-16 encoding.
+--
+-- If the input contains any invalid little endian UTF-16 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf16LEWith'.
 decodeUtf16LE :: B.ByteString -> Text
 decodeUtf16LE = decodeUtf16LEWith strictDecode
 {-# INLINE decodeUtf16LE #-}
 {-# INLINE decodeUtf16BEWith #-}
 
 -- | Decode text from big endian UTF-16 encoding.
+--
+-- If the input contains any invalid big endian UTF-16 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf16BEWith'.
 decodeUtf16BE :: B.ByteString -> Text
 decodeUtf16BE = decodeUtf16BEWith strictDecode
 {-# INLINE decodeUtf16BE #-}
 {-# INLINE decodeUtf32LEWith #-}
 
 -- | Decode text from little endian UTF-32 encoding.
+--
+-- If the input contains any invalid little endian UTF-32 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf32LEWith'.
 decodeUtf32LE :: B.ByteString -> Text
 decodeUtf32LE = decodeUtf32LEWith strictDecode
 {-# INLINE decodeUtf32LE #-}
 {-# INLINE decodeUtf32BEWith #-}
 
 -- | Decode text from big endian UTF-32 encoding.
+--
+-- If the input contains any invalid big endian UTF-32 data, an
+-- exception will be thrown.  For more control over the handling of
+-- invalid data, use 'decodeUtf32BEWith'.
 decodeUtf32BE :: B.ByteString -> Text
 decodeUtf32BE = decodeUtf32BEWith strictDecode
 {-# INLINE decodeUtf32BE #-}

Data/Text/Lazy/IO.hs

 -- Portability : GHC
 --
 -- Efficient locale-sensitive support for lazy text I\/O.
+--
+-- Skip past the synopsis for some important notes on performance and
+-- portability across different versions of GHC.
 
 module Data.Text.Lazy.IO
     (
+    -- * Performance
+    -- $performance 
+
     -- * Locale support
     -- $locale
     -- * File-at-a-time operations
 import System.IO.Unsafe (unsafeInterleaveIO)
 #endif
 
+-- $performance
+--
+-- The functions in this module obey the runtime system's locale,
+-- character set encoding, and line ending conversion settings.
+--
+-- If you know in advance that you will be working with data that has
+-- a specific encoding (e.g. UTF-8), and your application is highly
+-- performance sensitive, you may find that it is faster to perform
+-- I\/O with bytestrings and to encode and decode yourself than to use
+-- the functions in this module.
+--
+-- Whether this will hold depends on the version of GHC you are using,
+-- the platform you are working on, the data you are working with, and
+-- the encodings you are using, so be sure to test for yourself.
+
 -- | Read a file and return its contents as a string.  The file is
 -- read lazily, as with 'getContents'.
 readFile :: FilePath -> IO Text

Data/Text/Lazy/Read.hs

 --
 -- /Note/: For fixed-width integer types, this function does not
 -- attempt to detect overflow, so a sufficiently long input may give
--- incorrect results.
+-- incorrect results.  If you are worried about overflow, use
+-- 'Integer' for your result type.
 decimal :: Integral a => Reader a
 {-# SPECIALIZE decimal :: Reader Int #-}
 {-# SPECIALIZE decimal :: Reader Integer #-}
 --
 -- /Note/: For fixed-width integer types, this function does not
 -- attempt to detect overflow, so a sufficiently long input may give
--- incorrect results.
+-- incorrect results.  If you are worried about overflow, use
+-- 'Integer' for your result type.
 hexadecimal :: Integral a => Reader a
 {-# SPECIALIZE hexadecimal :: Reader Int #-}
 {-# SPECIALIZE hexadecimal :: Reader Integer #-}

Data/Text/Read.hs

 --
 -- /Note/: For fixed-width integer types, this function does not
 -- attempt to detect overflow, so a sufficiently long input may give
--- incorrect results.
+-- incorrect results.  If you are worried about overflow, use
+-- 'Integer' for your result type.
 decimal :: Integral a => Reader a
 {-# SPECIALIZE decimal :: Reader Int #-}
 {-# SPECIALIZE decimal :: Reader Integer #-}
 --
 -- /Note/: For fixed-width integer types, this function does not
 -- attempt to detect overflow, so a sufficiently long input may give
--- incorrect results.
+-- incorrect results.  If you are worried about overflow, use
+-- 'Integer' for your result type.
 hexadecimal :: Integral a => Reader a
 {-# SPECIALIZE hexadecimal :: Reader Int #-}
 {-# SPECIALIZE hexadecimal :: Reader Integer #-}
 -- by the 'read' function, with the exception that a trailing @\'.\'@
 -- or @\'e\'@ /not/ followed by a number is not consumed.
 --
--- Examples:
+-- Examples (with behaviour identical to 'read'):
 --
 -- >rational "3"     == Right (3.0, "")
 -- >rational "3.1"   == Right (3.1, "")
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.