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


-- | Use RawFilePath instead of FilePath
--   
--   Please see README.md
@package rawfilepath
@version 0.2.4


-- | A drop-in replacement of <tt>Data.ByteString</tt> from the
--   <tt>bytestring</tt> package that provides file I/O functions with
--   <a>RawFilePath</a> instead of <a>FilePath</a>.
module Data.ByteString.RawFilePath

-- | The interact function takes a function of type <tt>ByteString -&gt;
--   ByteString</tt> as its argument. The entire input from the standard
--   input device is passed to this function as its argument, and the
--   resulting string is output on the standard output device.
interact :: ByteString -> ByteString -> IO ()

-- | getContents. Read stdin strictly. Equivalent to hGetContents stdin The
--   <a>Handle</a> is closed after the contents have been read.
getContents :: IO ByteString

-- | Read a handle's entire contents strictly into a <a>ByteString</a>.
--   
--   This function reads chunks at a time, increasing the chunk size on
--   each read. The final string is then realloced to the appropriate size.
--   For files &gt; half of available memory, this may lead to memory
--   exhaustion. Consider using <a>readFile</a> in this case.
--   
--   The Handle is closed once the contents have been read, or if an
--   exception is thrown.
hGetContents :: Handle -> IO ByteString

-- | Like <a>hGet</a>, except that a shorter <a>ByteString</a> may be
--   returned if there are not enough bytes immediately available to
--   satisfy the whole request. <a>hGetSome</a> only blocks if there is no
--   data available, and EOF has not yet been reached.
hGetSome :: Handle -> Int -> IO ByteString

-- | hGetNonBlocking is similar to <a>hGet</a>, except that it will never
--   block waiting for data to become available, instead it returns only
--   whatever data is available. If there is no data available to be read,
--   <a>hGetNonBlocking</a> returns <a>empty</a>.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hGet</a>.
hGetNonBlocking :: Handle -> Int -> IO ByteString

-- | Read a <a>ByteString</a> directly from the specified <a>Handle</a>.
--   This is far more efficient than reading the characters into a
--   <a>String</a> and then using <a>pack</a>. First argument is the Handle
--   to read from, and the second is the number of bytes to read. It
--   returns the bytes read, up to n, or <a>empty</a> if EOF has been
--   reached.
--   
--   <a>hGet</a> is implemented in terms of <a>hGetBuf</a>.
--   
--   If the handle is a pipe or socket, and the writing end is closed,
--   <a>hGet</a> will behave as if EOF was reached.
hGet :: Handle -> Int -> IO ByteString

-- | Write a ByteString to stdout, appending a newline byte
putStrLn :: ByteString -> IO ()

-- | Write a ByteString to stdout
putStr :: ByteString -> IO ()

-- | Write a ByteString to a handle, appending a newline byte
hPutStrLn :: Handle -> ByteString -> IO ()

-- | A synonym for <tt>hPut</tt>, for compatibility
hPutStr :: Handle -> ByteString -> IO ()

-- | Similar to <a>hPut</a> except that it will never block. Instead it
--   returns any tail that did not get written. This tail may be
--   <a>empty</a> in the case that the whole string was written, or the
--   whole original string if nothing was written. Partial writes are also
--   possible.
--   
--   Note: on Windows and with Haskell implementation other than GHC, this
--   function does not work correctly; it behaves identically to
--   <a>hPut</a>.
hPutNonBlocking :: Handle -> ByteString -> IO ByteString

-- | Outputs a <a>ByteString</a> to the specified <a>Handle</a>.
hPut :: Handle -> ByteString -> IO ()

-- | Read a line from a handle
hGetLine :: Handle -> IO ByteString

-- | Read a line from stdin.
getLine :: IO ByteString

-- | <i>O(n)</i> Make a copy of the <a>ByteString</a> with its own storage.
--   This is mainly useful to allow the rest of the data pointed to by the
--   <a>ByteString</a> to be garbage collected, for example if a large
--   string has been read in, and only a small part of it is needed in the
--   rest of the program.
copy :: ByteString -> ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CStringLen</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CStringLen</tt>. The <tt>ByteString</tt> is a
--   normal Haskell value and will be managed on the Haskell heap.
packCStringLen :: CStringLen -> IO ByteString

-- | <i>O(n).</i> Construct a new <tt>ByteString</tt> from a
--   <tt>CString</tt>. The resulting <tt>ByteString</tt> is an immutable
--   copy of the original <tt>CString</tt>, and is managed on the Haskell
--   heap. The original <tt>CString</tt> must be null terminated.
packCString :: CString -> IO ByteString

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a <tt>CStringLen</tt>. As for <tt>useAsCString</tt> this
--   function makes a copy of the original <tt>ByteString</tt>. It must not
--   be stored or used after the subcomputation finishes.
useAsCStringLen :: () => ByteString -> CStringLen -> IO a -> IO a

-- | <i>O(n) construction</i> Use a <tt>ByteString</tt> with a function
--   requiring a null-terminated <tt>CString</tt>. The <tt>CString</tt> is
--   a copy and will be freed automatically; it must not be stored or used
--   after the subcomputation finishes.
useAsCString :: () => ByteString -> CString -> IO a -> IO a

-- | <i>O(n)</i> Sort a ByteString efficiently, using counting sort.
sort :: ByteString -> ByteString

-- | <i>O(n)</i> Return all final segments of the given <a>ByteString</a>,
--   longest first.
tails :: ByteString -> [ByteString]

-- | <i>O(n)</i> Return all initial segments of the given
--   <a>ByteString</a>, shortest first.
inits :: ByteString -> [ByteString]

-- | <i>O(n)</i> <a>unzip</a> transforms a list of pairs of bytes into a
--   pair of ByteStrings. Note that this performs two <a>pack</a>
--   operations.
unzip :: [(Word8, Word8)] -> (ByteString, ByteString)

-- | <a>zipWith</a> generalises <a>zip</a> by zipping with the function
--   given as the first argument, instead of a tupling function. For
--   example, <tt><a>zipWith</a> (+)</tt> is applied to two ByteStrings to
--   produce the list of corresponding sums.
zipWith :: () => Word8 -> Word8 -> a -> ByteString -> ByteString -> [a]

-- | <i>O(n)</i> <a>zip</a> takes two ByteStrings and returns a list of
--   corresponding pairs of bytes. If one input ByteString is short, excess
--   elements of the longer ByteString are discarded. This is equivalent to
--   a pair of <a>unpack</a> operations.
zip :: ByteString -> ByteString -> [(Word8, Word8)]

-- | Find the indexes of all (possibly overlapping) occurances of a
--   substring in a string.
findSubstrings :: ByteString -> ByteString -> [Int]

-- | Get the first index of a substring in another string, or
--   <a>Nothing</a> if the string is not found. <tt>findSubstring p s</tt>
--   is equivalent to <tt>listToMaybe (findSubstrings p s)</tt>.
findSubstring :: ByteString -> ByteString -> Maybe Int

-- | Break a string on a substring, returning a pair of the part of the
--   string prior to the match, and the rest of the string.
--   
--   The following relationships hold:
--   
--   <pre>
--   break (== c) l == breakSubstring (singleton c) l
--   </pre>
--   
--   and:
--   
--   <pre>
--   findSubstring s l ==
--      if null s then Just 0
--                else case breakSubstring s l of
--                         (x,y) | null y    -&gt; Nothing
--                               | otherwise -&gt; Just (length x)
--   </pre>
--   
--   For example, to tokenise a string, dropping delimiters:
--   
--   <pre>
--   tokenise x y = h : if null t then [] else tokenise x (drop (length x) t)
--       where (h,t) = breakSubstring x y
--   </pre>
--   
--   To skip to the first occurence of a string:
--   
--   <pre>
--   snd (breakSubstring x y)
--   </pre>
--   
--   To take the parts of a string before a delimiter:
--   
--   <pre>
--   fst (breakSubstring x y)
--   </pre>
--   
--   Note that calling `breakSubstring x` does some preprocessing work, so
--   you should avoid unnecessarily duplicating breakSubstring calls with
--   the same pattern.
breakSubstring :: ByteString -> ByteString -> (ByteString, ByteString)

-- | Check whether one string is a substring of another. <tt>isInfixOf p
--   s</tt> is equivalent to <tt>not (null (findSubstrings p s))</tt>.
isInfixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>stripSuffix</a> function takes two ByteStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   suffix, and otherwise <a>Nothing</a>.
stripSuffix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>isSuffixOf</a> function takes two ByteStrings and
--   returns <a>True</a> iff the first is a suffix of the second.
--   
--   The following holds:
--   
--   <pre>
--   isSuffixOf x y == reverse x `isPrefixOf` reverse y
--   </pre>
--   
--   However, the real implemenation uses memcmp to compare the end of the
--   string only, with no reverse required..
isSuffixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>stripPrefix</a> function takes two ByteStrings and
--   returns <a>Just</a> the remainder of the second iff the first is its
--   prefix, and otherwise <a>Nothing</a>.
stripPrefix :: ByteString -> ByteString -> Maybe ByteString

-- | <i>O(n)</i> The <a>isPrefixOf</a> function takes two ByteStrings and
--   returns <a>True</a> if the first is a prefix of the second.
isPrefixOf :: ByteString -> ByteString -> Bool

-- | <i>O(n)</i> The <a>partition</a> function takes a predicate a
--   ByteString and returns the pair of ByteStrings with elements which do
--   and do not satisfy the predicate, respectively; i.e.,
--   
--   <pre>
--   partition p bs == (filter p xs, filter (not . p) xs)
--   </pre>
partition :: Word8 -> Bool -> ByteString -> (ByteString, ByteString)

-- | <i>O(n)</i> The <a>find</a> function takes a predicate and a
--   ByteString, and returns the first element in matching the predicate,
--   or <a>Nothing</a> if there is no such element.
--   
--   <pre>
--   find f p = case findIndex f p of Just n -&gt; Just (p ! n) ; _ -&gt; Nothing
--   </pre>
find :: Word8 -> Bool -> ByteString -> Maybe Word8

-- | <i>O(n)</i> <a>filter</a>, applied to a predicate and a ByteString,
--   returns a ByteString containing those characters that satisfy the
--   predicate.
filter :: Word8 -> Bool -> ByteString -> ByteString

-- | <i>O(n)</i> <a>notElem</a> is the inverse of <a>elem</a>
notElem :: Word8 -> ByteString -> Bool

-- | <i>O(n)</i> <a>elem</a> is the <a>ByteString</a> membership predicate.
elem :: Word8 -> ByteString -> Bool

-- | The <a>findIndices</a> function extends <a>findIndex</a>, by returning
--   the indices of all elements satisfying the predicate, in ascending
--   order.
findIndices :: Word8 -> Bool -> ByteString -> [Int]

-- | The <a>findIndex</a> function takes a predicate and a
--   <a>ByteString</a> and returns the index of the first element in the
--   ByteString satisfying the predicate.
findIndex :: Word8 -> Bool -> ByteString -> Maybe Int

-- | count returns the number of times its argument appears in the
--   ByteString
--   
--   <pre>
--   count = length . elemIndices
--   </pre>
--   
--   But more efficiently than using length on the intermediate list.
count :: Word8 -> ByteString -> Int

-- | <i>O(n)</i> The <a>elemIndices</a> function extends <a>elemIndex</a>,
--   by returning the indices of all elements equal to the query element,
--   in ascending order. This implementation uses memchr(3).
elemIndices :: Word8 -> ByteString -> [Int]

-- | <i>O(n)</i> The <a>elemIndexEnd</a> function returns the last index of
--   the element in the given <a>ByteString</a> which is equal to the query
--   element, or <a>Nothing</a> if there is no such element. The following
--   holds:
--   
--   <pre>
--   elemIndexEnd c xs ==
--   (-) (length xs - 1) `fmap` elemIndex c (reverse xs)
--   </pre>
elemIndexEnd :: Word8 -> ByteString -> Maybe Int

-- | <i>O(n)</i> The <a>elemIndex</a> function returns the index of the
--   first element in the given <a>ByteString</a> which is equal to the
--   query element, or <a>Nothing</a> if there is no such element. This
--   implementation uses memchr(3).
elemIndex :: Word8 -> ByteString -> Maybe Int

-- | <i>O(1)</i> <a>ByteString</a> index (subscript) operator, starting
--   from 0.
index :: ByteString -> Int -> Word8

-- | <i>O(n)</i> The <a>intercalate</a> function takes a <a>ByteString</a>
--   and a list of <a>ByteString</a>s and concatenates the list after
--   interspersing the first argument between each element of the list.
intercalate :: ByteString -> [ByteString] -> ByteString

-- | The <a>groupBy</a> function is the non-overloaded version of
--   <a>group</a>.
groupBy :: Word8 -> Word8 -> Bool -> ByteString -> [ByteString]

-- | The <a>group</a> function takes a ByteString and returns a list of
--   ByteStrings such that the concatenation of the result is equal to the
--   argument. Moreover, each sublist in the result contains only equal
--   elements. For example,
--   
--   <pre>
--   group "Mississippi" = ["M","i","ss","i","ss","i","pp","i"]
--   </pre>
--   
--   It is a special case of <a>groupBy</a>, which allows the programmer to
--   supply their own equality test. It is about 40% faster than <i>groupBy
--   (==)</i>
group :: ByteString -> [ByteString]

-- | <i>O(n)</i> Break a <a>ByteString</a> into pieces separated by the
--   byte argument, consuming the delimiter. I.e.
--   
--   <pre>
--   split '\n' "a\nb\nd\ne" == ["a","b","d","e"]
--   split 'a'  "aXaXaXa"    == ["","X","X","X",""]
--   split 'x'  "x"          == ["",""]
--   </pre>
--   
--   and
--   
--   <pre>
--   intercalate [c] . split c == id
--   split == splitWith . (==)
--   </pre>
--   
--   As for all splitting functions in this library, this function does not
--   copy the substrings, it just constructs new <tt>ByteStrings</tt> that
--   are slices of the original.
split :: Word8 -> ByteString -> [ByteString]

-- | <i>O(n)</i> Splits a <a>ByteString</a> into components delimited by
--   separators, where the predicate returns True for a separator element.
--   The resulting components do not contain the separators. Two adjacent
--   separators result in an empty component in the output. eg.
--   
--   <pre>
--   splitWith (=='a') "aabbaca" == ["","","bb","c",""]
--   splitWith (=='a') []        == []
--   </pre>
splitWith :: Word8 -> Bool -> ByteString -> [ByteString]

-- | <a>spanEnd</a> behaves like <a>span</a> but from the end of the
--   <a>ByteString</a>. We have
--   
--   <pre>
--   spanEnd (not.isSpace) "x y z" == ("x y ","z")
--   </pre>
--   
--   and
--   
--   <pre>
--   spanEnd (not . isSpace) ps
--      ==
--   let (x,y) = span (not.isSpace) (reverse ps) in (reverse y, reverse x)
--   </pre>
spanEnd :: Word8 -> Bool -> ByteString -> (ByteString, ByteString)

-- | <a>span</a> <tt>p xs</tt> breaks the ByteString into two segments. It
--   is equivalent to <tt>(<a>takeWhile</a> p xs, <a>dropWhile</a> p
--   xs)</tt>
span :: Word8 -> Bool -> ByteString -> (ByteString, ByteString)

-- | <a>breakEnd</a> behaves like <a>break</a> but from the end of the
--   <a>ByteString</a>
--   
--   breakEnd p == spanEnd (not.p)
breakEnd :: Word8 -> Bool -> ByteString -> (ByteString, ByteString)

-- | <a>breakByte</a> breaks its ByteString argument at the first occurence
--   of the specified byte. It is more efficient than <a>break</a> as it is
--   implemented with <tt>memchr(3)</tt>. I.e.
--   
--   <pre>
--   break (=='c') "abcd" == breakByte 'c' "abcd"
--   </pre>
breakByte :: Word8 -> ByteString -> (ByteString, ByteString)

-- | <a>break</a> <tt>p</tt> is equivalent to <tt><a>span</a> (<a>not</a> .
--   p)</tt>.
--   
--   Under GHC, a rewrite rule will transform break (==) into a call to the
--   specialised breakByte:
--   
--   <pre>
--   break ((==) x) = breakByte x
--   break (==x) = breakByte x
--   </pre>
break :: Word8 -> Bool -> ByteString -> (ByteString, ByteString)

-- | <a>dropWhile</a> <tt>p xs</tt> returns the suffix remaining after
--   <a>takeWhile</a> <tt>p xs</tt>.
dropWhile :: Word8 -> Bool -> ByteString -> ByteString

-- | <a>takeWhile</a>, applied to a predicate <tt>p</tt> and a ByteString
--   <tt>xs</tt>, returns the longest prefix (possibly empty) of
--   <tt>xs</tt> of elements that satisfy <tt>p</tt>.
takeWhile :: Word8 -> Bool -> ByteString -> ByteString

-- | <i>O(1)</i> <a>splitAt</a> <tt>n xs</tt> is equivalent to
--   <tt>(<a>take</a> n xs, <a>drop</a> n xs)</tt>.
splitAt :: Int -> ByteString -> (ByteString, ByteString)

-- | <i>O(1)</i> <a>drop</a> <tt>n xs</tt> returns the suffix of
--   <tt>xs</tt> after the first <tt>n</tt> elements, or <tt>[]</tt> if
--   <tt>n &gt; <a>length</a> xs</tt>.
drop :: Int -> ByteString -> ByteString

-- | <i>O(1)</i> <a>take</a> <tt>n</tt>, applied to a ByteString
--   <tt>xs</tt>, returns the prefix of <tt>xs</tt> of length <tt>n</tt>,
--   or <tt>xs</tt> itself if <tt>n &gt; <a>length</a> xs</tt>.
take :: Int -> ByteString -> ByteString

-- | <i>O(n)</i> Like <a>unfoldr</a>, <a>unfoldrN</a> builds a ByteString
--   from a seed value. However, the length of the result is limited by the
--   first argument to <a>unfoldrN</a>. This function is more efficient
--   than <a>unfoldr</a> when the maximum length of the result is known.
--   
--   The following equation relates <a>unfoldrN</a> and <a>unfoldr</a>:
--   
--   <pre>
--   fst (unfoldrN n f s) == take n (unfoldr f s)
--   </pre>
unfoldrN :: () => Int -> a -> Maybe (Word8, a) -> a -> (ByteString, Maybe a)

-- | <i>O(n)</i>, where <i>n</i> is the length of the result. The
--   <a>unfoldr</a> function is analogous to the List 'unfoldr'.
--   <a>unfoldr</a> builds a ByteString from a seed value. The function
--   takes the element and returns <a>Nothing</a> if it is done producing
--   the ByteString or returns <a>Just</a> <tt>(a,b)</tt>, in which case,
--   <tt>a</tt> is the next byte in the string, and <tt>b</tt> is the seed
--   value for further production.
--   
--   Examples:
--   
--   <pre>
--      unfoldr (\x -&gt; if x &lt;= 5 then Just (x, x + 1) else Nothing) 0
--   == pack [0, 1, 2, 3, 4, 5]
--   </pre>
unfoldr :: () => a -> Maybe (Word8, a) -> a -> ByteString

-- | <i>O(n)</i> <a>replicate</a> <tt>n x</tt> is a ByteString of length
--   <tt>n</tt> with <tt>x</tt> the value of every element. The following
--   holds:
--   
--   <pre>
--   replicate w c = unfoldr w (\u -&gt; Just (u,u)) c
--   </pre>
--   
--   This implemenation uses <tt>memset(3)</tt>
replicate :: Int -> Word8 -> ByteString

-- | <a>scanr1</a> is a variant of <a>scanr</a> that has no starting value
--   argument.
scanr1 :: Word8 -> Word8 -> Word8 -> ByteString -> ByteString

-- | scanr is the right-to-left dual of scanl.
scanr :: Word8 -> Word8 -> Word8 -> Word8 -> ByteString -> ByteString

-- | <a>scanl1</a> is a variant of <a>scanl</a> that has no starting value
--   argument. This function will fuse.
--   
--   <pre>
--   scanl1 f [x1, x2, ...] == [x1, x1 `f` x2, ...]
--   </pre>
scanl1 :: Word8 -> Word8 -> Word8 -> ByteString -> ByteString

-- | <a>scanl</a> is similar to <a>foldl</a>, but returns a list of
--   successive reduced values from the left. This function will fuse.
--   
--   <pre>
--   scanl f z [x1, x2, ...] == [z, z `f` x1, (z `f` x1) `f` x2, ...]
--   </pre>
--   
--   Note that
--   
--   <pre>
--   last (scanl f z xs) == foldl f z xs.
--   </pre>
scanl :: Word8 -> Word8 -> Word8 -> Word8 -> ByteString -> ByteString

-- | The <a>mapAccumR</a> function behaves like a combination of <a>map</a>
--   and <a>foldr</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from right to left, and
--   returning a final value of this accumulator together with the new
--   ByteString.
mapAccumR :: () => acc -> Word8 -> (acc, Word8) -> acc -> ByteString -> (acc, ByteString)

-- | The <a>mapAccumL</a> function behaves like a combination of <a>map</a>
--   and <a>foldl</a>; it applies a function to each element of a
--   ByteString, passing an accumulating parameter from left to right, and
--   returning a final value of this accumulator together with the new
--   list.
mapAccumL :: () => acc -> Word8 -> (acc, Word8) -> acc -> ByteString -> (acc, ByteString)

-- | <i>O(n)</i> <a>minimum</a> returns the minimum value from a
--   <a>ByteString</a> This function will fuse. An exception will be thrown
--   in the case of an empty ByteString.
minimum :: ByteString -> Word8

-- | <i>O(n)</i> <a>maximum</a> returns the maximum value from a
--   <a>ByteString</a> This function will fuse. An exception will be thrown
--   in the case of an empty ByteString.
maximum :: ByteString -> Word8

-- | <i>O(n)</i> Applied to a predicate and a <a>ByteString</a>, <a>all</a>
--   determines if all elements of the <a>ByteString</a> satisfy the
--   predicate.
all :: Word8 -> Bool -> ByteString -> Bool

-- | <i>O(n)</i> Applied to a predicate and a ByteString, <a>any</a>
--   determines if any element of the <a>ByteString</a> satisfies the
--   predicate.
any :: Word8 -> Bool -> ByteString -> Bool

-- | Map a function over a <a>ByteString</a> and concatenate the results
concatMap :: Word8 -> ByteString -> ByteString -> ByteString

-- | <i>O(n)</i> Concatenate a list of ByteStrings.
concat :: [ByteString] -> ByteString

-- | 'foldr1\'' is a variant of <a>foldr1</a>, but is strict in the
--   accumulator.
foldr1' :: Word8 -> Word8 -> Word8 -> ByteString -> Word8

-- | <a>foldr1</a> is a variant of <a>foldr</a> that has no starting value
--   argument, and thus must be applied to non-empty <a>ByteString</a>s An
--   exception will be thrown in the case of an empty ByteString.
foldr1 :: Word8 -> Word8 -> Word8 -> ByteString -> Word8

-- | 'foldl1\'' is like <a>foldl1</a>, but strict in the accumulator. An
--   exception will be thrown in the case of an empty ByteString.
foldl1' :: Word8 -> Word8 -> Word8 -> ByteString -> Word8

-- | <a>foldl1</a> is a variant of <a>foldl</a> that has no starting value
--   argument, and thus must be applied to non-empty <tt>ByteStrings</tt>.
--   An exception will be thrown in the case of an empty ByteString.
foldl1 :: Word8 -> Word8 -> Word8 -> ByteString -> Word8

-- | <a>foldr'</a> is like <a>foldr</a>, but strict in the accumulator.
foldr' :: () => Word8 -> a -> a -> a -> ByteString -> a

-- | <a>foldr</a>, applied to a binary operator, a starting value
--   (typically the right-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from right to left.
foldr :: () => Word8 -> a -> a -> a -> ByteString -> a

-- | <a>foldl'</a> is like <a>foldl</a>, but strict in the accumulator.
foldl' :: () => a -> Word8 -> a -> a -> ByteString -> a

-- | <a>foldl</a>, applied to a binary operator, a starting value
--   (typically the left-identity of the operator), and a ByteString,
--   reduces the ByteString using the binary operator, from left to right.
foldl :: () => a -> Word8 -> a -> a -> ByteString -> a

-- | The <a>transpose</a> function transposes the rows and columns of its
--   <a>ByteString</a> argument.
transpose :: [ByteString] -> [ByteString]

-- | <i>O(n)</i> The <a>intersperse</a> function takes a <a>Word8</a> and a
--   <a>ByteString</a> and `intersperses' that byte between the elements of
--   the <a>ByteString</a>. It is analogous to the intersperse function on
--   Lists.
intersperse :: Word8 -> ByteString -> ByteString

-- | <i>O(n)</i> <a>reverse</a> <tt>xs</tt> efficiently returns the
--   elements of <tt>xs</tt> in reverse order.
reverse :: ByteString -> ByteString

-- | <i>O(n)</i> <a>map</a> <tt>f xs</tt> is the ByteString obtained by
--   applying <tt>f</tt> to each element of <tt>xs</tt>.
map :: Word8 -> Word8 -> ByteString -> ByteString

-- | <i>O(n)</i> Append two ByteStrings
append :: ByteString -> ByteString -> ByteString

-- | <i>O(1)</i> Extract the <a>init</a> and <a>last</a> of a ByteString,
--   returning Nothing if it is empty.
unsnoc :: ByteString -> Maybe (ByteString, Word8)

-- | <i>O(1)</i> Return all the elements of a <a>ByteString</a> except the
--   last one. An exception will be thrown in the case of an empty
--   ByteString.
init :: ByteString -> ByteString

-- | <i>O(1)</i> Extract the last element of a ByteString, which must be
--   finite and non-empty. An exception will be thrown in the case of an
--   empty ByteString.
last :: ByteString -> Word8

-- | <i>O(1)</i> Extract the head and tail of a ByteString, returning
--   Nothing if it is empty.
uncons :: ByteString -> Maybe (Word8, ByteString)

-- | <i>O(1)</i> Extract the elements after the head of a ByteString, which
--   must be non-empty. An exception will be thrown in the case of an empty
--   ByteString.
tail :: ByteString -> ByteString

-- | <i>O(1)</i> Extract the first element of a ByteString, which must be
--   non-empty. An exception will be thrown in the case of an empty
--   ByteString.
head :: ByteString -> Word8

-- | <i>O(n)</i> Append a byte to the end of a <a>ByteString</a>
snoc :: ByteString -> Word8 -> ByteString
infixl 5 `snoc`

-- | <i>O(n)</i> <a>cons</a> is analogous to (:) for lists, but of
--   different complexity, as it requires making a copy.
cons :: Word8 -> ByteString -> ByteString
infixr 5 `cons`

-- | <i>O(1)</i> <a>length</a> returns the length of a ByteString as an
--   <a>Int</a>.
length :: ByteString -> Int

-- | <i>O(1)</i> Test whether a ByteString is empty.
null :: ByteString -> Bool

-- | <i>O(n)</i> Converts a <a>ByteString</a> to a <tt>[<a>Word8</a>]</tt>.
unpack :: ByteString -> [Word8]

-- | <i>O(n)</i> Convert a <tt>[<a>Word8</a>]</tt> into a
--   <a>ByteString</a>.
--   
--   For applications with large numbers of string literals, pack can be a
--   bottleneck. In such cases, consider using packAddress (GHC only).
pack :: [Word8] -> ByteString

-- | <i>O(1)</i> Convert a <a>Word8</a> into a <a>ByteString</a>
singleton :: Word8 -> ByteString

-- | <i>O(1)</i> The empty <a>ByteString</a>
empty :: ByteString

-- | A space-efficient representation of a <a>Word8</a> vector, supporting
--   many efficient operations.
--   
--   A <a>ByteString</a> contains 8-bit bytes, or by using the operations
--   from <a>Data.ByteString.Char8</a> it can be interpreted as containing
--   8-bit characters.
data ByteString

-- | A literal POSIX file path
type RawFilePath = ByteString

-- | Read an entire file at the <a>RawFilePath</a> strictly into a
--   <a>ByteString</a>.
readFile :: RawFilePath -> IO ByteString

-- | Write a <a>ByteString</a> to a file at the <a>RawFilePath</a>.
writeFile :: RawFilePath -> ByteString -> IO ()

-- | Append a <a>ByteString</a> to a file at the <a>RawFilePath</a>.
appendFile :: RawFilePath -> ByteString -> IO ()

-- | Acquire a file handle and perform an I/O action. The file will be
--   closed on exit or when this I/O action throws an exception.
withFile :: RawFilePath -> IOMode -> (Handle -> IO r) -> IO r


-- | This is the module for the <a>RawFilePath</a> version of functions in
--   the <tt>directory</tt> package.
module RawFilePath.Directory

-- | A literal POSIX file path
type RawFilePath = ByteString

-- | Test whether the given path points to an existing filesystem object.
--   If the user lacks necessary permissions to search the parent
--   directories, this function may return false even if the file does
--   actually exist.
doesPathExist :: RawFilePath -> IO Bool

-- | Return <a>True</a> if the argument file exists and is not a directory,
--   and <a>False</a> otherwise.
doesFileExist :: RawFilePath -> IO Bool

-- | Return <a>True</a> if the argument file exists and is either a
--   directory or a symbolic link to a directory, and <a>False</a>
--   otherwise.
doesDirectoryExist :: RawFilePath -> IO Bool

-- | Returns the current user's home directory. More specifically, the
--   value of the <tt>HOME</tt> environment variable.
--   
--   The directory returned is expected to be writable by the current user,
--   but note that it isn't generally considered good practice to store
--   application-specific data here; use <tt>getXdgDirectory</tt> or
--   <tt>getAppUserDataDirectory</tt> instead.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>UnsupportedOperation</a> The operating system has no notion of
--   home directory.</li>
--   <li><a>isDoesNotExistError</a> The home directory for the current user
--   does not exist, or cannot be found.</li>
--   </ul>
getHomeDirectory :: IO (Maybe RawFilePath)

-- | Return the current directory for temporary files. It first returns the
--   value of the <tt>TMPDIR</tt> environment variable or "/tmp" if the
--   variable isn't defined.
getTemporaryDirectory :: IO ByteString

-- | Get a list of files in the specified directory, excluding "." and ".."
--   
--   <pre>
--   ghci&gt; listDirectory "/"
--   ["home","sys","var","opt","lib64","sbin","usr","srv","dev","lost+found","bin","tmp","run","root","boot","proc","etc","lib"]
--   </pre>
listDirectory :: RawFilePath -> IO [RawFilePath]

-- | Get a list of files in the specified directory, including "." and ".."
--   
--   <pre>
--   ghci&gt; getDirectoryFiles "/"
--   ["home","sys","var","opt","..","lib64","sbin","usr","srv","dev","lost+found","mnt","bin","tmp","run","root","boot",".","proc","etc","lib"]
--   </pre>
getDirectoryFiles :: RawFilePath -> IO [RawFilePath]

-- | Recursively get all files in all subdirectories of the specified
--   directory.
--   
--   <pre>
--   *System.RawFilePath&gt; getDirectoryFilesRecursive "src"
--   ["src/System/RawFilePath.hs"]
--   </pre>
getDirectoryFilesRecursive :: RawFilePath -> IO [RawFilePath]

-- | Create a new directory.
--   
--   <pre>
--   ghci&gt; createDirectory "/tmp/mydir"
--   ghci&gt; getDirectoryFiles "/tmp/mydir"
--   [".",".."]
--   ghci&gt; createDirectory "/tmp/mydir/anotherdir"
--   ghci&gt; getDirectoryFiles "/tmp/mydir"
--   [".","..","anotherdir"]
--   </pre>
createDirectory :: RawFilePath -> IO ()

-- | Create a new directory if it does not already exist. If the first
--   argument is <a>True</a> the function will also create all parent
--   directories when they are missing.
createDirectoryIfMissing :: Bool -> RawFilePath -> IO ()

-- | Remove a file. This function internally calls <tt>unlink</tt>. If the
--   file does not exist, an exception is thrown.
removeFile :: RawFilePath -> IO ()

-- | A function that "tries" to remove a file. If the file does not exist,
--   nothing happens.
tryRemoveFile :: RawFilePath -> IO ()

-- | Remove a directory. The target directory needs to be empty; Otherwise
--   an exception will be thrown.
removeDirectory :: RawFilePath -> IO ()

-- | Remove an existing directory <i>dir</i> together with its contents and
--   subdirectories. Within this directory, symbolic links are removed
--   without affecting their targets.
removeDirectoryRecursive :: RawFilePath -> IO ()


-- | Welcome to <tt>RawFilePath.Process</tt>, a small part of the Haskell
--   community's effort to purge <a>String</a> for the Greater Good.
--   
--   With this module, you can create (and interact with) sub-processes
--   without the encoding problem of <a>String</a>. The command and its
--   arguments, all <a>ByteString</a>s, never get converted from/to
--   <a>String</a> internally on its way to the actual syscall. It also
--   avoids the time/space waste of <a>String</a>.
--   
--   The interface, unlike the original <tt>process</tt> package, uses
--   types to prevent unnecessary runtime errors when obtaining
--   <a>Handle</a>s. This is inspired by the <tt>typed-process</tt> package
--   which is awesome, although this module is much simpler; it doesn't
--   introduce any new requirement of language extension or library package
--   (for the sake of portability).
--   
--   <a>Handle</a> (accessible with <a>processStdin</a>,
--   <a>processStdout</a>, and <a>processStderr</a>) is what you can use to
--   interact with the sub-process. For example, use <a>hGetContents</a>
--   from <a>Data.ByteString</a> to read from a <a>Handle</a> as a
--   <a>ByteString</a>.
--   
--   <h2>Example</h2>
--   
--   <pre>
--   {-# language OverloadedStrings #-}
--   
--   import RawFilePath.Process
--   import qualified Data.ByteString as B
--   
--   main :: IO ()
--   main = do
--       p &lt;- <a>startProcess</a> $ <a>proc</a> "echo" ["hello"]
--           `setStdout` <a>CreatePipe</a>
--       result &lt;- B.hGetContents (<a>processStdout</a> p)
--       _ &lt;- <a>waitForProcess</a> p
--   
--       print (result == "hello\n")
--   </pre>
module RawFilePath.Process

-- | A literal POSIX file path
type RawFilePath = ByteString

-- | The process configuration that is needed for creating new processes.
--   Use <a>proc</a> to make one.
data ProcessConf stdin stdout stderr

-- | Create a process configuration with the default settings.
proc :: RawFilePath -> [ByteString] -> ProcessConf Inherit Inherit Inherit

-- | The class of types that determine the standard stream of a
--   sub-process. You can decide how to initialize the standard streams
--   (stdin, stdout, and stderr) of a sub-process with the instances of
--   this class.
class StreamType c

-- | Create a new pipe for the stream. You get a new <a>Handle</a>.
data CreatePipe
CreatePipe :: CreatePipe

-- | Inherit the parent (current) process handle. The child will share the
--   stream. For example, if the child writes anything to stdout, it will
--   all go to the parent's stdout.
data Inherit
Inherit :: Inherit

-- | No stream handle will be passed. Use when you don't want to
--   communicate with a stream. For example, to run something silently.
data NoStream
NoStream :: NoStream

-- | Use the supplied <a>Handle</a>.
data UseHandle
UseHandle :: Handle -> UseHandle

-- | Control how the standard input of the process will be initialized.
setStdin :: (StreamType newStdin) => ProcessConf oldStdin stdout stderr -> newStdin -> ProcessConf newStdin stdout stderr
infixl 4 `setStdin`

-- | Control how the standard output of the process will be initialized.
setStdout :: (StreamType newStdout) => ProcessConf stdin oldStdout stderr -> newStdout -> ProcessConf stdin newStdout stderr
infixl 4 `setStdout`

-- | Control how the standard error of the process will be initialized.
setStderr :: (StreamType newStderr) => ProcessConf stdin stdout oldStderr -> newStderr -> ProcessConf stdin stdout newStderr
infixl 4 `setStderr`

-- | The process type. The three type variables denote how its standard
--   streams were initialized.
data Process stdin stdout stderr

-- | Start a new sub-process with the given configuration.
startProcess :: (StreamType stdin, StreamType stdout, StreamType stderr) => ProcessConf stdin stdout stderr -> IO (Process stdin stdout stderr)

-- | Take a process and return its standard input handle.
processStdin :: Process CreatePipe stdout stderr -> Handle

-- | Take a process and return its standard output handle.
processStdout :: Process stdin CreatePipe stderr -> Handle

-- | Take a process and return its standard error handle.
processStderr :: Process stdin stdout CreatePipe -> Handle

-- | Stop a sub-process. For now it simply calls <a>terminateProcess</a>
--   and then <a>waitForProcess</a>.
stopProcess :: Process stdin stdout stderr -> IO ExitCode

-- | Terminate a sub-process by sending SIGTERM to it.
terminateProcess :: Process stdin stdout stderr -> IO ()

-- | Wait (block) for a sub-process to exit and obtain its exit code.
waitForProcess :: Process stdin stdout stderr -> IO ExitCode

-- | Create a new process with the given configuration, and wait for it to
--   finish.
callProcess :: ProcessConf stdin stdout stderr -> IO ExitCode

-- | Fork an external process, read its standard output and standard error
--   strictly, blocking until the process terminates, and return them with
--   the process exit code.
readProcessWithExitCode :: ProcessConf stdin stdout stderr -> IO (ExitCode, ByteString, ByteString)


-- | Welcome to <tt>RawFilePath</tt>, a small part of the Haskell
--   community's effort to purge <a>String</a> for the Greater Good.
--   
--   With this package, you can interact with the Unix system without the
--   file path encoding issue or the <a>String</a> ↔ <a>ByteString</a>
--   conversion overhead.
--   
--   <h2>Rationale</h2>
--   
--   Traditional <a>String</a> is notorious:
--   
--   <ul>
--   <li>24 bytes (three words) required for one character (the List
--   constructor, the actual Char value, and the pointer to the next List
--   constructor). 24x memory consumption.</li>
--   <li>Heap fragmentation causing malloc/free overhead</li>
--   <li>A lot of pointer chasing for reading, devastating the cache hit
--   rate</li>
--   <li>A lot of pointer chasing plus a lot of heap object allocation for
--   manipulation (appending, slicing, etc.)</li>
--   <li>Completely unnecessary but mandatory conversions and memory
--   allocation when the data is sent to or received from the outside
--   world</li>
--   </ul>
--   
--   <a>String</a> has another problematic nature to serve as a file path
--   data type: Encoding blindness. All functions that return
--   <a>FilePath</a> would actually take a series of bytes returned by a
--   syscall and somehow magically "decode" it into a <a>String</a> which
--   is surprising because no encoding information was given. Of course
--   there is no magic and it's an abject fail. <a>FilePath</a> just
--   wouldn't work.
--   
--   <h2>Usage</h2>
--   
--   This is the top-level module that re-exports the sub-modules.
--   Therefore, you can
--   
--   <pre>
--   import RawFilePath
--   </pre>
--   
--   to import all functions.
module RawFilePath

-- | Test whether the given path points to an existing filesystem object.
--   If the user lacks necessary permissions to search the parent
--   directories, this function may return false even if the file does
--   actually exist.
doesPathExist :: RawFilePath -> IO Bool

-- | Return <a>True</a> if the argument file exists and is either a
--   directory or a symbolic link to a directory, and <a>False</a>
--   otherwise.
doesDirectoryExist :: RawFilePath -> IO Bool

-- | Return <a>True</a> if the argument file exists and is not a directory,
--   and <a>False</a> otherwise.
doesFileExist :: RawFilePath -> IO Bool

-- | Returns the current user's home directory. More specifically, the
--   value of the <tt>HOME</tt> environment variable.
--   
--   The directory returned is expected to be writable by the current user,
--   but note that it isn't generally considered good practice to store
--   application-specific data here; use <tt>getXdgDirectory</tt> or
--   <tt>getAppUserDataDirectory</tt> instead.
--   
--   The operation may fail with:
--   
--   <ul>
--   <li><a>UnsupportedOperation</a> The operating system has no notion of
--   home directory.</li>
--   <li><a>isDoesNotExistError</a> The home directory for the current user
--   does not exist, or cannot be found.</li>
--   </ul>
getHomeDirectory :: IO (Maybe RawFilePath)

-- | Return the current directory for temporary files. It first returns the
--   value of the <tt>TMPDIR</tt> environment variable or "/tmp" if the
--   variable isn't defined.
getTemporaryDirectory :: IO ByteString

-- | Get a list of files in the specified directory, excluding "." and ".."
--   
--   <pre>
--   ghci&gt; listDirectory "/"
--   ["home","sys","var","opt","lib64","sbin","usr","srv","dev","lost+found","bin","tmp","run","root","boot","proc","etc","lib"]
--   </pre>
listDirectory :: RawFilePath -> IO [RawFilePath]

-- | Get a list of files in the specified directory, including "." and ".."
--   
--   <pre>
--   ghci&gt; getDirectoryFiles "/"
--   ["home","sys","var","opt","..","lib64","sbin","usr","srv","dev","lost+found","mnt","bin","tmp","run","root","boot",".","proc","etc","lib"]
--   </pre>
getDirectoryFiles :: RawFilePath -> IO [RawFilePath]

-- | Recursively get all files in all subdirectories of the specified
--   directory.
--   
--   <pre>
--   *System.RawFilePath&gt; getDirectoryFilesRecursive "src"
--   ["src/System/RawFilePath.hs"]
--   </pre>
getDirectoryFilesRecursive :: RawFilePath -> IO [RawFilePath]

-- | Create a new directory.
--   
--   <pre>
--   ghci&gt; createDirectory "/tmp/mydir"
--   ghci&gt; getDirectoryFiles "/tmp/mydir"
--   [".",".."]
--   ghci&gt; createDirectory "/tmp/mydir/anotherdir"
--   ghci&gt; getDirectoryFiles "/tmp/mydir"
--   [".","..","anotherdir"]
--   </pre>
createDirectory :: RawFilePath -> IO ()

-- | Create a new directory if it does not already exist. If the first
--   argument is <a>True</a> the function will also create all parent
--   directories when they are missing.
createDirectoryIfMissing :: Bool -> RawFilePath -> IO ()

-- | Remove a file. This function internally calls <tt>unlink</tt>. If the
--   file does not exist, an exception is thrown.
removeFile :: RawFilePath -> IO ()

-- | A function that "tries" to remove a file. If the file does not exist,
--   nothing happens.
tryRemoveFile :: RawFilePath -> IO ()

-- | Remove a directory. The target directory needs to be empty; Otherwise
--   an exception will be thrown.
removeDirectory :: RawFilePath -> IO ()

-- | Remove an existing directory <i>dir</i> together with its contents and
--   subdirectories. Within this directory, symbolic links are removed
--   without affecting their targets.
removeDirectoryRecursive :: RawFilePath -> IO ()

-- | The class of types that determine the standard stream of a
--   sub-process. You can decide how to initialize the standard streams
--   (stdin, stdout, and stderr) of a sub-process with the instances of
--   this class.
class StreamType c

-- | Use the supplied <a>Handle</a>.
data UseHandle
UseHandle :: Handle -> UseHandle

-- | No stream handle will be passed. Use when you don't want to
--   communicate with a stream. For example, to run something silently.
data NoStream
NoStream :: NoStream

-- | Inherit the parent (current) process handle. The child will share the
--   stream. For example, if the child writes anything to stdout, it will
--   all go to the parent's stdout.
data Inherit
Inherit :: Inherit

-- | Create a new pipe for the stream. You get a new <a>Handle</a>.
data CreatePipe
CreatePipe :: CreatePipe

-- | The process type. The three type variables denote how its standard
--   streams were initialized.
data Process stdin stdout stderr

-- | The process configuration that is needed for creating new processes.
--   Use <a>proc</a> to make one.
data ProcessConf stdin stdout stderr

-- | Create a process configuration with the default settings.
proc :: RawFilePath -> [ByteString] -> ProcessConf Inherit Inherit Inherit

-- | Control how the standard input of the process will be initialized.
setStdin :: (StreamType newStdin) => ProcessConf oldStdin stdout stderr -> newStdin -> ProcessConf newStdin stdout stderr
infixl 4 `setStdin`

-- | Control how the standard output of the process will be initialized.
setStdout :: (StreamType newStdout) => ProcessConf stdin oldStdout stderr -> newStdout -> ProcessConf stdin newStdout stderr
infixl 4 `setStdout`

-- | Control how the standard error of the process will be initialized.
setStderr :: (StreamType newStderr) => ProcessConf stdin stdout oldStderr -> newStderr -> ProcessConf stdin stdout newStderr
infixl 4 `setStderr`

-- | Take a process and return its standard input handle.
processStdin :: Process CreatePipe stdout stderr -> Handle

-- | Take a process and return its standard output handle.
processStdout :: Process stdin CreatePipe stderr -> Handle

-- | Take a process and return its standard error handle.
processStderr :: Process stdin stdout CreatePipe -> Handle

-- | Start a new sub-process with the given configuration.
startProcess :: (StreamType stdin, StreamType stdout, StreamType stderr) => ProcessConf stdin stdout stderr -> IO (Process stdin stdout stderr)

-- | Stop a sub-process. For now it simply calls <a>terminateProcess</a>
--   and then <a>waitForProcess</a>.
stopProcess :: Process stdin stdout stderr -> IO ExitCode

-- | Wait (block) for a sub-process to exit and obtain its exit code.
waitForProcess :: Process stdin stdout stderr -> IO ExitCode

-- | Terminate a sub-process by sending SIGTERM to it.
terminateProcess :: Process stdin stdout stderr -> IO ()

-- | Create a new process with the given configuration, and wait for it to
--   finish.
callProcess :: ProcessConf stdin stdout stderr -> IO ExitCode

-- | Fork an external process, read its standard output and standard error
--   strictly, blocking until the process terminates, and return them with
--   the process exit code.
readProcessWithExitCode :: ProcessConf stdin stdout stderr -> IO (ExitCode, ByteString, ByteString)

-- | A literal POSIX file path
type RawFilePath = ByteString
