/usr/share/doc/libghc-text-doc/html/Data-Text-Encoding.html is in libghc-text-doc 1.2.2.2-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Data.Text.Encoding</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script src="file:///usr/share/javascript/mathjax/MathJax.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Data-Text-Encoding.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Data-Text-Encoding.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">text-1.2.2.2: An efficient packed Unicode text type.</p></div><div id="content"><div id="module-header"><table class="info"><tr><th valign="top">Copyright</th><td>(c) 2009 2010 2011 Bryan O'Sullivan<br />(c) 2009 Duncan Coutts<br />(c) 2008 2009 Tom Harper</td></tr><tr><th>License</th><td>BSD-style</td></tr><tr><th>Maintainer</th><td>bos@serpentine.com</td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Portability</th><td>portable</td></tr><tr><th>Safe Haskell</th><td>Trustworthy</td></tr><tr><th>Language</th><td>Haskell98</td></tr></table><p class="caption">Data.Text.Encoding</p></div><div id="table-of-contents"><p class="caption">Contents</p><ul><li><a href="#g:1">Decoding ByteStrings to Text</a><ul><li><a href="#g:2">Catchable failure</a></li><li><a href="#g:3">Controllable error handling</a></li><li><a href="#g:4">Stream oriented decoding</a></li></ul></li><li><a href="#g:5">Encoding Text to ByteStrings</a></li><li><a href="#g:6">Encoding Text using ByteString Builders</a></li></ul></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Functions for converting <code><a href="Data-Text.html#t:Text">Text</a></code> values to and from <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code>,
using several standard encodings.</p><p>To gain access to a much larger family of encodings, use the
<code>text-icu</code> package: <a href="http://hackage.haskell.org/package/text-icu">http://hackage.haskell.org/package/text-icu</a></p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><a href="#v:decodeASCII">decodeASCII</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeLatin1">decodeLatin1</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf8">decodeUtf8</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf16LE">decodeUtf16LE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf16BE">decodeUtf16BE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf32LE">decodeUtf32LE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf32BE">decodeUtf32BE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf8-39-">decodeUtf8'</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Either.html#t:Either">Either</a> <a href="Data-Text-Encoding-Error.html#t:UnicodeException">UnicodeException</a> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf8With">decodeUtf8With</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf16LEWith">decodeUtf16LEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf16BEWith">decodeUtf16BEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf32LEWith">decodeUtf32LEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:decodeUtf32BEWith">decodeUtf32BEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a></li><li class="src short"><a href="#v:streamDecodeUtf8">streamDecodeUtf8</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a></li><li class="src short"><a href="#v:streamDecodeUtf8With">streamDecodeUtf8With</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a></li><li class="src short"><span class="keyword">data</span> <a href="#t:Decoding">Decoding</a> = <a href="#v:Some">Some</a> <a href="Data-Text.html#t:Text">Text</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> (<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a>)</li><li class="src short"><a href="#v:encodeUtf8">encodeUtf8</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:encodeUtf16LE">encodeUtf16LE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:encodeUtf16BE">encodeUtf16BE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:encodeUtf32LE">encodeUtf32LE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:encodeUtf32BE">encodeUtf32BE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></li><li class="src short"><a href="#v:encodeUtf8Builder">encodeUtf8Builder</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a></li><li class="src short"><a href="#v:encodeUtf8BuilderEscaped">encodeUtf8BuilderEscaped</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder-Prim.html#t:BoundedPrim">BoundedPrim</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a> -> <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a></li></ul></div><div id="interface"><h1 id="g:1">Decoding ByteStrings to Text</h1><div class="doc"><p>All of the single-parameter functions for decoding bytestrings
encoded in one of the Unicode Transformation Formats (UTF) operate
in a <em>strict</em> mode: each will throw an exception if given invalid
input.</p><p>Each function has a variant, whose name is suffixed with -<code>With</code>,
that gives greater control over the handling of decoding errors.
For instance, <code><a href="Data-Text-Encoding.html#v:decodeUtf8">decodeUtf8</a></code> will throw an exception, but
<code><a href="Data-Text-Encoding.html#v:decodeUtf8With">decodeUtf8With</a></code> allows the programmer to determine what to do on a
decoding error.</p></div><div class="top"><p class="src"><a id="v:decodeASCII" class="def">decodeASCII</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeASCII" class="link">Source</a> <a href="#v:decodeASCII" class="selflink">#</a></p><div class="doc"><div class="warning"><p>Deprecated: Use decodeUtf8 instead</p></div><p><em>Deprecated</em>. Decode a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> containing 7-bit ASCII
encoded text.</p></div></div><div class="top"><p class="src"><a id="v:decodeLatin1" class="def">decodeLatin1</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeLatin1" class="link">Source</a> <a href="#v:decodeLatin1" class="selflink">#</a></p><div class="doc"><p>Decode a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> containing Latin-1 (aka ISO-8859-1) encoded text.</p><p><code><a href="Data-Text-Encoding.html#v:decodeLatin1">decodeLatin1</a></code> is semantically equivalent to
<code>Data.Text.pack . Data.ByteString.Char8.unpack</code></p></div></div><div class="top"><p class="src"><a id="v:decodeUtf8" class="def">decodeUtf8</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf8" class="link">Source</a> <a href="#v:decodeUtf8" class="selflink">#</a></p><div class="doc"><p>Decode a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> containing UTF-8 encoded text that is known
to be valid.</p><p>If the input contains any invalid UTF-8 data, an exception will be
thrown that cannot be caught in pure code. For more control over
the handling of invalid data, use <code><a href="Data-Text-Encoding.html#v:decodeUtf8-39-">decodeUtf8'</a></code> or
<code><a href="Data-Text-Encoding.html#v:decodeUtf8With">decodeUtf8With</a></code>.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf16LE" class="def">decodeUtf16LE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf16LE" class="link">Source</a> <a href="#v:decodeUtf16LE" class="selflink">#</a></p><div class="doc"><p>Decode text from little endian UTF-16 encoding.</p><p>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 <code><a href="Data-Text-Encoding.html#v:decodeUtf16LEWith">decodeUtf16LEWith</a></code>.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf16BE" class="def">decodeUtf16BE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf16BE" class="link">Source</a> <a href="#v:decodeUtf16BE" class="selflink">#</a></p><div class="doc"><p>Decode text from big endian UTF-16 encoding.</p><p>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 <code><a href="Data-Text-Encoding.html#v:decodeUtf16BEWith">decodeUtf16BEWith</a></code>.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf32LE" class="def">decodeUtf32LE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf32LE" class="link">Source</a> <a href="#v:decodeUtf32LE" class="selflink">#</a></p><div class="doc"><p>Decode text from little endian UTF-32 encoding.</p><p>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 <code><a href="Data-Text-Encoding.html#v:decodeUtf32LEWith">decodeUtf32LEWith</a></code>.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf32BE" class="def">decodeUtf32BE</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf32BE" class="link">Source</a> <a href="#v:decodeUtf32BE" class="selflink">#</a></p><div class="doc"><p>Decode text from big endian UTF-32 encoding.</p><p>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 <code><a href="Data-Text-Encoding.html#v:decodeUtf32BEWith">decodeUtf32BEWith</a></code>.</p></div></div><h2 id="g:2">Catchable failure</h2><div class="top"><p class="src"><a id="v:decodeUtf8-39-" class="def">decodeUtf8'</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Either.html#t:Either">Either</a> <a href="Data-Text-Encoding-Error.html#t:UnicodeException">UnicodeException</a> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf8%27" class="link">Source</a> <a href="#v:decodeUtf8-39-" class="selflink">#</a></p><div class="doc"><p>Decode a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> containing UTF-8 encoded text.</p><p>If the input contains any invalid UTF-8 data, the relevant
exception will be returned, otherwise the decoded text.</p></div></div><h2 id="g:3">Controllable error handling</h2><div class="top"><p class="src"><a id="v:decodeUtf8With" class="def">decodeUtf8With</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf8With" class="link">Source</a> <a href="#v:decodeUtf8With" class="selflink">#</a></p><div class="doc"><p>Decode a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> containing UTF-8 encoded text.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf16LEWith" class="def">decodeUtf16LEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf16LEWith" class="link">Source</a> <a href="#v:decodeUtf16LEWith" class="selflink">#</a></p><div class="doc"><p>Decode text from little endian UTF-16 encoding.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf16BEWith" class="def">decodeUtf16BEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf16BEWith" class="link">Source</a> <a href="#v:decodeUtf16BEWith" class="selflink">#</a></p><div class="doc"><p>Decode text from big endian UTF-16 encoding.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf32LEWith" class="def">decodeUtf32LEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf32LEWith" class="link">Source</a> <a href="#v:decodeUtf32LEWith" class="selflink">#</a></p><div class="doc"><p>Decode text from little endian UTF-32 encoding.</p></div></div><div class="top"><p class="src"><a id="v:decodeUtf32BEWith" class="def">decodeUtf32BEWith</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text.html#t:Text">Text</a> <a href="src/Data-Text-Encoding.html#decodeUtf32BEWith" class="link">Source</a> <a href="#v:decodeUtf32BEWith" class="selflink">#</a></p><div class="doc"><p>Decode text from big endian UTF-32 encoding.</p></div></div><h2 id="g:4">Stream oriented decoding</h2><div class="doc"><p>The <code><a href="Data-Text-Encoding.html#v:streamDecodeUtf8">streamDecodeUtf8</a></code> and <code><a href="Data-Text-Encoding.html#v:streamDecodeUtf8With">streamDecodeUtf8With</a></code> functions accept
a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> that represents a possibly incomplete input (e.g. a
packet from a network stream) that may not end on a UTF-8 boundary.</p><ol><li>The maximal prefix of <code><a href="Data-Text.html#t:Text">Text</a></code> that could be decoded from the
given input.</li><li>The suffix of the <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> that could not be decoded due to
insufficient input.</li><li>A function that accepts another <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code>. That string will
be assumed to directly follow the string that was passed as
input to the original function, and it will in turn be decoded.</li></ol><p>To help understand the use of these functions, consider the Unicode
string <code>"hi ☃"</code>. If encoded as UTF-8, this becomes <code>"hi
\xe2\x98\x83"</code>; the final <code>'☃'</code> is encoded as 3 bytes.</p><p>Now suppose that we receive this encoded string as 3 packets that
are split up on untidy boundaries: <code>["hi \xe2", "\x98",
"\x83"]</code>. We cannot decode the entire Unicode string until we
have received all three packets, but we would like to make progress
as we receive each one.</p><pre>ghci> let s0@(<code><a href="Data-Text-Encoding.html#v:Some">Some</a></code> _ _ f0) = <code><a href="Data-Text-Encoding.html#v:streamDecodeUtf8">streamDecodeUtf8</a></code> "hi \xe2"
ghci> s0
<code><a href="Data-Text-Encoding.html#v:Some">Some</a></code> "hi " "\xe2" _
</pre><p>We use the continuation <code>f0</code> to decode our second packet.</p><pre>ghci> let s1@(<code><a href="Data-Text-Encoding.html#v:Some">Some</a></code> _ _ f1) = f0 "\x98"
ghci> s1
<code><a href="Data-Text-Encoding.html#v:Some">Some</a></code> "" "\xe2\x98"
</pre><p>We could not give <code>f0</code> enough input to decode anything, so it
returned an empty string. Once we feed our second continuation <code>f1</code>
the last byte of input, it will make progress.</p><pre>ghci> let s2@(<code><a href="Data-Text-Encoding.html#v:Some">Some</a></code> _ _ f2) = f1 "\x83"
ghci> s2
<code><a href="Data-Text-Encoding.html#v:Some">Some</a></code> "\x2603" "" _
</pre><p>If given invalid input, an exception will be thrown by the function
or continuation where it is encountered.</p></div><div class="top"><p class="src"><a id="v:streamDecodeUtf8" class="def">streamDecodeUtf8</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a> <a href="src/Data-Text-Encoding.html#streamDecodeUtf8" class="link">Source</a> <a href="#v:streamDecodeUtf8" class="selflink">#</a></p><div class="doc"><p>Decode, in a stream oriented way, a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> containing UTF-8
encoded text that is known to be valid.</p><p>If the input contains any invalid UTF-8 data, an exception will be
thrown (either by this function or a continuation) that cannot be
caught in pure code. For more control over the handling of invalid
data, use <code><a href="Data-Text-Encoding.html#v:streamDecodeUtf8With">streamDecodeUtf8With</a></code>.</p></div></div><div class="top"><p class="src"><a id="v:streamDecodeUtf8With" class="def">streamDecodeUtf8With</a> :: <a href="Data-Text-Encoding-Error.html#t:OnDecodeError">OnDecodeError</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a> <a href="src/Data-Text-Encoding.html#streamDecodeUtf8With" class="link">Source</a> <a href="#v:streamDecodeUtf8With" class="selflink">#</a></p><div class="doc"><p>Decode, in a stream oriented way, a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a></code> containing UTF-8
encoded text.</p></div></div><div class="top"><p class="src"><span class="keyword">data</span> <a id="t:Decoding" class="def">Decoding</a> <a href="src/Data-Text-Encoding.html#Decoding" class="link">Source</a> <a href="#t:Decoding" class="selflink">#</a></p><div class="doc"><p>A stream oriented decoding result.</p></div><div class="subs constructors"><p class="caption">Constructors</p><table><tr><td class="src"><a id="v:Some" class="def">Some</a> <a href="Data-Text.html#t:Text">Text</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> (<a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> -> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a>)</td><td class="doc empty"> </td></tr></table></div><div class="subs instances"><p id="control.i:Decoding" class="caption collapser" onclick="toggleSection('i:Decoding')">Instances</p><div id="section.i:Decoding" class="show"><table><tr><td class="src clearfix"><span class="inst-left"><span id="control.i:id:Decoding:Show:1" class="instance expander" onclick="toggleSection('i:id:Decoding:Show:1')"></span> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Text-Show.html#t:Show">Show</a> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a></span> <a href="src/Data-Text-Encoding.html#line-214" class="link">Source</a> <a href="#t:Decoding" class="selflink">#</a></td><td class="doc empty"> </td></tr><tr><td colspan="2"><div id="section.i:id:Decoding:Show:1" class="inst-details hide"><div class="subs methods"><p class="caption">Methods</p><p class="src"><a href="#v:showsPrec">showsPrec</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Int.html#t:Int">Int</a> -> <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Text-Show.html#t:ShowS">ShowS</a> <a href="#v:showsPrec" class="selflink">#</a></p><p class="src"><a href="#v:show">show</a> :: <a href="Data-Text-Encoding.html#t:Decoding">Decoding</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-String.html#t:String">String</a> <a href="#v:show" class="selflink">#</a></p><p class="src"><a href="#v:showList">showList</a> :: [<a href="Data-Text-Encoding.html#t:Decoding">Decoding</a>] -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Text-Show.html#t:ShowS">ShowS</a> <a href="#v:showList" class="selflink">#</a></p></div></div></td></tr></table></div></div></div><h1 id="g:5">Encoding Text to ByteStrings</h1><div class="top"><p class="src"><a id="v:encodeUtf8" class="def">encodeUtf8</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> <a href="src/Data-Text-Encoding.html#encodeUtf8" class="link">Source</a> <a href="#v:encodeUtf8" class="selflink">#</a></p><div class="doc"><p>Encode text using UTF-8 encoding.</p></div></div><div class="top"><p class="src"><a id="v:encodeUtf16LE" class="def">encodeUtf16LE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> <a href="src/Data-Text-Encoding.html#encodeUtf16LE" class="link">Source</a> <a href="#v:encodeUtf16LE" class="selflink">#</a></p><div class="doc"><p>Encode text using little endian UTF-16 encoding.</p></div></div><div class="top"><p class="src"><a id="v:encodeUtf16BE" class="def">encodeUtf16BE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> <a href="src/Data-Text-Encoding.html#encodeUtf16BE" class="link">Source</a> <a href="#v:encodeUtf16BE" class="selflink">#</a></p><div class="doc"><p>Encode text using big endian UTF-16 encoding.</p></div></div><div class="top"><p class="src"><a id="v:encodeUtf32LE" class="def">encodeUtf32LE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> <a href="src/Data-Text-Encoding.html#encodeUtf32LE" class="link">Source</a> <a href="#v:encodeUtf32LE" class="selflink">#</a></p><div class="doc"><p>Encode text using little endian UTF-32 encoding.</p></div></div><div class="top"><p class="src"><a id="v:encodeUtf32BE" class="def">encodeUtf32BE</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString.html#t:ByteString">ByteString</a> <a href="src/Data-Text-Encoding.html#encodeUtf32BE" class="link">Source</a> <a href="#v:encodeUtf32BE" class="selflink">#</a></p><div class="doc"><p>Encode text using big endian UTF-32 encoding.</p></div></div><h1 id="g:6">Encoding Text using ByteString Builders</h1><div class="top"><p class="src"><a id="v:encodeUtf8Builder" class="def">encodeUtf8Builder</a> :: <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a> <a href="src/Data-Text-Encoding.html#encodeUtf8Builder" class="link">Source</a> <a href="#v:encodeUtf8Builder" class="selflink">#</a></p><div class="doc"><p>Encode text to a ByteString <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a></code> using UTF-8 encoding.</p></div></div><div class="top"><p class="src"><a id="v:encodeUtf8BuilderEscaped" class="def">encodeUtf8BuilderEscaped</a> :: <a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder-Prim.html#t:BoundedPrim">BoundedPrim</a> <a href="file:///usr/share/doc/ghc-doc/html/libraries/base-4.9.1.0/Data-Word.html#t:Word8">Word8</a> -> <a href="Data-Text.html#t:Text">Text</a> -> <a href="file:///usr/share/doc/ghc-doc/html/libraries/binary-0.8.3.0/Data-Binary-Builder.html#t:Builder">Builder</a> <a href="src/Data-Text-Encoding.html#encodeUtf8BuilderEscaped" class="link">Source</a> <a href="#v:encodeUtf8BuilderEscaped" class="selflink">#</a></p><div class="doc"><p>Encode text using UTF-8 encoding and escape the ASCII characters using
a <code><a href="file:///usr/share/doc/ghc-doc/html/libraries/bytestring-0.10.8.1/Data-ByteString-Builder-Prim.html#t:BoundedPrim">BoundedPrim</a></code>.</p><p>Use this function is to implement efficient encoders for text-based formats
like JSON or HTML.</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.17.3</p></div></body></html>
|