PageRenderTime 81ms CodeModel.GetById 22ms RepoModel.GetById 1ms app.codeStats 0ms

/fparsec/main/Doc/html/reference/charstream.html

http://github.com/sandersn/fing
HTML | 1839 lines | 1804 code | 29 blank | 6 comment | 0 complexity | 0eb8354014409e44363fac4b55d0b5f9 MD5 | raw file
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  2. <html xmlns="http://www.w3.org/1999/xhtml">
  3. <head>
  4. <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  5. <title>FParsec.CharStream</title>
  6. <link rel="stylesheet" type="text/css" media="all" href="../css/style.css" />
  7. <link rel="stylesheet" type="text/css" media="screen" href="../css/screen-sidebar.css" title="Sidebar" />
  8. <link rel="alternate stylesheet" type="text/css" media="screen" href="../css/screen-no-sidebar.css" title="No sidebar" />
  9. <!--[if IE]>
  10. <link rel="stylesheet" type="text/css" media="all" href="../css/style-ie.css" />
  11. <![endif]-->
  12. <!--[if IE 6]>
  13. <link rel="stylesheet" type="text/css" media="all" href="../css/style-ie6.css" />
  14. <![endif]-->
  15. <link rel="stylesheet" type="text/css" media="print" href="../css/print.css" />
  16. </head>
  17. <body>
  18. <div id="fixed-layer">
  19. <div id="fixed-wrapper">
  20. <div id="sidebar">
  21. <div id="breadcrumbs-dummy"><span class="breadcrumbs">&nbsp;</span></div>
  22. <div id="nav-tree">
  23. <table class="nav n1">
  24. <tbody class="nav-open n1">
  25. <tr class="nav-entry n1 _1">
  26. <td class="nav-number n1"></td>
  27. <td class="nav-title n1"><a href="../index.html">FParsec Documentation</a></td>
  28. </tr>
  29. <tr class="nav-sub-entries n1 _1">
  30. <td class="nav-sub-entries-number n1"></td>
  31. <td class="nav-sub-entries n1">
  32. <table class="nav n2">
  33. <tbody class="nav-before-open n2">
  34. <tr class="nav-entry n2 _1">
  35. <td class="nav-number n2"><a href="../tutorial.html"><span class="section-number">1</span><span class="nav-space"></span></a></td>
  36. <td class="nav-title n2"><a href="../tutorial.html">Tutorial</a></td>
  37. </tr>
  38. </tbody>
  39. <tbody class="nav-open n2">
  40. <tr class="nav-entry n2 _2">
  41. <td class="nav-number n2"><a href="index.html"><span class="section-number">2</span><span class="nav-space"></span></a></td>
  42. <td class="nav-title n2"><a href="index.html">Reference</a></td>
  43. </tr>
  44. <tr class="nav-sub-entries n2 _2">
  45. <td class="nav-sub-entries-number n2"></td>
  46. <td class="nav-sub-entries n2">
  47. <table class="nav n3">
  48. <tbody class="nav-before-open n3">
  49. <tr class="nav-entry n3 _1">
  50. <td class="nav-number n3"><a href="parser-overview.html"><span class="section-number">1</span><span class="nav-space"></span></a></td>
  51. <td class="nav-title n3"><a href="parser-overview.html">Parser overview</a></td>
  52. </tr>
  53. <tr class="nav-entry n3 _2">
  54. <td class="nav-number n3"><a href="primitives.html"><span class="section-number">2</span><span class="nav-space"></span></a></td>
  55. <td class="nav-title n3"><a href="primitives.html">FParsec.Primitives</a></td>
  56. </tr>
  57. <tr class="nav-entry n3 _3">
  58. <td class="nav-number n3"><a href="charparsers.html"><span class="section-number">3</span><span class="nav-space"></span></a></td>
  59. <td class="nav-title n3"><a href="charparsers.html">FParsec.CharParsers</a></td>
  60. </tr>
  61. <tr class="nav-entry n3 _4">
  62. <td class="nav-number n3">
  63. <a href="operatorprecedenceparser.html"><span class="section-number">4</span><span class="nav-space"></span></a>
  64. </td>
  65. <td class="nav-title n3"><a href="operatorprecedenceparser.html">FParsec.OperatorPrecedenceParser</a></td>
  66. </tr>
  67. <tr class="nav-entry n3 _5">
  68. <td class="nav-number n3"><a href="error.html"><span class="section-number">5</span><span class="nav-space"></span></a></td>
  69. <td class="nav-title n3"><a href="error.html">FParsec.Error</a></td>
  70. </tr>
  71. <tr class="nav-entry n3 _6">
  72. <td class="nav-number n3"><a href="state.html"><span class="section-number">6</span><span class="nav-space"></span></a></td>
  73. <td class="nav-title n3"><a href="state.html">FParsec.State</a></td>
  74. </tr>
  75. <tr class="nav-entry n3 _7">
  76. <td class="nav-number n3"><a href="position.html"><span class="section-number">7</span><span class="nav-space"></span></a></td>
  77. <td class="nav-title n3"><a href="position.html">FParsec.Position</a></td>
  78. </tr>
  79. </tbody>
  80. <tbody class="nav-open selected n3">
  81. <tr class="nav-entry selected n3 _8">
  82. <td class="nav-number selected n3"><a href="#"><span class="section-number">8</span><span class="nav-space"></span></a></td>
  83. <td class="nav-title selected n3"><a href="#">FParsec.CharStream</a></td>
  84. </tr>
  85. <tr class="nav-sub-entries selected n3 _8">
  86. <td class="nav-sub-entries-number selected n3"></td>
  87. <td class="nav-sub-entries selected n3">
  88. <table class="nav n4">
  89. <tbody class="nav-before-open n4">
  90. <tr class="nav-entry n4 _1">
  91. <td class="nav-number n4"><a href="#interface"><span class="section-number">1</span><span class="nav-space"></span></a></td>
  92. <td class="nav-title n4"><a href="#interface">Interface</a></td>
  93. </tr>
  94. <tr class="nav-entry n4 _2">
  95. <td class="nav-number n4"><a href="#remarks"><span class="section-number">2</span><span class="nav-space"></span></a></td>
  96. <td class="nav-title n4"><a href="#remarks">Remarks</a></td>
  97. </tr>
  98. <tr class="nav-entry n4 _3">
  99. <td class="nav-number n4"><a href="#exceptions"><span class="section-number">3</span><span class="nav-space"></span></a></td>
  100. <td class="nav-title n4"><a href="#exceptions">I/O exceptions</a></td>
  101. </tr>
  102. <tr class="nav-entry n4 _4">
  103. <td class="nav-number n4"><a href="#members"><span class="section-number">4</span><span class="nav-space"></span></a></td>
  104. <td class="nav-title n4"><a href="#members">Members</a></td>
  105. </tr>
  106. <tr class="nav-entry n4 _5">
  107. <td class="nav-number n4"><a href="#Iterator"><span class="section-number">5</span><span class="nav-space"></span></a></td>
  108. <td class="nav-title n4"><a href="#Iterator">CharStream.Iterator</a></td>
  109. </tr>
  110. <tr class="nav-sub-entries n4 _5">
  111. <td class="nav-sub-entries-number n4"></td>
  112. <td class="nav-sub-entries n4">
  113. <table class="nav n5">
  114. <tbody class="nav-before-open n5">
  115. <tr class="nav-entry n5 _1">
  116. <td class="nav-number n5">
  117. <a href="#Iterator.interface"><span class="section-number">1</span><span class="nav-space"></span></a>
  118. </td>
  119. <td class="nav-title n5"><a href="#Iterator.interface">Interface</a></td>
  120. </tr>
  121. <tr class="nav-entry n5 _2">
  122. <td class="nav-number n5">
  123. <a href="#Iterator.members"><span class="section-number">2</span><span class="nav-space"></span></a>
  124. </td>
  125. <td class="nav-title n5"><a href="#Iterator.members">Members</a></td>
  126. </tr>
  127. </tbody>
  128. </table>
  129. </td>
  130. </tr>
  131. </tbody>
  132. </table>
  133. </td>
  134. </tr>
  135. </tbody>
  136. </table>
  137. </td>
  138. </tr>
  139. </tbody>
  140. </table>
  141. </td>
  142. </tr>
  143. </tbody>
  144. </table>
  145. </div>
  146. </div>
  147. </div>
  148. </div>
  149. <div id="wrapper">
  150. <div id="main">
  151. <div id="main-content">
  152. <div id="breadcrumbs">
  153. <span class="breadcrumbs">
  154. <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
  155. </span>
  156. </div>
  157. <div class="section s2">
  158. <h1 class="title h2"><span class="section-number">2.8</span> FParsec.CharStream</h1>
  159. <div class="intro i2">
  160. <p class="para _1">
  161. The <code class="fsharp"><span class="ci">CharStream</span></code> class provides a unified interface for reading the UTF16 char content from
  162. binary streams or inmemory char buffers.
  163. </p>
  164. </div>
  165. <div id="interface" class="section s3">
  166. <h2 class="title h3"><span class="section-number">2.8.1</span> Interface</h2>
  167. <div class="intro i3">
  168. <div class="para _1">
  169. <pre class="code fsharp"><span class="ck">namespace</span> <span class="ci">FParsec</span>
  170. <span class="cp">[&lt;</span><span class="ci">Sealed</span><span class="cp">&gt;]</span>
  171. <span class="ck">type</span> <span class="ci">CharStream</span> <span class="cp">=</span>
  172. <span class="ck">interface</span> <span class="ci">System</span><span class="cm">.</span><span class="ci">IDisposable</span>
  173. <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>
  174. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  175. <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>
  176. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  177. <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>
  178. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  179. <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>
  180. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  181. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
  182. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  183. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</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>
  184. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  185. <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>
  186. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  187. <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>
  188. <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>
  189. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  190. <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>
  191. <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>
  192. <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>
  193. <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
  194. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  195. <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>
  196. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  197. <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>
  198. <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>
  199. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  200. <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>
  201. <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>
  202. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  203. <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>
  204. <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>
  205. <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>
  206. <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
  207. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  208. <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">-&gt;</span> <span class="ci">unit</span>
  209. <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>
  210. <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">-&gt;</span> <a href="#Iterator"><span class="ci">Iterator</span></a>
  211. <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>
  212. <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>
  213. <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">-&gt;</span> <span class="ci">string</span>
  214. <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">-&gt;</span> <span class="ci">string</span>
  215. <span class="cp">[&lt;</span><span class="ci">Struct</span><span class="cp">&gt;]</span>
  216. <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>
  217. </pre>
  218. </div>
  219. </div>
  220. </div>
  221. <div id="remarks" class="section s3">
  222. <h2 class="title h3"><span class="section-number">2.8.2</span> Remarks</h2>
  223. <div class="intro i3">
  224. <p class="para _1">
  225. The <code class="fsharp"><span class="ci">CharStream</span></code> class provides an <a
  226. href="http://en.wikipedia.org/wiki/Iterator">iteratorbased</a> interface for reading UTF16 chars from a binary stream or an inmemory char
  227. buffer (e.g. a string). It is optimized for use in backtracking parser applications and supports arbitrary <em>charbased</em> seeking, even for
  228. streams larger than physical memory.
  229. </p>
  230. <p class="para _2">
  231. A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a <code class="fsharp"><a
  232. href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
  233. class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path reads the stream blockwise and only holds
  234. the most recently accessed block in memory. The blocks overlap in order to provide efficient access on the boundary between blocks.
  235. </p>
  236. <p class="para _3">
  237. 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
  238. directly constructed from the char buffer (without needing to copy the buffer). The overhead of accessing an inmemory char buffer through a
  239. <code class="fsharp"><span class="ci">CharStream</span></code> is minimal.
  240. </p>
  241. <p class="para _4">
  242. You can access the content of a <code class="fsharp"><span class="ci">CharStream</span></code> only through its <code class="fsharp"><a
  243. href="#Iterator"><span class="ci">Iterator</span></a></code> instances. The <code class="fsharp"><a href="#members.Begin"><span
  244. class="ci">Begin</span></a></code> property returns an iterator pointing to the first char in the stream. The <code class="fsharp"><a
  245. href="#members.Seek"><span class="ci">Seek</span></a></code> method returns an iterator pointing to the char with a given index.
  246. </p>
  247. <div class="para _5">
  248. <div class="dl multi-para">
  249. <dl class="dl multi-para">
  250. <dt class="_1"><a id="remarks.low-trust-version"></a>LowTrust version</dt>
  251. <dd class="_1">
  252. <div class="para _1">
  253. <p>
  254. If you compile FParsec with the <code class="fsharp"><span class="ci">LOW_TRUST</span></code> conditional compiler symbol, the <code
  255. class="fsharp"><span class="ci">CharStream</span></code> class differs from the normal version as follows:
  256. </p>
  257. <ul class="l1">
  258. <li class="_1">
  259. No <a href="http://msdn.microsoft.com/en-us/library/t2yzs44b.aspx">unverifiable code</a> involving pointers is used. <em>This allows
  260. FParsec to be executed in an environment with reduced trust</em>, such as medium trust ASP.NET applications.
  261. </li>
  262. <li class="_2">
  263. A <code class="fsharp"><span class="ci">CharStream</span></code> that is constructed from a <code class="fsharp"><a
  264. href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
  265. 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
  266. string during construction. <em>This severely limits the maximum practical stream size.</em>
  267. </li>
  268. <li class="_3">
  269. Although the <code class="fsharp"><span class="ci">CharStream</span></code> class still supports the <code class="fsharp"><span
  270. class="ci">IDisposable</span></code> interface, disposing the <code class="fsharp"><span class="ci">CharStream</span></code> instances is
  271. no longer necessary, since no resources are hold that need to be explicitly released.
  272. </li>
  273. </ul>
  274. </div>
  275. </dd>
  276. <dt class="_2"><a id="remarks.non-sequential-access"></a>Nonsequential access</dt>
  277. <dd class="_2">
  278. <p class="para _1">
  279. <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">LowTrust version</a> of
  280. FParsec.</span></span><br /> If you construct a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
  281. href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
  282. 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
  283. enough to require the <code class="fsharp"><span class="ci">CharStream</span></code> to reread a previous block, then the underlying
  284. <strong>byte stream needs to support seeking</strong>, otherwise a <code class="fsharp"><a
  285. href="http://msdn.microsoft.com/en-us/library/system.notsupportedexception.aspx"><span class="ci">NotSupportedException</span></a></code> is
  286. thrown. Furthermore, the <strong><a href="http://msdn.microsoft.com/en-us/library/system.text.decoder.aspx">Decoder</a> for the input <a
  287. href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx">Encoding</a> must be serializable</strong> if you backtrack to a
  288. 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
  289. standard decoders are serializable</em>. In order to support nonseekable streams for applications which dont require extensive
  290. backtracking, no exception will be thrown before an operation actually requires backtracking and the necessary capabilities of the stream or
  291. decoder are not available.
  292. </p>
  293. </dd>
  294. <dt class="_3">Decoder errors</dt>
  295. <dd class="_3">
  296. <p class="para _1">
  297. A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a binary input stream decodes the input data with the help
  298. of a <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.text.decoder.aspx"><span
  299. class="ci">Decoder</span></a></code> instance obtained via the <code class="fsharp"><span class="ci">Encodings</span></code>s <code
  300. class="fsharp"><span class="ci">GetDecoder</span></code> method. Depending on the configuration of the encoding the decoder might throw an
  301. exception if it encounters invalid byte sequences, usually a <code class="fsharp"><span class="ci">System</span><span
  302. class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><a
  303. href="http://msdn.microsoft.com/en-us/library/system.text.decoderfallbackexception.aspx"><span
  304. class="ci">DecoderFallbackException</span></a></code> or a <code class="fsharp"><span class="ci">System</span><span class="cm">.</span><span
  305. class="ci">IO</span><span class="cm">.</span><a href="http://msdn.microsoft.com/en-us/library/system.argumentexception.aspx"><span
  306. class="ci">ArgumentException</span></a></code>. <sup class="fn-mark"><a id="remarks.:FN:1:B:" href="#remarks.:FN:1">[1]</a></sup>
  307. </p>
  308. </dd>
  309. <dt class="_4"><a id="remarks.case-insensitive-matching"></a>Caseinsensitive matching</dt>
  310. <dd class="_4">
  311. <p class="para _1">
  312. The <code class="fsharp"><a href="#Iterator.members.MatchCaseFolded"><span class="ci">MatchCaseFolded</span></a></code> member matches the
  313. content of the stream &#x201C;caseinsensitively&#x201D; with a reference string. In this instance &#x201C;caseinsensitive&#x201D; means
  314. that before the chars are matched with the reference string they are <a
  315. href="http://unicode.org/reports/tr21/tr21-5.html#Caseless_Matching">mapped to a canonical form where case differences are erased</a>. For
  316. performance reasons <code class="fsharp"><a href="#Iterator.members.MatchCaseFolded"><span class="ci">MatchCaseFolded</span></a></code> only
  317. applies the (nonTurkic) 1to1 <a href="http://unicode.org/Public/UNIDATA/CaseFolding.txt">case folding mappings</a> (v. 5.1) for Unicode
  318. code points in the Basic Multilingual Plane, i.e. code points below 0x10000. These mappings are sufficient for many caseinsensitive parser
  319. grammars encountered in practice, but they are not appropriate for matching arbitrary natural language content. Also note that the <code
  320. class="fsharp"><span class="ci">CharStream</span></code> class performs no Unicode <a
  321. href="http://unicode.org/reports/tr15/">normalization</a>.
  322. </p>
  323. </dd>
  324. <dt class="_5">Newlines</dt>
  325. <dd class="_5">
  326. <p class="para _1">
  327. The <code class="fsharp"><span class="ci">CharStream</span></code> class itself does not apply any automatic newline conversion to the
  328. processed input. A useful helper function for this purpose is <code class="fsharp"><a href="#members.NormalizeNewlines"><span
  329. class="ci">NormalizeNewlines</span></a></code>, which replaces all ASCII newline character sequences (<code class="fsharp"><span
  330. class="cs"><span class="left-delimiter">"</span><span class="ce">\n</span><span class="right-delimiter">"</span></span></code>, <code
  331. class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span class="ce">\r</span><span class="ce">\n</span><span
  332. class="right-delimiter">"</span></span></code> or <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span
  333. class="ce">\r</span><span class="right-delimiter">"</span></span></code>) in a given string with <code class="fsharp"><span class="cs"><span
  334. class="left-delimiter">"</span><span class="ce">\n</span><span class="right-delimiter">"</span></span></code>.
  335. </p>
  336. </dd>
  337. <dt class="_6">Disposable interface</dt>
  338. <dd class="_6">
  339. <p class="para _1">
  340. <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">LowTrust version</a> of
  341. FParsec.</span></span><br /> A <code class="fsharp"><span class="ci">CharStream</span></code> holds managed and unmanaged resources that need
  342. to be explicitly released. Hence, it is very important that <code class="fsharp"><span class="ci">CharStream</span></code> objects are
  343. promptly disposed after use. Where possible <code class="fsharp"><span class="ci">CharStream</span></code> objects should only be used within
  344. a &#x201C;using&#x201D; block (C#), a &#x201C;use&#x201D; expression( F#) or similar constructs in other languages. Members of <code
  345. class="fsharp"><a href="#Iterator"><span class="ci">CharStream</span><span class="cm">.</span><span class="ci">Iterator</span></a></code>
  346. instances must not be accessed after the corresponding <code class="fsharp"><span class="ci">CharStream</span></code> has been disposed, of
  347. course.
  348. </p>
  349. </dd>
  350. <dt class="_7">Thread safety</dt>
  351. <dd class="_7">
  352. <p class="para _1">
  353. A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a <code class="fsharp"><a
  354. href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
  355. 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
  356. not be accessed by multiple threads, except in the <a href="#remarks.low-trust-version">LowTrust version</a> of FParsec. A <code
  357. class="fsharp"><span class="ci">CharStream</span></code> constructed directly from a string, char array or char pointer can always be safely
  358. accessed concurrently using different <code class="fsharp"><span class="ci">Iterators</span></code> (provided that the <code
  359. class="fsharp"><span class="ci">CharStream</span></code> is disposed by only one thread, of course). <span class="italic"><code
  360. class="fsharp"><a href="#Iterator"><span class="ci">CharStream</span><span class="cm">.</span><span class="ci">Iterator</span></a></code>
  361. instances are never thread safe.</span>
  362. </p>
  363. </dd>
  364. </dl>
  365. </div>
  366. </div>
  367. </div>
  368. </div>
  369. <div id="exceptions" class="section s3">
  370. <h2 class="title h3"><span class="section-number">2.8.3</span> I/O exceptions</h2>
  371. <div class="intro i3">
  372. <p class="para _1">
  373. If you construct a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
  374. href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
  375. class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path, any <code class="fsharp"><span
  376. class="ci">CharStream</span></code> operation that requires reading chars from the underlying byte stream may throw one of the following
  377. exceptions.
  378. </p>
  379. <p class="para _2">
  380. 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
  381. these exceptions was thrown. Calling <code class="fsharp"><a href="#members.Dispose"><span class="ci">Dispose</span></a><span
  382. class="cp">()</span></code> on an <code class="fsharp"><span class="ci">CharStream</span></code> instance after the instance or one of its
  383. iterators has thrown an exception is always safe.
  384. </p>
  385. <div class="para _3">
  386. <div class="dl multi-para">
  387. <dl class="dl multi-para">
  388. <dt class="_1"><code class="fsharp"><span class="ci">NotSupportedException</span></code></dt>
  389. <dd class="_1">
  390. <p class="para _1">
  391. Seeking of the underlying byte stream is required, but the byte stream does not support seeking or the <code class="fsharp"><a
  392. href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">Encoding</span></a></code>s <code
  393. class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.text.decoder.aspx"><span class="ci">Decoder</span></a></code> is not
  394. serializable. See also the remarks above on <a href="#remarks.non-sequential-access">nonsequential access</a>.
  395. </p>
  396. </dd>
  397. <dt class="_2"><code class="fsharp"><span class="ci">IOException</span></code></dt>
  398. <dd class="_2">
  399. <p class="para _1">An I/O occured while reading data from the underlying byte stream.</p>
  400. </dd>
  401. <dt class="_3"><code class="fsharp"><span class="ci">ArgumentException</span></code></dt>
  402. <dd class="_3">
  403. <p class="para _1">
  404. The underlying byte stream contains invalid bytes and the <code class="fsharp"><a
  405. href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span class="ci">Encoding</span></a></code> was constructed with the
  406. <code class="fsharp"><span class="ci">throwOnInvalidBytes</span></code> option.
  407. </p>
  408. </dd>
  409. <dt class="_4"><code class="fsharp"><span class="ci">DecoderFallbackException</span></code></dt>
  410. <dd class="_4">
  411. <p class="para _1">The underlying byte stream contains invalid bytes for which the decoder fallback threw this exception.</p>
  412. <p class="para _2">
  413. The byte index of the invalid bytes in the stream is stored as a boxed <code class="fsharp"><span class="ci">System</span><span
  414. class="cm">.</span><span class="ci">Int64</span></code> in the <code class="fsharp"><span class="cs"><span
  415. class="left-delimiter">"</span>Stream.Position<span class="right-delimiter">"</span></span></code> entry of the <code class="fsharp"><a
  416. href="http://msdn.microsoft.com/en-us/library/system.exception.data.aspx"><span class="ci">Data</span></a></code> member of the exception
  417. instance. The precision of the index depends on the precision of the <code class="fsharp"><a
  418. href="http://msdn.microsoft.com/en-us/library/system.text.decoderfallbackexception.aspx"><span
  419. class="ci">DecoderFallbackException</span></a></code>s <code class="fsharp"><a
  420. href="http://msdn.microsoft.com/en-us/library/system.text.decoderfallbackexception.index.aspx"><span class="ci">Index</span></a></code>
  421. member. If the underlying <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span
  422. class="ci">System</span><span class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code>
  423. is not seekable, the byte index only takes into account the bytes read by the <code class="fsharp"><span class="ci">CharStream</span></code>,
  424. but not any bytes read before the <code class="fsharp"><span class="ci">CharStream</span></code> was constructed.
  425. </p>
  426. </dd>
  427. </dl>
  428. </div>
  429. </div>
  430. </div>
  431. </div>
  432. <div id="members" class="section s3">
  433. <h2 class="title h3"><span class="section-number">2.8.4</span> Members</h2>
  434. <div class="intro i3">
  435. <div class="para _1">
  436. <div class="interface-members">
  437. <div class="interface-member _1" id="members.new_string">
  438. <div class="interface-member-code">
  439. <a class="interface-member-backlink" href="#interface.new_string:B:"></a>
  440. <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>
  441. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  442. </pre>
  443. </div>
  444. <div class="interface-member-description">
  445. <p class="para _1">
  446. Is equivalent to <code class="fsharp"><a href="#members.new_string_offset"><span class="ck">new</span> <span
  447. class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">chars</span><span class="cp">,</span> <span
  448. class="ci">index</span><span class="cp">,</span> <span class="ci">length</span><span class="cp">,</span> <span class="cn">0L</span><span
  449. class="cp">)</span></code>.
  450. </p>
  451. </div>
  452. </div>
  453. <div class="interface-member _2" id="members.new_string_offset">
  454. <div class="interface-member-code">
  455. <a class="interface-member-backlink" href="#interface.new_string_offset:B:"></a>
  456. <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>
  457. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  458. </pre>
  459. </div>
  460. <div class="interface-member-description">
  461. <p class="para _1">
  462. Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from the chars in the string argument between the indices <code
  463. class="fsharp"><span class="ci">index</span></code> (inclusive) and <code class="fsharp"><span class="ci">index</span> <span
  464. class="co">+</span> <span class="ci">length</span></code> (exclusive). By directly referencing the chars in the string this constructor
  465. avoids any copy of the string content.
  466. </p>
  467. <p class="para _2">
  468. The first char in the stream is assigned the index <code class="fsharp"><span class="ci">streamBeginIndex</span></code>. A positive <code
  469. class="fsharp"><span class="ci">streamBeginIndex</span></code> allows you for example to create a substream of another <code
  470. class="fsharp"><span class="ci">CharStream</span></code>, i.e. a <code class="fsharp"><span class="ci">CharStream</span></code> instance that
  471. only contains a subsegment of another char stream but is accessible through the same char indices.
  472. </p>
  473. <div class="para _3">
  474. <p>
  475. <code class="fsharp"><span class="ci">chars</span></code> must not be null. An <code class="fsharp"><a
  476. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  477. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions:
  478. </p>
  479. <ul class="l1">
  480. <li class="_1">
  481. <code class="fsharp"><span class="ci">index</span></code> 0, <code class="fsharp"><span class="ci">length</span></code> 0, <code
  482. class="fsharp"><span class="ci">index</span></code> + <code class="fsharp"><span class="ci">length</span></code> <code
  483. class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code> and
  484. </li>
  485. <li class="_2">0 <code class="fsharp"><span class="ci">streamBeginIndex</span></code> &lt; 2<sup>60</sup>.</li>
  486. </ul>
  487. </div>
  488. <div class="para _4">
  489. <div class="admonition">
  490. <div class="admonition-title">Important</div>
  491. <div class="admonition-body">
  492. <p class="para _1">
  493. <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">LowTrust version</a> of
  494. FParsec.</span></span><br /> The given string is &#x201C;<a
  495. href="http://msdn.microsoft.com/en-us/library/83y4ak54.aspx">pinned</a>&#x201D; until the <code class="fsharp"><span
  496. class="ci">CharStream</span></code> is disposed. Pinning the string prevents the GC from moving it around in memory during garbage
  497. 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
  498. on the Large Object Heap, i.e. has a length of about 42500 chars or more. However, pinning smaller strings does constrain the normal
  499. operations of the GC. Thus, <strong>to minimize the negative impact on the GC, you should dispose <code class="fsharp"><span
  500. class="ci">CharStream</span></code> instances constructed from small strings as soon as youre done parsing it</strong>. If you keep a
  501. large number of <code class="fsharp"><span class="ci">CharStream</span></code> instances constructed from small strings around for an
  502. extended period of time, you risk fragmenting the heap.
  503. </p>
  504. </div>
  505. </div>
  506. </div>
  507. </div>
  508. </div>
  509. <div class="interface-member _3" id="members.new_char-array">
  510. <div class="interface-member-code">
  511. <a class="interface-member-backlink" href="#interface.new_char-array:B:"></a>
  512. <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>
  513. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  514. </pre>
  515. </div>
  516. <div class="interface-member-description">
  517. <p class="para _1">
  518. <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">LowTrust version</a>
  519. of FParsec.</span></span>
  520. </p>
  521. <p class="para _2">
  522. Is equivalent to <code class="fsharp"><a href="#members.new_char-array_offset"><span class="ck">new</span> <span
  523. class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">chars</span><span class="cp">,</span> <span
  524. class="ci">index</span><span class="cp">,</span> <span class="ci">length</span><span class="cp">,</span> <span class="cn">0L</span><span
  525. class="cp">)</span></code>.
  526. </p>
  527. </div>
  528. </div>
  529. <div class="interface-member _4" id="members.new_char-array_offset">
  530. <div class="interface-member-code">
  531. <a class="interface-member-backlink" href="#interface.new_char-array_offset:B:"></a>
  532. <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>
  533. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  534. </pre>
  535. </div>
  536. <div class="interface-member-description">
  537. <p class="para _1">
  538. <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">LowTrust version</a>
  539. of FParsec.</span></span>
  540. </p>
  541. <p class="para _2">
  542. Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from the chars in the char array argument between the indices
  543. <code class="fsharp"><span class="ci">index</span></code> (inclusive) and <code class="fsharp"><span class="ci">index</span> <span
  544. class="co">+</span> <span class="ci">length</span></code> (exclusive). By directly referencing the chars in the char array this constructor
  545. avoids any copy of the char array content.
  546. </p>
  547. <p class="para _3">
  548. The first char in the stream is assigned the index <code class="fsharp"><span class="ci">streamBeginIndex</span></code>. A positive <code
  549. class="fsharp"><span class="ci">streamBeginIndex</span></code> allows you for example to create a substream of another <code
  550. class="fsharp"><span class="ci">CharStream</span></code>, i.e. a <code class="fsharp"><span class="ci">CharStream</span></code> instance that
  551. only contains a subsegment of another char stream but is accessible through the same char indices.
  552. </p>
  553. <div class="para _4">
  554. <p>
  555. <code class="fsharp"><span class="ci">chars</span></code> must not be null. An <code class="fsharp"><a
  556. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  557. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions:
  558. </p>
  559. <ul class="l1">
  560. <li class="_1">
  561. <code class="fsharp"><span class="ci">index</span></code> 0, <code class="fsharp"><span class="ci">length</span></code> 0, <code
  562. class="fsharp"><span class="ci">index</span></code> + <code class="fsharp"><span class="ci">length</span></code> <code
  563. class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code> and
  564. </li>
  565. <li class="_2">0 <code class="fsharp"><span class="ci">streamBeginIndex</span></code> &lt; 2<sup>60</sup>.</li>
  566. </ul>
  567. </div>
  568. <div class="para _5">
  569. <div class="admonition">
  570. <div class="admonition-title">Note</div>
  571. <div class="admonition-body">
  572. <p class="para _1">
  573. A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a char array does not support .NET regex matching via
  574. the <code class="fsharp"><a href="#Iterator.members.Match_Regex"><span class="ci">Iterator</span><span class="cm">.</span><span
  575. class="ci">Match</span></a></code> member.
  576. </p>
  577. </div>
  578. </div>
  579. </div>
  580. <div class="para _6">
  581. <div class="admonition">
  582. <div class="admonition-title">Important</div>
  583. <div class="admonition-body">
  584. <p class="para _1">
  585. The given char array is &#x201C;<a href="http://msdn.microsoft.com/en-us/library/83y4ak54.aspx">pinned</a>&#x201D; until the <code
  586. class="fsharp"><span class="ci">CharStream</span></code> is disposed. Pinning the char array prevents the GC from moving it around in
  587. 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
  588. 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
  589. arrays does constrain the normal operations of the GC. Thus, <strong>to minimize the negative impact on the GC, you should dispose <code
  590. class="fsharp"><span class="ci">CharStream</span></code> instances constructed from small char arrays as soon as youre done parsing
  591. it</strong>. If you keep a large number of <code class="fsharp"><span class="ci">CharStream</span></code> instances constructed from small
  592. char arrays around for an extended period of time, you risk fragmenting the heap.
  593. </p>
  594. </div>
  595. </div>
  596. </div>
  597. </div>
  598. </div>
  599. <div class="interface-member _5" id="members.new_char-pointer">
  600. <div class="interface-member-code">
  601. <a class="interface-member-backlink" href="#interface.new_char-pointer:B:"></a>
  602. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span>
  603. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  604. </pre>
  605. </div>
  606. <div class="interface-member-description">
  607. <p class="para _1">
  608. <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">LowTrust version</a>
  609. of FParsec.</span></span><br />
  610. </p>
  611. <p class="para _2">
  612. Is equivalent to <code class="fsharp"><a href="#members.new_char-pointer_offset"><span class="ck">new</span> <span
  613. class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">chars</span><span class="cp">,</span> <span
  614. class="ci">length</span><span class="cp">,</span> <span class="cn">0L</span><span class="cp">)</span></code>.
  615. </p>
  616. </div>
  617. </div>
  618. <div class="interface-member _6" id="members.new_char-pointer_offset">
  619. <div class="interface-member-code">
  620. <a class="interface-member-backlink" href="#interface.new_char-pointer_offset:B:"></a>
  621. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</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>
  622. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  623. </pre>
  624. </div>
  625. <div class="interface-member-description">
  626. <p class="para _1">
  627. <span class="small"><span class="italic">This constructor is not available in the <a href="#remarks.low-trust-version">LowTrust version</a>
  628. of FParsec.</span></span>
  629. </p>
  630. <p class="para _2">
  631. Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from the <code class="fsharp"><span
  632. class="ci">length</span></code> chars at the pointer address. By directly referencing the chars at the pointer address this constructor
  633. avoids any copy of the char buffer.
  634. </p>
  635. <p class="para _3">
  636. The first char in the stream is assigned the index <code class="fsharp"><span class="ci">streamBeginIndex</span></code>. A positive <code
  637. class="fsharp"><span class="ci">streamBeginIndex</span></code> allows you for example to create a substream of another <code
  638. class="fsharp"><span class="ci">CharStream</span></code>, i.e. a <code class="fsharp"><span class="ci">CharStream</span></code> instance that
  639. only contains a subsegment of another char stream but is accessible through the same char indices.
  640. </p>
  641. <div class="para _4">
  642. <p>
  643. <code class="fsharp"><span class="ci">chars</span></code> must not be null. An <code class="fsharp"><a
  644. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  645. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions:
  646. </p>
  647. <ul class="l1">
  648. <li class="_1">
  649. <code class="fsharp"><span class="ci">length</span></code> 0, <code class="fsharp"><span class="ci">chars</span> <span
  650. class="co">+</span> <span class="ci">length</span></code> must not overflow and
  651. </li>
  652. <li class="_2">0 <code class="fsharp"><span class="ci">streamBeginIndex</span></code> &lt; 2<sup>60</sup>.</li>
  653. </ul>
  654. </div>
  655. <div class="para _5">
  656. <div class="admonition">
  657. <div class="admonition-title">Note</div>
  658. <div class="admonition-body">
  659. <p class="para _1">
  660. A <code class="fsharp"><span class="ci">CharStream</span></code> constructed from a pointer does not support .NET regex matching via the
  661. <code class="fsharp"><a href="#Iterator.members.Match_Regex"><span class="ci">Iterator</span><span class="cm">.</span><span
  662. class="ci">Match</span></a></code> member.
  663. </p>
  664. </div>
  665. </div>
  666. </div>
  667. </div>
  668. </div>
  669. <div class="interface-member _7" id="members.new_file-path">
  670. <div class="interface-member-code">
  671. <a class="interface-member-backlink" href="#interface.new_file-path:B:"></a>
  672. <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>
  673. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  674. </pre>
  675. </div>
  676. <div class="interface-member-description">
  677. <p class="para _1">
  678. Is equivalent to <code class="fsharp"><a href="#members.new_file-path_2"><span class="ck">new</span> <span
  679. class="ci">CharStream</span></a><span class="cp">(</span><span class="ci">path</span><span class="cp">,</span> <span
  680. class="ci">encoding</span><span class="cp">,</span> <span class="cb">true</span><span class="cp">)</span></code>.
  681. </p>
  682. </div>
  683. </div>
  684. <div class="interface-member _8" id="members.new_file-path_2">
  685. <div class="interface-member-code">
  686. <a class="interface-member-backlink" href="#interface.new_file-path_2:B:"></a>
  687. <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>
  688. <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>
  689. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  690. </pre>
  691. </div>
  692. <div class="interface-member-description">
  693. <div class="para _1">
  694. <p>Is equivalent to</p>
  695. <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>
  696. <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>
  697. <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>
  698. <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>
  699. <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>
  700. <span class="ci">byteBufferLength</span> <span class="cp">=</span> <span class="ci">DefaultByteBufferLength</span>
  701. <span class="cp">)</span>
  702. </pre>
  703. </div>
  704. </div>
  705. </div>
  706. <div class="interface-member _9" id="members.new_file-path_3">
  707. <div class="interface-member-code">
  708. <a class="interface-member-backlink" href="#interface.new_file-path_3:B:"></a>
  709. <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>
  710. <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>
  711. <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>
  712. <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
  713. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  714. </pre>
  715. </div>
  716. <div class="interface-member-description">
  717. <div class="para _1">
  718. <p>
  719. Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
  720. href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span class="ci">FileStream</span></a></code> as if by calling
  721. </p>
  722. <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>
  723. <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>
  724. <span class="ci">FileOptions</span><span class="cm">.</span><span class="ci">SequentialScan</span><span class="cp">)</span><span class="cp">,</span>
  725. <span class="ci">leaveOpen</span> <span class="cp">=</span> <span class="cb">false</span><span class="cp">,</span>
  726. <span class="ci">encoding</span> <span class="cp">=</span> <span class="ci">encoding</span><span class="cp">,</span>
  727. <span class="ci">detectEncoding</span> <span class="cp">=</span> <span class="cb">true</span><span class="cp">,</span>
  728. <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>
  729. <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>
  730. <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>
  731. <span class="ci">byteBufferLength</span> <span class="cp">=</span> <span class="ci">DefaultByteBufferLength</span>
  732. <span class="cp">)</span>
  733. </pre>
  734. </div>
  735. <p class="para _2">
  736. If an exception occurs after the <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span
  737. class="ci">FileStream</span></a></code> is constructed but before the <code class="fsharp"><span class="ci">CharStream</span></code>
  738. constructor is finished, the <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span
  739. class="ci">FileStream</span></a></code> is disposed.
  740. </p>
  741. <div class="para _3">
  742. <div class="admonition">
  743. <div class="admonition-title">Note</div>
  744. <div class="admonition-body">
  745. <p class="para _1">
  746. The <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.filestream.aspx"><span
  747. class="ci">FileStream</span></a></code> constructor might throw an exception, too.
  748. </p>
  749. </div>
  750. </div>
  751. </div>
  752. </div>
  753. </div>
  754. <div class="interface-member _0" id="members.new_stream">
  755. <div class="interface-member-code">
  756. <a class="interface-member-backlink" href="#interface.new_stream:B:"></a>
  757. <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>
  758. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  759. </pre>
  760. </div>
  761. <div class="interface-member-description">
  762. <p class="para _1">
  763. Is equivalent to <code class="fsharp"><a href="#members.new_stream_3"><span class="ck">new</span> <span class="ci">CharStream</span></a><span
  764. class="cp">(</span><span class="ci">stream</span><span class="cp">,</span> <span class="cb">false</span><span class="cp">,</span> <span
  765. class="ci">encoding</span><span class="cp">,</span> <span class="cb">true</span><span class="cp">)</span></code>.
  766. </p>
  767. </div>
  768. </div>
  769. <div class="interface-member _1" id="members.new_stream_2">
  770. <div class="interface-member-code">
  771. <a class="interface-member-backlink" href="#interface.new_stream_2:B:"></a>
  772. <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>
  773. <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>
  774. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  775. </pre>
  776. </div>
  777. <div class="interface-member-description">
  778. <p class="para _1">
  779. Is equivalent to <code class="fsharp"><a href="#members.new_stream_3"><span class="ck">new</span> <span class="ci">CharStream</span></a><span
  780. class="cp">(</span><span class="ci">stream</span><span class="cp">,</span> <span class="ci">leaveOpen</span><span class="cp">,</span> <span
  781. class="ci">encoding</span><span class="cp">,</span> <span class="cb">true</span><span class="cp">)</span></code>.
  782. </p>
  783. </div>
  784. </div>
  785. <div class="interface-member _2" id="members.new_stream_3">
  786. <div class="interface-member-code">
  787. <a class="interface-member-backlink" href="#interface.new_stream_3:B:"></a>
  788. <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>
  789. <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>
  790. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  791. </pre>
  792. </div>
  793. <div class="interface-member-description">
  794. <div class="para _1">
  795. <p>Is equivalent to</p>
  796. <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>
  797. <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>
  798. <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>
  799. <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>
  800. <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>
  801. <span class="ci">byteBufferLength</span> <span class="cp">=</span> <span class="ci">DefaultByteBufferLength</span>
  802. <span class="cp">)</span>
  803. </pre>
  804. </div>
  805. </div>
  806. </div>
  807. <div class="interface-member _3" id="members.new_stream_4">
  808. <div class="interface-member-code">
  809. <a class="interface-member-backlink" href="#interface.new_stream_4:B:"></a>
  810. <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>
  811. <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>
  812. <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>
  813. <span class="cp">*</span> <span class="ci">byteBufferLength</span><span class="cp">:</span> <span class="ci">int</span>
  814. <span class="cr">-&gt;</span> <span class="ci">CharStream</span>
  815. </pre>
  816. </div>
  817. <div class="interface-member-description">
  818. <p class="para _1">
  819. Constructs a <code class="fsharp"><span class="ci">CharStream</span></code> from a <code class="fsharp"><a
  820. href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
  821. class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code>.
  822. </p>
  823. <p class="para _2">
  824. The normal version of the <code class="fsharp"><span class="ci">CharStream</span></code> class supports stream sizes up to approximately
  825. (2<sup>31</sup>/p)×(<code class="fsharp"><span class="ci">blockSize</span></code> <code class="fsharp"><span
  826. class="ci">blockOverlap</span></code>) chars, where p is 4 on a 32bit CLR and 8 on a 64bit CLR.<br />The <a
  827. href="#remarks.low-trust-version">LowTrust version</a> only supports streams small enough that the complete content can be read into a
  828. single string.
  829. </p>
  830. <div class="para _3">
  831. <div class="admonition">
  832. <div class="admonition-title">Note</div>
  833. <div class="admonition-body">
  834. <p class="para _1">
  835. 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
  836. the <a href="#exceptions">exceptions</a> section above.
  837. </p>
  838. </div>
  839. </div>
  840. </div>
  841. <div class="para _4">
  842. <p>Arguments:</p>
  843. <div class="dl multi-para">
  844. <dl class="dl multi-para">
  845. <dt class="_1"><code class="fsharp"><span class="ci">stream</span></code></dt>
  846. <dd class="_1">
  847. <p class="para _1">
  848. The byte stream providing the input. If <code class="fsharp"><span class="ci">stream</span><span class="cm">.</span><a
  849. href="http://msdn.microsoft.com/en-us/library/system.io.stream.canread.aspx"><span class="ci">CanRead</span></a></code> returns <code
  850. class="fsharp"><span class="cb">false</span></code>, an <code class="fsharp"><a
  851. href="http://msdn.microsoft.com/en-us/library/system.argumentexception.aspx"><span class="ci">ArgumentException</span></a></code> is
  852. thrown.
  853. </p>
  854. </dd>
  855. <dt class="_2"><code class="fsharp"><span class="ci">leaveOpen</span></code></dt>
  856. <dd class="_2">
  857. <p class="para _1">
  858. Indicates whether the <code class="fsharp"><span class="ci">stream</span></code> should be left open when the <code class="fsharp"><span
  859. class="ci">CharStream</span></code> has finished reading it.
  860. </p>
  861. </dd>
  862. <dt class="_3"><code class="fsharp"><span class="ci">encoding</span></code></dt>
  863. <dd class="_3">
  864. <p class="para _1">
  865. The default <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.text.encoding.aspx"><span
  866. class="ci">Encoding</span></a></code> used for decoding the byte stream into chars.
  867. </p>
  868. <p class="para _2">
  869. If the preamble returned by <code class="fsharp"><span class="ci">encoding</span><span class="cm">.</span><a
  870. href="http://msdn.microsoft.com/en-us/library/system.text.encoding.getpreamble.aspx"><span class="ci">GetPreamble</span></a><span
  871. class="cp">()</span></code> is present at the beginning of the stream, the <code class="fsharp"><span class="ci">CharStream</span></code>
  872. will skip over it.
  873. </p>
  874. </dd>
  875. <dt class="_4"><code class="fsharp"><span class="ci">detectEncodingFromByteOrderMarks</span></code></dt>
  876. <dd class="_4">
  877. <p class="para _1">
  878. Indicates whether the constructor should detect the encoding from a unicode <a
  879. href="http://en.wikipedia.org/wiki/Byte-order_mark">byteorder mark</a> at the beginning of the stream. An encoding detected from a
  880. byteorder mark overrides the default <code class="fsharp"><span class="ci">encoding</span></code>. The standard byteorder marks for the
  881. following encodings are supported: UTF8, UTF16 LE/BE and UTF32 LE/BE.
  882. </p>
  883. </dd>
  884. <dt class="_5"><code class="fsharp"><span class="ci">blockSize</span></code></dt>
  885. <dd class="_5">
  886. <p class="para _1">
  887. 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.
  888. </p>
  889. </dd>
  890. <dt class="_6"><code class="fsharp"><span class="ci">blockOverlap</span></code></dt>
  891. <dd class="_6">
  892. <p class="para _1">
  893. 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
  894. <code class="fsharp"><span class="ci">encoding</span><span class="cm">.</span><span class="ci">GetMaxCharCount</span><span
  895. class="cp">(</span><span class="cn">1</span><span class="cp">)</span></code> or not less than <code class="fsharp"><span
  896. class="ci">blockSize</span><span class="co">/</span><span class="cn">2</span></code>, the default value is used instead. The default is
  897. <code class="fsharp"><span class="ci">blockSize</span><span class="co">/</span><span class="cn">3</span></code>.
  898. </p>
  899. </dd>
  900. <dt class="_7"><code class="fsharp"><a id="members.minRegexSpace"></a><span class="ci">minRegexSpace</span></code></dt>
  901. <dd class="_7">
  902. <p class="para _1">
  903. The number of chars that are guaranteed to be visible to a regular expression when it is matched by <code class="fsharp"><a
  904. href="#Iterator.members.Match_Regex"><span class="ci">Match</span></a></code> (assuming there are enough chars remaining in the stream).
  905. If this value is negative or greater than <code class="fsharp"><span class="ci">blockOverlap</span></code>, the default value is used
  906. instead. The default value is 2/3 of <code class="fsharp"><span class="ci">blockOverlap</span></code>.
  907. </p>
  908. </dd>
  909. <dt class="_8">byteBufferLength</dt>
  910. <dd class="_8">
  911. <p class="para _1">The size of the byte buffer used for decoding purposes. The default is 2<sup>12</sup> = 4KB.</p>
  912. </dd>
  913. </dl>
  914. </div>
  915. </div>
  916. </div>
  917. </div>
  918. <div class="interface-member _4" id="members.Dispose">
  919. <div class="interface-member-code">
  920. <a class="interface-member-backlink" href="#interface.Dispose:B:"></a>
  921. <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">-&gt;</span> <span class="ci">unit</span>
  922. </pre>
  923. </div>
  924. <div class="interface-member-description">
  925. <p class="para _1">
  926. Releases all resources used by the <code class="fsharp"><span class="ci">CharStream</span></code>. If the <code class="fsharp"><span
  927. class="ci">CharStream</span></code> was constructed from a <code class="fsharp"><a
  928. href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span class="cm">.</span><span
  929. 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
  930. <code class="fsharp"><span class="ci">leaveOpen</span> <span class="co">=</span> <span class="cb">true</span></code>, the byte stream is
  931. closed.
  932. </p>
  933. </div>
  934. </div>
  935. <div class="interface-member _5" id="members.Begin">
  936. <div class="interface-member-code">
  937. <a class="interface-member-backlink" href="#interface.Begin:B:"></a>
  938. <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>
  939. </pre>
  940. </div>
  941. <div class="interface-member-description">
  942. <p class="para _1">
  943. Returns an <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> pointing to the beginning of the stream (or
  944. to the end if the <code class="fsharp"><span class="ci">CharStream</span></code> is empty).
  945. </p>
  946. </div>
  947. </div>
  948. <div class="interface-member _6" id="members.Seek">
  949. <div class="interface-member-code">
  950. <a class="interface-member-backlink" href="#interface.Seek:B:"></a>
  951. <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">-&gt;</span> <a href="#Iterator"><span class="ci">Iterator</span></a>
  952. </pre>
  953. </div>
  954. <div class="interface-member-description">
  955. <p class="para _1">
  956. Returns an <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> pointing to the given index in the stream.
  957. </p>
  958. <p class="para _2">
  959. An <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> pointing to one char after the last char in the
  960. stream represents an <code class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> to the end of the stream. The <code
  961. class="fsharp"><a href="#Iterator"><span class="ci">Iterator</span></a></code> cant move past the end of the stream and <code
  962. class="fsharp"><span class="ci">Seek</span></code> interprets any index larger than the index of the last char as precisely one plus the
  963. index of the last char.
  964. </p>
  965. <p class="para _3">
  966. The index is zerobased, except if the <code class="fsharp"><span class="ci">CharStream</span></code> was constructed with a positive <code
  967. class="fsharp"><span class="ci">streamBeginIndex</span></code> argument, in which case the index of the first char equals <code
  968. class="fsharp"><span class="ci">streamBeginIndex</span></code> and <code class="fsharp"><a href="#members.BeginIndex"><span
  969. class="ci">BeginIndex</span></a></code>.
  970. </p>
  971. <p class="para _4">
  972. An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  973. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the index is less than the <code class="fsharp"><a
  974. href="#members.BeginIndex"><span class="ci">BeginIndex</span></a></code>. This method may also throw any of the <a href="#exceptions">I/O
  975. related exceptions</a> detailed above.
  976. </p>
  977. </div>
  978. </div>
  979. <div class="interface-member _7" id="members.BeginIndex">
  980. <div class="interface-member-code">
  981. <a class="interface-member-backlink" href="#interface.BeginIndex:B:"></a>
  982. <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>
  983. </pre>
  984. </div>
  985. <div class="interface-member-description">
  986. <p class="para _1">
  987. 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
  988. class="cm">.</span><a href="#Iterator.members.Index"><span class="ci">Index</span></a></code>. This value is determined by the <code
  989. class="fsharp"><span class="ci">streamBeginIndex</span></code> argument of some of the <code class="fsharp"><span
  990. class="ci">CharStream</span></code> constructors. By default this value is 0.
  991. </p>
  992. </div>
  993. </div>
  994. <div class="interface-member _8" id="members.EndIndex">
  995. <div class="interface-member-code">
  996. <a class="interface-member-backlink" href="#interface.EndIndex:B:"></a>
  997. <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>
  998. </pre>
  999. </div>
  1000. <div class="interface-member-description">
  1001. <p class="para _1">
  1002. 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
  1003. class="ci">MaxValue</span></code> if the end of the stream has not yet been detected.
  1004. </p>
  1005. </div>
  1006. </div>
  1007. <div class="interface-member _9" id="members.FoldCase">
  1008. <div class="interface-member-code">
  1009. <a class="interface-member-backlink" href="#interface.FoldCase:B:"></a>
  1010. <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">-&gt;</span> <span class="ci">string</span>
  1011. </pre>
  1012. </div>
  1013. <div class="interface-member-description">
  1014. <p class="para _1">
  1015. Returns a casefolded copy of the string argument. All chars are mapped using the (nonTurkic) 1to1 <a
  1016. href="http://unicode.org/Public/UNIDATA/CaseFolding.txt">case folding mappings</a> (v. 5.1) for Unicode code points in the Basic Multilingual
  1017. Plane, i.e. code points below 0x10000. If the casefolded string equals the argument string, the original argument is returned (to preserve
  1018. its reference identity). If the argument is <code class="fsharp"><span class="cnu">null</span></code>, <code class="fsharp"><span
  1019. class="cnu">null</span></code> is returned.
  1020. </p>
  1021. <p class="para _2">
  1022. <code class="fsharp"><span class="ci">CharParsers</span><span class="cm">.</span><a href="charparsers.html#members.foldCase"><span
  1023. class="ci">foldCase</span></a></code> is a convenient helper function that forwards all calls to this method.
  1024. </p>
  1025. </div>
  1026. </div>
  1027. <div class="interface-member _0" id="members.NormalizeNewlines">
  1028. <div class="interface-member-code">
  1029. <a class="interface-member-backlink" href="#interface.NormalizeNewlines:B:"></a>
  1030. <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">-&gt;</span> <span class="ci">string</span>
  1031. </pre>
  1032. </div>
  1033. <div class="interface-member-description">
  1034. <p class="para _1">
  1035. Returns the given string with all occurrences of <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span
  1036. class="ce">\r</span><span class="ce">\n</span><span class="right-delimiter">"</span></span></code> and <code class="fsharp"><span
  1037. class="cs"><span class="left-delimiter">"</span><span class="ce">\r</span><span class="right-delimiter">"</span></span></code> replaced by
  1038. <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span class="ce">\n</span><span
  1039. class="right-delimiter">"</span></span></code>. If the normalized string equals the argument string, the original argument is returned (to
  1040. preserve its reference identity). If the argument is <code class="fsharp"><span class="cnu">null</span></code>, <code class="fsharp"><span
  1041. class="cnu">null</span></code> is returned.
  1042. </p>
  1043. <p class="para _2">
  1044. <code class="fsharp"><span class="ci">CharParsers</span><span class="cm">.</span><a href="charparsers.html#members.normalizeNewlines"><span
  1045. class="ci">normalizeNewlines</span></a></code> is a convenient helper function that forwards all calls to this method.
  1046. </p>
  1047. </div>
  1048. </div>
  1049. </div>
  1050. </div>
  1051. </div>
  1052. </div>
  1053. <div id="Iterator" class="section s3">
  1054. <h2 class="title h3"><span class="section-number">2.8.5</span> CharStream.Iterator</h2>
  1055. <div class="intro i3">
  1056. <p class="para _1">
  1057. The <code class="fsharp"><span class="ci">Iterator</span></code> struct represents a pointer to a particular char in a <code class="fsharp"><a
  1058. href="#"><span class="ci">CharStream</span></a></code>. It provides efficient methods for reading chars or strings from the stream and for
  1059. matching chars, strings or regular expressions with the content of the stream.
  1060. </p>
  1061. </div>
  1062. <div id="Iterator.interface" class="section s4">
  1063. <h3 class="title h4"><span class="section-number">2.8.5.1</span> Interface</h3>
  1064. <div class="intro i4">
  1065. <div class="para _1">
  1066. <pre class="code fsharp"><span class="ck">namespace</span> <span class="ci">FParsec</span>
  1067. <span class="ck">open</span> <span class="ci">NativeInterop</span>
  1068. <span class="cp">[&lt;</span><span class="ci">Sealed</span><span class="cp">&gt;]</span>
  1069. <span class="ck">type</span> <a href="#"><span class="ci">CharStream</span></a> <span class="cp">=</span>
  1070. <span class="cbc"><span class="left-delimiter">(*</span> ... <span class="right-delimiter">*)</span></span>
  1071. <span class="cp">[&lt;</span><span class="ci">Struct</span><span class="cp">&gt;]</span>
  1072. <span class="ck">type</span> <span class="ci">Iterator</span> <span class="cp">=</span>
  1073. <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">&lt;</span><span class="ci">Iterator</span><span class="cp">&gt;</span>
  1074. <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>
  1075. <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>
  1076. <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>
  1077. <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>
  1078. <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>
  1079. <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">-&gt;</span> <span class="ci">Iterator</span>
  1080. <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">-&gt;</span> <span class="ci">Iterator</span>
  1081. <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">-&gt;</span> <span class="ci">Iterator</span>
  1082. <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">-&gt;</span> <span class="ci">bool</span>
  1083. <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">-&gt;</span> <span class="ci">bool</span>
  1084. <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">-&gt;</span> <span class="ci">bool</span>
  1085. <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">-&gt;</span> <span class="ci">bool</span>
  1086. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-&gt;</span> <span class="ci">bool</span>
  1087. <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">-&gt;</span> <span class="ci">bool</span>
  1088. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span><span class="ci">int</span> <span class="cr">-&gt;</span> <span class="ci">bool</span>
  1089. <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>
  1090. <span class="cr">-&gt;</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>
  1091. <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">-&gt;</span> <span class="ci">char</span>
  1092. <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>
  1093. <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>
  1094. <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">-&gt;</span> <span class="ci">TwoChars</span>
  1095. <span class="ck">val</span> <span class="ci">Char0</span><span class="cp">:</span> <span class="ci">char</span>
  1096. <span class="ck">val</span> <span class="ci">Char1</span><span class="cp">:</span> <span class="ci">char</span>
  1097. <span class="ck">end</span>
  1098. <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">-&gt;</span> <a href="#Iterator.interface.TwoChars"><span class="ci">TwoChars</span></a>
  1099. <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">-&gt;</span> <span class="ci">string</span>
  1100. <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">-&gt;</span> <span class="ci">string</span>
  1101. <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">-&gt;</span> <span class="ci">int</span>
  1102. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-&gt;</span> <span class="ci">int</span>
  1103. <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">-&gt;</span> <span class="ci">string</span>
  1104. <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">-&gt;</span> <span class="ci">char</span>
  1105. <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">-&gt;</span> <span class="ci">char</span>
  1106. <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">-&gt;</span> <span class="ci">char</span>
  1107. <span class="clc"><span class="left-delimiter">//</span> the following members mutate the instance</span>
  1108. <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">-&gt;</span> <span class="ci">char</span>
  1109. <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">-&gt;</span> <span class="ci">char</span>
  1110. <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">-&gt;</span> <span class="ci">char</span>
  1111. <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">-&gt;</span> <span class="ci">char</span>
  1112. </pre>
  1113. </div>
  1114. </div>
  1115. </div>
  1116. <div id="Iterator.members" class="section s4">
  1117. <h3 class="title h4"><span class="section-number">2.8.5.2</span> Members</h3>
  1118. <div class="intro i4">
  1119. <div class="para _1">
  1120. <div class="interface-members">
  1121. <div class="interface-member _1" id="Iterator.members.Stream">
  1122. <div class="interface-member-code">
  1123. <a class="interface-member-backlink" href="#Iterator.interface.Stream:B:"></a>
  1124. <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>
  1125. </pre>
  1126. </div>
  1127. <div class="interface-member-description">
  1128. <p class="para _1">
  1129. The <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> over which the <code class="fsharp"><span
  1130. class="ci">Iterator</span></code> iterates.
  1131. </p>
  1132. </div>
  1133. </div>
  1134. <div class="interface-member _2" id="Iterator.members.Index">
  1135. <div class="interface-member-code">
  1136. <a class="interface-member-backlink" href="#Iterator.interface.Index:B:"></a>
  1137. <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>
  1138. </pre>
  1139. </div>
  1140. <div class="interface-member-description">
  1141. <p class="para _1">The index of the stream char pointed to by the <code class="fsharp"><span class="ci">Iterator</span></code>.</p>
  1142. <p class="para _2">
  1143. The index is zerobased, except if the <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> was constructed with a
  1144. positive <code class="fsharp"><span class="ci">streamBeginIndex</span></code> argument, in which case the index of the first char equals
  1145. <code class="fsharp"><span class="ci">streamBeginIndex</span></code> and <code class="fsharp"><a href="#Iterator.members.Stream"><span
  1146. class="ci">Stream</span></a><span class="cm">.</span><a href="#members.BeginIndex"><span class="ci">BeginIndex</span></a></code>.
  1147. </p>
  1148. </div>
  1149. </div>
  1150. <div class="interface-member _3" id="Iterator.members.IsBeginOfStream">
  1151. <div class="interface-member-code">
  1152. <a class="interface-member-backlink" href="#Iterator.interface.IsBeginOfStream:B:"></a>
  1153. <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>
  1154. </pre>
  1155. </div>
  1156. <div class="interface-member-description">
  1157. <p class="para _1">
  1158. Indicates whether the <code class="fsharp"><span class="ci">Iterator</span></code> points to the first char in the <code class="fsharp"><a
  1159. href="#"><span class="ci">CharStream</span></a></code>. If the <code class="fsharp"><a href="#"><span
  1160. class="ci">CharStream</span></a></code> is empty, this property is always <code class="fsharp"><span class="cb">true</span></code>.
  1161. </p>
  1162. </div>
  1163. </div>
  1164. <div class="interface-member _4" id="Iterator.members.IsEndOfStream">
  1165. <div class="interface-member-code">
  1166. <a class="interface-member-backlink" href="#Iterator.interface.IsEndOfStream:B:"></a>
  1167. <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>
  1168. </pre>
  1169. </div>
  1170. <div class="interface-member-description">
  1171. <p class="para _1">
  1172. Indicates whether the <code class="fsharp"><span class="ci">Iterator</span></code> points to the end of the <code class="fsharp"><a
  1173. href="#"><span class="ci">CharStream</span></a></code>, i.e. whether it points to one char beyond the last char in the <code
  1174. class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code>.
  1175. </p>
  1176. </div>
  1177. </div>
  1178. <div class="interface-member _5" id="Iterator.members.Next">
  1179. <div class="interface-member-code">
  1180. <a class="interface-member-backlink" href="#Iterator.interface.Next:B:"></a>
  1181. <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>
  1182. </pre>
  1183. </div>
  1184. <div class="interface-member-description">
  1185. <p class="para _1">
  1186. Returns an <code class="fsharp"><span class="ci">Iterator</span></code> pointing to the next char in the stream. If the <code
  1187. 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
  1188. last char, the same <code class="fsharp"><span class="ci">Iterator</span></code> is returned.
  1189. </p>
  1190. <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
  1191. </div>
  1192. </div>
  1193. <div class="interface-member _6" id="Iterator.members.Advance_int">
  1194. <div class="interface-member-code">
  1195. <a class="interface-member-backlink" href="#Iterator.interface.Advance_int:B:"></a>
  1196. <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">-&gt;</span> <span class="ci">Iterator</span>
  1197. </pre>
  1198. </div>
  1199. <div class="interface-member-description">
  1200. <p class="para _1">
  1201. Is an optimized version of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a></code> for <code
  1202. class="fsharp"><span class="ci">int</span></code> arguments.
  1203. </p>
  1204. </div>
  1205. </div>
  1206. <div class="interface-member _7" id="Iterator.members.Advance_uint">
  1207. <div class="interface-member-code">
  1208. <a class="interface-member-backlink" href="#Iterator.interface.Advance_uint:B:"></a>
  1209. <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">-&gt;</span> <span class="ci">Iterator</span>
  1210. </pre>
  1211. </div>
  1212. <div class="interface-member-description">
  1213. <p class="para _1">
  1214. Is an optimized version of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a></code> for <code
  1215. class="fsharp"><span class="ci">uint</span></code> arguments.
  1216. </p>
  1217. </div>
  1218. </div>
  1219. <div class="interface-member _8" id="Iterator.members.Advance">
  1220. <div class="interface-member-code">
  1221. <a class="interface-member-backlink" href="#Iterator.interface.Advance:B:"></a>
  1222. <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">-&gt;</span> <span class="ci">Iterator</span>
  1223. </pre>
  1224. </div>
  1225. <div class="interface-member-description">
  1226. <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>
  1227. <p class="para _2">
  1228. The <code class="fsharp"><span class="ci">Iterator</span></code> cant move past the end of the stream, i.e. any position beyond the last
  1229. char in the stream is interpreted as precisely one char beyond the last char.
  1230. </p>
  1231. <p class="para _3">
  1232. An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1233. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the new position would lie before the beginning of the <code
  1234. class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code>, i.e. if the new index would be less than the <code
  1235. class="fsharp"><a href="#Iterator.members.Stream"><span class="ci">Stream</span></a><span class="cm">.</span><a
  1236. href="#members.BeginIndex"><span class="ci">BeginIndex</span></a></code>. This method may also throw any of the <a href="#exceptions">I/O
  1237. related exceptions</a> detailed above.
  1238. </p>
  1239. </div>
  1240. </div>
  1241. <div class="interface-member _9" id="Iterator.members.Match">
  1242. <div class="interface-member-code">
  1243. <a class="interface-member-backlink" href="#Iterator.interface.Match:B:"></a>
  1244. <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">-&gt;</span> <span class="ci">bool</span>
  1245. </pre>
  1246. </div>
  1247. <div class="interface-member-description">
  1248. <p class="para _1">
  1249. 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
  1250. class="fsharp"><span class="ci">Iterator</span></code>. At the end of the stream <code class="fsharp"><span class="ci">Match</span></code>
  1251. always returns <code class="fsharp"><span class="cb">false</span></code>.
  1252. </p>
  1253. <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
  1254. </div>
  1255. </div>
  1256. <div class="interface-member _0" id="Iterator.members.Match_string">
  1257. <div class="interface-member-code">
  1258. <a class="interface-member-backlink" href="#Iterator.interface.Match_string:B:"></a>
  1259. <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">-&gt;</span> <span class="ci">bool</span>
  1260. </pre>
  1261. </div>
  1262. <div class="interface-member-description">
  1263. <p class="para _1">
  1264. Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">chars</span></code> matches the
  1265. 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
  1266. not match or if there are not enough chars remaining in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned.
  1267. If <code class="fsharp"><span class="ci">chars</span></code> is empty, <code class="fsharp"><span class="cb">true</span></code> is returned.
  1268. <code class="fsharp"><span class="ci">chars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
  1269. </p>
  1270. <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
  1271. </div>
  1272. </div>
  1273. <div class="interface-member _1" id="Iterator.members.Match_substring">
  1274. <div class="interface-member-code">
  1275. <a class="interface-member-backlink" href="#Iterator.interface.Match_substring:B:"></a>
  1276. <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">-&gt;</span> <span class="ci">bool</span>
  1277. </pre>
  1278. </div>
  1279. <div class="interface-member-description">
  1280. <p class="para _1">
  1281. Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">chars</span><span
  1282. class="cm">.</span><span class="cp">[</span><span class="ci">charsIndex</span><span class="cra">..</span><span class="cp">(</span><span
  1283. class="ci">charsIndex</span> <span class="co">+</span> <span class="ci">length</span> <span class="co">-</span> <span
  1284. class="cn">1</span><span class="cp">)</span><span class="cp">]</span></code> matches the chars in the stream beginning with the char pointed
  1285. 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
  1286. in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned. If <code class="fsharp"><span
  1287. class="ci">length</span></code> is 0, <code class="fsharp"><span class="cb">true</span></code> is returned. <code class="fsharp"><span
  1288. class="ci">chars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
  1289. </p>
  1290. <p class="para _2">
  1291. An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1292. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions: <code
  1293. class="fsharp"><span class="ci">charsIndex</span></code> 0, <code class="fsharp"><span class="ci">length</span></code> 0 and <code
  1294. class="fsharp"><span class="ci">charsIndex</span></code> + <code class="fsharp"><span class="ci">length</span></code> <code
  1295. class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code>. This method may also throw any
  1296. of the <a href="#exceptions">I/O related exceptions</a> detailed above.
  1297. </p>
  1298. </div>
  1299. </div>
  1300. <div class="interface-member _2" id="Iterator.members.Match_char-array">
  1301. <div class="interface-member-code">
  1302. <a class="interface-member-backlink" href="#Iterator.interface.Match_char-array:B:"></a>
  1303. <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">-&gt;</span> <span class="ci">bool</span>
  1304. </pre>
  1305. </div>
  1306. <div class="interface-member-description">
  1307. <p class="para _1">
  1308. Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">chars</span><span
  1309. class="cm">.</span><span class="cp">[</span><span class="ci">charsIndex</span><span class="cra">..</span><span class="cp">(</span><span
  1310. class="ci">charsIndex</span> <span class="co">+</span> <span class="ci">length</span> <span class="co">-</span> <span
  1311. class="cn">1</span><span class="cp">)</span><span class="cp">]</span></code> matches the chars in the stream beginning with the char pointed
  1312. 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
  1313. in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned. If <code class="fsharp"><span
  1314. class="ci">length</span></code> is 0, <code class="fsharp"><span class="cb">true</span></code> is returned. <code class="fsharp"><span
  1315. class="ci">chars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
  1316. </p>
  1317. <p class="para _2">
  1318. An <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1319. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions: <code
  1320. class="fsharp"><span class="ci">charsIndex</span></code> 0, <code class="fsharp"><span class="ci">length</span></code> 0 and <code
  1321. class="fsharp"><span class="ci">charsIndex</span></code> + <code class="fsharp"><span class="ci">length</span></code> <code
  1322. class="fsharp"><span class="ci">chars</span><span class="cm">.</span><span class="ci">Length</span></code>. This method may also throw any
  1323. of the <a href="#exceptions">I/O related exceptions</a> detailed above.
  1324. </p>
  1325. </div>
  1326. </div>
  1327. <div class="interface-member _3" id="Iterator.members.Match_char-pointer">
  1328. <div class="interface-member-code">
  1329. <a class="interface-member-backlink" href="#Iterator.interface.Match_char-pointer:B:"></a>
  1330. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-&gt;</span> <span class="ci">bool</span>
  1331. </pre>
  1332. </div>
  1333. <div class="interface-member-description">
  1334. <p class="para _1">
  1335. <span class="small"><span class="italic">This method is not available in the <a href="#remarks.low-trust-version">LowTrust version</a> of
  1336. FParsec.</span></span>
  1337. </p>
  1338. <p class="para _2">
  1339. Returns <code class="fsharp"><span class="cb">true</span></code> if the <code class="fsharp"><span class="ci">length</span></code> chars at
  1340. the pointer address match the chars in the stream beginning with the char pointed to by the <code class="fsharp"><span
  1341. class="ci">Iterator</span></code>. If the chars do not match or if there are not enough chars remaining in the stream, <code
  1342. class="fsharp"><span class="cb">false</span></code> is returned. If <code class="fsharp"><span class="ci">length</span></code> is 0, <code
  1343. class="fsharp"><span class="cb">true</span></code> is returned.
  1344. </p>
  1345. <p class="para _3">
  1346. If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
  1347. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1348. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
  1349. exceptions</a> detailed above.
  1350. </p>
  1351. </div>
  1352. </div>
  1353. <div class="interface-member _4" id="Iterator.members.MatchCaseFolded">
  1354. <div class="interface-member-code">
  1355. <a class="interface-member-backlink" href="#Iterator.interface.MatchCaseFolded:B:"></a>
  1356. <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">-&gt;</span> <span class="ci">bool</span>
  1357. </pre>
  1358. </div>
  1359. <div class="interface-member-description">
  1360. <p class="para _1">
  1361. Returns <code class="fsharp"><span class="cb">true</span></code> if <code class="fsharp"><span class="ci">caseFoldedChars</span></code>
  1362. matches the chars in the stream beginning with the char pointed to by the <code class="fsharp"><span class="ci">Iterator</span></code>. The
  1363. chars in the stream are casefolded before they are matched, while the chars in the string argument are assumed to already be casefolded
  1364. (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
  1365. match or if there are not enough chars remaining in the stream, <code class="fsharp"><span class="cb">false</span></code> is returned. <code
  1366. class="fsharp"><span class="ci">caseFoldedChars</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>.
  1367. </p>
  1368. <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
  1369. <p class="para _3">Please also see the above remarks on <a href="#remarks.case-insensitive-matching">caseinsensitive matching</a>.</p>
  1370. </div>
  1371. </div>
  1372. <div class="interface-member _5" id="Iterator.members.MatchCaseFolded_char-pointer">
  1373. <div class="interface-member-code">
  1374. <a class="interface-member-backlink" href="#Iterator.interface.MatchCaseFolded_char-pointer:B:"></a>
  1375. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span><span class="ci">int</span> <span class="cr">-&gt;</span> <span class="ci">bool</span>
  1376. </pre>
  1377. </div>
  1378. <div class="interface-member-description">
  1379. <p class="para _1">
  1380. <span class="small"><span class="italic">This method is not available in the <a href="#remarks.low-trust-version">LowTrust version</a> of
  1381. FParsec.</span></span>
  1382. </p>
  1383. <p class="para _2">
  1384. Returns <code class="fsharp"><span class="cb">true</span></code> if the <code class="fsharp"><span class="ci">length</span></code> chars at
  1385. the pointer address match the chars in the stream beginning with the char pointed to by the <code class="fsharp"><span
  1386. class="ci">Iterator</span></code>. The chars in the stream are casefolded before they are matched, while the chars at the pointer address
  1387. are assumed to already be casefolded (e.g. with the help of <code class="fsharp"><a href="#members.FoldCase"><span
  1388. class="ci">FoldCase</span></a></code>). If the chars do not match or if there are not enough chars remaining in the stream, <code
  1389. class="fsharp"><span class="cb">false</span></code> is returned.
  1390. </p>
  1391. <p class="para _3">
  1392. If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
  1393. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1394. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
  1395. exceptions</a> detailed above.
  1396. </p>
  1397. <p class="para _4">Please also see the above remarks on <a href="#remarks.case-insensitive-matching">caseinsensitive matching</a>.</p>
  1398. </div>
  1399. </div>
  1400. <div class="interface-member _6" id="Iterator.members.Match_Regex">
  1401. <div class="interface-member-code">
  1402. <a class="interface-member-backlink" href="#Iterator.interface.Match_Regex:B:"></a>
  1403. <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>
  1404. <span class="cr">-&gt;</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>
  1405. </pre>
  1406. </div>
  1407. <div class="interface-member-description">
  1408. <p class="para _1">
  1409. Applies the given regular expression to the stream chars beginning with the char pointed to by the <code class="fsharp"><span
  1410. class="ci">Iterator</span></code>. Returns the resulting <code class="fsharp"><span class="ci">Match</span></code> object.
  1411. </p>
  1412. <p class="para _2">
  1413. For performance reasons you should specify the regular expression such that it can only match at the beginning of a string, for example by
  1414. prepending <code class="fsharp"><span class="cs"><span class="left-delimiter">"</span><span class="ce">\\</span>A<span
  1415. class="right-delimiter">"</span></span></code>.
  1416. </p>
  1417. <p class="para _3">
  1418. For <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> instances constructed from large streams the regular
  1419. expression is not applied to a string containing all the remaining chars in the stream. The <code class="fsharp"><a
  1420. href="#members.minRegexSpace"><span class="ci">minRegexSpace</span></a></code> parameter of the <code class="fsharp"><a href="#"><span
  1421. class="ci">CharStream</span></a></code> constructors determines the minimum number of chars that are guaranteed to be visible to the regular
  1422. expression.
  1423. </p>
  1424. <p class="para _4">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
  1425. <div class="para _5">
  1426. <div class="admonition">
  1427. <div class="admonition-title">Important</div>
  1428. <div class="admonition-body">
  1429. <p class="para _1">
  1430. <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">LowTrust version</a> of
  1431. FParsec.</span></span><br /> This method is not supported by <code class="fsharp"><a href="#"><span
  1432. class="ci">CharStream</span></a></code> instances constructed directly from char arrays or pointers. A <code class="fsharp"><a
  1433. href="http://msdn.microsoft.com/en-us/library/system.notsupportedexception.aspx"><span class="ci">NotSupportedException</span></a></code>
  1434. is thrown if this method is called on such a <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> instance.
  1435. </p>
  1436. </div>
  1437. </div>
  1438. </div>
  1439. <div class="para _6">
  1440. <div class="admonition">
  1441. <div class="admonition-title">Important</div>
  1442. <div class="admonition-body">
  1443. <p class="para _1">
  1444. <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">LowTrust version</a> of
  1445. FParsec.</span></span><br /> If the <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> was constructed from a
  1446. <code class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.io.stream.aspx"><span class="ci">System</span><span
  1447. class="cm">.</span><span class="ci">IO</span><span class="cm">.</span><span class="ci">Stream</span></a></code> or a file path, the
  1448. regular expression is applied to an internal <em>mutable</em> buffer. Since the <code class="fsharp"><span class="ci">Match</span></code>
  1449. object may work lazily, i.e. compute return values not before they are needed, you need to <em>retrieve all the required information from
  1450. the <code class="fsharp"><span class="ci">Match</span></code> object before you continue to access the <code class="fsharp"><a
  1451. href="#"><span class="ci">CharStream</span></a></code></em>, otherwise you might get back invalid match results. Note that all strings
  1452. returned by the <code class="fsharp"><span class="ci">Match</span></code> object are, of course, immutable.
  1453. </p>
  1454. </div>
  1455. </div>
  1456. </div>
  1457. </div>
  1458. </div>
  1459. <div class="interface-member _7" id="Iterator.members.Read">
  1460. <div class="interface-member-code">
  1461. <a class="interface-member-backlink" href="#Iterator.interface.Read:B:"></a>
  1462. <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">-&gt;</span> <span class="ci">char</span>
  1463. </pre>
  1464. </div>
  1465. <div class="interface-member-description">
  1466. <p class="para _1">
  1467. Returns the stream char pointed to by the <code class="fsharp"><span class="ci">Iterator</span></code>, or the <code class="fsharp"><a
  1468. href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span
  1469. class="left-delimiter">'</span><span class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) if the <code
  1470. 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
  1471. in the stream.
  1472. </p>
  1473. <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
  1474. </div>
  1475. </div>
  1476. <div class="interface-member _8" id="Iterator.members.EndOfStreamChar">
  1477. <div class="interface-member-code">
  1478. <a class="interface-member-backlink" href="#Iterator.interface.EndOfStreamChar:B:"></a>
  1479. <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>
  1480. </pre>
  1481. </div>
  1482. <div class="interface-member-description">
  1483. <p class="para _1">
  1484. The char returned by <code class="fsharp"><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">()</span></code>
  1485. 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
  1486. the last char in the stream. The value is <code class="fsharp"><span class="cc"><span class="left-delimiter">'</span><span
  1487. class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>.
  1488. </p>
  1489. </div>
  1490. </div>
  1491. <div class="interface-member _9" id="Iterator.members.Read2">
  1492. <div class="interface-member-code">
  1493. <a class="interface-member-backlink" href="#Iterator.interface.Read2:B:"></a>
  1494. <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">-&gt;</span> <a href="#Iterator.interface.TwoChars"><span class="ci">TwoChars</span></a>
  1495. </pre>
  1496. </div>
  1497. <div class="interface-member-description">
  1498. <p class="para _1">
  1499. <code class="fsharp"><span class="ci">Read2</span><span class="cp">()</span></code> is an optimized implementation of <code
  1500. class="fsharp"><a href="#Iterator.interface.TwoChars"><span class="ci">TwoChars</span></a><span class="cp">(</span><a
  1501. href="#Iterator.members.Read"><span class="ci">Read</span></a><span class="cp">()</span><span class="cp">,</span> <a
  1502. href="#Iterator.members.Next"><span class="ci">Next</span></a><span class="cm">.</span><a href="#Iterator.members.Read"><span
  1503. class="ci">Read</span></a><span class="cp">()</span><span class="cp">)</span></code>.
  1504. </p>
  1505. <p class="para _2">This method may throw any of the <a href="#exceptions">I/O related exceptions</a> detailed above.</p>
  1506. </div>
  1507. </div>
  1508. <div class="interface-member _0" id="Iterator.members.Read_int">
  1509. <div class="interface-member-code">
  1510. <a class="interface-member-backlink" href="#Iterator.interface.Read_int:B:"></a>
  1511. <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">-&gt;</span> <span class="ci">string</span>
  1512. </pre>
  1513. </div>
  1514. <div class="interface-member-description">
  1515. <p class="para _1">
  1516. Is equivalent to <code class="fsharp"><a href="#Iterator.members.Read_int_bool"><span class="ci">Read</span></a><span
  1517. class="cp">(</span><span class="ci">length</span><span class="cp">,</span> <span class="cb">false</span><span class="cp">)</span></code>.
  1518. </p>
  1519. </div>
  1520. </div>
  1521. <div class="interface-member _1" id="Iterator.members.Read_int_bool">
  1522. <div class="interface-member-code">
  1523. <a class="interface-member-backlink" href="#Iterator.interface.Read_int_bool:B:"></a>
  1524. <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">-&gt;</span> <span class="ci">string</span>
  1525. </pre>
  1526. </div>
  1527. <div class="interface-member-description">
  1528. <p class="para _1">
  1529. Returns a string with the <code class="fsharp"><span class="ci">length</span></code> stream chars beginning with the char pointed to by the
  1530. <code class="fsharp"><span class="ci">Iterator</span></code>. If less than <code class="fsharp"><span class="ci">length</span></code> chars
  1531. are remaining in the stream, only the remaining chars are returned, or an empty string if <code class="fsharp"><span
  1532. class="ci">allOrEmpty</span></code> is <code class="fsharp"><span class="cb">true</span></code>.
  1533. </p>
  1534. <div class="para _2">
  1535. <div class="admonition">
  1536. <div class="admonition-title">Note</div>
  1537. <div class="admonition-body">
  1538. <p class="para _1">
  1539. <span class="small"><span class="italic">This note does not apply to the <a href="#remarks.low-trust-version">LowTrust version</a> of
  1540. FParsec.</span></span><br /> If <code class="fsharp"><span class="ci">length</span></code> is greater than the number of remaining chars
  1541. in the stream, a temporary string with <code class="fsharp"><span class="ci">length</span></code> chars may be allocated. For very large
  1542. <code class="fsharp"><span class="ci">length</span></code> values this might lead to an <code class="fsharp"><span
  1543. class="ci">OutOfMemoryException</span></code> even though a string with only the remaining chars in the stream would comfortably fit into
  1544. memory.
  1545. </p>
  1546. <p class="para _2">
  1547. 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
  1548. will always yield an <code class="fsharp"><span class="ci">OutOfMemoryException</span></code>, even on 64bit systems with enough
  1549. physical memory.
  1550. </p>
  1551. </div>
  1552. </div>
  1553. </div>
  1554. <p class="para _3">
  1555. If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
  1556. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1557. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
  1558. exceptions</a> detailed above.
  1559. </p>
  1560. </div>
  1561. </div>
  1562. <div class="interface-member _2" id="Iterator.members.Read_char-array">
  1563. <div class="interface-member-code">
  1564. <a class="interface-member-backlink" href="#Iterator.interface.Read_char-array:B:"></a>
  1565. <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">-&gt;</span> <span class="ci">int</span>
  1566. </pre>
  1567. </div>
  1568. <div class="interface-member-description">
  1569. <p class="para _1">
  1570. Copies the <code class="fsharp"><span class="ci">length</span></code> stream chars beginning with the char pointed to by the <code
  1571. class="fsharp"><span class="ci">Iterator</span></code> into <code class="fsharp"><span class="ci">buffer</span></code>. The chars are
  1572. written into <code class="fsharp"><span class="ci">buffer</span></code> beginning at the index <code class="fsharp"><span
  1573. class="ci">bufferIndex</span></code>. If less than <code class="fsharp"><span class="ci">length</span></code> chars are remaining in the
  1574. stream, only the remaining chars are copied. Returns the actual number of chars copied.
  1575. </p>
  1576. <p class="para _2">
  1577. <code class="fsharp"><span class="ci">buffer</span></code> must not be <code class="fsharp"><span class="cnu">null</span></code>. An <code
  1578. class="fsharp"><a href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1579. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown if the arguments do not satisfy the following conditions: <code
  1580. class="fsharp"><span class="ci">bufferIndex</span></code> 0, <code class="fsharp"><span class="ci">length</span></code> 0 and <code
  1581. class="fsharp"><span class="ci">bufferIndex</span></code> + <code class="fsharp"><span class="ci">length</span></code> <code
  1582. class="fsharp"><span class="ci">buffer</span><span class="cm">.</span><span class="ci">Length</span></code>. This method may also throw any
  1583. of the <a href="#exceptions">I/O related exceptions</a> detailed above.
  1584. </p>
  1585. </div>
  1586. </div>
  1587. <div class="interface-member _3" id="Iterator.members.Read_char-pointer">
  1588. <div class="interface-member-code">
  1589. <a class="interface-member-backlink" href="#Iterator.interface.Read_char-pointer:B:"></a>
  1590. <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">&lt;</span><span class="ci">char</span><span class="cp">&gt;</span> <span class="cp">*</span> <span class="ci">length</span><span class="cp">:</span> <span class="ci">int</span> <span class="cr">-&gt;</span> <span class="ci">int</span>
  1591. </pre>
  1592. </div>
  1593. <div class="interface-member-description">
  1594. <p class="para _1">
  1595. <span class="small"><span class="italic">This method is not available in the <a href="#remarks.low-trust-version">LowTrust version</a> of
  1596. FParsec.</span></span>
  1597. </p>
  1598. <p class="para _2">
  1599. Copies the <code class="fsharp"><span class="ci">length</span></code> stream chars beginning with the char pointed to by the <code
  1600. class="fsharp"><span class="ci">Iterator</span></code> into the buffer at the given pointer address. If less than <code class="fsharp"><span
  1601. class="ci">length</span></code> chars are remaining in the stream, only the remaining chars are copied. Returns the actual number of chars
  1602. copied.
  1603. </p>
  1604. <p class="para _3">
  1605. If <code class="fsharp"><span class="ci">length</span></code> is negative, an <code class="fsharp"><a
  1606. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1607. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
  1608. exceptions</a> detailed above.
  1609. </p>
  1610. </div>
  1611. </div>
  1612. <div class="interface-member _4" id="Iterator.members.ReadUntil">
  1613. <div class="interface-member-code">
  1614. <a class="interface-member-backlink" href="#Iterator.interface.ReadUntil:B:"></a>
  1615. <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">-&gt;</span> <span class="ci">string</span>
  1616. </pre>
  1617. </div>
  1618. <div class="interface-member-description">
  1619. <p class="para _1">
  1620. Returns a string with all the chars in the stream between the position of this <code class="fsharp"><span class="ci">Iterator</span></code>
  1621. (inclusive) and the position of the <code class="fsharp"><span class="ci">Iterator</span></code> argument (exclusive). If the <code
  1622. class="fsharp"><span class="ci">Iterator</span></code> argument does not point to a position after the position of this <code
  1623. class="fsharp"><span class="ci">Iterator</span></code>, the returned string is empty.
  1624. </p>
  1625. <p class="para _2">
  1626. If the <code class="fsharp"><span class="ci">Iterator</span></code> argument belongs to a different <code class="fsharp"><a href="#"><span
  1627. class="ci">CharStream</span></a></code>, an <code class="fsharp"><a
  1628. href="http://msdn.microsoft.com/en-us/library/system.argumentoutofrangeexception.aspx"><span
  1629. class="ci">ArgumentOutOfRangeException</span></a></code> is thrown. This method may also throw any of the <a href="#exceptions">I/O related
  1630. exceptions</a> detailed above.
  1631. </p>
  1632. </div>
  1633. </div>
  1634. <div class="interface-member _5" id="Iterator.members.Peek">
  1635. <div class="interface-member-code">
  1636. <a class="interface-member-backlink" href="#Iterator.interface.Peek:B:"></a>
  1637. <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">-&gt;</span> <span class="ci">char</span>
  1638. </pre>
  1639. </div>
  1640. <div class="interface-member-description">
  1641. <p class="para _1">
  1642. <code class="fsharp"><span class="ci">Peek</span><span class="cp">()</span></code> is an optimized implementation of <code class="fsharp"><a
  1643. href="#Iterator.members.Next"><span class="ci">Next</span></a><span class="cm">.</span><a href="#Iterator.members.Read"><span
  1644. class="ci">Read</span></a><span class="cp">()</span></code>.
  1645. </p>
  1646. </div>
  1647. </div>
  1648. <div class="interface-member _6" id="Iterator.members.Peek_int">
  1649. <div class="interface-member-code">
  1650. <a class="interface-member-backlink" href="#Iterator.interface.Peek_int:B:"></a>
  1651. <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">-&gt;</span> <span class="ci">char</span>
  1652. </pre>
  1653. </div>
  1654. <div class="interface-member-description">
  1655. <p class="para _1">
  1656. <code class="fsharp"><span class="ci">Peek</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an
  1657. optimized implementation of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span
  1658. class="cp">(</span><span class="ci">n</span><span class="cp">)</span><span class="cm">.</span><a href="#Iterator.members.Read"><span
  1659. class="ci">Read</span></a><span class="cp">()</span></code>, except that the <code class="fsharp"><a
  1660. href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span
  1661. class="left-delimiter">'</span><span class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) is returned if the new
  1662. position would lie before the beginning of the <code class="fsharp"><a href="#"><span class="ci">CharStream</span></a></code> (instead of an
  1663. exception being thrown).
  1664. </p>
  1665. </div>
  1666. </div>
  1667. <div class="interface-member _7" id="Iterator.members.Peek_uint">
  1668. <div class="interface-member-code">
  1669. <a class="interface-member-backlink" href="#Iterator.interface.Peek_uint:B:"></a>
  1670. <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">-&gt;</span> <span class="ci">char</span>
  1671. </pre>
  1672. </div>
  1673. <div class="interface-member-description">
  1674. <p class="para _1">
  1675. <code class="fsharp"><span class="ci">Peek</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an
  1676. optimized implementation of <code class="fsharp"><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span
  1677. class="cp">(</span><span class="ci">n</span><span class="cp">)</span><span class="cm">.</span><a href="#Iterator.members.Read"><span
  1678. class="ci">Read</span></a><span class="cp">()</span></code>.
  1679. </p>
  1680. </div>
  1681. </div>
  1682. <div class="interface-member _8" id="Iterator.members._Increment">
  1683. <div class="interface-member-code">
  1684. <a class="interface-member-backlink" href="#Iterator.interface._Increment:B:"></a>
  1685. <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">-&gt;</span> <span class="ci">char</span>
  1686. </pre>
  1687. </div>
  1688. <div class="interface-member-description">
  1689. <p class="para _1">
  1690. Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>inplace</em> by one char and returns the char on the new
  1691. position.
  1692. </p>
  1693. <p class="para _2">
  1694. <code class="fsharp"><span class="ci">c</span> <span class="co">&lt;-</span> <span class="ci">iter</span><span class="cm">.</span><span
  1695. class="ci">_Increment</span><span class="cp">()</span></code> is an optimized implementation of <code class="fsharp"><span
  1696. class="ci">iter</span> <span class="co">&lt;-</span> <span class="ci">iter</span><span class="cm">.</span><a
  1697. href="#Iterator.members.Next"><span class="ci">Next</span></a><span class="cp">;</span> <span class="ci">c</span> <span
  1698. class="co">&lt;-</span> <span class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Read"><span
  1699. class="ci">Read</span></a><span class="cp">()</span></code>.
  1700. </p>
  1701. </div>
  1702. </div>
  1703. <div class="interface-member _9" id="Iterator.members._Increment_uint">
  1704. <div class="interface-member-code">
  1705. <a class="interface-member-backlink" href="#Iterator.interface._Increment_uint:B:"></a>
  1706. <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">-&gt;</span> <span class="ci">char</span>
  1707. </pre>
  1708. </div>
  1709. <div class="interface-member-description">
  1710. <p class="para _1">
  1711. Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>inplace</em> by the given number of chars and returns the
  1712. char on the new position.
  1713. </p>
  1714. <p class="para _2">
  1715. <code class="fsharp"><span class="ci">c</span> <span class="co">&lt;-</span> <span class="ci">iter</span><span class="cm">.</span><span
  1716. class="ci">_Increment</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an optimized
  1717. implementation of <code class="fsharp"><span class="ci">iter</span> <span class="co">&lt;-</span> <span class="ci">iter</span><span
  1718. class="cm">.</span><a href="#Iterator.members.Advance"><span class="ci">Advance</span></a><span class="cp">(</span><span
  1719. class="ci">n</span><span class="cp">)</span><span class="cp">;</span> <span class="ci">c</span> <span class="co">&lt;-</span> <span
  1720. class="ci">iter</span><span class="cm">.</span><a href="#Iterator.members.Read"><span class="ci">Read</span></a><span
  1721. class="cp">()</span></code>.
  1722. </p>
  1723. </div>
  1724. </div>
  1725. <div class="interface-member _0" id="Iterator.members._Decrement">
  1726. <div class="interface-member-code">
  1727. <a class="interface-member-backlink" href="#Iterator.interface._Decrement:B:"></a>
  1728. <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">-&gt;</span> <span class="ci">char</span>
  1729. </pre>
  1730. </div>
  1731. <div class="interface-member-description">
  1732. <p class="para _1">
  1733. Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>inplace</em> by 1 and returns the char on the new position,
  1734. except if the <code class="fsharp"><span class="ci">Iterator</span></code> already points to the beginning of the <code class="fsharp"><a
  1735. href="#"><span class="ci">CharStream</span></a></code>, in which case the position does not change and the <code class="fsharp"><a
  1736. href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span
  1737. class="left-delimiter">'</span><span class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) is returned.
  1738. </p>
  1739. <div class="para _2">
  1740. <p>
  1741. <code class="fsharp"><span class="ci">c</span> <span class="co">&lt;-</span> <span class="ci">iter</span><span class="cm">.</span><span
  1742. class="ci">_Decrement</span><span class="cp">()</span></code> is an optimized implementation of
  1743. </p>
  1744. <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>
  1745. <span class="ci">iter</span> <span class="co">&lt;-</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>
  1746. <span class="ci">c</span> <span class="co">&lt;-</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>
  1747. <span class="ck">else</span>
  1748. <span class="ci">c</span> <span class="co">&lt;-</span> <a href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a>
  1749. </pre>
  1750. </div>
  1751. </div>
  1752. </div>
  1753. <div class="interface-member _1" id="Iterator.members._Decrement_uint">
  1754. <div class="interface-member-code">
  1755. <a class="interface-member-backlink" href="#Iterator.interface._Decrement_uint:B:"></a>
  1756. <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">-&gt;</span> <span class="ci">char</span>
  1757. </pre>
  1758. </div>
  1759. <div class="interface-member-description">
  1760. <p class="para _1">
  1761. Advances the <code class="fsharp"><span class="ci">Iterator</span></code> <em>inplace</em> by minus the given number of chars and returns
  1762. the char on the new position, except if the new position would lie before the beginning of the <code class="fsharp"><a href="#"><span
  1763. class="ci">CharStream</span></a></code>, in which case the <code class="fsharp"><span class="ci">Iterator</span></code> is advanced to the
  1764. beginning of the stream and the <code class="fsharp"><a href="#Iterator.members.EndOfStreamChar"><span
  1765. class="ci">EndOfStreamChar</span></a></code> (<code class="fsharp"><span class="cc"><span class="left-delimiter">'</span><span
  1766. class="ce">\uFFFF</span><span class="right-delimiter">'</span></span></code>) is returned.
  1767. </p>
  1768. <div class="para _2">
  1769. <p>
  1770. <code class="fsharp"><span class="ci">c</span> <span class="co">&lt;-</span> <span class="ci">iter</span><span class="cm">.</span><span
  1771. class="ci">_Decrement</span><span class="cp">(</span><span class="ci">n</span><span class="cp">)</span></code> is an optimized
  1772. implementation of
  1773. </p>
  1774. <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">&gt;=</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>
  1775. <span class="ci">iter</span> <span class="co">&lt;-</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>
  1776. <span class="ci">c</span> <span class="co">&lt;-</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>
  1777. <span class="ck">else</span>
  1778. <span class="ci">iter</span> <span class="co">&lt;-</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>
  1779. <span class="ci">c</span> <span class="co">&lt;-</span> <a href="#Iterator.members.EndOfStreamChar"><span class="ci">EndOfStreamChar</span></a>
  1780. </pre>
  1781. </div>
  1782. </div>
  1783. </div>
  1784. </div>
  1785. </div>
  1786. </div>
  1787. </div>
  1788. </div>
  1789. <div class="fn-list">
  1790. <div class="fn-title">Footnotes:</div>
  1791. <table class="fn">
  1792. <tr class="fn _1">
  1793. <th class="fn _1"><a class="footnote-backlink" id="remarks.:FN:1" href="#remarks.:FN:1:B:">[1]</a></th>
  1794. <td class="fn _2">
  1795. The detection of invalid byte sequences by the .NET decoders is not entirely reliable. For example, <code class="fsharp"><span
  1796. class="ci">System</span><span class="cm">.</span><span class="ci">Text</span><span class="cm">.</span><span
  1797. class="ci">UnicodeEncoding</span></code> (UTF16) has an alignment related bug in .NET versions prior to 4.0 that sometimes leads to invalid
  1798. surrogate pairs not being detected. The implementations of more complicated encodings, like GB18030, ISO2022 and ISCII, also have <a
  1799. href="https://connect.microsoft.com/VisualStudio/feedback/ViewFeedback.aspx?FeedbackID=432648">several issues</a> with regard to the detection
  1800. of invalid input data.
  1801. </td>
  1802. </tr>
  1803. </table>
  1804. </div>
  1805. </div>
  1806. </div>
  1807. </div>
  1808. </div>
  1809. </body>
  1810. </html>