/fparsec/main/Doc/html/reference/charstream.html
HTML | 1839 lines | 1804 code | 29 blank | 6 comment | 0 complexity | 0eb8354014409e44363fac4b55d0b5f9 MD5 | raw file
- <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
- <html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
- <title>FParsec.CharStream</title>
- <link rel="stylesheet" type="text/css" media="all" href="../css/style.css" />
- <link rel="stylesheet" type="text/css" media="screen" href="../css/screen-sidebar.css" title="Sidebar" />
- <link rel="alternate stylesheet" type="text/css" media="screen" href="../css/screen-no-sidebar.css" title="No sidebar" />
- <!--[if IE]>
- <link rel="stylesheet" type="text/css" media="all" href="../css/style-ie.css" />
- <![endif]-->
- <!--[if IE 6]>
- <link rel="stylesheet" type="text/css" media="all" href="../css/style-ie6.css" />
- <![endif]-->
- <link rel="stylesheet" type="text/css" media="print" href="../css/print.css" />
- </head>
- <body>
- <div id="fixed-layer">
- <div id="fixed-wrapper">
- <div id="sidebar">
- <div id="breadcrumbs-dummy"><span class="breadcrumbs"> </span></div>
- <div id="nav-tree">
- <table class="nav n1">
- <tbody class="nav-open n1">
- <tr class="nav-entry n1 _1">
- <td class="nav-number n1"></td>
- <td class="nav-title n1"><a href="../index.html">FParsec Documentation</a></td>
- </tr>
- <tr class="nav-sub-entries n1 _1">
- <td class="nav-sub-entries-number n1"></td>
- <td class="nav-sub-entries n1">
- <table class="nav n2">
- <tbody class="nav-before-open n2">
- <tr class="nav-entry n2 _1">
- <td class="nav-number n2"><a href="../tutorial.html"><span class="section-number">1</span><span class="nav-space"></span></a></td>
- <td class="nav-title n2"><a href="../tutorial.html">Tutorial</a></td>
- </tr>
- </tbody>
- <tbody class="nav-open n2">
- <tr class="nav-entry n2 _2">
- <td class="nav-number n2"><a href="index.html"><span class="section-number">2</span><span class="nav-space"></span></a></td>
- <td class="nav-title n2"><a href="index.html">Reference</a></td>
- </tr>
- <tr class="nav-sub-entries n2 _2">
- <td class="nav-sub-entries-number n2"></td>
- <td class="nav-sub-entries n2">
- <table class="nav n3">
- <tbody class="nav-before-open n3">
- <tr class="nav-entry n3 _1">
- <td class="nav-number n3"><a href="parser-overview.html"><span class="section-number">1</span><span class="nav-space"></span></a></td>
- <td class="nav-title n3"><a href="parser-overview.html">Parser overview</a></td>
- </tr>
- <tr class="nav-entry n3 _2">
- <td class="nav-number n3"><a href="primitives.html"><span class="section-number">2</span><span class="nav-space"></span></a></td>
- <td class="nav-title n3"><a href="primitives.html">FParsec.Primitives</a></td>
- </tr>
- <tr class="nav-entry n3 _3">
- <td class="nav-number n3"><a href="charparsers.html"><span class="section-number">3</span><span class="nav-space"></span></a></td>
- <td class="nav-title n3"><a href="charparsers.html">FParsec.CharParsers</a></td>
- </tr>
- <tr class="nav-entry n3 _4">
- <td class="nav-number n3">
- <a href="operatorprecedenceparser.html"><span class="section-number">4</span><span class="nav-space"></span></a>
- </td>
- <td class="nav-title n3"><a href="operatorprecedenceparser.html">FParsec.OperatorPrecedenceParser</a></td>
- </tr>
- <tr class="nav-entry n3 _5">
- <td class="nav-number n3"><a href="error.html"><span class="section-number">5</span><span class="nav-space"></span></a></td>
- <td class="nav-title n3"><a href="error.html">FParsec.Error</a></td>
- </tr>
- <tr class="nav-entry n3 _6">
- <td class="nav-number n3"><a href="state.html"><span class="section-number">6</span><span class="nav-space"></span></a></td>
- <td class="nav-title n3"><a href="state.html">FParsec.State</a></td>
- </tr>
- <tr class="nav-entry n3 _7">
- <td class="nav-number n3"><a href="position.html"><span class="section-number">7</span><span class="nav-space"></span></a></td>
- <td class="nav-title n3"><a href="position.html">FParsec.Position</a></td>
- </tr>
- </tbody>
- <tbody class="nav-open selected n3">
- <tr class="nav-entry selected n3 _8">
- <td class="nav-number selected n3"><a href="#"><span class="section-number">8</span><span class="nav-space"></span></a></td>
- <td class="nav-title selected n3"><a href="#">FParsec.CharStream</a></td>
- </tr>
- <tr class="nav-sub-entries selected n3 _8">
- <td class="nav-sub-entries-number selected n3"></td>
- <td class="nav-sub-entries selected n3">
- <table class="nav n4">
- <tbody class="nav-before-open n4">
- <tr class="nav-entry n4 _1">
- <td class="nav-number n4"><a href="#interface"><span class="section-number">1</span><span class="nav-space"></span></a></td>
- <td class="nav-title n4"><a href="#interface">Interface</a></td>
- </tr>
- <tr class="nav-entry n4 _2">
- <td class="nav-number n4"><a href="#remarks"><span class="section-number">2</span><span class="nav-space"></span></a></td>
- <td class="nav-title n4"><a href="#remarks">Remarks</a></td>
- </tr>
- <tr class="nav-entry n4 _3">
- <td class="nav-number n4"><a href="#exceptions"><span class="section-number">3</span><span class="nav-space"></span></a></td>
- <td class="nav-title n4"><a href="#exceptions">I/O exceptions</a></td>
- </tr>
- <tr class="nav-entry n4 _4">
- <td class="nav-number n4"><a href="#members"><span class="section-number">4</span><span class="nav-space"></span></a></td>
- <td class="nav-title n4"><a href="#members">Members</a></td>
- </tr>
- <tr class="nav-entry n4 _5">
- <td class="nav-number n4"><a href="#Iterator"><span class="section-number">5</span><span class="nav-space"></span></a></td>
- <td class="nav-title n4"><a href="#Iterator">CharStream.Iterator</a></td>
- </tr>
- <tr class="nav-sub-entries n4 _5">
- <td class="nav-sub-entries-number n4"></td>
- <td class="nav-sub-entries n4">
- <table class="nav n5">
- <tbody class="nav-before-open n5">
- <tr class="nav-entry n5 _1">
- <td class="nav-number n5">
- <a href="#Iterator.interface"><span class="section-number">1</span><span class="nav-space"></span></a>
- </td>
- <td class="nav-title n5"><a href="#Iterator.interface">Interface</a></td>
- </tr>
- <tr class="nav-entry n5 _2">
- <td class="nav-number n5">
- <a href="#Iterator.members"><span class="section-number">2</span><span class="nav-space"></span></a>
- </td>
- <td class="nav-title n5"><a href="#Iterator.members">Members</a></td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
- </table>
- </td>
- </tr>
- </tbody>
- </table>
- </div>
- </div>
- </div>
- </div>
- <div id="wrapper">
- <div id="main">
- <div id="main-content">
- <div id="breadcrumbs">
- <span class="breadcrumbs">
- <span id="breadcrumbs-parents"><a href="../index.html">FParsec Documentation</a><span class="breadcrumbs-sep"> > </span><a href="index.html">Reference</a></span><span class="breadcrumbs-sep"> > </span>FParsec.CharStream
- </span>
- </div>
- <div class="section s2">
- <h1 class="title h2"><span class="section-number">2.8</span> FParsec.CharStream</h1>
- <div class="intro i2">
- <p class="para _1">
- The <code class="fsharp"><span class="ci">CharStream</span></code> class provides a unified interface for reading the UTF‐16 char content from
- binary streams or in‐memory char buffers.
- </p>
- </div>
- <div id="interface" class="section s3">
- <h2 class="title h3"><span class="section-number">2.8.1</span> Interface</h2>
- <div class="intro i3">
- <div class="para _1">
- <pre class="code fsharp"><span class="ck">namespace</span> <span class="ci">FParsec</span>
- <span class="cp">[<</span><span class="ci">Sealed</span><span class="cp">>]</span>
- <span class="ck">type</span> <span class="ci">CharStream</span> <span class="cp">=</span>
- <span class="ck">interface</span> <span class="ci">System</span><span class="cm">.</span><span class="ci">IDisposable</span>
- <a id="interface.new_string:B:" href="#members.new_string"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_string_offset:B:" href="#members.new_string_offset"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">streamBeginIndex</span><span class="cp">:</span> <span class="ci">int64</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_char-array:B:" href="#members.new_char-array"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_char-array_offset:B:" href="#members.new_char-array_offset"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">streamBeginIndex</span><span class="cp">:</span> <span class="ci">int64</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_char-pointer:B:" href="#members.new_char-pointer"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_char-pointer_offset:B:" href="#members.new_char-pointer_offset"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">streamBeginIndex</span><span class="cp">:</span> <span class="ci">int64</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_file-path:B:" href="#members.new_file-path"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">path</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_file-path_2:B:" href="#members.new_file-path_2"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">path</span><span class="cp">:</span> <span class="ci">string</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_file-path_3:B:" href="#members.new_file-path_3"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">path</span><span class="cp">:</span> <span class="ci">string</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">blockSize</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">blockOverlap</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">minRegexSpace</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_stream:B:" href="#members.new_stream"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_stream_2:B:" href="#members.new_stream_2"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">leaveOpen</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_stream_3:B:" href="#members.new_stream_3"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">leaveOpen</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <a id="interface.new_stream_4:B:" href="#members.new_stream_4"><span class="interface-member-marker"><span class="ck">new</span></span></a><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">leaveOpen</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">blockSize</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">blockOverlap</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">minRegexSpace</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- <span class="ck">member</span> <a id="interface.Dispose:B:" href="#members.Dispose"><span class="interface-member-marker"><span class="ci">Dispose</span></span></a><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">unit</span>
- <span class="ck">member</span> <a id="interface.Begin:B:" href="#members.Begin"><span class="interface-member-marker"><span class="ci">Begin</span></span></a><span class="cp">:</span> <a href="#Iterator"><span class="ci">Iterator</span></a>
- <span class="ck">member</span> <a id="interface.Seek:B:" href="#members.Seek"><span class="interface-member-marker"><span class="ci">Seek</span></span></a><span class="cp">:</span> <span class="ci">int64</span> <span class="cr">-></span> <a href="#Iterator"><span class="ci">Iterator</span></a>
- <span class="ck">member</span> <a id="interface.BeginIndex:B:" href="#members.BeginIndex"><span class="interface-member-marker"><span class="ci">BeginIndex</span></span></a><span class="cp">:</span> <span class="ci">int64</span>
- <span class="ck">member</span> <a id="interface.EndIndex:B:" href="#members.EndIndex"><span class="interface-member-marker"><span class="ci">EndIndex</span></span></a><span class="cp">:</span> <span class="ci">int64</span>
- <span class="ck">static</span> <span class="ck">member</span> <a id="interface.FoldCase:B:" href="#members.FoldCase"><span class="interface-member-marker"><span class="ci">FoldCase</span></span></a><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">string</span>
- <span class="ck">static</span> <span class="ck">member</span> <a id="interface.NormalizeNewlines:B:" href="#members.NormalizeNewlines"><span class="interface-member-marker"><span class="ci">NormalizeNewlines</span></span></a><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">string</span>
- <span class="cp">[<</span><span class="ci">Struct</span><span class="cp">>]</span>
- <span class="ck">type</span> <span class="bold"><a href="#Iterator"><span class="ci">Iterator</span></a></span> <span class="cp">=</span> <span class="cbc"><span class="left-delimiter">(*</span> see below <span class="right-delimiter">*)</span></span>
- </pre>
- </div>
- </div>
- </div>
- <div id="remarks" class="section s3">
- <h2 class="title h3"><span class="section-number">2.8.2</span> Remarks</h2>
- <div class="intro i3">
- <p class="para _1">
- The <code class="fsharp"><span class="ci">CharStream</span></code> class provides an <a
- href="http://en.wikipedia.org/wiki/Iterator">iterator‐based</a> interface for reading UTF‐16 chars from a binary stream or an in‐memory char
- buffer (e.g. a string). It is optimized for use in backtracking parser applications and supports arbitrary <em>char‐based</em> seeking, even for
- streams larger than physical memory.
- </p>
- <p class="para _2">
- A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path reads the stream block‐wise and only holds
- the most recently accessed block in memory. The blocks overlap in order to provide efficient access on the boundary between blocks.
- </p>
- <p class="para _3">
- If the char content is already available as a string or a char array, a <code class="fsharp"><span class="ci">CharStream</span></code> can be
- directly constructed from the char buffer (without needing to copy the buffer). The overhead of accessing an in‐memory char buffer through a
- <code class="fsharp"><span class="ci">CharStream</span></code> is minimal.
- </p>
- <p class="para _4">
- You can access the content of a <code class="fsharp"><span class="ci">CharStream</span></code> only through its <code class="fsharp"><a
- href="#Iterator"><span class="ci">Iterator</span></a></code> instances. The <code class="fsharp"><a href="#members.Begin"><span
- class="ci">Begin</span></a></code> property returns an iterator pointing to the first char in the stream. The <code class="fsharp"><a
- href="#members.Seek"><span class="ci">Seek</span></a></code> method returns an iterator pointing to the char with a given index.
- </p>
- <div class="para _5">
- <div class="dl multi-para">
- <dl class="dl multi-para">
- <dt class="_1"><a id="remarks.low-trust-version"></a>Low‐Trust version</dt>
- <dd class="_1">
- <div class="para _1">
- <p>
- If you compile FParsec with the <code class="fsharp"><span class="ci">LOW_TRUST</span></code> conditional compiler symbol, the <code
- class="fsharp"><span class="ci">CharStream</span></code> class differs from the normal version as follows:
- </p>
- <ul class="l1">
- <li class="_1">
- No <a href="http://msdn.microsoft.com/en-us/library/t2yzs44b.aspx">unverifiable code</a> involving pointers is used. <em>This allows
- FParsec to be executed in an environment with reduced trust</em>, such as medium trust ASP.NET applications.
- </li>
- <li class="_2">
- A <code class="fsharp"><span class="ci">CharStream</span></code> that is constructed from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path reads the complete file into a single
- string during construction. <em>This severely limits the maximum practical stream size.</em>
- </li>
- <li class="_3">
- Although the <code class="fsharp"><span class="ci">CharStream</span></code> class still supports the <code class="fsharp"><span
- class="ci">IDisposable</span></code> interface, disposing the <code class="fsharp"><span class="ci">CharStream</span></code> instances is
- no longer necessary, since no resources are hold that need to be explicitly released.
- </li>
- </ul>
- </div>
- </dd>
- <dt class="_2"><a id="remarks.non-sequential-access"></a>Non‐sequential access</dt>
- <dd class="_2">
- <p class="para _1">
- <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span><br /> If you construct a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path and you backtrack over a distance long
- enough to require the <code class="fsharp"><span class="ci">CharStream</span></code> to reread a previous block, then the underlying
- <strong>byte stream needs to support seeking</strong>, otherwise a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.notsupportedexception.aspx"><span class="ci">NotSupportedException</span></a></code> is
- thrown. Furthermore, the <strong><a href="http://msdn.microsoft.com/en-us/library/system.text.decoder.aspx">Decoder</a> for the input <a
- href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx">Encoding</a> must be serializable</strong> if you backtrack to a
- block other than the first in the stream. Note that <em>file streams created for regular disk files are always seekable and all the .NET
- standard decoders are serializable</em>. In order to support non‐seekable streams for applications which don’t require extensive
- backtracking, no exception will be thrown before an operation actually requires backtracking and the necessary capabilities of the stream or
- decoder are not available.
- </p>
- </dd>
- <dt class="_3">Decoder errors</dt>
- <dd class="_3">
- <p class="para _1">
- A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a binary input stream decodes the input data with the help
- of a <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.text.decoder.aspx"><span
- class="ci">Decoder</span></a></code> instance obtained via the <code class="fsharp"><span class="ci">Encodings</span></code>’s <code
- class="fsharp"><span class="ci">GetDecoder</span></code> method. Depending on the configuration of the encoding the decoder might throw an
- exception if it encounters invalid byte sequences, usually a <code class="fsharp"><span class="ci">System</span><span
- class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><a
- href="http://msdn.microsoft.com/en-us/library/system.text.decoderfallbackexception.aspx"><span
- class="ci">DecoderFallbackException</span></a></code> or a <code class="fsharp"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><a href="http://msdn.microsoft.com/en-us/library/system.argumentexception.aspx"><span
- class="ci">ArgumentException</span></a></code>. <sup class="fn-mark"><a id="remarks.:FN:1:B:" href="#remarks.:FN:1">[1]</a></sup>
- </p>
- </dd>
- <dt class="_4"><a id="remarks.case-insensitive-matching"></a>Case‐insensitive matching</dt>
- <dd class="_4">
- <p class="para _1">
- The <code class="fsharp"><a href="#Iterator.members.MatchCaseFolded"><span class="ci">MatchCaseFolded</span></a></code> member matches the
- content of the stream “case‐insensitively” with a reference string. In this instance “case‐insensitive” means
- that before the chars are matched with the reference string they are <a
- href="http://unicode.org/reports/tr21/tr21-5.html#Caseless_Matching">mapped to a canonical form where case differences are erased</a>. For
- performance reasons <code class="fsharp"><a href="#Iterator.members.MatchCaseFolded"><span class="ci">MatchCaseFolded</span></a></code> only
- applies the (non‐Turkic) 1‐to‐1 <a href="http://unicode.org/Public/UNIDATA/CaseFolding.txt">case folding mappings</a> (v. 5.1) for Unicode
- code points in the Basic Multilingual Plane, i.e. code points below 0x10000. These mappings are sufficient for many case‐insensitive parser
- grammars encountered in practice, but they are not appropriate for matching arbitrary natural language content. Also note that the <code
- class="fsharp"><span class="ci">CharStream</span></code> class performs no Unicode <a
- href="http://unicode.org/reports/tr15/">normalization</a>.
- </p>
- </dd>
- <dt class="_5">Newlines</dt>
- <dd class="_5">
- <p class="para _1">
- The <code class="fsharp"><span class="ci">CharStream</span></code> class itself does not apply any automatic newline conversion to the
- processed input. A useful helper function for this purpose is <code class="fsharp"><a href="#members.NormalizeNewlines"><span
- class="ci">NormalizeNewlines</span></a></code>, which replaces all ASCII newline character sequences (<code class="fsharp"><span
- class="cs"><span class="left-delimiter">"</span><span class="ce">\n</span><span class="right-delimiter">"</span></span></code>, <code
- class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span class="ce">\r</span><span class="ce">\n</span><span
- class="right-delimiter">"</span></span></code> or <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span
- class="ce">\r</span><span class="right-delimiter">"</span></span></code>) in a given string with <code class="fsharp"><span class="cs"><span
- class="left-delimiter">"</span><span class="ce">\n</span><span class="right-delimiter">"</span></span></code>.
- </p>
- </dd>
- <dt class="_6">Disposable interface</dt>
- <dd class="_6">
- <p class="para _1">
- <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span><br /> A <code class="fsharp"><span class="ci">CharStream</span></code> holds managed and unmanaged resources that need
- to be explicitly released. Hence, it is very important that <code class="fsharp"><span class="ci">CharStream</span></code> objects are
- promptly disposed after use. Where possible <code class="fsharp"><span class="ci">CharStream</span></code> objects should only be used within
- a “using” block (C#), a “use” expression( F#) or similar constructs in other languages. Members of <code
- class="fsharp"><a href="#Iterator"><span class="ci">CharStream</span><span class="cm">.</span><span class="ci">Iterator</span></a></code>
- instances must not be accessed after the corresponding <code class="fsharp"><span class="ci">CharStream</span></code> has been disposed, of
- course.
- </p>
- </dd>
- <dt class="_7">Thread safety</dt>
- <dd class="_7">
- <p class="para _1">
- A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path is not thread safe and its members may
- not be accessed by multiple threads, except in the <a href="#remarks.low-trust-version">Low‐Trust version</a> of FParsec. A <code
- class="fsharp"><span class="ci">CharStream</span></code> constructed directly from a string, char array or char pointer can always be safely
- accessed concurrently using different <code class="fsharp"><span class="ci">Iterators</span></code> (provided that the <code
- class="fsharp"><span class="ci">CharStream</span></code> is disposed by only one thread, of course). <span class="italic"><code
- class="fsharp"><a href="#Iterator"><span class="ci">CharStream</span><span class="cm">.</span><span class="ci">Iterator</span></a></code>
- instances are never thread safe.</span>
- </p>
- </dd>
- </dl>
- </div>
- </div>
- </div>
- </div>
- <div id="exceptions" class="section s3">
- <h2 class="title h3"><span class="section-number">2.8.3</span> I/O exceptions</h2>
- <div class="intro i3">
- <p class="para _1">
- If you construct a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path, any <code class="fsharp"><span
- class="ci">CharStream</span></code> operation that requires reading chars from the underlying byte stream may throw one of the following
- exceptions.
- </p>
- <p class="para _2">
- In general it is <em>not</em> safe to continue to use a <code class="fsharp"><span class="ci">CharStream</span></code> instance after one of
- these exceptions was thrown. Calling <code class="fsharp"><a href="#members.Dispose"><span class="ci">Dispose</span></a><span
- class="cp">()</span></code> on an <code class="fsharp"><span class="ci">CharStream</span></code> instance after the instance or one of its
- iterators has thrown an exception is always safe.
- </p>
- <div class="para _3">
- <div class="dl multi-para">
- <dl class="dl multi-para">
- <dt class="_1"><code class="fsharp"><span class="ci">NotSupportedException</span></code></dt>
- <dd class="_1">
- <p class="para _1">
- Seeking of the underlying byte stream is required, but the byte stream does not support seeking or the <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">Encoding</span></a></code>’s <code
- class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.text.decoder.aspx"><span class="ci">Decoder</span></a></code> is not
- serializable. See also the remarks above on <a href="#remarks.non-sequential-access">non‐sequential access</a>.
- </p>
- </dd>
- <dt class="_2"><code class="fsharp"><span class="ci">IOException</span></code></dt>
- <dd class="_2">
- <p class="para _1">An I/O occured while reading data from the underlying byte stream.</p>
- </dd>
- <dt class="_3"><code class="fsharp"><span class="ci">ArgumentException</span></code></dt>
- <dd class="_3">
- <p class="para _1">
- The underlying byte stream contains invalid bytes and the <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">Encoding</span></a></code> was constructed with the
- <code class="fsharp"><span class="ci">throwOnInvalidBytes</span></code> option.
- </p>
- </dd>
- <dt class="_4"><code class="fsharp"><span class="ci">DecoderFallbackException</span></code></dt>
- <dd class="_4">
- <p class="para _1">The underlying byte stream contains invalid bytes for which the decoder fallback threw this exception.</p>
- <p class="para _2">
- The byte index of the invalid bytes in the stream is stored as a boxed <code class="fsharp"><span class="ci">System</span><span
- class="cm">.</span><span class="ci">Int64</span></code> in the <code class="fsharp"><span class="cs"><span
- class="left-delimiter">"</span>Stream.Position<span class="right-delimiter">"</span></span></code> entry of the <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.exception.data.aspx"><span class="ci">Data</span></a></code> member of the exception
- instance. The precision of the index depends on the precision of the <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.text.decoderfallbackexception.aspx"><span
- class="ci">DecoderFallbackException</span></a></code>’s <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.text.decoderfallbackexception.index.aspx"><span class="ci">Index</span></a></code>
- member. If the underlying <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span
- class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code>
- is not seekable, the byte index only takes into account the bytes read by the <code class="fsharp"><span class="ci">CharStream</span></code>,
- but not any bytes read before the <code class="fsharp"><span class="ci">CharStream</span></code> was constructed.
- </p>
- </dd>
- </dl>
- </div>
- </div>
- </div>
- </div>
- <div id="members" class="section s3">
- <h2 class="title h3"><span class="section-number">2.8.4</span> Members</h2>
- <div class="intro i3">
- <div class="para _1">
- <div class="interface-members">
- <div class="interface-member _1" id="members.new_string">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_string:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Is equivalent to <code class="fsharp"><a href="#members.new_string_offset"><span class="ck">new</span> <span
- class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">chars</span><span class="cp">,</span> <span
- class="ci">index</span><span class="cp">,</span> <span class="ci">length</span><span class="cp">,</span> <span class="cn">0L</span><span
- class="cp">)</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _2" id="members.new_string_offset">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_string_offset:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">streamBeginIndex</span><span class="cp">:</span> <span class="ci">int64</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from the chars in the string argument between the indices <code
- class="fsharp"><span class="ci">index</span></code> (inclusive) and <code class="fsharp"><span class="ci">index</span> <span
- class="co">+</span> <span class="ci">length</span></code> (exclusive). By directly referencing the chars in the string this constructor
- avoids any copy of the string content.
- </p>
- <p class="para _2">
- The first char in the stream is assigned the index <code class="fsharp"><span class="ci">streamBeginIndex</span></code>. A positive <code
- class="fsharp"><span class="ci">streamBeginIndex</span></code> allows you for example to create a substream of another <code
- class="fsharp"><span class="ci">CharStream</span></code>, i.e. a <code class="fsharp"><span class="ci">CharStream</span></code> instance that
- only contains a sub‐segment of another char stream but is accessible through the same char indices.
- </p>
- <div class="para _3">
- <p>
- <code class="fsharp"><span class="ci">chars</span></code> must not be null. An <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions:
- </p>
- <ul class="l1">
- <li class="_1">
- <code class="fsharp"><span class="ci">index</span></code> ≥ 0, <code class="fsharp"><span class="ci">length</span></code> ≥ 0, <code
- class="fsharp"><span class="ci">index</span></code> + <code class="fsharp"><span class="ci">length</span></code> ≤ <code
- class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code> and
- </li>
- <li class="_2">0 ≤ <code class="fsharp"><span class="ci">streamBeginIndex</span></code> < 2<sup>60</sup>.</li>
- </ul>
- </div>
- <div class="para _4">
- <div class="admonition">
- <div class="admonition-title">Important</div>
- <div class="admonition-body">
- <p class="para _1">
- <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span><br /> The given string is “<a
- href="http://msdn.microsoft.com/en-us/library/83y4ak54.aspx">pinned</a>” until the <code class="fsharp"><span
- class="ci">CharStream</span></code> is disposed. Pinning the string prevents the GC from moving it around in memory during garbage
- collection. On .NET (at least in versions up to and including 4.0) the pinning has no effect if the string is large enough to be allocated
- on the Large Object Heap, i.e. has a length of about 42500 chars or more. However, pinning smaller strings does constrain the normal
- operations of the GC. Thus, <strong>to minimize the negative impact on the GC, you should dispose <code class="fsharp"><span
- class="ci">CharStream</span></code> instances constructed from small strings as soon as you’re done parsing it</strong>. If you keep a
- large number of <code class="fsharp"><span class="ci">CharStream</span></code> instances constructed from small strings around for an
- extended period of time, you risk fragmenting the heap.
- </p>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="interface-member _3" id="members.new_char-array">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_char-array:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">Low‐Trust version</a>
- of FParsec.</span></span>
- </p>
- <p class="para _2">
- Is equivalent to <code class="fsharp"><a href="#members.new_char-array_offset"><span class="ck">new</span> <span
- class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">chars</span><span class="cp">,</span> <span
- class="ci">index</span><span class="cp">,</span> <span class="ci">length</span><span class="cp">,</span> <span class="cn">0L</span><span
- class="cp">)</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _4" id="members.new_char-array_offset">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_char-array_offset:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">index</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">streamBeginIndex</span><span class="cp">:</span> <span class="ci">int64</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">Low‐Trust version</a>
- of FParsec.</span></span>
- </p>
- <p class="para _2">
- Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from the chars in the char array argument between the indices
- <code class="fsharp"><span class="ci">index</span></code> (inclusive) and <code class="fsharp"><span class="ci">index</span> <span
- class="co">+</span> <span class="ci">length</span></code> (exclusive). By directly referencing the chars in the char array this constructor
- avoids any copy of the char array content.
- </p>
- <p class="para _3">
- The first char in the stream is assigned the index <code class="fsharp"><span class="ci">streamBeginIndex</span></code>. A positive <code
- class="fsharp"><span class="ci">streamBeginIndex</span></code> allows you for example to create a substream of another <code
- class="fsharp"><span class="ci">CharStream</span></code>, i.e. a <code class="fsharp"><span class="ci">CharStream</span></code> instance that
- only contains a sub‐segment of another char stream but is accessible through the same char indices.
- </p>
- <div class="para _4">
- <p>
- <code class="fsharp"><span class="ci">chars</span></code> must not be null. An <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions:
- </p>
- <ul class="l1">
- <li class="_1">
- <code class="fsharp"><span class="ci">index</span></code> ≥ 0, <code class="fsharp"><span class="ci">length</span></code> ≥ 0, <code
- class="fsharp"><span class="ci">index</span></code> + <code class="fsharp"><span class="ci">length</span></code> ≤ <code
- class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code> and
- </li>
- <li class="_2">0 ≤ <code class="fsharp"><span class="ci">streamBeginIndex</span></code> < 2<sup>60</sup>.</li>
- </ul>
- </div>
- <div class="para _5">
- <div class="admonition">
- <div class="admonition-title">Note</div>
- <div class="admonition-body">
- <p class="para _1">
- A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a char array does not support .NET regex matching via
- the <code class="fsharp"><a href="#Iterator.members.Match_Regex"><span class="ci">Iterator</span><span class="cm">.</span><span
- class="ci">Match</span></a></code> member.
- </p>
- </div>
- </div>
- </div>
- <div class="para _6">
- <div class="admonition">
- <div class="admonition-title">Important</div>
- <div class="admonition-body">
- <p class="para _1">
- The given char array is “<a href="http://msdn.microsoft.com/en-us/library/83y4ak54.aspx">pinned</a>” until the <code
- class="fsharp"><span class="ci">CharStream</span></code> is disposed. Pinning the char array prevents the GC from moving it around in
- memory during garbage collection. On .NET (at least in versions up to and including 4.0) the pinning has no effect if the char array is
- large enough to be allocated on the Large Object Heap, i.e. has a length of about 42500 chars or more. However, pinning smaller char
- arrays does constrain the normal operations of the GC. Thus, <strong>to minimize the negative impact on the GC, you should dispose <code
- class="fsharp"><span class="ci">CharStream</span></code> instances constructed from small char arrays as soon as you’re done parsing
- it</strong>. If you keep a large number of <code class="fsharp"><span class="ci">CharStream</span></code> instances constructed from small
- char arrays around for an extended period of time, you risk fragmenting the heap.
- </p>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="interface-member _5" id="members.new_char-pointer">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_char-pointer:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">Low‐Trust version</a>
- of FParsec.</span></span><br />
- </p>
- <p class="para _2">
- Is equivalent to <code class="fsharp"><a href="#members.new_char-pointer_offset"><span class="ck">new</span> <span
- class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">chars</span><span class="cp">,</span> <span
- class="ci">length</span><span class="cp">,</span> <span class="cn">0L</span><span class="cp">)</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _6" id="members.new_char-pointer_offset">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_char-pointer_offset:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">streamBeginIndex</span><span class="cp">:</span> <span class="ci">int64</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">Low‐Trust version</a>
- of FParsec.</span></span>
- </p>
- <p class="para _2">
- Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from the <code class="fsharp"><span
- class="ci">length</span></code> chars at the pointer address. By directly referencing the chars at the pointer address this constructor
- avoids any copy of the char buffer.
- </p>
- <p class="para _3">
- The first char in the stream is assigned the index <code class="fsharp"><span class="ci">streamBeginIndex</span></code>. A positive <code
- class="fsharp"><span class="ci">streamBeginIndex</span></code> allows you for example to create a substream of another <code
- class="fsharp"><span class="ci">CharStream</span></code>, i.e. a <code class="fsharp"><span class="ci">CharStream</span></code> instance that
- only contains a sub‐segment of another char stream but is accessible through the same char indices.
- </p>
- <div class="para _4">
- <p>
- <code class="fsharp"><span class="ci">chars</span></code> must not be null. An <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions:
- </p>
- <ul class="l1">
- <li class="_1">
- <code class="fsharp"><span class="ci">length</span></code> ≥ 0, <code class="fsharp"><span class="ci">chars</span> <span
- class="co">+</span> <span class="ci">length</span></code> must not overflow and
- </li>
- <li class="_2">0 ≤ <code class="fsharp"><span class="ci">streamBeginIndex</span></code> < 2<sup>60</sup>.</li>
- </ul>
- </div>
- <div class="para _5">
- <div class="admonition">
- <div class="admonition-title">Note</div>
- <div class="admonition-body">
- <p class="para _1">
- A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a pointer does not support .NET regex matching via the
- <code class="fsharp"><a href="#Iterator.members.Match_Regex"><span class="ci">Iterator</span><span class="cm">.</span><span
- class="ci">Match</span></a></code> member.
- </p>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="interface-member _7" id="members.new_file-path">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_file-path:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">path</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Is equivalent to <code class="fsharp"><a href="#members.new_file-path_2"><span class="ck">new</span> <span
- class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">path</span><span class="cp">,</span> <span
- class="ci">encoding</span><span class="cp">,</span> <span class="cb">true</span><span class="cp">)</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _8" id="members.new_file-path_2">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_file-path_2:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">path</span><span class="cp">:</span> <span class="ci">string</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <div class="para _1">
- <p>Is equivalent to</p>
- <pre class="code fsharp"><a href="#members.new_file-path_3"><span class="ck">new</span> <span class="ci">CharStream</span></a><span class="cp">(</span>
- <span class="ci">path</span><span class="cp">,</span> <span class="ci">encoding</span><span class="cp">,</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">,</span>
- <span class="ci">blockSize</span> <span class="cp">=</span> <span class="ci">DefaultBlockSize</span> <span class="cbc"><span class="left-delimiter">(*</span> = 3*2^16 ≈ 200k <span class="right-delimiter">*)</span></span><span class="cp">,</span>
- <span class="ci">blockOverlap</span> <span class="cp">=</span> <span class="ci">DefaultBlockSize</span><span class="co">/</span><span class="cn">3</span><span class="cp">,</span>
- <span class="ci">minRegexSpace</span> <span class="cp">=</span> <span class="cp">(</span><span class="cp">(</span><span class="ci">DefaultBlockSize</span><span class="co">/</span><span class="cn">3</span><span class="cp">)</span><span class="co">*</span><span class="cn">2</span><span class="cp">)</span><span class="co">/</span><span class="cn">3</span><span class="cp">,</span>
- <span class="ci">byteBufferLength</span> <span class="cp">=</span> <span class="ci">DefaultByteBufferLength</span>
- <span class="cp">)</span>
- </pre>
- </div>
- </div>
- </div>
- <div class="interface-member _9" id="members.new_file-path_3">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_file-path_3:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">path</span><span class="cp">:</span> <span class="ci">string</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">blockSize</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">blockOverlap</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">minRegexSpace</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <div class="para _1">
- <p>
- Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span class="ci">FileStream</span></a></code> as if by calling
- </p>
- <pre class="code fsharp"><a href="#members.new_stream_4"><span class="ck">new</span> <span class="ci">CharStream</span></a><span class="cp">(</span>
- <span class="ck">new</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span class="ci">FileStream</span></a><span class="cp">(</span><span class="ci">path</span><span class="cp">,</span> <span class="ci">FileMode</span><span class="cm">.</span><span class="ci">Open</span><span class="cp">,</span> <span class="ci">FileAccess</span><span class="cm">.</span><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">,</span> <span class="ci">FileShare</span><span class="cm">.</span><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">,</span> <span class="cn">4096</span><span class="cp">,</span>
- <span class="ci">FileOptions</span><span class="cm">.</span><span class="ci">SequentialScan</span><span class="cp">)</span><span class="cp">,</span>
- <span class="ci">leaveOpen</span> <span class="cp">=</span> <span class="cb">false</span><span class="cp">,</span>
- <span class="ci">encoding</span> <span class="cp">=</span> <span class="ci">encoding</span><span class="cp">,</span>
- <span class="ci">detectEncoding</span> <span class="cp">=</span> <span class="cb">true</span><span class="cp">,</span>
- <span class="ci">blockSize</span> <span class="cp">=</span> <span class="ci">DefaultBlockSize</span> <span class="cbc"><span class="left-delimiter">(*</span> = 3*2^16 ≈ 200k <span class="right-delimiter">*)</span></span><span class="cp">,</span>
- <span class="ci">blockOverlap</span> <span class="cp">=</span> <span class="ci">DefaultBlockSize</span><span class="co">/</span><span class="cn">3</span><span class="cp">,</span>
- <span class="ci">minRegexSpace</span> <span class="cp">=</span> <span class="cp">(</span><span class="cp">(</span><span class="ci">DefaultBlockSize</span><span class="co">/</span><span class="cn">3</span><span class="cp">)</span><span class="co">*</span><span class="cn">2</span><span class="cp">)</span><span class="co">/</span><span class="cn">3</span><span class="cp">,</span>
- <span class="ci">byteBufferLength</span> <span class="cp">=</span> <span class="ci">DefaultByteBufferLength</span>
- <span class="cp">)</span>
- </pre>
- </div>
- <p class="para _2">
- If an exception occurs after the <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span
- class="ci">FileStream</span></a></code> is constructed but before the <code class="fsharp"><span class="ci">CharStream</span></code>
- constructor is finished, the <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span
- class="ci">FileStream</span></a></code> is disposed.
- </p>
- <div class="para _3">
- <div class="admonition">
- <div class="admonition-title">Note</div>
- <div class="admonition-body">
- <p class="para _1">
- The <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span
- class="ci">FileStream</span></a></code> constructor might throw an exception, too.
- </p>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="interface-member _0" id="members.new_stream">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_stream:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Is equivalent to <code class="fsharp"><a href="#members.new_stream_3"><span class="ck">new</span> <span class="ci">CharStream</span></a><span
- class="cp">(</span><span class="ci">stream</span><span class="cp">,</span> <span class="cb">false</span><span class="cp">,</span> <span
- class="ci">encoding</span><span class="cp">,</span> <span class="cb">true</span><span class="cp">)</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _1" id="members.new_stream_2">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_stream_2:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">leaveOpen</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Is equivalent to <code class="fsharp"><a href="#members.new_stream_3"><span class="ck">new</span> <span class="ci">CharStream</span></a><span
- class="cp">(</span><span class="ci">stream</span><span class="cp">,</span> <span class="ci">leaveOpen</span><span class="cp">,</span> <span
- class="ci">encoding</span><span class="cp">,</span> <span class="cb">true</span><span class="cp">)</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _2" id="members.new_stream_3">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_stream_3:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">leaveOpen</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <div class="para _1">
- <p>Is equivalent to</p>
- <pre class="code fsharp"><a href="#members.new_stream_4"><span class="ck">new</span> <span class="ci">CharStream</span></a><span class="cp">(</span>
- <span class="ci">stream</span><span class="cp">,</span> <span class="ci">leaveOpen</span><span class="cp">,</span> <span class="ci">encoding</span><span class="cp">,</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">,</span>
- <span class="ci">blockSize</span> <span class="cp">=</span> <span class="ci">DefaultBlockSize</span> <span class="cbc"><span class="left-delimiter">(*</span> = 3*2^16 ≈ 200k <span class="right-delimiter">*)</span></span><span class="cp">,</span>
- <span class="ci">blockOverlap</span> <span class="cp">=</span> <span class="ci">DefaultBlockSize</span><span class="co">/</span><span class="cn">3</span><span class="cp">,</span>
- <span class="ci">minRegexSpace</span> <span class="cp">=</span> <span class="cp">(</span><span class="cp">(</span><span class="ci">DefaultBlockSize</span><span class="co">/</span><span class="cn">3</span><span class="cp">)</span><span class="co">*</span><span class="cn">2</span><span class="cp">)</span><span class="co">/</span><span class="cn">3</span><span class="cp">,</span>
- <span class="ci">byteBufferLength</span> <span class="cp">=</span> <span class="ci">DefaultByteBufferLength</span>
- <span class="cp">)</span>
- </pre>
- </div>
- </div>
- </div>
- <div class="interface-member _3" id="members.new_stream_4">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.new_stream_4:B:">⇧</a>
- <pre class="code fsharp"><span class="interface-member-marker"><span class="ck">new</span></span><span class="cp">:</span> <span class="ci">stream</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a> <span class="cp">*</span> <span class="ci">leaveOpen</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">encoding</span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">Encoding</span></a> <span class="cp">*</span> <span class="ci">detectEncodingFromByteOrderMarks</span><span class="cp">:</span> <span class="ci">bool</span>
- <span class="cp">*</span> <span class="ci">blockSize</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">blockOverlap</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">minRegexSpace</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
- <span class="cr">-></span> <span class="ci">CharStream</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code>.
- </p>
- <p class="para _2">
- The normal version of the <code class="fsharp"><span class="ci">CharStream</span></code> class supports stream sizes up to approximately
- (2<sup>31</sup>/p)×(<code class="fsharp"><span class="ci">blockSize</span></code> ‐ <code class="fsharp"><span
- class="ci">blockOverlap</span></code>) chars, where p is 4 on a 32‐bit CLR and 8 on a 64‐bit CLR.<br />The <a
- href="#remarks.low-trust-version">Low‐Trust version</a> only supports streams small enough that the complete content can be read into a
- single string.
- </p>
- <div class="para _3">
- <div class="admonition">
- <div class="admonition-title">Note</div>
- <div class="admonition-body">
- <p class="para _1">
- This constructor reads the first block of chars from the input stream and hence can throw any of the I/O related exceptions detailed in
- the <a href="#exceptions">exceptions</a> section above.
- </p>
- </div>
- </div>
- </div>
- <div class="para _4">
- <p>Arguments:</p>
- <div class="dl multi-para">
- <dl class="dl multi-para">
- <dt class="_1"><code class="fsharp"><span class="ci">stream</span></code></dt>
- <dd class="_1">
- <p class="para _1">
- The byte stream providing the input. If <code class="fsharp"><span class="ci">stream</span><span class="cm">.</span><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.canread.aspx"><span class="ci">CanRead</span></a></code> returns <code
- class="fsharp"><span class="cb">false</span></code>, an <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentexception.aspx"><span class="ci">ArgumentException</span></a></code> is
- thrown.
- </p>
- </dd>
- <dt class="_2"><code class="fsharp"><span class="ci">leaveOpen</span></code></dt>
- <dd class="_2">
- <p class="para _1">
- Indicates whether the <code class="fsharp"><span class="ci">stream</span></code> should be left open when the <code class="fsharp"><span
- class="ci">CharStream</span></code> has finished reading it.
- </p>
- </dd>
- <dt class="_3"><code class="fsharp"><span class="ci">encoding</span></code></dt>
- <dd class="_3">
- <p class="para _1">
- The default <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span
- class="ci">Encoding</span></a></code> used for decoding the byte stream into chars.
- </p>
- <p class="para _2">
- If the preamble returned by <code class="fsharp"><span class="ci">encoding</span><span class="cm">.</span><a
- href="http://msdn.microsoft.com/en-us/library/system.text.encoding.getpreamble.aspx"><span class="ci">GetPreamble</span></a><span
- class="cp">()</span></code> is present at the beginning of the stream, the <code class="fsharp"><span class="ci">CharStream</span></code>
- will skip over it.
- </p>
- </dd>
- <dt class="_4"><code class="fsharp"><span class="ci">detectEncodingFromByteOrderMarks</span></code></dt>
- <dd class="_4">
- <p class="para _1">
- Indicates whether the constructor should detect the encoding from a unicode <a
- href="http://en.wikipedia.org/wiki/Byte-order_mark">byte‐order mark</a> at the beginning of the stream. An encoding detected from a
- byte‐order mark overrides the default <code class="fsharp"><span class="ci">encoding</span></code>. The standard byte‐order marks for the
- following encodings are supported: UTF‐8, UTF‐16 LE/BE and UTF‐32 LE/BE.
- </p>
- </dd>
- <dt class="_5"><code class="fsharp"><span class="ci">blockSize</span></code></dt>
- <dd class="_5">
- <p class="para _1">
- The number of chars per block. The value is rounded up to the first positive multiple of 1536. The default is 3×2<sup>16</sup> ≈ 200k.
- </p>
- </dd>
- <dt class="_6"><code class="fsharp"><span class="ci">blockOverlap</span></code></dt>
- <dd class="_6">
- <p class="para _1">
- The number of chars at the end of a block that are preserved when reading the next block into the char buffer. If this value is less than
- <code class="fsharp"><span class="ci">encoding</span><span class="cm">.</span><span class="ci">GetMaxCharCount</span><span
- class="cp">(</span><span class="cn">1</span><span class="cp">)</span></code> or not less than <code class="fsharp"><span
- class="ci">blockSize</span><span class="co">/</span><span class="cn">2</span></code>, the default value is used instead. The default is
- <code class="fsharp"><span class="ci">blockSize</span><span class="co">/</span><span class="cn">3</span></code>.
- </p>
- </dd>
- <dt class="_7"><code class="fsharp"><a id="members.minRegexSpace"></a><span class="ci">minRegexSpace</span></code></dt>
- <dd class="_7">
- <p class="para _1">
- The number of chars that are guaranteed to be visible to a regular expression when it is matched by <code class="fsharp"><a
- href="#Iterator.members.Match_Regex"><span class="ci">Match</span></a></code> (assuming there are enough chars remaining in the stream).
- If this value is negative or greater than <code class="fsharp"><span class="ci">blockOverlap</span></code>, the default value is used
- instead. The default value is 2/3 of <code class="fsharp"><span class="ci">blockOverlap</span></code>.
- </p>
- </dd>
- <dt class="_8">byteBufferLength</dt>
- <dd class="_8">
- <p class="para _1">The size of the byte buffer used for decoding purposes. The default is 2<sup>12</sup> = 4KB.</p>
- </dd>
- </dl>
- </div>
- </div>
- </div>
- </div>
- <div class="interface-member _4" id="members.Dispose">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.Dispose:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Dispose</span></span><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">unit</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Releases all resources used by the <code class="fsharp"><span class="ci">CharStream</span></code>. If the <code class="fsharp"><span
- class="ci">CharStream</span></code> was constructed from a <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
- class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path and the constructor was not called with
- <code class="fsharp"><span class="ci">leaveOpen</span> <span class="co">=</span> <span class="cb">true</span></code>, the byte stream is
- closed.
- </p>
- </div>
- </div>
- <div class="interface-member _5" id="members.Begin">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.Begin:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Begin</span></span><span class="cp">:</span> <a href="#Iterator"><span class="ci">Iterator</span></a>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns an <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> pointing to the beginning of the stream (or
- to the end if the <code class="fsharp"><span class="ci">CharStream</span></code> is empty).
- </p>
- </div>
- </div>
- <div class="interface-member _6" id="members.Seek">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.Seek:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Seek</span></span><span class="cp">:</span> <span class="ci">int64</span> <span class="cr">-></span> <a href="#Iterator"><span class="ci">Iterator</span></a>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns an <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> pointing to the given index in the stream.
- </p>
- <p class="para _2">
- An <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> pointing to one char after the last char in the
- stream represents an <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> to the end of the stream. The <code
- class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> can’t move past the end of the stream and <code
- class="fsharp"><span class="ci">Seek</span></code> interprets any index larger than the index of the last char as precisely one plus the
- index of the last char.
- </p>
- <p class="para _3">
- The index is zero‐based, except if the <code class="fsharp"><span class="ci">CharStream</span></code> was constructed with a positive <code
- class="fsharp"><span class="ci">streamBeginIndex</span></code> argument, in which case the index of the first char equals <code
- class="fsharp"><span class="ci">streamBeginIndex</span></code> and <code class="fsharp"><a href="#members.BeginIndex"><span
- class="ci">BeginIndex</span></a></code>.
- </p>
- <p class="para _4">
- An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the index is less than the <code class="fsharp"><a
- href="#members.BeginIndex"><span class="ci">BeginIndex</span></a></code>. This method may also throw any of the <a href="#exceptions">I/O
- related exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _7" id="members.BeginIndex">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.BeginIndex:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">BeginIndex</span></span><span class="cp">:</span> <span class="ci">int64</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- The index of the first char in the stream, i.e. <code class="fsharp"><a href="#members.Begin"><span class="ci">Begin</span></a><span
- class="cm">.</span><a href="#Iterator.members.Index"><span class="ci">Index</span></a></code>. This value is determined by the <code
- class="fsharp"><span class="ci">streamBeginIndex</span></code> argument of some of the <code class="fsharp"><span
- class="ci">CharStream</span></code> constructors. By default this value is 0.
- </p>
- </div>
- </div>
- <div class="interface-member _8" id="members.EndIndex">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.EndIndex:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">EndIndex</span></span><span class="cp">:</span> <span class="ci">int64</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- The index of the last char of the stream plus 1, or <code class="fsharp"><span class="ci">Int64</span><span class="cm">.</span><span
- class="ci">MaxValue</span></code> if the end of the stream has not yet been detected.
- </p>
- </div>
- </div>
- <div class="interface-member _9" id="members.FoldCase">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.FoldCase:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">static</span> <span class="ck">member</span> <span class="interface-member-marker"><span class="ci">FoldCase</span></span><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">string</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns a case‐folded copy of the string argument. All chars are mapped using the (non‐Turkic) 1‐to‐1 <a
- href="http://unicode.org/Public/UNIDATA/CaseFolding.txt">case folding mappings</a> (v. 5.1) for Unicode code points in the Basic Multilingual
- Plane, i.e. code points below 0x10000. If the case‐folded string equals the argument string, the original argument is returned (to preserve
- its reference identity). If the argument is <code class="fsharp"><span class="cnu">null</span></code>, <code class="fsharp"><span
- class="cnu">null</span></code> is returned.
- </p>
- <p class="para _2">
- <code class="fsharp"><span class="ci">CharParsers</span><span class="cm">.</span><a href="charparsers.html#members.foldCase"><span
- class="ci">foldCase</span></a></code> is a convenient helper function that forwards all calls to this method.
- </p>
- </div>
- </div>
- <div class="interface-member _0" id="members.NormalizeNewlines">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#interface.NormalizeNewlines:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">static</span> <span class="ck">member</span> <span class="interface-member-marker"><span class="ci">NormalizeNewlines</span></span><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">string</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns the given string with all occurrences of <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span
- class="ce">\r</span><span class="ce">\n</span><span class="right-delimiter">"</span></span></code> and <code class="fsharp"><span
- class="cs"><span class="left-delimiter">"</span><span class="ce">\r</span><span class="right-delimiter">"</span></span></code> replaced by
- <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span class="ce">\n</span><span
- class="right-delimiter">"</span></span></code>. If the normalized string equals the argument string, the original argument is returned (to
- preserve its reference identity). If the argument is <code class="fsharp"><span class="cnu">null</span></code>, <code class="fsharp"><span
- class="cnu">null</span></code> is returned.
- </p>
- <p class="para _2">
- <code class="fsharp"><span class="ci">CharParsers</span><span class="cm">.</span><a href="charparsers.html#members.normalizeNewlines"><span
- class="ci">normalizeNewlines</span></a></code> is a convenient helper function that forwards all calls to this method.
- </p>
- </div>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div id="Iterator" class="section s3">
- <h2 class="title h3"><span class="section-number">2.8.5</span> CharStream.Iterator</h2>
- <div class="intro i3">
- <p class="para _1">
- The <code class="fsharp"><span class="ci">Iterator</span></code> struct represents a pointer to a particular char in a <code class="fsharp"><a
- href="#"><span class="ci">CharStream</span></a></code>. It provides efficient methods for reading chars or strings from the stream and for
- matching chars, strings or regular expressions with the content of the stream.
- </p>
- </div>
- <div id="Iterator.interface" class="section s4">
- <h3 class="title h4"><span class="section-number">2.8.5.1</span> Interface</h3>
- <div class="intro i4">
- <div class="para _1">
- <pre class="code fsharp"><span class="ck">namespace</span> <span class="ci">FParsec</span>
- <span class="ck">open</span> <span class="ci">NativeInterop</span>
- <span class="cp">[<</span><span class="ci">Sealed</span><span class="cp">>]</span>
- <span class="ck">type</span> <a href="#"><span class="ci">CharStream</span></a> <span class="cp">=</span>
- <span class="cbc"><span class="left-delimiter">(*</span> ... <span class="right-delimiter">*)</span></span>
- <span class="cp">[<</span><span class="ci">Struct</span><span class="cp">>]</span>
- <span class="ck">type</span> <span class="ci">Iterator</span> <span class="cp">=</span>
- <span class="ck">interface</span> <a href="http://msdn.microsoft.com/en-us/library/ms131187.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">IEquatable</span></a><span class="cp"><</span><span class="ci">Iterator</span><span class="cp">></span>
- <span class="ck">member</span> <a id="Iterator.interface.Stream:B:" href="#Iterator.members.Stream"><span class="interface-member-marker"><span class="ci">Stream</span></span></a><span class="cp">:</span> <a href="#"><span class="ci">CharStream</span></a>
- <span class="ck">member</span> <a id="Iterator.interface.Index:B:" href="#Iterator.members.Index"><span class="interface-member-marker"><span class="ci">Index</span></span></a><span class="cp">:</span> <span class="ci">int64</span>
- <span class="ck">member</span> <a id="Iterator.interface.IsBeginOfStream:B:" href="#Iterator.members.IsBeginOfStream"><span class="interface-member-marker"><span class="ci">IsBeginOfStream</span></span></a><span class="cp">:</span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.IsEndOfStream:B:" href="#Iterator.members.IsEndOfStream"><span class="interface-member-marker"><span class="ci">IsEndOfStream</span></span></a><span class="cp">:</span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.Next:B:" href="#Iterator.members.Next"><span class="interface-member-marker"><span class="ci">Next</span></span></a><span class="cp">:</span> <span class="ci">Iterator</span>
- <span class="ck">member</span> <a id="Iterator.interface.Advance_int:B:" href="#Iterator.members.Advance_int"><span class="interface-member-marker"><span class="ci">Advance</span></span></a><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">Iterator</span>
- <span class="ck">member</span> <a id="Iterator.interface.Advance_uint:B:" href="#Iterator.members.Advance_uint"><span class="interface-member-marker"><span class="ci">Advance</span></span></a><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">Iterator</span>
- <span class="ck">member</span> <a id="Iterator.interface.Advance:B:" href="#Iterator.members.Advance"><span class="interface-member-marker"><span class="ci">Advance</span></span></a><span class="cp">:</span> <span class="ci">int64</span> <span class="cr">-></span> <span class="ci">Iterator</span>
- <span class="ck">member</span> <a id="Iterator.interface.Match:B:" href="#Iterator.members.Match"><span class="interface-member-marker"><span class="ci">Match</span></span></a><span class="cp">:</span> <span class="ci">char</span> <span class="cr">-></span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.Match_string:B:" href="#Iterator.members.Match_string"><span class="interface-member-marker"><span class="ci">Match</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.Match_substring:B:" href="#Iterator.members.Match_substring"><span class="interface-member-marker"><span class="ci">Match</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">charsIndex</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.Match_char-array:B:" href="#Iterator.members.Match_char-array"><span class="interface-member-marker"><span class="ci">Match</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">charsIndex</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.Match_char-pointer:B:" href="#Iterator.members.Match_char-pointer"><span class="interface-member-marker"><span class="ci">Match</span></span></a><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.MatchCaseFolded:B:" href="#Iterator.members.MatchCaseFolded"><span class="interface-member-marker"><span class="ci">MatchCaseFolded</span></span></a><span class="cp">:</span> <span class="ci">caseFoldedChars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.MatchCaseFolded_char-pointer:B:" href="#Iterator.members.MatchCaseFolded_char-pointer"><span class="interface-member-marker"><span class="ci">MatchCaseFolded</span></span></a><span class="cp">:</span> <span class="ci">caseFoldedChars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span><span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- <span class="ck">member</span> <a id="Iterator.interface.Match_Regex:B:" href="#Iterator.members.Match_Regex"><span class="interface-member-marker"><span class="ci">Match</span></span></a><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.regularexpressions.regex.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">RegularExpressions</span><span class="cm">.</span><span class="ci">Regex</span></a>
- <span class="cr">-></span> <a href="http://msdn.microsoft.com/en-us/library/system.text.regularexpressions.match.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">RegularExpressions</span><span class="cm">.</span><span class="ci">Match</span></a>
- <span class="ck">member</span> <a id="Iterator.interface.Read:B:" href="#Iterator.members.Read"><span class="interface-member-marker"><span class="ci">Read</span></span></a><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- <span class="ck">static</span> <span class="ck">val</span> <a id="Iterator.interface.EndOfStreamChar:B:" href="#Iterator.members.EndOfStreamChar"><span class="interface-member-marker"><span class="ci">EndOfStreamChar</span></span></a><span class="cp">:</span> <span class="ci">char</span>
- <span class="ck">type</span> <a id="Iterator.interface.TwoChars"></a><span class="ci">TwoChars</span> <span class="cp">=</span> <span class="ck">struct</span>
- <span class="ck">new</span><span class="cp">:</span> <span class="ci">char</span> <span class="cp">*</span> <span class="ci">char</span> <span class="cr">-></span> <span class="ci">TwoChars</span>
- <span class="ck">val</span> <span class="ci">Char0</span><span class="cp">:</span> <span class="ci">char</span>
- <span class="ck">val</span> <span class="ci">Char1</span><span class="cp">:</span> <span class="ci">char</span>
- <span class="ck">end</span>
- <span class="ck">member</span> <a id="Iterator.interface.Read2:B:" href="#Iterator.members.Read2"><span class="interface-member-marker"><span class="ci">Read2</span></span></a><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <a href="#Iterator.interface.TwoChars"><span class="ci">TwoChars</span></a>
- <span class="ck">member</span> <a id="Iterator.interface.Read_int:B:" href="#Iterator.members.Read_int"><span class="interface-member-marker"><span class="ci">Read</span></span></a><span class="cp">:</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">string</span>
- <span class="ck">member</span> <a id="Iterator.interface.Read_int_bool:B:" href="#Iterator.members.Read_int_bool"><span class="interface-member-marker"><span class="ci">Read</span></span></a><span class="cp">:</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">allOrEmpty</span><span class="cp">:</span> <span class="ci">bool</span> <span class="cr">-></span> <span class="ci">string</span>
- <span class="ck">member</span> <a id="Iterator.interface.Read_char-array:B:" href="#Iterator.members.Read_char-array"><span class="interface-member-marker"><span class="ci">Read</span></span></a><span class="cp">:</span> <span class="ci">buffer</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">bufferIndex</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">int</span>
- <span class="ck">member</span> <a id="Iterator.interface.Read_char-pointer:B:" href="#Iterator.members.Read_char-pointer"><span class="interface-member-marker"><span class="ci">Read</span></span></a><span class="cp">:</span> <span class="ci">buffer</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">int</span>
- <span class="ck">member</span> <a id="Iterator.interface.ReadUntil:B:" href="#Iterator.members.ReadUntil"><span class="interface-member-marker"><span class="ci">ReadUntil</span></span></a><span class="cp">:</span> <span class="ci">iterToCharAfterLastInString</span><span class="cp">:</span> <span class="ci">Iterator</span> <span class="cr">-></span> <span class="ci">string</span>
- <span class="ck">member</span> <a id="Iterator.interface.Peek:B:" href="#Iterator.members.Peek"><span class="interface-member-marker"><span class="ci">Peek</span></span></a><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- <span class="ck">member</span> <a id="Iterator.interface.Peek_int:B:" href="#Iterator.members.Peek_int"><span class="interface-member-marker"><span class="ci">Peek</span></span></a><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">char</span>
- <span class="ck">member</span> <a id="Iterator.interface.Peek_uint:B:" href="#Iterator.members.Peek_uint"><span class="interface-member-marker"><span class="ci">Peek</span></span></a><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">char</span>
- <span class="clc"><span class="left-delimiter">//</span> the following members mutate the instance</span>
- <span class="ck">member</span> <a id="Iterator.interface._Increment:B:" href="#Iterator.members._Increment"><span class="interface-member-marker"><span class="ci">_Increment</span></span></a><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- <span class="ck">member</span> <a id="Iterator.interface._Increment_uint:B:" href="#Iterator.members._Increment_uint"><span class="interface-member-marker"><span class="ci">_Increment</span></span></a><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">char</span>
- <span class="ck">member</span> <a id="Iterator.interface._Decrement:B:" href="#Iterator.members._Decrement"><span class="interface-member-marker"><span class="ci">_Decrement</span></span></a><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- <span class="ck">member</span> <a id="Iterator.interface._Decrement_uint:B:" href="#Iterator.members._Decrement_uint"><span class="interface-member-marker"><span class="ci">_Decrement</span></span></a><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- </div>
- </div>
- <div id="Iterator.members" class="section s4">
- <h3 class="title h4"><span class="section-number">2.8.5.2</span> Members</h3>
- <div class="intro i4">
- <div class="para _1">
- <div class="interface-members">
- <div class="interface-member _1" id="Iterator.members.Stream">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Stream:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Stream</span></span><span class="cp">:</span> <a href="#"><span class="ci">CharStream</span></a>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- The <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> over which the <code class="fsharp"><span
- class="ci">Iterator</span></code> iterates.
- </p>
- </div>
- </div>
- <div class="interface-member _2" id="Iterator.members.Index">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Index:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Index</span></span><span class="cp">:</span> <span class="ci">int64</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">The index of the stream char pointed to by the <code class="fsharp"><span class="ci">Iterator</span></code>.</p>
- <p class="para _2">
- The index is zero‐based, except if the <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> was constructed with a
- positive <code class="fsharp"><span class="ci">streamBeginIndex</span></code> argument, in which case the index of the first char equals
- <code class="fsharp"><span class="ci">streamBeginIndex</span></code> and <code class="fsharp"><a href="#Iterator.members.Stream"><span
- class="ci">Stream</span></a><span class="cm">.</span><a href="#members.BeginIndex"><span class="ci">BeginIndex</span></a></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _3" id="Iterator.members.IsBeginOfStream">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.IsBeginOfStream:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">IsBeginOfStream</span></span><span class="cp">:</span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Indicates whether the <code class="fsharp"><span class="ci">Iterator</span></code> points to the first char in the <code class="fsharp"><a
- href="#"><span class="ci">CharStream</span></a></code>. If the <code class="fsharp"><a href="#"><span
- class="ci">CharStream</span></a></code> is empty, this property is always <code class="fsharp"><span class="cb">true</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _4" id="Iterator.members.IsEndOfStream">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.IsEndOfStream:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">IsEndOfStream</span></span><span class="cp">:</span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Indicates whether the <code class="fsharp"><span class="ci">Iterator</span></code> points to the end of the <code class="fsharp"><a
- href="#"><span class="ci">CharStream</span></a></code>, i.e. whether it points to one char beyond the last char in the <code
- class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _5" id="Iterator.members.Next">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Next:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Next</span></span><span class="cp">:</span> <span class="ci">Iterator</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns an <code class="fsharp"><span class="ci">Iterator</span></code> pointing to the next char in the stream. If the <code
- class="fsharp"><span class="ci">Iterator</span></code> already has reached the end of the stream, i.e. if it points to one char beyond the
- last char, the same <code class="fsharp"><span class="ci">Iterator</span></code> is returned.
- </p>
- <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
- </div>
- </div>
- <div class="interface-member _6" id="Iterator.members.Advance_int">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Advance_int:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Advance</span></span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">Iterator</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Is an optimized version of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a></code> for <code
- class="fsharp"><span class="ci">int</span></code> arguments.
- </p>
- </div>
- </div>
- <div class="interface-member _7" id="Iterator.members.Advance_uint">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Advance_uint:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Advance</span></span><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">Iterator</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Is an optimized version of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a></code> for <code
- class="fsharp"><span class="ci">uint</span></code> arguments.
- </p>
- </div>
- </div>
- <div class="interface-member _8" id="Iterator.members.Advance">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Advance:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Advance</span></span><span class="cp">:</span> <span class="ci">int64</span> <span class="cr">-></span> <span class="ci">Iterator</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">Returns an <code class="fsharp"><span class="ci">Iterator</span></code> that is advanced by the given number of chars.</p>
- <p class="para _2">
- The <code class="fsharp"><span class="ci">Iterator</span></code> can’t move past the end of the stream, i.e. any position beyond the last
- char in the stream is interpreted as precisely one char beyond the last char.
- </p>
- <p class="para _3">
- An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the new position would lie before the beginning of the <code
- class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code>, i.e. if the new index would be less than the <code
- class="fsharp"><a href="#Iterator.members.Stream"><span class="ci">Stream</span></a><span class="cm">.</span><a
- href="#members.BeginIndex"><span class="ci">BeginIndex</span></a></code>. This method may also throw any of the <a href="#exceptions">I/O
- related exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _9" id="Iterator.members.Match">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Match:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Match</span></span><span class="cp">:</span> <span class="ci">char</span> <span class="cr">-></span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns <code class="fsharp"><span class="cb">true</span></code> if and only if the char argument matches the char pointed to by the <code
- class="fsharp"><span class="ci">Iterator</span></code>. At the end of the stream <code class="fsharp"><span class="ci">Match</span></code>
- always returns <code class="fsharp"><span class="cb">false</span></code>.
- </p>
- <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
- </div>
- </div>
- <div class="interface-member _0" id="Iterator.members.Match_string">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Match_string:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Match</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">chars</span></code> matches the
- chars in the stream beginning with the char pointed to by the <code class="fsharp"><span class="ci">Iterator</span></code>. If the chars do
- not match or if there are not enough chars remaining in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned.
- If <code class="fsharp"><span class="ci">chars</span></code> is empty, <code class="fsharp"><span class="cb">true</span></code> is returned.
- <code class="fsharp"><span class="ci">chars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
- </p>
- <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
- </div>
- </div>
- <div class="interface-member _1" id="Iterator.members.Match_substring">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Match_substring:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Match</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cp">*</span> <span class="ci">charsIndex</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">chars</span><span
- class="cm">.</span><span class="cp">[</span><span class="ci">charsIndex</span><span class="cra">..</span><span class="cp">(</span><span
- class="ci">charsIndex</span> <span class="co">+</span> <span class="ci">length</span> <span class="co">-</span> <span
- class="cn">1</span><span class="cp">)</span><span class="cp">]</span></code> matches the chars in the stream beginning with the char pointed
- to by the <code class="fsharp"><span class="ci">Iterator</span></code>. If the chars do not match or if there are not enough chars remaining
- in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned. If <code class="fsharp"><span
- class="ci">length</span></code> is 0, <code class="fsharp"><span class="cb">true</span></code> is returned. <code class="fsharp"><span
- class="ci">chars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
- </p>
- <p class="para _2">
- An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions: <code
- class="fsharp"><span class="ci">charsIndex</span></code> ≥ 0, <code class="fsharp"><span class="ci">length</span></code> ≥ 0 and <code
- class="fsharp"><span class="ci">charsIndex</span></code> + <code class="fsharp"><span class="ci">length</span></code> ≤ <code
- class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code>. This method may also throw any
- of the <a href="#exceptions">I/O related exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _2" id="Iterator.members.Match_char-array">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Match_char-array:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Match</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">charsIndex</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">chars</span><span
- class="cm">.</span><span class="cp">[</span><span class="ci">charsIndex</span><span class="cra">..</span><span class="cp">(</span><span
- class="ci">charsIndex</span> <span class="co">+</span> <span class="ci">length</span> <span class="co">-</span> <span
- class="cn">1</span><span class="cp">)</span><span class="cp">]</span></code> matches the chars in the stream beginning with the char pointed
- to by the <code class="fsharp"><span class="ci">Iterator</span></code>. If the chars do not match or if there are not enough chars remaining
- in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned. If <code class="fsharp"><span
- class="ci">length</span></code> is 0, <code class="fsharp"><span class="cb">true</span></code> is returned. <code class="fsharp"><span
- class="ci">chars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
- </p>
- <p class="para _2">
- An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions: <code
- class="fsharp"><span class="ci">charsIndex</span></code> ≥ 0, <code class="fsharp"><span class="ci">length</span></code> ≥ 0 and <code
- class="fsharp"><span class="ci">charsIndex</span></code> + <code class="fsharp"><span class="ci">length</span></code> ≤ <code
- class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code>. This method may also throw any
- of the <a href="#exceptions">I/O related exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _3" id="Iterator.members.Match_char-pointer">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Match_char-pointer:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Match</span></span><span class="cp">:</span> <span class="ci">chars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <span class="small"><span class="italic">This method is not available in the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span>
- </p>
- <p class="para _2">
- Returns <code class="fsharp"><span class="cb">true</span></code> if the <code class="fsharp"><span class="ci">length</span></code> chars at
- the pointer address match the chars in the stream beginning with the char pointed to by the <code class="fsharp"><span
- class="ci">Iterator</span></code>. If the chars do not match or if there are not enough chars remaining in the stream, <code
- class="fsharp"><span class="cb">false</span></code> is returned. If <code class="fsharp"><span class="ci">length</span></code> is 0, <code
- class="fsharp"><span class="cb">true</span></code> is returned.
- </p>
- <p class="para _3">
- If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
- exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _4" id="Iterator.members.MatchCaseFolded">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.MatchCaseFolded:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">MatchCaseFolded</span></span><span class="cp">:</span> <span class="ci">caseFoldedChars</span><span class="cp">:</span> <span class="ci">string</span> <span class="cr">-></span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">caseFoldedChars</span></code>
- matches the chars in the stream beginning with the char pointed to by the <code class="fsharp"><span class="ci">Iterator</span></code>. The
- chars in the stream are case‐folded before they are matched, while the chars in the string argument are assumed to already be case‐folded
- (e.g. with the help of <code class="fsharp"><a href="#members.FoldCase"><span class="ci">FoldCase</span></a></code>). If the chars do not
- match or if there are not enough chars remaining in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned. <code
- class="fsharp"><span class="ci">caseFoldedChars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
- </p>
- <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
- <p class="para _3">Please also see the above remarks on <a href="#remarks.case-insensitive-matching">case‐insensitive matching</a>.</p>
- </div>
- </div>
- <div class="interface-member _5" id="Iterator.members.MatchCaseFolded_char-pointer">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.MatchCaseFolded_char-pointer:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">MatchCaseFolded</span></span><span class="cp">:</span> <span class="ci">caseFoldedChars</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span><span class="ci">int</span> <span class="cr">-></span> <span class="ci">bool</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <span class="small"><span class="italic">This method is not available in the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span>
- </p>
- <p class="para _2">
- Returns <code class="fsharp"><span class="cb">true</span></code> if the <code class="fsharp"><span class="ci">length</span></code> chars at
- the pointer address match the chars in the stream beginning with the char pointed to by the <code class="fsharp"><span
- class="ci">Iterator</span></code>. The chars in the stream are case‐folded before they are matched, while the chars at the pointer address
- are assumed to already be case‐folded (e.g. with the help of <code class="fsharp"><a href="#members.FoldCase"><span
- class="ci">FoldCase</span></a></code>). If the chars do not match or if there are not enough chars remaining in the stream, <code
- class="fsharp"><span class="cb">false</span></code> is returned.
- </p>
- <p class="para _3">
- If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
- exceptions</a> detailed above.
- </p>
- <p class="para _4">Please also see the above remarks on <a href="#remarks.case-insensitive-matching">case‐insensitive matching</a>.</p>
- </div>
- </div>
- <div class="interface-member _6" id="Iterator.members.Match_Regex">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Match_Regex:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Match</span></span><span class="cp">:</span> <a href="http://msdn.microsoft.com/en-us/library/system.text.regularexpressions.regex.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">RegularExpressions</span><span class="cm">.</span><span class="ci">Regex</span></a>
- <span class="cr">-></span> <a href="http://msdn.microsoft.com/en-us/library/system.text.regularexpressions.match.aspx"><span class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span class="ci">RegularExpressions</span><span class="cm">.</span><span class="ci">Match</span></a>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Applies the given regular expression to the stream chars beginning with the char pointed to by the <code class="fsharp"><span
- class="ci">Iterator</span></code>. Returns the resulting <code class="fsharp"><span class="ci">Match</span></code> object.
- </p>
- <p class="para _2">
- For performance reasons you should specify the regular expression such that it can only match at the beginning of a string, for example by
- prepending <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span class="ce">\\</span>A<span
- class="right-delimiter">"</span></span></code>.
- </p>
- <p class="para _3">
- For <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> instances constructed from large streams the regular
- expression is not applied to a string containing all the remaining chars in the stream. The <code class="fsharp"><a
- href="#members.minRegexSpace"><span class="ci">minRegexSpace</span></a></code> parameter of the <code class="fsharp"><a href="#"><span
- class="ci">CharStream</span></a></code> constructors determines the minimum number of chars that are guaranteed to be visible to the regular
- expression.
- </p>
- <p class="para _4">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
- <div class="para _5">
- <div class="admonition">
- <div class="admonition-title">Important</div>
- <div class="admonition-body">
- <p class="para _1">
- <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span><br /> This method is not supported by <code class="fsharp"><a href="#"><span
- class="ci">CharStream</span></a></code> instances constructed directly from char arrays or pointers. A <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.notsupportedexception.aspx"><span class="ci">NotSupportedException</span></a></code>
- is thrown if this method is called on such a <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> instance.
- </p>
- </div>
- </div>
- </div>
- <div class="para _6">
- <div class="admonition">
- <div class="admonition-title">Important</div>
- <div class="admonition-body">
- <p class="para _1">
- <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span><br /> If the <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> was constructed from a
- <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span
- class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path, the
- regular expression is applied to an internal <em>mutable</em> buffer. Since the <code class="fsharp"><span class="ci">Match</span></code>
- object may work lazily, i.e. compute return values not before they are needed, you need to <em>retrieve all the required information from
- the <code class="fsharp"><span class="ci">Match</span></code> object before you continue to access the <code class="fsharp"><a
- href="#"><span class="ci">CharStream</span></a></code></em>, otherwise you might get back invalid match results. Note that all strings
- returned by the <code class="fsharp"><span class="ci">Match</span></code> object are, of course, immutable.
- </p>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="interface-member _7" id="Iterator.members.Read">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Read:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Read</span></span><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns the stream char pointed to by the <code class="fsharp"><span class="ci">Iterator</span></code>, or the <code class="fsharp"><a
- href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span
- class="left-delimiter">'</span><span class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) if the <code
- class="fsharp"><span class="ci">Iterator</span></code> has reached the end of the stream, i.e. if it points to one char beyond the last char
- in the stream.
- </p>
- <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
- </div>
- </div>
- <div class="interface-member _8" id="Iterator.members.EndOfStreamChar">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.EndOfStreamChar:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">static</span> <span class="ck">val</span> <span class="interface-member-marker"><span class="ci">EndOfStreamChar</span></span><span class="cp">:</span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- The char returned by <code class="fsharp"><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">()</span></code>
- if the <code class="fsharp"><span class="ci">Iterator</span></code> has reached the end of the stream, i.e. if it points to one char beyond
- the last char in the stream. The value is <code class="fsharp"><span class="cc"><span class="left-delimiter">'</span><span
- class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _9" id="Iterator.members.Read2">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Read2:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Read2</span></span><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <a href="#Iterator.interface.TwoChars"><span class="ci">TwoChars</span></a>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <code class="fsharp"><span class="ci">Read2</span><span class="cp">()</span></code> is an optimized implementation of <code
- class="fsharp"><a href="#Iterator.interface.TwoChars"><span class="ci">TwoChars</span></a><span class="cp">(</span><a
- href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">()</span><span class="cp">,</span> <a
- href="#Iterator.members.Next"><span class="ci">Next</span></a><span class="cm">.</span><a href="#Iterator.members.Read"><span
- class="ci">Read</span></a><span class="cp">()</span><span class="cp">)</span></code>.
- </p>
- <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
- </div>
- </div>
- <div class="interface-member _0" id="Iterator.members.Read_int">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Read_int:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Read</span></span><span class="cp">:</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">string</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Is equivalent to <code class="fsharp"><a href="#Iterator.members.Read_int_bool"><span class="ci">Read</span></a><span
- class="cp">(</span><span class="ci">length</span><span class="cp">,</span> <span class="cb">false</span><span class="cp">)</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _1" id="Iterator.members.Read_int_bool">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Read_int_bool:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Read</span></span><span class="cp">:</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">allOrEmpty</span><span class="cp">:</span> <span class="ci">bool</span> <span class="cr">-></span> <span class="ci">string</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns a string with the <code class="fsharp"><span class="ci">length</span></code> stream chars beginning with the char pointed to by the
- <code class="fsharp"><span class="ci">Iterator</span></code>. If less than <code class="fsharp"><span class="ci">length</span></code> chars
- are remaining in the stream, only the remaining chars are returned, or an empty string if <code class="fsharp"><span
- class="ci">allOrEmpty</span></code> is <code class="fsharp"><span class="cb">true</span></code>.
- </p>
- <div class="para _2">
- <div class="admonition">
- <div class="admonition-title">Note</div>
- <div class="admonition-body">
- <p class="para _1">
- <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span><br /> If <code class="fsharp"><span class="ci">length</span></code> is greater than the number of remaining chars
- in the stream, a temporary string with <code class="fsharp"><span class="ci">length</span></code> chars may be allocated. For very large
- <code class="fsharp"><span class="ci">length</span></code> values this might lead to an <code class="fsharp"><span
- class="ci">OutOfMemoryException</span></code> even though a string with only the remaining chars in the stream would comfortably fit into
- memory.
- </p>
- <p class="para _2">
- Please also note that the maximum length of a CLR string is less than 2<sup>30</sup>. Allocating a string larger than the maximum length
- will always yield an <code class="fsharp"><span class="ci">OutOfMemoryException</span></code>, even on 64‐bit systems with enough
- physical memory.
- </p>
- </div>
- </div>
- </div>
- <p class="para _3">
- If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
- exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _2" id="Iterator.members.Read_char-array">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Read_char-array:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Read</span></span><span class="cp">:</span> <span class="ci">buffer</span><span class="cp">:</span> <span class="ci">char</span><span class="cp">[]</span> <span class="cp">*</span> <span class="ci">bufferIndex</span><span class="cp">:</span> <span class="ci">int</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">int</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Copies the <code class="fsharp"><span class="ci">length</span></code> stream chars beginning with the char pointed to by the <code
- class="fsharp"><span class="ci">Iterator</span></code> into <code class="fsharp"><span class="ci">buffer</span></code>. The chars are
- written into <code class="fsharp"><span class="ci">buffer</span></code> beginning at the index <code class="fsharp"><span
- class="ci">bufferIndex</span></code>. If less than <code class="fsharp"><span class="ci">length</span></code> chars are remaining in the
- stream, only the remaining chars are copied. Returns the actual number of chars copied.
- </p>
- <p class="para _2">
- <code class="fsharp"><span class="ci">buffer</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>. An <code
- class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions: <code
- class="fsharp"><span class="ci">bufferIndex</span></code> ≥ 0, <code class="fsharp"><span class="ci">length</span></code> ≥ 0 and <code
- class="fsharp"><span class="ci">bufferIndex</span></code> + <code class="fsharp"><span class="ci">length</span></code> ≤ <code
- class="fsharp"><span class="ci">buffer</span><span class="cm">.</span><span class="ci">Length</span></code>. This method may also throw any
- of the <a href="#exceptions">I/O related exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _3" id="Iterator.members.Read_char-pointer">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Read_char-pointer:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Read</span></span><span class="cp">:</span> <span class="ci">buffer</span><span class="cp">:</span> <span class="ci">NativePtr</span><span class="cp"><</span><span class="ci">char</span><span class="cp">></span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">int</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <span class="small"><span class="italic">This method is not available in the <a href="#remarks.low-trust-version">Low‐Trust version</a> of
- FParsec.</span></span>
- </p>
- <p class="para _2">
- Copies the <code class="fsharp"><span class="ci">length</span></code> stream chars beginning with the char pointed to by the <code
- class="fsharp"><span class="ci">Iterator</span></code> into the buffer at the given pointer address. If less than <code class="fsharp"><span
- class="ci">length</span></code> chars are remaining in the stream, only the remaining chars are copied. Returns the actual number of chars
- copied.
- </p>
- <p class="para _3">
- If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
- exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _4" id="Iterator.members.ReadUntil">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.ReadUntil:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">ReadUntil</span></span><span class="cp">:</span> <span class="ci">iterToCharAfterLastInString</span><span class="cp">:</span> <span class="ci">Iterator</span> <span class="cr">-></span> <span class="ci">string</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Returns a string with all the chars in the stream between the position of this <code class="fsharp"><span class="ci">Iterator</span></code>
- (inclusive) and the position of the <code class="fsharp"><span class="ci">Iterator</span></code> argument (exclusive). If the <code
- class="fsharp"><span class="ci">Iterator</span></code> argument does not point to a position after the position of this <code
- class="fsharp"><span class="ci">Iterator</span></code>, the returned string is empty.
- </p>
- <p class="para _2">
- If the <code class="fsharp"><span class="ci">Iterator</span></code> argument belongs to a different <code class="fsharp"><a href="#"><span
- class="ci">CharStream</span></a></code>, an <code class="fsharp"><a
- href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
- class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
- exceptions</a> detailed above.
- </p>
- </div>
- </div>
- <div class="interface-member _5" id="Iterator.members.Peek">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Peek:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Peek</span></span><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <code class="fsharp"><span class="ci">Peek</span><span class="cp">()</span></code> is an optimized implementation of <code class="fsharp"><a
- href="#Iterator.members.Next"><span class="ci">Next</span></a><span class="cm">.</span><a href="#Iterator.members.Read"><span
- class="ci">Read</span></a><span class="cp">()</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _6" id="Iterator.members.Peek_int">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Peek_int:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Peek</span></span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <code class="fsharp"><span class="ci">Peek</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an
- optimized implementation of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span
- class="cp">(</span><span class="ci">n</span><span class="cp">)</span><span class="cm">.</span><a href="#Iterator.members.Read"><span
- class="ci">Read</span></a><span class="cp">()</span></code>, except that the <code class="fsharp"><a
- href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span
- class="left-delimiter">'</span><span class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) is returned if the new
- position would lie before the beginning of the <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> (instead of an
- exception being thrown).
- </p>
- </div>
- </div>
- <div class="interface-member _7" id="Iterator.members.Peek_uint">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface.Peek_uint:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">Peek</span></span><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- <code class="fsharp"><span class="ci">Peek</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an
- optimized implementation of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span
- class="cp">(</span><span class="ci">n</span><span class="cp">)</span><span class="cm">.</span><a href="#Iterator.members.Read"><span
- class="ci">Read</span></a><span class="cp">()</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _8" id="Iterator.members._Increment">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface._Increment:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">_Increment</span></span><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>in‐place</em> by one char and returns the char on the new
- position.
- </p>
- <p class="para _2">
- <code class="fsharp"><span class="ci">c</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><span
- class="ci">_Increment</span><span class="cp">()</span></code> is an optimized implementation of <code class="fsharp"><span
- class="ci">iter</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><a
- href="#Iterator.members.Next"><span class="ci">Next</span></a><span class="cp">;</span> <span class="ci">c</span> <span
- class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Read"><span
- class="ci">Read</span></a><span class="cp">()</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _9" id="Iterator.members._Increment_uint">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface._Increment_uint:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">_Increment</span></span><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>in‐place</em> by the given number of chars and returns the
- char on the new position.
- </p>
- <p class="para _2">
- <code class="fsharp"><span class="ci">c</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><span
- class="ci">_Increment</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an optimized
- implementation of <code class="fsharp"><span class="ci">iter</span> <span class="co"><-</span> <span class="ci">iter</span><span
- class="cm">.</span><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span class="cp">(</span><span
- class="ci">n</span><span class="cp">)</span><span class="cp">;</span> <span class="ci">c</span> <span class="co"><-</span> <span
- class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span
- class="cp">()</span></code>.
- </p>
- </div>
- </div>
- <div class="interface-member _0" id="Iterator.members._Decrement">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface._Decrement:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">_Decrement</span></span><span class="cp">:</span> <span class="ci">unit</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>in‐place</em> by ‐1 and returns the char on the new position,
- except if the <code class="fsharp"><span class="ci">Iterator</span></code> already points to the beginning of the <code class="fsharp"><a
- href="#"><span class="ci">CharStream</span></a></code>, in which case the position does not change and the <code class="fsharp"><a
- href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span
- class="left-delimiter">'</span><span class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) is returned.
- </p>
- <div class="para _2">
- <p>
- <code class="fsharp"><span class="ci">c</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><span
- class="ci">_Decrement</span><span class="cp">()</span></code> is an optimized implementation of
- </p>
- <pre class="code fsharp"><span class="ck">if</span> <span class="ci">not</span> <span class="cp">(</span><span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.IsBeginOfStream"><span class="ci">IsBeginOfStream</span></a><span class="cp">)</span> <span class="ck">then</span>
- <span class="ci">iter</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span class="cp">(</span><span class="co">-</span><span class="cn">1</span><span class="cp">)</span>
- <span class="ci">c</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">()</span>
- <span class="ck">else</span>
- <span class="ci">c</span> <span class="co"><-</span> <a href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a>
- </pre>
- </div>
- </div>
- </div>
- <div class="interface-member _1" id="Iterator.members._Decrement_uint">
- <div class="interface-member-code">
- <a class="interface-member-backlink" href="#Iterator.interface._Decrement_uint:B:">⇧</a>
- <pre class="code fsharp"><span class="ck">member</span> <span class="interface-member-marker"><span class="ci">_Decrement</span></span><span class="cp">:</span> <span class="ci">uint</span> <span class="cr">-></span> <span class="ci">char</span>
- </pre>
- </div>
- <div class="interface-member-description">
- <p class="para _1">
- Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>in‐place</em> by minus the given number of chars and returns
- the char on the new position, except if the new position would lie before the beginning of the <code class="fsharp"><a href="#"><span
- class="ci">CharStream</span></a></code>, in which case the <code class="fsharp"><span class="ci">Iterator</span></code> is advanced to the
- beginning of the stream and the <code class="fsharp"><a href="#Iterator.members.EndOfStreamChar"><span
- class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span class="left-delimiter">'</span><span
- class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) is returned.
- </p>
- <div class="para _2">
- <p>
- <code class="fsharp"><span class="ci">c</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><span
- class="ci">_Decrement</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an optimized
- implementation of
- </p>
- <pre class="code fsharp"><span class="ck">if</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Index"><span class="ci">Index</span></a> <span class="co">-</span> <span class="ci">n</span> <span class="co">>=</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Stream"><span class="ci">Stream</span></a><span class="cm">.</span><a href="#members.BeginIndex"><span class="ci">BeginIndex</span></a> <span class="ck">then</span>
- <span class="ci">iter</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span class="cp">(</span><span class="co">-</span><span class="ci">n</span><span class="cp">)</span>
- <span class="ci">c</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">()</span>
- <span class="ck">else</span>
- <span class="ci">iter</span> <span class="co"><-</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Stream"><span class="ci">Stream</span></a><span class="cm">.</span><a href="#members.Begin"><span class="ci">Begin</span></a>
- <span class="ci">c</span> <span class="co"><-</span> <a href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a>
- </pre>
- </div>
- </div>
- </div>
- </div>
- </div>
- </div>
- </div>
- </div>
- <div class="fn-list">
- <div class="fn-title">Footnotes:</div>
- <table class="fn">
- <tr class="fn _1">
- <th class="fn _1"><a class="footnote-backlink" id="remarks.:FN:1" href="#remarks.:FN:1:B:">[1]</a></th>
- <td class="fn _2">
- The detection of invalid byte sequences by the .NET decoders is not entirely reliable. For example, <code class="fsharp"><span
- class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span
- class="ci">UnicodeEncoding</span></code> (UTF‐16) has an alignment related bug in .NET versions prior to 4.0 that sometimes leads to invalid
- surrogate pairs not being detected. The implementations of more complicated encodings, like GB18030, ISO‐2022 and ISCII, also have <a
- href="https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=432648">several issues</a> with regard to the detection
- of invalid input data.
- </td>
- </tr>
- </table>
- </div>
- </div>
- </div>
- </div>
- </div>
- </body>
- </html>