-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Support for reading and writing UTF8 Strings
--   
--   A UTF8 layer for IO and Strings. The utf8-string package provides
--   operations for encoding UTF8 strings to Word8 lists and back, and for
--   reading and writing UTF8 without truncation.
@package utf8-string
@version 0.3


-- | Support for encoding UTF8 Strings to and from <tt>[Word8]</tt>
module Codec.Binary.UTF8.String

-- | Encode a Haskell String to a list of Word8 values, in UTF8 format.
encode :: String -> [Word8]

-- | Decode a UTF8 string packed into a list of Word8 values, directly to
--   String
decode :: [Word8] -> String

-- | Encode a string using <a>encode</a> and store the result in a
--   <a>String</a>.
encodeString :: String -> String

-- | Decode a string using <a>decode</a> using a <a>String</a> as input. |
--   This is not safe but it is necessary if UTF-8 encoded text | has been
--   loaded into a <a>String</a> prior to being decoded.
decodeString :: String -> String


-- | String IO preserving UTF8 encoding.
module System.IO.UTF8

-- | The <a>print</a> function outputs a value of any printable type to the
--   standard output device. This function differs from the System.IO.print
--   in that it preserves any UTF8 encoding of the shown value.
print :: (Show a) => a -> IO ()

-- | Write a UTF8 string to the standard output device
putStr :: String -> IO ()

-- | The same as <a>putStr</a>, but adds a newline character.
putStrLn :: String -> IO ()

-- | Read a UTF8 line from the standard input device
getLine :: IO String

-- | The <a>readLn</a> function combines <a>getLine</a> and
--   <tt>readIO</tt>, preserving UTF8
readLn :: (Read a) => IO a

-- | The <a>readFile</a> function reads a file and returns the contents of
--   the file as a UTF8 string. The file is read lazily, on demand, as with
--   <a>getContents</a>.
readFile :: FilePath -> IO String

-- | The computation <a>writeFile</a> <tt>file str</tt> function writes the
--   UTF8 string <tt>str</tt>, to the file <tt>file</tt>.
writeFile :: FilePath -> String -> IO ()

-- | The computation <a>appendFile</a> <tt>file str</tt> function appends
--   the UTF8 string <tt>str</tt>, to the file <tt>file</tt>.
appendFile :: FilePath -> String -> IO ()

-- | Lazily read stdin as a UTF8 string.
getContents :: IO String

-- | Read a UTF8 line from a Handle
hGetLine :: Handle -> IO String

-- | Lazily read a UTF8 string from a Handle
hGetContents :: Handle -> IO String

-- | Write a UTF8 string to a Handle.
hPutStr :: Handle -> String -> IO ()

-- | Write a UTF8 string to a Handle, appending a newline.
hPutStrLn :: Handle -> String -> IO ()


-- | This module provides fast, validated encoding and decoding functions
--   between <tt>ByteString</tt>s and <a>String</a>s. It does not exactly
--   match the output of the Codec.Binary.UTF8.String output for invalid
--   encodings as the number of replacement characters is sometimes longer.
module Data.ByteString.UTF8

-- | A space-efficient representation of a Word8 vector, supporting many
--   efficient operations. A <a>ByteString</a> contains 8-bit characters
--   only.
--   
--   Instances of Eq, Ord, Read, Show, Data, Typeable
data ByteString :: *

-- | Try to extract a character from a byte string. Returns <a>Nothing</a>
--   if there are no more bytes in the byte string. Otherwise, it returns a
--   decoded character and the number of bytes used in its representation.
--   Errors are replaced by character '\0xFFFD'.
decode :: ByteString -> Maybe (Char, Int)

-- | This character is used to mark errors in a UTF8 encoded string.
replacement_char :: Char

-- | Get the first character of a byte string, if any. Malformed characters
--   are replaced by '\0xFFFD'.
uncons :: ByteString -> Maybe (Char, ByteString)

-- | Split after a given number of characters. Negative values are treated
--   as if they are 0.
splitAt :: Int -> ByteString -> (ByteString, ByteString)

-- | <tt>take n s</tt> returns the first <tt>n</tt> characters of
--   <tt>s</tt>. If <tt>s</tt> has less then <tt>n</tt> characters, then we
--   return the whole of <tt>s</tt>.
take :: Int -> ByteString -> ByteString

-- | <tt>drop n s</tt> returns the <tt>s</tt> without its first <tt>n</tt>
--   characters. If <tt>s</tt> has less then <tt>n</tt> characters, then we
--   return the an empty string.
drop :: Int -> ByteString -> ByteString

-- | Split a string into two parts: the first is the longest prefix that
--   contains only characters that satisfy the predicate; the second part
--   is the rest of the string. Invalid characters are passed as '\0xFFFD'
--   to the predicate.
span :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Split a string into two parts: the first is the longest prefix that
--   contains only characters that do not satisfy the predicate; the second
--   part is the rest of the string. Invalid characters are passed as
--   '\0xFFFD' to the predicate.
break :: (Char -> Bool) -> ByteString -> (ByteString, ByteString)

-- | Converts a Haskell string into a UTF8 encoded bytestring.
fromString :: String -> ByteString

-- | Convert a UTF8 encoded bytestring into a Haskell string. Invalid
--   characters are replaced with '\xFFFD'.
toString :: ByteString -> String

-- | Traverse a bytestring (left biased). This fuction is strict in the
--   acumulator.
foldl :: (a -> Char -> a) -> a -> ByteString -> a

-- | Traverse a bytestring (right biased).
foldr :: (Char -> a -> a) -> a -> ByteString -> a

-- | Counts the number of characters encoded in the bytestring. Note that
--   this includes replacment characters.
length :: ByteString -> Int

-- | Split a string into a list of lines. Lines are termianted by '\n' or
--   the end of the string. Empty line may not be terminated by the end of
--   the string. See also 'lines\''.
lines :: ByteString -> [ByteString]

-- | Split a string into a list of lines. Lines are termianted by '\n' or
--   the end of the string. Empty line may not be terminated by the end of
--   the string. This function preserves the terminators. See also
--   <a>lines</a>.
lines' :: ByteString -> [ByteString]