autodoc.git
/
traditional_manual
/
chapter_9.html
version
»
Context lines:
10
20
40
80
file
none
3
autodoc.git/traditional_manual/chapter_9.html:6081:
<dl class='group--doc'> <dt class='head--type'><span class='homogen--type'>Inherit</span> <span class='homogen--name'><b>Fd</b></span> </dt> <dd><p><code><span class='datatype'>inherit Fd</span> : <span class='inherit'>Fd</span></code></p></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'><p>Fake inherit to propagate the documentation from <code>_Stdio.Fd</code>.</p> </dd></dl>
+
</dd></dl><dl><dt><h2 class='header'>Class <b class='ms datatype'>Stdio.IOBuffer</b></h2>
+
</dt><dd><dl class='group--doc'>
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>A buffer to use as input or buffering when doing I/O. It is
+
similar to <code>String.Buffer</code>, but can only contain 8bit data and is
+
designed for protocol parsing. It is optimized for reading from
+
the beginning and adding to the end, and will try to minimize the
+
amount of data copying that is done.</p>
+
<p> The class maintains two separate offsets, one for reading and one
+
for writing. The functions that add data all do so at the write
+
offset (the end of the buffer), and reading is done from the read
+
offset (the start of the buffer).</p>
+
<p> The class can also be used to directly read from and write to
+
filedescriptors if so desired. This eliminates at least one memory
+
copy.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>The "avoid copy" part means that a IOBuffer will never shrink
+
unless you call the <code>trim</code> function.</p>
+
</dd></dl>
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>_encode</b></span><br>
+
<span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>_decode</b></span><br>
+
</dt>
+
<dd><p><code><span class='datatype'>string(8bit)</span> <b><span class='method'>encode_value</span>(</b><span class='class'>Stdio.IOBuffer</span> <span class='argument'>data</span>)</b></code><br>
+
<code><span class='class'>Stdio.IOBuffer</span> <b><span class='method'>decode_value</span>(</b><span class='datatype'>string(8bit)</span> <span class='argument'>data</span>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Encode and decode Stdio.IOBuffer objects.
+
Only the buffer data is kept, no other state is saved.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>_sizeof</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>sizeof</span>(</b> <span class='class'>Stdio.IOBuffer</span> <span class='argument'>arg</span> <b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Returns the buffer size, in bytes.
+
This is how much you can read from the buffer until it runs out of data.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>`[]</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> res = <code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ]</code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Return the character at the specified offset.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>`[]=</b></span>
+
</dt>
+
<dd><p><code><code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ] = <code class='class'>char</code></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Set the character at the specified offset to <code>char</code>.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>void</code> <b><span class='method'>add</span>(</b><code class='object unresolved'>System.Memory</code>|<code class='object unresolved'>Stdio.IOBuffer</code>|<code class='object unresolved'>String.Buffer</code>|<code class='datatype'>string(8bit)</code>|<code class='datatype'>int(8bit)</code> ... <code class='argument'>data</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Add the items in data to the end of the buffer.
+
Integers are assumed to be 8bit numbers (characters)</p>
+
</dd>
+
<dt class='head--doc'>See also</dt>
+
<dd class='body--doc'><p><code>sprintf</code>, <code>add_int8</code>, <code>add_int16</code>, <code>add_int32</code>, <code>add_int</code>
+
and
+
<code>add_hstring</code></p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_byte</b></span><br>
+
<span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_int8</b></span><br>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_byte</span>(</b><code class='datatype'>int(8bit)</code><b>)</b></code><br>
+
<code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_int8</span>(</b><code class='datatype'>int(8bit)</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Adds a single byte to the buffer.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_hstring</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_hstring</span>(</b><code class='datatype'>string(8bit)</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Adds length/data for <code>data</code> to the buffer.</p>
+
<p> This is identical to <code>sprintf("%"+size_size+"H",data)</code> but
+
significantly faster.</p>
+
<p> <code>size_size</code> must be less than Int.NATIVE_MAX.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_int</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_int</span>(</b><code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>width</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Adds a generic integer to the buffer as an (width*8)bit
+
network byteorder number.</p>
+
<p> <code>width</code> must be less than Int.NATIVE_MAX.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_int16</b></span><br>
+
<span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_short</b></span><br>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_int16</span>(</b><code class='datatype'>int(16bit)</code><b>)</b></code><br>
+
<code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_short</span>(</b><code class='datatype'>int(16bit)</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Add a 16-bit network byte order value to the buffer</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_int32</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_int32</span>(</b><code class='datatype'>int</code> <code class='argument'>i</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Adds a 32 bit network byte order value to the buffer</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>add_ints</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>add_ints</span>(</b><code class='datatype'>array</code>(<code class='datatype'>int</code>) <code class='argument'>integers</code>, <code class='datatype'>int(8bit)</code> <code class='argument'>len</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Add the integers in the specified array, <code>len</code> bytes per int.
+
Equivalent to add_int( integers[*], len ) but faster.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>cast</b></span>
+
</dt>
+
<dd><p><code><b>(</b><span class='datatype'><code class='datatype'>string</code></span><b>)</b><span class='class'>Stdio.IOBuffer</span>()</code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Convert the buffer to a string.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>This only works for buffers whose length is less than 0x7fffffff.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>clear</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>void</code> <b><span class='method'>clear</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Clear the buffer.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>consume</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> <b><span class='method'>consume</span>(</b><code class='datatype'>int(0..)</code> <code class='argument'>n</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Discard the first <code>n</code> bytes from the buffer</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>create</b></span>
+
</dt>
+
<dd><p><code><span class='object'>Stdio.IOBuffer</span> <span class='class'>Stdio.IOBuffer</span><b>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>len</code><b>)</b></code><br>
+
<code><span class='object'>Stdio.IOBuffer</span> <span class='class'>Stdio.IOBuffer</span><b>(</b><code class='datatype'>string(8bit)</code> <code class='argument'>contents</code><b>)</b></code><br>
+
<code><span class='object'>Stdio.IOBuffer</span> <span class='class'>Stdio.IOBuffer</span><b>(</b><code class='object unresolved'>System.Memory</code>|<code class='object unresolved'>String.Buffer</code> <code class='argument'>contents</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>If passed an integer or no argument, create a buffer of that
+
size, or if no argument is given, 226 bytes.</p>
+
<p> If <code>contents</code> are specified a new buffer with the contents of
+
the given string/System.Memory or String.Buffer will be created.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>In the <code>String.Buffer</code> case the data has to be copied unless
+
there is only one reference to the String.Buffer object, since
+
modifications of the String.Buffer would cause the IOBuffer to
+
point into invalid memory.</p>
+
<p> In all other cases this will not copy the string data, instead
+
data will be read from the source until it needs to be modified,
+
so the buffer creation is fast regardless of the length of the
+
string.</p>
+
<p> However, as an example, if the buffer is created with a 100Gb
+
<code>System.Memory</code> mmap:ed file as the <code>contents</code> and you later on
+
try to modify the buffer using one of the <code>add</code> functions (or
+
<code>sprintf</code> and similar) the old contents <b>will</b> be copied.</p>
+
<p> You can use <code>read_only()</code> to avoid accidents.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>input_from</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int(0..)</code> <b><span class='method'>input_from</span>(</b><code class='object unresolved'>Stdio.Stream</code> <code class='argument'>f</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Read data from <code>f</code> into this buffer.</p>
+
<p> Returns the amount of data that was read</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>Please note that this funcition will read all data from the
+
filedescriptor unless it's set to be non-blocking.</p>
+
<p> It is designed to only be used in non-blocking IO mode.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>lock</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>object</code> <b><span class='method'>lock</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Makes this buffer read only until the returned object is released.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>This currently simply returns a 0-length subbuffer.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>match</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>match</span>(</b><code class='datatype'>string(8bit)</code> <code class='argument'>format</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Reads data from the beginning of the buffer to match the
+
specifed format, then return the match.</p>
+
<p> The non-matching data will be left in the buffer.</p>
+
<p> This function is very similar to <code>sscanf</code>, but the
+
result is the sum of the matches. Most useful to match
+
a single value.</p>
+
</dd>
+
<dt class='head--doc'>Example</dt>
+
<dd class='example'><pre><pre><code><span class='comment'>// get the next whitespace separated word from the buffer.</span>
+
buffer->match<span class='delim'>(</span><span class='string'>"%*[ \t\r\n]%*[^ \t\r\n]"</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>output_to</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>output_to</span>(</b><code class='object unresolved'>Stdio.Stream</code> <code class='argument'>f</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Write data from the buffer to the indicated file.</p>
+
<p> Will return the number of bytes that were successfully written.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>range_error</b></span>
+
</dt>
+
<dd><p><code><code class='modifier'>protected</code> <code class='object unresolved'>bool</code> <b><span class='method'>range_error</span>(</b><code class='datatype'>int</code> <code class='argument'>howmuch</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>This function is called when an attempt is made to read out of bounds.
+
The default implementation simply returnns 0.</p>
+
<p> Override this function to change the behaviour</p>
+
<p> The argument <code>howmuch</code> indicates how much data is needed:</p>
+
<dl class='group--doc'><dt>int(1..) howmuch</dt>
+
<dd><p>Need <code>howmuch</code> bytes more</p>
+
</dd>
+
<dt>int(0..0) howmuch</dt>
+
<dd><p>The amount of data needed is not certain.
+
This most often happens when <code>sscanf</code> or <code>read_json</code> is used</p>
+
</dd>
+
<dt>int(..-1) howmuch=...</dt>
+
<dd><p>Tried to <code>unread</code> X bytes. There is usually no way to satisfy
+
the requested range.</p>
+
<p> The only supported way is to extract the data from the buffer,
+
add the requested amount of "go backbuffer", add the data
+
back, and forward -<code>howmuch</code> bytes.</p>
+
</dd>
+
</dl>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p><code>true</code> if the operation should be retried, <code>false</code> otherwise.</p>
+
<p> Do not return true unless you have added data to the buffer,
+
doing so could result in an infinite loop (since no data is
+
added, the range_error will be called again immediately).</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>read</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>string(8bit)</code> <b><span class='method'>read</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Read all data from the buffer.</p>
+
<p> If there is not enough data available this returns 0.</p>
+
<p> This is basically equivalent to (string)buffer, but it also
+
removes the data from the buffer.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>read</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>string(8bit)</code> <b><span class='method'>read</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Read <code>bytes</code> bytes of data from the buffer.</p>
+
<p> If there is not enough data available this returns 0.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>read_buffer</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>read_buffer</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code><b>)</b></code><br>
+
<code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>read_buffer</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Same as <code>read</code>, but returns the result as an IOBuffer.</p>
+
<p> No data is copied unless <code>copy</code> is specified and true, the new buffer
+
points into the old one.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>As long as the subbuffer exists no data can be added to the main buffer.</p>
+
<p> Usually this is OK, since it often represents something that
+
should be parsed before the next whatever is extracted from
+
the buffer, but do take care.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>read_hbuffer</b></span>
+
</dt>
+
<dd><p><code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>read_hbuffer</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code><b>)</b></code><br>
+
<code><code class='object unresolved'>IOBuffer</code> <b><span class='method'>read_hbuffer</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Same as <code>read_hstring</code>, but returns the result as an IOBuffer.</p>
+
<p> No data is copied unless <code>copy</code> is specified and true, the new
+
buffer points into the old one.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>As long as the subbuffer exists no data can be added to the
+
main buffer.</p>
+
<p> Usually this is OK, since it often represents something that
+
should be parsed before the next whatever is extracted from
+
the buffer, but do take care.</p>
+
<p> If you need to unlink the new buffer after it has been
+
created, call <code>trim</code> in it.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>read_hstring</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>string(8bit)</code> <b><span class='method'>read_hstring</span>(</b><code class='datatype'>int(0..)</code> <code class='argument'>n</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Identical in functionality to <code>read</code>(<code>read_number</code>(<code>n</code>)) but
+
faster.</p>
+
<p> Read a network byte order number of size n*8 bits, then return the
+
indicated number of bytes as a string.</p>
+
<p> If there is not enough data available return 0.</p>
+
<p> Note that pike string can not be longer than 0x7fffffff bytes (~2Gb).</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>read_int</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>read_int</span>(</b><code class='datatype'>int</code> <code class='argument'>n</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Read a network (if n is positive) or little endian (if n is
+
negative) byte order unsigned number of size n*8 bits, then
+
return it.</p>
+
<p> Will return -1 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>read_json</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>mixed</code> <b><span class='method'>read_json</span>(</b><code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>require_whitespace_separator</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Read a single JSON expression from the buffer and return it.</p>
+
<p> If <code>require_whitespace_separator</code> is true there must be a whitespace
+
after each json value (as an example, newline or space).</p>
+
<p> The JSON is assumed to be utf-8 encoded.</p>
+
</dd>
+
<dt class='head--doc'>Returns</dt>
+
<dd class='body--doc'><p>UNDEFINED if no data is available to read.
+
The read value otherwise.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>Unless whitespaces are required this function only really work correctly
+
with objects, arrays and strings.</p>
+
<p> There is really no way to see where one value starts and the other ends
+
for most other cases</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>read_only</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>void</code> <b><span class='method'>read_only</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Make the buffer permanently read only.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>You can use lock() to do this temporarily.</p>
+
</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='datatype'>void</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='datatype'>void</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>
+
<p> This is useful when parsing received data, you do not have to
+
verify that each and every read operation suceeds.</p>
+
<p> However, the non-error mode is more useful when checking to see
+
if a packet/segment/whatever has arrived.</p>
+
<p> The thrown error object will have the constant buffer_error set
+
to a non-false value.</p>
+
</dd>
+
<dt class='head--doc'>Example</dt>
+
<dd class='example'><pre><pre><code><span class='type'>void</span> read_callback<span class='delim'>(</span><span class='type'>int</span> i<span class='delim'>,</span> <span class='type'>string</span> new_data<span class='delim'>)</span>
+
<span class='delim'>{</span>
+
inbuffer->add<span class='delim'>(</span> new_data <span class='delim'>)</span><span class='delim'>;</span>
+
+
<span class='lang'>while</span><span class='delim'>(</span> IOBuffer packet <span class='delim'>=</span> inbuffer->read_hbuffer<span class='delim'>(</span>2<span class='delim'>)</span> <span class='delim'>)</span>
+
<span class='delim'>{</span>
+
packet->set_error_mode<span class='delim'>(</span>Buffer<span class='delim'>.</span>THROW_ERROR<span class='delim'>)</span><span class='delim'>;</span>
+
<span class='lang'>if</span><span class='delim'>(</span> <span class='type'>mixed</span> e <span class='delim'>=</span> <span class='lang'>catch</span><span class='delim'>(</span> handle_packet<span class='delim'>(</span> packet <span class='delim'>)</span> <span class='delim'>)</span> <span class='delim'>)</span>
+
<span class='lang'>if</span><span class='delim'>(</span> e->buffer_error <span class='delim'>)</span>
+
protocol_error<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span> <span class='comment'>// illegal data in packet</span>
+
<span class='lang'>else</span>
+
throw<span class='delim'>(</span>e<span class='delim'>)</span><span class='delim'>;</span> <span class='comment'>// the other code did something bad</span>
+
<span class='delim'>}</span>
+
<span class='delim'>}</span>
+
+
<span class='type'>void</span> handle_packet<span class='delim'>(</span> IOBuffer pack <span class='delim'>)</span>
+
<span class='delim'>{</span>
+
<span class='lang'>switch</span><span class='delim'>(</span> pack->read_int8<span class='delim'>(</span><span class='delim'>)</span> <span class='delim'>)</span>
+
<span class='delim'>{</span>
+
...
+
<span class='lang'>case</span> HEADER_FRAME<span class='delim'>:</span>
+
<span class='type'>int</span> num_headers <span class='delim'>=</span> pack->read_int32<span class='delim'>(</span><span class='delim'>)</span><span class='delim'>;</span>
+
<span class='lang'>for</span><span class='delim'>(</span> <span class='type'>int</span> i <span class='delim'>=</span> 0<span class='delim'>;</span> i<span class='delim'><</span>num_headers<span class='delim'>;</span> i++ <span class='delim'>)</span>
+
headers<span class='delim'>[</span>pack->read_hstring<span class='delim'>(</span>2<span class='delim'>)</span><span class='delim'>]</span> <span class='delim'>=</span> pack->read_hstring<span class='delim'>(</span>2<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>sprintf</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int</code> <b><span class='method'>sprintf</span>(</b><code class='object unresolved'>strict_sprintf_format</code> <code class='argument'>format</code>, <code class='object unresolved'>sprintf_args</code> ... <code class='argument'>args</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Appends the output from <code>sprintf</code> at the end of the buffer.</p>
+
<p> This is somewhat faster than add(sprintf(...)) since no
+
intermediate string is created.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>sscanf</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>array</code> <b><span class='method'>sscanf</span>(</b><code class='datatype'>string(8bit)</code> <code class='argument'>format</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Reads data from the beginning of the buffer to match the
+
specifed format, then return an array with the matches.</p>
+
<p> The non-matching data will be left in the buffer.</p>
+
<p> See <code>array_sscanf</code> for more information.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>trim</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>void</code> <b><span class='method'>trim</span>(</b><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Frees unused memory.</p>
+
<p> Note that calling this function excessively will slow things
+
down, since the data often has to be copied.</p>
+
</dd>
+
<dt class='head--doc'>Note</dt>
+
<dd class='body--doc'><p>This function could possibly throw an out-of-memory error
+
if the realloc fails to find a new (smaller) memory area.</p>
+
</dd></dl>
+
+
+
<hr />
+
<dl class='group--doc'>
+
<dt class='head--type'><span class='homogen--type'>Method</span>
+
<span class='homogen--name'><b>unread</b></span>
+
</dt>
+
<dd><p><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> <b><span class='method'>unread</span>(</b><code class='datatype'>int(0..)</code> <code class='argument'>n</code><b>)</b></code></p></dd>
+
+
<dt class='head--doc'>Description</dt>
+
<dd class='body--doc'><p>Rewind the buffer <code>n</code> bytes.</p>
+
</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>undread(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> </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>