autodoc.git / traditional_manual / chapter_9.html

version» Context lines:

autodoc.git/traditional_manual/chapter_9.html:6740:   <dd class='body--doc'><p>Read a network byte order two:s complement signed number of size n*8 bits, then    return it.</p>   <p> Will return UNDEFINED if there is not enough buffer space    available unless error mode is set to throw errors.</p>   </dd></dl>         <hr />   <dl class='group--doc'>   <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>rewind_on_error</b></span> + </dt> + <dd><p><code><code class='object unresolved'>UnwindKey</code> <b><span class='method'>rewind_on_error</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Create an object that, when it goes out of scope without having +  been destructed explicitly, will cause the buffer to rewind to +  the location it had when this function is called.</p> + <p> This will happen if you throw an error or otherwise let the +  object fall out of scope.</p> + <p> Take some care with these objects, if you create multiple ones +  at once the results might be somewhat confusing if you do not +  release them in the reverse order they were created in (then +  again, you almost certainly really only need one)</p> + <p> Use <code>destruct</code> or <code>UnwindKey.release</code> to stop the buffer from being rewound.</p> + <p> You can call <code>update</code> in the generated object to change where +  it will be rewound to.</p> + <p> The typical usecase of this object is when pasing a packet +  protocol with variable length packets where the lenght is not +  immediately known. It saves you from keeping track of how much +  to rewind if you had not actually gotten the whole packet yet.</p> + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code><span class='type'>void</span> parse_packet<span class='delim'>(</span> <span class='ns'>Stdio</span><span class='delim'>.</span>IOBuffer b <span class='delim'>)</span> + <span class='delim'>{</span> +  <span class='ns'>Stdio</span><span class='delim'>.</span>IOBuffer<span class='delim'>.</span>UnwindKey rewind <span class='delim'>=</span> b-&gt;rewind_on_error<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span> +  b-&gt;set_error_mode<span class='delim'>(</span>1<span class='delim'>)</span><span class='delim'>;</span> +  +  <span class='lang'>switch</span><span class='delim'>(</span> b-&gt;read_int8<span class='delim'>(</span><span class='delim'>)</span> <span class='delim'>)</span> <span class='comment'>// packet type</span> +  <span class='delim'>{</span> +  <span class='lang'>case</span> DATA<span class='delim'>:</span> +  <span class='type'>int</span> channel <span class='delim'>=</span> b-&gt;read_int8<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span> +  <span class='ns'>Stdio</span><span class='delim'>.</span>IOBuffer data <span class='delim'>=</span> b-&gt;read_hbuffer<span class='delim'>(</span> 4 <span class='delim'>)</span><span class='delim'>;</span> +  <span class='comment'>// we have read the whole packet, so no longer rewind on error.</span> +  rewind-&gt;release<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span> +  <span class='lang'>return</span> handle_data_packet<span class='delim'>(</span> chennel<span class='delim'>,</span> data <span class='delim'>)</span><span class='delim'>;</span> +  <span class='delim'>}</span> + <span class='delim'>}</span> + </code></pre></pre></dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span>   <span class='homogen--name'><b>set_error_mode</b></span>   </dt>   <dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>set_error_mode</span>(</b><code class='datatype'>int</code> <code class='argument'>m</code><b>)</b></code><br>   <code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>set_error_mode</span>(</b><code class='datatype'>program</code> <code class='argument'>m</code><b>)</b></code></p></dd>      <dt class='head--doc'>Description</dt>   <dd class='body--doc'><p>Set the error mode of this buffer to <code>m</code>.</p>   <p> If true operations that would normally return 0 (like trying to    read too much) will instead throw an error. If <code>m</code> is a program    a clone of it will be thrown on error.</p>
autodoc.git/traditional_manual/chapter_9.html:6877:   </dd>   <dt class='head--doc'>Returns</dt>   <dd class='body--doc'><p>This function returns how many more bytes of buffer is    available to rewind, or -1 on error.</p>   </dd>   <dt class='head--doc'>Note</dt>   <dd class='body--doc'><p>Unless you add new data to the buffer using any of the add    functions you can always rewind.</p>   <p> You can call <code>unread(0)</code> to see how much.</p>   </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.NonblockingStream</b></h2> + <dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.IOBuffer.UnwindKey</b></h2>   </dt><dd><dl class='group--doc'>   <dt class='head--doc'>Description</dt> -  + <dd class='body--doc'><p>The return value of unwind_when_released()</p> + <p> This object will cause the buffer to unwind to the position it +  was at when the object was created when it is released +  (when it falls out of scope, explicit destruct does not count).</p> + </dd></dl> +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>release</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>release</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Do not rewind if the object is released.</p> + <p> This is equivalent to calling destruct() on the object.</p> + </dd></dl> +  +  + <hr /> + <dl class='group--doc'> + <dt class='head--type'><span class='homogen--type'>Method</span> + <span class='homogen--name'><b>update</b></span> + </dt> + <dd><p><code><code class='datatype'>void</code> <b><span class='method'>update</span>(</b><b>)</b></code></p></dd> +  + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><p>Update the location the buffer will be rewound to to the current +  position of the buffer.</p> + </dd></dl> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.NonblockingStream</b></h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt>   <dd class='body--doc'><p>The Stdio.NonblockingStream API.</p>   <p> This class exists purely for typing reasons.</p>   <p> Use in types in place of <code>Stdio.File</code> where nonblocking and/or    blocking stream-oriented I/O is done with the object.</p>   </dd>   <dt class='head--doc'>See also</dt>   <dd class='body--doc'><p><code>Stream</code>, <code>BlockFile</code>, <code>File</code>, <code>FILE</code></p>   </dd></dl>      <hr />