@@ -172,11 +172,15 @@ decodeUtf8With onErr (PS fp off len) = runText $ \done -> do
172-- a 'ByteString' that represents a possibly incomplete input (e.g. a
172-- a 'ByteString' that represents a possibly incomplete input (e.g. a
173-- packet from a network stream) that may not end on a UTF-8 boundary.
173-- packet from a network stream) that may not end on a UTF-8 boundary.
175−-- The first element of the result is the maximal chunk of 'Text' that
175+-- 1. The maximal prefix of 'Text' that could be decoded from the
176−-- can be decoded from the given input. The second is a function which
176+-- given input.
178+-- 2. The suffix of the 'ByteString' that could not be decoded due to
179+-- insufficient input.
177−-- accepts another 'ByteString'. That string will be assumed to
181+-- 3. A function that accepts another 'ByteString'. That string will
178−-- directly follow the string that was passed as input to the original
182+-- be assumed to directly follow the string that was passed as
179−-- function, and it will in turn be decoded.
183+-- input to the original function, and it will in turn be decoded.
181-- To help understand the use of these functions, consider the Unicode
185-- To help understand the use of these functions, consider the Unicode
182-- string @\"hi ☃\"@. If encoded as UTF-8, this becomes @\"hi
186-- string @\"hi ☃\"@. If encoded as UTF-8, this becomes @\"hi
@@ -189,15 +193,17 @@ decodeUtf8With onErr (PS fp off len) = runText $ \done -> do
189-- as we receive each one.
193-- as we receive each one.
192−-- let 'Some' t0 f0 = 'streamDecodeUtf8' \"hi \\xe2\"
196+-- ghci> let s0\@('Some' _ _ f0) = 'streamDecodeUtf8' \"hi \\xe2\"
193−-- t0 == \"hi \" :: 'Text'
197+-- ghci> s0
198+-- 'Some' \"hi \" \"\\xe2\" _
196-- We use the continuation @f0@ to decode our second packet.
201-- We use the continuation @f0@ to decode our second packet.
199−-- let 'Some' t1 f1 = f0 \"\\x98\"
204+-- ghci> let s1\@('Some' _ _ f1) = f0 \"\\x98\"
200−-- t1 == \"\"
205+-- ghci> s1
206+-- 'Some' \"\" \"\\xe2\\x98\"
203-- We could not give @f0@ enough input to decode anything, so it
209-- We could not give @f0@ enough input to decode anything, so it
@@ -205,8 +211,9 @@ decodeUtf8With onErr (PS fp off len) = runText $ \done -> do
205-- the last byte of input, it will make progress.
211-- the last byte of input, it will make progress.
208−-- let 'Some' t2 f2 = f1 \"\\x83\"
214+-- ghci> let s2\@('Some' _ _ f2) = f1 \"\\x83\"
209−-- t2 == \"☃\"
215+-- ghci> s2
216+-- 'Some' \"\\x2603\" \"\" _
212-- If given invalid input, an exception will be thrown by the function
219-- If given invalid input, an exception will be thrown by the function