Moduleio-streams-1.5.2.2Haskell2010

System.IO.Streams.ByteString

Stream operations on ByteString.

6 types
20 values

Packageio-streams-1.5.2.2
Exports26
LanguageHaskell2010
LicenceBSD-3-Clause
SourceByteString.hs

Counting bytes

2 declarations

valuecountInput

:: InputStream ByteString
-> IO (InputStream ByteString, IO Int64)

Wraps an InputStream, counting the number of bytes produced by the stream as a side effect. Produces a new InputStream as well as an IO action to retrieve the count of bytes produced.

Strings pushed back to the returned InputStream will be pushed back to the original stream, and the count of produced bytes will be subtracted accordingly.

Example:

ghci> is <- Streams.System.IO.Streams.fromList ["abc", "def", "ghi"::ByteString]
ghci> (is', getCount) <- Streams.countInput is
ghci> Streams.read is'
Just "abc"
ghci> getCount
3
ghci> Streams.unRead "bc" is'
ghci> getCount
1
ghci> Streams.System.IO.Streams.peek is
Just "bc"
ghci> Streams.System.IO.Streams.toList is'
["bc","def","ghi"]
ghci> getCount
9

valuecountOutput

:: OutputStream ByteString
-> IO (OutputStream ByteString, IO Int64)

Wraps an OutputStream, counting the number of bytes consumed by the stream as a side effect. Produces a new OutputStream as well as an IO action to retrieve the count of bytes consumed.

Example:

ghci> (os :: OutputStream ByteString, getList) <- Streams.System.IO.Streams.listOutputStream
ghci> (os', getCount) <- Streams.countOutput os
ghci> Streams.System.IO.Streams.fromList ["abc", "def", "ghi"] >>= Streams.System.IO.Streams.connectTo os'
ghci> getList
["abc","def","ghi"]
ghci> getCount
9

Treating strings as streams

2 declarations

valuefromByteString :: ByteString -> IO (InputStream ByteString)

Creates an InputStream from a ByteString.

valuefromLazyByteString :: ByteString -> IO (InputStream ByteString)

Creates an InputStream from a lazy ByteString.

Input and output

3 declarations

valuereadExactly

:: Int
number of bytes to read
-> InputStream ByteString
input stream
-> IO ByteString

Reads an n-byte ByteString from an input stream. Throws a ReadTooShortException if fewer than n bytes were available.

Example:

ghci> Streams.System.IO.Streams.fromList ["long string"] >>= Streams.readExactly 6
"long s"
ghci> Streams.System.IO.Streams.fromList ["short"] >>= Streams.readExactly 6
*** Exception: Short read, expected 6 bytes

valuetakeBytesWhile

:: (Char -> Bool)
predicate
-> InputStream ByteString
input stream
-> IO (Maybe ByteString)

Takes from a stream until the given predicate is no longer satisfied. Returns Nothing on end-of-stream, or Just "" if the predicate is never satisfied. See takeWhile and takeWhile.

Example:

ghci> Streams.System.IO.Streams.fromList ["Hello, world!"] >>= Streams.takeBytesWhile (/= ',')
Just "Hello"
ghci> import Data.Char
ghci> Streams.System.IO.Streams.fromList ["7 Samurai"] >>= Streams.takeBytesWhile isAlpha
Just ""
ghci> Streams.System.IO.Streams.fromList [] >>= Streams.takeBytesWhile isAlpha
Nothing

valuewriteLazyByteString

:: ByteString
string to write to output
-> OutputStream ByteString
output stream
-> IO ()

Writes a lazy ByteString to an OutputStream.

Example:

ghci> Streams.writeLazyByteString "Test\n" Streams.System.IO.Streams.stdout
Test

Stream transformers

0 declarations

Splitting/Joining

valuesplitOn

:: (Char -> Bool)
predicate used to break the input stream into chunks
-> InputStream ByteString
input stream
-> IO (InputStream ByteString)

Splits an InputStream over ByteStrings using a delimiter predicate.

Note that:

data pushed back with unRead is *not* propagated upstream here.
the resulting InputStream may hold an unbounded amount of the bytestring in memory waiting for the function to return true, so this function should not be used in unsafe contexts.
the delimiter is NOT included in the output.
consecutive delimiters are not merged.
if the input ends in the delimiter, a final empty string is not emitted. (/Since: 1.5.0.0. Previous versions had the opposite behaviour, which was changed to match Prelude.lines./)

Example:

ghci> Streams.System.IO.Streams.fromList ["the quick br", "own  fox"::ByteString] >>=
      Streams.splitOn (== ' ') >>= Streams.System.IO.Streams.toList
["the","quick","brown","","fox"]

valuelines :: InputStream ByteString -> IO (InputStream ByteString)

Splits a bytestring InputStream into lines. See splitOn and lines.

Example:

ghci> is <- Streams.System.IO.Streams.fromList ["Hello,\n world!"] >>= Streams.lines
ghci> replicateM 3 (Streams.read is)
[Just "Hello", Just ", world!", Nothing]

Note that this may increase the chunk size if the input contains extremely long lines.

valueunlines :: OutputStream ByteString -> IO (OutputStream ByteString)

Intersperses string chunks sent to the given OutputStream with newlines. See intersperse and unlines.

ghci> os <- Streams.unlines Streams.System.IO.Streams.stdout
ghci> Streams.write (Just "Hello,") os
Hello
ghci> Streams.write Nothing os
ghci> Streams.write (Just "world!") os
world!

valuewords :: InputStream ByteString -> IO (InputStream ByteString)

Splits a bytestring InputStream into words. See splitOn and words.

Example:

ghci> is <- Streams.System.IO.Streams.fromList ["Hello, world!"] >>= Streams.words
ghci> replicateM 3 (Streams.read is)
[Just "Hello,", Just "world!", Nothing]

Note that this may increase the chunk size if the input contains extremely long words.

valueunwords :: OutputStream ByteString -> IO (OutputStream ByteString)

Intersperses string chunks sent to the given OutputStream with spaces. See intersperse and unwords.

ghci> os <- Streams.unwords Streams.System.IO.Streams.stdout
ghci> forM_ [Just "Hello,", Nothing, Just "world!\n"] $ w -> Streams.write w os
Hello, world!

Other

valuegiveBytes

:: Int64
maximum number of bytes to send to the wrapped stream
-> OutputStream ByteString
output stream to wrap
-> IO (OutputStream ByteString)

Wraps an OutputStream, producing a new stream that will pass along at most n bytes to the wrapped stream, throwing any subsequent input away.

Example:

ghci> (os :: OutputStream ByteString, getList) <- Streams.System.IO.Streams.listOutputStream
ghci> os' <- Streams.giveBytes 6 os
ghci> Streams.System.IO.Streams.fromList ["long ", "string"] >>= Streams.System.IO.Streams.connectTo os'
ghci> getList
["long ","s"]

valuegiveExactly

Wraps an OutputStream, producing a new stream that will pass along exactly n bytes to the wrapped stream. If the stream is sent more or fewer than the given number of bytes, the resulting stream will throw an exception (either TooFewBytesWrittenException or TooManyBytesWrittenException) during a call to write.

Example:

ghci> is <- Streams.System.IO.Streams.fromList ["ok"]
ghci> Streams.System.IO.Streams.outputToList (Streams.giveExactly 2 >=> Streams.System.IO.Streams.connect is)
["ok"]
ghci> is <- Streams.System.IO.Streams.fromList ["ok"]
ghci> Streams.System.IO.Streams.outputToList (Streams.giveExactly 1 >=> Streams.System.IO.Streams.connect is)
*** Exception: Too many bytes written
ghci> is <- Streams.System.IO.Streams.fromList ["ok"]
ghci> Streams.System.IO.Streams.outputToList (Streams.giveExactly 3 >=> Streams.System.IO.Streams.connect is)
*** Exception: Too few bytes written

valuetakeBytes

:: Int64
maximum number of bytes to read
-> InputStream ByteString
input stream to wrap
-> IO (InputStream ByteString)

Wraps an InputStream, producing a new InputStream that will produce at most n bytes, subsequently yielding end-of-stream forever.

Strings pushed back to the returned InputStream will be propagated upstream, modifying the count of taken bytes accordingly.

Example:

ghci> is <- Streams.System.IO.Streams.fromList ["truncated", " string"::ByteString]
ghci> is' <- Streams.takeBytes 9 is
ghci> Streams.read is'
Just "truncated"
ghci> Streams.read is'
Nothing
ghci> Streams.System.IO.Streams.peek is
Just " string"
ghci> Streams.unRead "cated" is'
ghci> Streams.System.IO.Streams.peek is
Just "cated"
ghci> Streams.System.IO.Streams.peek is'
Just "cated"
ghci> Streams.read is'
Just "cated"
ghci> Streams.read is'
Nothing
ghci> Streams.read is
Just " string"

valuetakeExactly

:: Int64
number of bytes to read
-> InputStream ByteString
input stream to wrap
-> IO (InputStream ByteString)

Like Streams.takeBytes, but throws ReadTooShortException when there aren't enough bytes present on the source.

valuethrowIfConsumesMoreThan

:: Int64
maximum number of bytes to send to the wrapped stream
-> OutputStream ByteString
output stream to wrap
-> IO (OutputStream ByteString)

Wraps an OutputStream, producing a new stream that will pass along at most n bytes to the wrapped stream. If more than n bytes are sent to the outer stream, a TooManyBytesWrittenException will be thrown.

Note: if more than n bytes are sent to the outer stream, throwIfConsumesMoreThan will not necessarily send the first n bytes through to the wrapped stream before throwing the exception.

Example:

ghci> (os :: OutputStream ByteString, getList) <- Streams.System.IO.Streams.listOutputStream
ghci> os' <- Streams.throwIfConsumesMoreThan 5 os
ghci> Streams.System.IO.Streams.fromList ["short"] >>= Streams.System.IO.Streams.connectTo os'
ghci> getList
["short"]
ghci> os'' <- Streams.throwIfConsumesMoreThan 5 os
ghci> Streams.System.IO.Streams.fromList ["long", "string"] >>= Streams.System.IO.Streams.connectTo os''
*** Exception: Too many bytes written

valuethrowIfProducesMoreThan

:: Int64
maximum number of bytes to read
-> InputStream ByteString
input stream
-> IO (InputStream ByteString)

Wraps an InputStream. If more than n bytes are produced by this stream, read will throw a TooManyBytesReadException.

If a chunk yielded by the input stream would result in more than n bytes being produced, throwIfProducesMoreThan will cut the generated string such that exactly n bytes are yielded by the returned stream, and the subsequent read will throw an exception. Example:

ghci> is <- Streams.System.IO.Streams.fromList ["abc", "def", "ghi"] >>=
            Streams.throwIfProducesMoreThan 5
ghci> replicateM 2 (read is)
[Just "abc",Just "de"]
ghci> Streams.read is
*** Exception: Too many bytes read

Strings pushed back to the returned InputStream will be propagated upstream, modifying the count of taken bytes accordingly. Example:

ghci> is  <- Streams.System.IO.Streams.fromList ["abc", "def", "ghi"]
ghci> is' <- Streams.throwIfProducesMoreThan 5 is
ghci> Streams.read is'
Just "abc"
ghci> Streams.unRead "xyz" is'
ghci> Streams.System.IO.Streams.peek is
Just "xyz"
ghci> Streams.read is
Just "xyz"
ghci> Streams.read is
Just "de"
ghci> Streams.read is
*** Exception: Too many bytes read

Rate limiting

valuethrowIfTooSlow

:: IO ()
action to bump timeout
-> Double
minimum data rate, in bytes per second
-> Int
amount of time in seconds to wait before data rate calculation takes effect
-> InputStream ByteString
input stream
-> IO (InputStream ByteString)

Rate-limits an input stream. If the input stream is not read from faster than the given rate, reading from the wrapped stream will throw a RateTooSlowException.

Strings pushed back to the returned InputStream will be propagated up to the original stream.

String search

2 declarations

datadata MatchInfo

MatchInfo provides match information when performing string search.

Constructors

Match !ByteString
NoMatch !ByteString

Instances2Eq, Show

Eq MatchInfoDefined in io-streams-1.5.2.2 · System.IO.Streams.Internal.Search
Show MatchInfoDefined in io-streams-1.5.2.2 · System.IO.Streams.Internal.Search

valuesearch

:: ByteString
"needle" to look for
-> InputStream ByteString
input stream to wrap
-> IO (InputStream MatchInfo)

Given a ByteString to look for (the "needle") and an InputStream, produces a new InputStream which yields data of type MatchInfo.

Example:

ghci> System.IO.Streams.fromList ["food", "oof", "oodles", "ok"] >>=
      search "foo" >>= System.IO.Streams.toList
[Match "foo",NoMatch "d",NoMatch "oo",Match "foo",NoMatch "dlesok"]

Uses the Boyer-Moore-Horspool algorithm (http://en.wikipedia.org/wiki/Boyer%E2%80%93Moore%E2%80%93Horspool_algorithm).

Exception types

5 declarations

datadata RateTooSlowException

Thrown by throwIfTooSlow if input is not being produced fast enough by the given InputStream.

Instances2Show, Exception

Show RateTooSlowExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString
Exception RateTooSlowExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString

datadata ReadTooShortException

Thrown by readExactly and takeExactly when not enough bytes were available on the input.

Instances2Show, Exception

Show ReadTooShortExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString
Exception ReadTooShortExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString

datadata TooManyBytesReadException

Thrown by throwIfProducesMoreThan when too many bytes were read from the original InputStream.

Instances2Show, Exception

Show TooManyBytesReadExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString
Exception TooManyBytesReadExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString

datadata TooManyBytesWrittenException

Thrown by throwIfConsumesMoreThan when too many bytes were sent to the produced OutputStream.

Instances2Show, Exception

Show TooManyBytesWrittenExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString
Exception TooManyBytesWrittenExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString

datadata TooFewBytesWrittenException

Thrown by giveExactly when too few bytes were written to the produced OutputStream.

Instances2Show, Exception

Show TooFewBytesWrittenExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString
Exception TooFewBytesWrittenExceptionDefined in io-streams-1.5.2.2 · System.IO.Streams.ByteString