Log of autodoc.git/traditional_manual/chapter

2014-10-01

2014-10-01 14:34:26 by Martin Nilsson <nilsson@opera.com>

f3d0cc173b07b7d18bdce84586cb5ebf66af2a61 (3241 lines) (+1621/-1620) ^{[

Show
| Annotate

]}
Branch: 8.0

Stdio.IOBuffer -> Stdio.Buffer (part 1)

508: <dt class='head--type'>Typedef read_callback_t </dt> - <dd><code><code class='datatype'>typedef</code> <code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>) Stdio.File.<code class='typedef'>read_callback_t</code></code></dd> + <dd><code><code class='datatype'>typedef</code> <code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>) Stdio.File.<code class='typedef'>read_callback_t</code></code></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'>The various read_callback signatures. The string (or void) version is used when buffer mode (see <code>set_buffer_mode</code>) has not been enabled for reading. - The IOBuffer version is used when an IOBuffer has been enabled + The Buffer version is used when an Buffer has been enabled for reading In both cases the data is the newly arrived data, but in buffered mode data you did not fully read in the last read callback is
598: <dt class='head--type'>Method set_buffer_mode </dt> - <dd><code><code class='datatype'>void</code> set_buffer_mode(<code class='object unresolved'>Stdio.IOBuffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>in</code>, <code class='object unresolved'>Stdio.IOBuffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>out</code>)</code></dd> + <dd><code><code class='datatype'>void</code> set_buffer_mode(<code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>in</code>, <code class='object unresolved'>Stdio.Buffer</code>|<code class='datatype'>int(0..0)</code> <code class='argument'>out</code>)</code></dd> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Toggle the file to IOBuffer mode. - In this mode reading and writing will be done via IOBuffer + <dd class='body--doc'>Toggle the file to Buffer mode. + In this mode reading and writing will be done via Buffer objects, in the directions you included buffers. </dd> <dt class='head--doc'>Parameter <code class='parameter'>in</code></dt>
657: set_fs_event_callback </dt> <dd><code><code class='datatype'>void</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>)</code> - <code><code class='datatype'>void</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>)</code> + <code><code class='datatype'>void</code> set_read_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>) <code class='argument'>read_cb</code>)</code> <code><code class='datatype'>void</code> set_write_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>)</code> - <code><code class='datatype'>void</code> set_write_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>)</code> + <code><code class='datatype'>void</code> set_write_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>) <code class='argument'>write_cb</code>)</code> <code><code class='datatype'>void</code> set_read_oob_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>, <code class='datatype'>string</code>:<code class='datatype'>int</code>) <code class='argument'>read_oob_cb</code>)</code> <code><code class='datatype'>void</code> set_write_oob_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>write_oob_cb</code>)</code> <code><code class='datatype'>void</code> set_close_callback(<code class='datatype'>function</code>(<code class='datatype'>mixed</code>:<code class='datatype'>int</code>) <code class='argument'>close_cb</code>)</code> 
680: <ul> <li>When data arrives on the stream, <code>read_cb</code> will be called with some or all of that data as the second argument. - If the file is in buffer mode, the second argument will be an IOBuffer. + If the file is in buffer mode, the second argument will be an Buffer. This will always be the same buffer, so data you do not use in one read callback can be simply left in the buffer, when new data arrives it will be appended
692: If the remote end has closed both directions simultaneously (the usual case), Pike will first attempt to call <code>close_cb</code>, then this callback (unless <code>close_cb</code> has closed the stream). - If the file is in buffer mode, the second argument will be an IOBuffer. + If the file is in buffer mode, the second argument will be an Buffer. You should add data to write to this buffer. </li><li>When out-of-band data arrives on the stream, <code>read_oob_cb</code> will be called with some or all of that data as the second
925: <dt class='head--type'>Typedef write_callback_t </dt> - <dd><code><code class='datatype'>typedef</code> <code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='object unresolved'>IOBuffer</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>) Stdio.File.<code class='typedef'>write_callback_t</code></code></dd> + <dd><code><code class='datatype'>typedef</code> <code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>)|<code class='datatype'>function</code>(<code class='datatype'>mixed</code>|<code class='datatype'>void</code>, <code class='object unresolved'>Buffer</code>:<code class='datatype'>int</code>|<code class='datatype'>void</code>) Stdio.File.<code class='typedef'>write_callback_t</code></code></dd> <dt class='head--doc'>Description</dt> <dd class='body--doc'>The various read_callback signatures. The void version is used when buffer mode (see <code>set_buffer_mode</code>) has not been enabled for writing. - The IOBuffer version is used when an IOBuffer has been enabled + The Buffer version is used when an Buffer has been enabled for reading, add data to that buffer to send it. </dd></dl> </dd></dl><dl><dt><h2 class='header'>Class Stdio.FILE</h2>
4261: </dt> <dd><code><code class='datatype'>int</code> tell()</code></dd> </dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.FakeFile</h2> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.Buffer</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - + <dd class='body--doc'>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. + 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). + The class can also be used to directly read from and write to + filedescriptors if so desired. This eliminates at least one memory + copy. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>The "avoid copy" part means that a Buffer will never shrink + unless you call the <code>trim</code> function. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + __fd_set_output + </dt> + <dd><code><code class='datatype'>int</code> __fd_set_output(<code class='datatype'>object</code> <code class='argument'>f</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This tells the buffer to trigger the write callback for the + specified filedescriptor when data is added to the buffer. + This is used internally by Stdio.File to handle nonblocking + buffered mode, and is not really intended to be used directly. + If f is 0 the state is cleared. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _encode + Method + _decode + </dt> + <dd><code>string(8bit) encode_value(Stdio.Buffer data)</code> + <code>Stdio.Buffer decode_value(string(8bit) data)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Encode and decode Stdio.Buffer objects. + Only the buffer data is kept, no other state is saved. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + _sizeof + </dt> + <dd><code><code class='datatype'>int</code> sizeof( Stdio.Buffer arg )</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Returns the buffer size, in bytes. + This is how much you can read from the buffer until it runs out of data. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + `[] + </dt> + <dd><code><code class='datatype'>int</code> res = <code class='class'>Stdio.Buffer()</code>[ <code class='class'>off</code> ]</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Return the character at the specified offset. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + `[]= + </dt> + <dd><code><code class='class'>Stdio.Buffer()</code>[ <code class='class'>off</code> ] = <code class='class'>char</code></code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the character at the specified offset to <code>char</code>. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add(<code class='object unresolved'>AddArgument</code> ... <code class='argument'>data</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'><pre><code>private typedef System.Memory|Stdio.Buffer|String.Buffer BufferObject; + private typedef BufferObject|string(8bit)|int(8bit)|array(AddArgument) AddArgument;</code></pre>Add the items in data to the end of the buffer. + The supported argument types are: + <table class='box'><tr><td><code><code class='datatype'>string(8bit)</code></code></td><td>An eight bit string. + </td></tr> + <tr><td><code><code class='datatype'>int(8bit)</code></code></td><td>A single byte + </td></tr> + <tr><td><code><code class='object unresolved'>System.Memory</code></code></td><td>A chunk of memory. The whole memory area is added. + </td></tr> + <tr><td><code><code class='object unresolved'>Stdio.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. + </td></tr> + <tr><td><code><code class='object unresolved'>String.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. + </td></tr> + <tr><td><code><code class='datatype'>array</code>(<code class='object unresolved'>AddArgument</code>)</code></td><td>Add all elements in the array individually. Each element may be + any one of the types listed here. + </td></tr> + </table> + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>sprintf</code>, <code>add_int8</code>, <code>add_int16</code>, <code>add_int32</code>, <code>add_int</code> + and + <code>add_hstring</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_hint + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_hint(<code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>size_width</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>First add the size of the integer when encoded to base 256 as a + <code>size_width</code> integer, then add the integer to the buffer, both + in network byte order. + <code>size_width</code> must be less than Int.NATIVE_MAX. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_hstring + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_hstring(<code class='datatype'>string(8bit)</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> + <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='object unresolved'>Stdio.Buffer</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> + <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='object unresolved'>System.Memory</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> + <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='object unresolved'>String.Buffer</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> + <code><code class='object unresolved'>Buffer</code> add_hstring(<code class='datatype'>array</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Adds length of data followed by <code>data</code> to the buffer. + This is identical to + <tt>sprintf("%"+size_size+"H",(string)Stdio.IObuffer(data))</tt> but + significantly faster. + <code>size_size</code> is the number of bytes used to represent the length of the data. + It must be less than Int.NATIVE_MAX. + The supported <code>data</code> argument types are + <table class='box'><tr><td><code><code class='datatype'>string(8bit)</code></code></td><td>An eight bit string. + </td></tr> + <tr><td><code><code class='object unresolved'>System.Memory</code></code></td><td>A chunk of memory. The whole memory area is added. + </td></tr> + <tr><td><code><code class='object unresolved'>Stdio.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. + </td></tr> + <tr><td><code><code class='object unresolved'>String.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. + </td></tr> + <tr><td><code><code class='datatype'>array</code></code></td><td>Add all elements in the array individually. Each element may be + any one of the types listed here. + </td></tr> + </table></dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_int + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_int(<code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>width</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Adds a generic integer to the buffer as an (width*8)bit + network byteorder number. + <code>width</code> must be less than Int.NATIVE_MAX. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_int16 + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_int16(<code class='datatype'>int(16bit)</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add a 16-bit network byte order value to the buffer + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_int32 + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_int32(<code class='datatype'>int</code> <code class='argument'>i</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Adds a 32 bit network byte order value to the buffer + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_int8 + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_int8(<code class='datatype'>int(8bit)</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Adds a single byte to the buffer. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_ints + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_ints(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add the integers in the specified array, <code>len</code> bytes per int. + Equivalent to calling <code>add_int</code> for each integer, but faster, + and if an error occurs the buffer will contain no new + data. Either all or none of the integers will be added. + Errors can occur if one of the elements in <code>integers</code> is not + actually an integer, if sizeof(integers)*len is bigger than can + be represented in a size_t, or if the buffer cannot grow due to + an out of memory condition. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + add_padding + </dt> + <dd><code><code class='object unresolved'>Buffer</code> add_padding(<code class='datatype'>int</code> <code class='argument'>nbytes</code>, <code class='datatype'>int(8bit)</code>|<code class='datatype'>void</code> <code class='argument'>byte</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Add <code>nbytes</code> bytes of padding, if <code>byte</code> is not specified the + area will be filled with 0's, otherwise the specified byte will + be repeated. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + cast + </dt> + <dd><code>(<code class='datatype'>string</code>)Stdio.Buffer()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Convert the buffer to a string. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This only works for buffers whose length is less than 0x7fffffff. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + clear + </dt> + <dd><code><code class='datatype'>void</code> clear()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Clear the buffer. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + consume + </dt> + <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> consume(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Discard the first <code>n</code> bytes from the buffer + Returns -1 on error and the amount of space still left otherwise. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + create + </dt> + <dd><code>Stdio.Buffer Stdio.Buffer(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>len</code>)</code> + <code>Stdio.Buffer Stdio.Buffer(<code class='datatype'>string(8bit)</code> <code class='argument'>contents</code>)</code> + <code>Stdio.Buffer Stdio.Buffer(<code class='object unresolved'>System.Memory</code>|<code class='object unresolved'>String.Buffer</code> <code class='argument'>contents</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>If passed an integer or no argument, create a buffer of that + size, or if no argument is given, 226 bytes. + If <code>contents</code> are specified a new buffer with the contents of + the given string/System.Memory or String.Buffer will be created. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>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 Buffer to + point into invalid memory. + 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. + 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 will be copied. + You can use <code>read_only()</code> to avoid accidents. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + input_from + </dt> + <dd><code><code class='datatype'>int(-1..)</code> input_from(<code class='object unresolved'>Stdio.Stream</code> <code class='argument'>f</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read data from <code>f</code> into this buffer. If <code>nbytes</code> is not + specified, read until there is no more data to read (currently). + Returns the amount of data that was read, or <code class='expr'>-1</code> on + read error. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Please note that this funcition will read all data from the + filedescriptor unless it's set to be non-blocking. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + lock + </dt> + <dd><code><code class='datatype'>object</code> lock()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Makes this buffer read only until the returned object is released. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This currently simply returns a 0-length subbuffer. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + match + </dt> + <dd><code><code class='datatype'>mixed</code> match(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads data from the beginning of the buffer to match the + specifed format, then return the match. + The non-matching data will be left in the buffer. + 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. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code>// get the next whitespace separated word from the buffer. + buffer->match("%*[ \t\r\n]%[^ \t\r\n]"); + </code></pre></pre></dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + output_to + </dt> + <dd><code><code class='datatype'>int(-1..)</code> output_to(<code class='object unresolved'>Stdio.Stream</code> <code class='argument'>f</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Write data from the buffer to the indicated file. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>nbytes</code></dt> + <dd></dd><dd class='body--doc'>If <code>nbytes</code> is not specified the whole buffer will be written + if possible. Otherwise at most <code>nbytes</code> will be written. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>Will return the number of bytes that have been written successfully. + If no bytes have been written successfully and <code class='expr'>f->write()</code> failed + with an error, <code class='expr'>-1</code> will be returned. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + range_error + </dt> + <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>bool</code> range_error(<code class='datatype'>int</code> <code class='argument'>howmuch</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>This function is called when an attempt is made to read out of bounds. + The default implementation simply returns <code class='expr'>0</code> (zero). + Override this function to change the behavior. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>howmuch</code></dt> + <dd></dd><dd class='body--doc'>The argument <code>howmuch</code> indicates how much data is needed: + <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td>Need <code>howmuch</code> bytes more + </td></tr> + <tr><td><code><code class='key'>0</code></code></td><td>The amount of data needed is not certain. + This most often happens when <code>sscanf</code> or <code>read_json</code> is used + </td></tr> + <tr><td><code><code class='key'>(..-1)</code></code></td><td>Tried to <code>unread</code> -<code>howmuch</code> bytes. There is usually no way to satisfy + the requested range. + 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. + </td></tr> + </table> + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'><code>true</code> if the operation should be retried, <code>false</code> otherwise. + 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). + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>string(8bit)</code> read()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read all data from the buffer. + If there is not enough data available this returns 0. + This is basically equivalent to (string)buffer, but it also + removes the data from the buffer. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>try_read()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read + </dt> + <dd><code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read <code>bytes</code> bytes of data from the buffer. + If there is not enough data available this returns 0. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>try_read()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_buffer + </dt> + <dd><code><code class='object unresolved'>Buffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> + <code><code class='object unresolved'>Buffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Same as <code>read</code>, but returns the result as an Buffer. + No data is copied unless <code>copy</code> is specified and true, the new buffer + points into the old one. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>As long as the subbuffer exists no data can be added to the main buffer. + 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. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_cstring + </dt> + <dd><code><code class='datatype'>string(8bit)</code> read_cstring()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads a \0 terminated C-string and returns the + string excluding the terminating \0. + If there is not enough data available return UNDEFINED. + Note that pike string can not be longer than 0x7fffffff bytes (~2Gb). + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_hbuffer + </dt> + <dd><code><code class='object unresolved'>Buffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> + <code><code class='object unresolved'>Buffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Same as <code>read_hstring</code>, but returns the result as an Buffer. + No data is copied unless <code>copy</code> is specified and true, the new + buffer points into the old one. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>As long as the subbuffer exists no data can be added to the + main buffer. + 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. + If you need to unlink the new buffer after it has been + created, call <code>trim</code> in it. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_hint + </dt> + <dd><code><code class='datatype'>int</code> read_hint(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read a network byte order unsigned number of size n*8 bits, then + read another network byte order number of the size indicated by + the first size. + Will return -1 if there is not enough buffer space available + unless error mode is set to throw errors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_hstring + </dt> + <dd><code><code class='datatype'>string(8bit)</code> read_hstring(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Identical in functionality to <code>read</code>(<code>read_number</code>(<code>n</code>)) but + faster. + Read a network byte order number of size n*8 bits, then return the + indicated number of bytes as a string. + If there is not enough data available return 0. + Note that pike string can not be longer than 0x7fffffff bytes (~2Gb). + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_int + </dt> + <dd><code><code class='datatype'>int</code> read_int(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read a network byte order unsigned number of size n*8 bits, then + return it. + Will return -1 if there is not enough buffer space available + unless error mode is set to throw errors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_int16 + </dt> + <dd><code><code class='datatype'>int(16bit)</code> read_int16()</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_int24 + </dt> + <dd><code><code class='datatype'>int(24bit)</code> read_int24()</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_int32 + </dt> + <dd><code><code class='datatype'>int(32bit)</code> read_int32()</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_int8 + </dt> + <dd><code><code class='datatype'>int(8bit)</code> read_int8()</code></dd> + </dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_ints + </dt> + <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) read_ints(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>int</code> <code class='argument'>width</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read a list of <code>n</code> network byte order unsigned numbers each of + size <code>width</code>*8 bits, then return it. + Will return 0 if there is not enough buffer space available + unless error mode is set to throw errors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_json + </dt> + <dd><code><code class='datatype'>mixed</code> read_json(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>require_whitespace_separator</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read a single JSON expression from the buffer and return it. + If <code>require_whitespace_separator</code> is true there must be a whitespace + after each json value (as an example, newline or space). + The JSON is assumed to be utf-8 encoded. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>UNDEFINED if no data is available to read. + The read value otherwise. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Unless whitespaces are required this function only really work correctly + with objects, arrays and strings. + There is really no way to see where one value starts and the other ends + for most other cases + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_only + </dt> + <dd><code><code class='datatype'>void</code> read_only()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Make the buffer permanently read only. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>You can use lock() to do this temporarily. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + read_sint + </dt> + <dd><code><code class='datatype'>int</code> read_sint(<code class='datatype'>int</code> <code class='argument'>size</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Read a network byte order two:s complement signed number of size n*8 bits, then + return it. + Will return UNDEFINED if there is not enough buffer space + available unless error mode is set to throw errors. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + rewind_on_error + Method + rewind_key + </dt> + <dd><code><code class='object unresolved'>RewindKey</code> rewind_on_error()</code> + <code><code class='object unresolved'>RewindKey</code> rewind_key()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>These functions are very similar. The <code>rewind_on_error</code> edition + will 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. + This will happen if you throw an error or otherwise let the + object fall out of scope. + Use <code>destruct(RewindKey)</code> or <code>RewindKey.release</code> to stop the + buffer from being rewound. + The second version (<code>rewind_key</code>) requires you to explicitly + call <code>RewindKey.rewind</code> to do the rewind. + 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) + You can call <code>RewindKey.update</code> in the generated object to + change where it will be rewound to. + The typical use-case of this functionality is when parsing 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. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code>void parse_packet( Stdio.Buffer b ) + { + Stdio.Buffer.RewindKey rewind = b->rewind_on_error(); + b->set_error_mode(1); + + switch( b->read_int8() ) // packet type + { + case DATA: + int channel = b->read_int8(); + Stdio.Buffer data = b->read_hbuffer( 4 ); + // we have read the whole packet, so no longer rewind on error. + rewind->release(); + return handle_data_packet( chennel, data ); + } + } + </code></pre></pre></dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Just calling <code>rewind_on_error</code> without assigning the return + value to something will not do anything. You need to keep the + object around while the rewind-to position is still valid. + Keeping the object around forbids the buffer from moving data + inside itself, this means that it can only grow. So do not keep + the rewind key when it is not needed. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + set_error_mode + </dt> + <dd><code><code class='object unresolved'>Buffer</code> set_error_mode(<code class='datatype'>int</code> <code class='argument'>m</code>)</code> + <code><code class='object unresolved'>Buffer</code> set_error_mode(<code class='datatype'>program</code> <code class='argument'>m</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Set the error mode of this buffer to <code>m</code>. + 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. + This is useful when parsing received data, you do not have to + verify that each and every read operation suceeds. + However, the non-error mode is more useful when checking to see + if a packet/segment/whatever has arrived. + The thrown error object will have the constant buffer_error set + to a non-false value. + </dd> + <dt class='head--doc'>Example</dt> + <dd class='example'><pre><pre><code>void read_callback(int i, string new_data) + { + inbuffer->add( new_data ); + + while( Buffer packet = inbuffer->read_hbuffer(2) ) + { + packet->set_error_mode(Buffer.THROW_ERROR); + if( mixed e = catch( handle_packet( packet ) ) ) + if( e->buffer_error ) + protocol_error(); // illegal data in packet + else + throw(e); // the other code did something bad + } + } + + void handle_packet( Buffer pack ) + { + switch( pack->read_int8() ) + { + ... + case HEADER_FRAME: + int num_headers = pack->read_int32(); + for( int i = 0; i<num_headers; i++ ) + headers[pack->read_hstring(2)] = pack->read_hstring(2); + ... + } + } + </code></pre></pre></dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + sprintf + </dt> + <dd><code><code class='object unresolved'>Buffer</code> sprintf(<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>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Appends the output from <code>sprintf</code> at the end of the buffer. + This is somewhat faster than add(sprintf(...)) since no + intermediate string is created. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + sscanf + </dt> + <dd><code><code class='datatype'>array</code> sscanf(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Reads data from the beginning of the buffer to match the + specifed format, then return an array with the matches. + The non-matching data will be left in the buffer. + See <code>array_sscanf</code> for more information. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + trim + </dt> + <dd><code><code class='datatype'>void</code> trim()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Frees unused memory. + Note that calling this function excessively will slow things + down, since the data often has to be copied. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This function could possibly throw an out-of-memory error + if the realloc fails to find a new (smaller) memory area. + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + try_read + </dt> + <dd><code><code class='datatype'>string(8bit)</code> try_read(<code class='datatype'>int</code> <code class='argument'>len</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Attempt to read some data from the buffer. + </dd> + <dt class='head--doc'>Parameter <code class='parameter'>len</code></dt> + <dd></dd><dd class='body--doc'>Read at most <code>len</code> bytes from the buffer. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>If the buffer contains less than <code>len</code> bytes + of data, the entire buffer contents are returned. + Otherwise the first <code>len</code> bytes are returned. + </dd> + <dt class='head--doc'>See also</dt> + <dd class='body--doc'><code>read()</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + unread + </dt> + <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> unread(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Rewind the buffer <code>n</code> bytes. + </dd> + <dt class='head--doc'>Returns</dt> + <dd class='body--doc'>This function returns how many more bytes of buffer is + available to rewind, or -1 on error. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Unless you add new data to the buffer using any of the add + functions you can always rewind. + You can call <code>unread(0)</code> to see how much. + </dd></dl> + <dl><dt><h2 class='header'>Class Stdio.Buffer.RewindKey</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The return value of <code>Buffer.rewind_on_error()</code> and + <code>Buffer.rewind_key()</code> + This object will cause the buffer to unwind to the position it was + at when the object was created either when it is released (when it + falls out of scope, explicit destruct does not count) or when + <code>rewind</code> is called, depending on which function was used to + create it. + </dd></dl> + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + release + </dt> + <dd><code><code class='datatype'>void</code> release()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Do not rewind if the object is released. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>This is equivalent to calling destruct() on the object + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + rewind + </dt> + <dd><code><code class='datatype'>void</code> rewind()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Rewinds the buffer explicitly. + </dd> + <dt class='head--doc'>Note</dt> + <dd class='body--doc'>Destructs this <code>RewindKey</code> + </dd></dl> + + + <hr /> + <dl class='group--doc'> + <dt class='head--type'>Method + update + </dt> + <dd><code><code class='datatype'>void</code> update()</code></dd> + + <dt class='head--doc'>Description</dt> + <dd class='body--doc'>Update the location the buffer will be rewound to to the current + position of the buffer. + </dd></dl> + </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.FakeFile</h2> + </dt><dd><dl class='group--doc'> + <dt class='head--doc'>Description</dt> <dd class='body--doc'>A string wrapper that pretends to be a <code>Stdio.File</code> object in addition to some features of a <code>Stdio.FILE</code> object. </dd></dl>
6147: <dd class='body--doc'>Fake inherit to propagate the documentation from <code>_Stdio.Fd</code>. </dd></dl> - </dd></dl><dl><dt><h2 class='header'>Class Stdio.IOBuffer</h2> + </dd></dl><dl><dt><h2 class='header'>Class Stdio.NonblockingStream</h2> </dt><dd><dl class='group--doc'> <dt class='head--doc'>Description</dt> - <dd class='body--doc'>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. - 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). - The class can also be used to directly read from and write to - filedescriptors if so desired. This eliminates at least one memory - copy. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>The "avoid copy" part means that a IOBuffer will never shrink - unless you call the <code>trim</code> function. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - __fd_set_output - </dt> - <dd><code><code class='datatype'>int</code> __fd_set_output(<code class='datatype'>object</code> <code class='argument'>f</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This tells the buffer to trigger the write callback for the - specified filedescriptor when data is added to the buffer. - This is used internally by Stdio.File to handle nonblocking - buffered mode, and is not really intended to be used directly. - If f is 0 the state is cleared. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _encode - Method - _decode - </dt> - <dd><code>string(8bit) encode_value(Stdio.IOBuffer data)</code> - <code>Stdio.IOBuffer decode_value(string(8bit) data)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Encode and decode Stdio.IOBuffer objects. - Only the buffer data is kept, no other state is saved. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - _sizeof - </dt> - <dd><code><code class='datatype'>int</code> sizeof( Stdio.IOBuffer arg )</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Returns the buffer size, in bytes. - This is how much you can read from the buffer until it runs out of data. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `[] - </dt> - <dd><code><code class='datatype'>int</code> res = <code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ]</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Return the character at the specified offset. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - `[]= - </dt> - <dd><code><code class='class'>Stdio.IOBuffer()</code>[ <code class='class'>off</code> ] = <code class='class'>char</code></code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the character at the specified offset to <code>char</code>. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add(<code class='object unresolved'>AddArgument</code> ... <code class='argument'>data</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'><pre><code>private typedef System.Memory|Stdio.IOBuffer|String.Buffer BufferObject; - private typedef BufferObject|string(8bit)|int(8bit)|array(AddArgument) AddArgument;</code></pre>Add the items in data to the end of the buffer. - The supported argument types are: - <table class='box'><tr><td><code><code class='datatype'>string(8bit)</code></code></td><td>An eight bit string. - </td></tr> - <tr><td><code><code class='datatype'>int(8bit)</code></code></td><td>A single byte - </td></tr> - <tr><td><code><code class='object unresolved'>System.Memory</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>Stdio.IOBuffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>String.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='datatype'>array</code>(<code class='object unresolved'>AddArgument</code>)</code></td><td>Add all elements in the array individually. Each element may be - any one of the types listed here. - </td></tr> - </table> - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>sprintf</code>, <code>add_int8</code>, <code>add_int16</code>, <code>add_int32</code>, <code>add_int</code> - and - <code>add_hstring</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_hint - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_hint(<code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>size_width</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>First add the size of the integer when encoded to base 256 as a - <code>size_width</code> integer, then add the integer to the buffer, both - in network byte order. - <code>size_width</code> must be less than Int.NATIVE_MAX. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_hstring - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_hstring(<code class='datatype'>string(8bit)</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> add_hstring(<code class='object unresolved'>Stdio.IOBuffer</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> add_hstring(<code class='object unresolved'>System.Memory</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> add_hstring(<code class='object unresolved'>String.Buffer</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> add_hstring(<code class='datatype'>array</code> <code class='argument'>data</code>, <code class='datatype'>int</code> <code class='argument'>size_size</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds length of data followed by <code>data</code> to the buffer. - This is identical to - <tt>sprintf("%"+size_size+"H",(string)Stdio.IObuffer(data))</tt> but - significantly faster. - <code>size_size</code> is the number of bytes used to represent the length of the data. - It must be less than Int.NATIVE_MAX. - The supported <code>data</code> argument types are - <table class='box'><tr><td><code><code class='datatype'>string(8bit)</code></code></td><td>An eight bit string. - </td></tr> - <tr><td><code><code class='object unresolved'>System.Memory</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>Stdio.IOBuffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='object unresolved'>String.Buffer</code></code></td><td>A chunk of memory. The whole memory area is added. - </td></tr> - <tr><td><code><code class='datatype'>array</code></code></td><td>Add all elements in the array individually. Each element may be - any one of the types listed here. - </td></tr> - </table></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_int(<code class='datatype'>int</code> <code class='argument'>i</code>, <code class='datatype'>int(0..)</code> <code class='argument'>width</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a generic integer to the buffer as an (width*8)bit - network byteorder number. - <code>width</code> must be less than Int.NATIVE_MAX. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int16 - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_int16(<code class='datatype'>int(16bit)</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add a 16-bit network byte order value to the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int32 - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_int32(<code class='datatype'>int</code> <code class='argument'>i</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a 32 bit network byte order value to the buffer - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_int8 - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_int8(<code class='datatype'>int(8bit)</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Adds a single byte to the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_ints - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_ints(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add the integers in the specified array, <code>len</code> bytes per int. - Equivalent to calling <code>add_int</code> for each integer, but faster, - and if an error occurs the buffer will contain no new - data. Either all or none of the integers will be added. - Errors can occur if one of the elements in <code>integers</code> is not - actually an integer, if sizeof(integers)*len is bigger than can - be represented in a size_t, or if the buffer cannot grow due to - an out of memory condition. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - add_padding - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> add_padding(<code class='datatype'>int</code> <code class='argument'>nbytes</code>, <code class='datatype'>int(8bit)</code>|<code class='datatype'>void</code> <code class='argument'>byte</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Add <code>nbytes</code> bytes of padding, if <code>byte</code> is not specified the - area will be filled with 0's, otherwise the specified byte will - be repeated. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - cast - </dt> - <dd><code>(<code class='datatype'>string</code>)Stdio.IOBuffer()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Convert the buffer to a string. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This only works for buffers whose length is less than 0x7fffffff. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - clear - </dt> - <dd><code><code class='datatype'>void</code> clear()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Clear the buffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - consume - </dt> - <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> consume(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Discard the first <code>n</code> bytes from the buffer - Returns -1 on error and the amount of space still left otherwise. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - create - </dt> - <dd><code>Stdio.IOBuffer Stdio.IOBuffer(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>len</code>)</code> - <code>Stdio.IOBuffer Stdio.IOBuffer(<code class='datatype'>string(8bit)</code> <code class='argument'>contents</code>)</code> - <code>Stdio.IOBuffer Stdio.IOBuffer(<code class='object unresolved'>System.Memory</code>|<code class='object unresolved'>String.Buffer</code> <code class='argument'>contents</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>If passed an integer or no argument, create a buffer of that - size, or if no argument is given, 226 bytes. - If <code>contents</code> are specified a new buffer with the contents of - the given string/System.Memory or String.Buffer will be created. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>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. - 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. - 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 will be copied. - You can use <code>read_only()</code> to avoid accidents. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - input_from - </dt> - <dd><code><code class='datatype'>int(-1..)</code> input_from(<code class='object unresolved'>Stdio.Stream</code> <code class='argument'>f</code>, <code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read data from <code>f</code> into this buffer. If <code>nbytes</code> is not - specified, read until there is no more data to read (currently). - Returns the amount of data that was read, or <code class='expr'>-1</code> on - read error. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Please note that this funcition will read all data from the - filedescriptor unless it's set to be non-blocking. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - lock - </dt> - <dd><code><code class='datatype'>object</code> lock()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Makes this buffer read only until the returned object is released. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This currently simply returns a 0-length subbuffer. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - match - </dt> - <dd><code><code class='datatype'>mixed</code> match(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from the beginning of the buffer to match the - specifed format, then return the match. - The non-matching data will be left in the buffer. - 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. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>// get the next whitespace separated word from the buffer. - buffer->match("%*[ \t\r\n]%[^ \t\r\n]"); - </code></pre></pre></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - output_to - </dt> - <dd><code><code class='datatype'>int(-1..)</code> output_to(<code class='object unresolved'>Stdio.Stream</code> <code class='argument'>f</code>, <code class='datatype'>int(0..)</code>|<code class='datatype'>void</code> <code class='argument'>nbytes</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Write data from the buffer to the indicated file. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>nbytes</code></dt> - <dd></dd><dd class='body--doc'>If <code>nbytes</code> is not specified the whole buffer will be written - if possible. Otherwise at most <code>nbytes</code> will be written. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>Will return the number of bytes that have been written successfully. - If no bytes have been written successfully and <code class='expr'>f->write()</code> failed - with an error, <code class='expr'>-1</code> will be returned. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - range_error - </dt> - <dd><code><code class='modifier'>protected</code> <code class='object unresolved'>bool</code> range_error(<code class='datatype'>int</code> <code class='argument'>howmuch</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>This function is called when an attempt is made to read out of bounds. - The default implementation simply returns <code class='expr'>0</code> (zero). - Override this function to change the behavior. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>howmuch</code></dt> - <dd></dd><dd class='body--doc'>The argument <code>howmuch</code> indicates how much data is needed: - <table class='box'><tr><td><code><code class='key'>(1..)</code></code></td><td>Need <code>howmuch</code> bytes more - </td></tr> - <tr><td><code><code class='key'>0</code></code></td><td>The amount of data needed is not certain. - This most often happens when <code>sscanf</code> or <code>read_json</code> is used - </td></tr> - <tr><td><code><code class='key'>(..-1)</code></code></td><td>Tried to <code>unread</code> -<code>howmuch</code> bytes. There is usually no way to satisfy - the requested range. - 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. - </td></tr> - </table> - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'><code>true</code> if the operation should be retried, <code>false</code> otherwise. - 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). - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read all data from the buffer. - If there is not enough data available this returns 0. - This is basically equivalent to (string)buffer, but it also - removes the data from the buffer. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>try_read()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read <code>bytes</code> bytes of data from the buffer. - If there is not enough data available this returns 0. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>try_read()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_buffer - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> read_buffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>read</code>, but returns the result as an IOBuffer. - No data is copied unless <code>copy</code> is specified and true, the new buffer - points into the old one. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>As long as the subbuffer exists no data can be added to the main buffer. - 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. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_cstring - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read_cstring()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads a \0 terminated C-string and returns the - string excluding the terminating \0. - If there is not enough data available return UNDEFINED. - Note that pike string can not be longer than 0x7fffffff bytes (~2Gb). - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hbuffer - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> read_hbuffer(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='object unresolved'>bool</code> <code class='argument'>copy</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Same as <code>read_hstring</code>, but returns the result as an IOBuffer. - No data is copied unless <code>copy</code> is specified and true, the new - buffer points into the old one. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>As long as the subbuffer exists no data can be added to the - main buffer. - 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. - If you need to unlink the new buffer after it has been - created, call <code>trim</code> in it. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hint - </dt> - <dd><code><code class='datatype'>int</code> read_hint(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a network byte order unsigned number of size n*8 bits, then - read another network byte order number of the size indicated by - the first size. - Will return -1 if there is not enough buffer space available - unless error mode is set to throw errors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_hstring - </dt> - <dd><code><code class='datatype'>string(8bit)</code> read_hstring(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Identical in functionality to <code>read</code>(<code>read_number</code>(<code>n</code>)) but - faster. - Read a network byte order number of size n*8 bits, then return the - indicated number of bytes as a string. - If there is not enough data available return 0. - Note that pike string can not be longer than 0x7fffffff bytes (~2Gb). - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int - </dt> - <dd><code><code class='datatype'>int</code> read_int(<code class='datatype'>int</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a network byte order unsigned number of size n*8 bits, then - return it. - Will return -1 if there is not enough buffer space available - unless error mode is set to throw errors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int16 - </dt> - <dd><code><code class='datatype'>int(16bit)</code> read_int16()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int24 - </dt> - <dd><code><code class='datatype'>int(24bit)</code> read_int24()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int32 - </dt> - <dd><code><code class='datatype'>int(32bit)</code> read_int32()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_int8 - </dt> - <dd><code><code class='datatype'>int(8bit)</code> read_int8()</code></dd> - </dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_ints - </dt> - <dd><code><code class='datatype'>array</code>(<code class='datatype'>int</code>) read_ints(<code class='datatype'>int</code> <code class='argument'>n</code>, <code class='datatype'>int</code> <code class='argument'>width</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a list of <code>n</code> network byte order unsigned numbers each of - size <code>width</code>*8 bits, then return it. - Will return 0 if there is not enough buffer space available - unless error mode is set to throw errors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_json - </dt> - <dd><code><code class='datatype'>mixed</code> read_json(<code class='datatype'>int</code>|<code class='datatype'>void</code> <code class='argument'>require_whitespace_separator</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a single JSON expression from the buffer and return it. - If <code>require_whitespace_separator</code> is true there must be a whitespace - after each json value (as an example, newline or space). - The JSON is assumed to be utf-8 encoded. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>UNDEFINED if no data is available to read. - The read value otherwise. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Unless whitespaces are required this function only really work correctly - with objects, arrays and strings. - There is really no way to see where one value starts and the other ends - for most other cases - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_only - </dt> - <dd><code><code class='datatype'>void</code> read_only()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Make the buffer permanently read only. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>You can use lock() to do this temporarily. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - read_sint - </dt> - <dd><code><code class='datatype'>int</code> read_sint(<code class='datatype'>int</code> <code class='argument'>size</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Read a network byte order two:s complement signed number of size n*8 bits, then - return it. - Will return UNDEFINED if there is not enough buffer space - available unless error mode is set to throw errors. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - rewind_on_error - Method - rewind_key - </dt> - <dd><code><code class='object unresolved'>RewindKey</code> rewind_on_error()</code> - <code><code class='object unresolved'>RewindKey</code> rewind_key()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>These functions are very similar. The <code>rewind_on_error</code> edition - will 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. - This will happen if you throw an error or otherwise let the - object fall out of scope. - Use <code>destruct(RewindKey)</code> or <code>RewindKey.release</code> to stop the - buffer from being rewound. - The second version (<code>rewind_key</code>) requires you to explicitly - call <code>RewindKey.rewind</code> to do the rewind. - 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) - You can call <code>RewindKey.update</code> in the generated object to - change where it will be rewound to. - The typical use-case of this functionality is when parsing 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. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>void parse_packet( Stdio.IOBuffer b ) - { - Stdio.IOBuffer.RewindKey rewind = b->rewind_on_error(); - b->set_error_mode(1); - - switch( b->read_int8() ) // packet type - { - case DATA: - int channel = b->read_int8(); - Stdio.IOBuffer data = b->read_hbuffer( 4 ); - // we have read the whole packet, so no longer rewind on error. - rewind->release(); - return handle_data_packet( chennel, data ); - } - } - </code></pre></pre></dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Just calling <code>rewind_on_error</code> without assigning the return - value to something will not do anything. You need to keep the - object around while the rewind-to position is still valid. - Keeping the object around forbids the buffer from moving data - inside itself, this means that it can only grow. So do not keep - the rewind key when it is not needed. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - set_error_mode - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> set_error_mode(<code class='datatype'>int</code> <code class='argument'>m</code>)</code> - <code><code class='object unresolved'>IOBuffer</code> set_error_mode(<code class='datatype'>program</code> <code class='argument'>m</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Set the error mode of this buffer to <code>m</code>. - 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. - This is useful when parsing received data, you do not have to - verify that each and every read operation suceeds. - However, the non-error mode is more useful when checking to see - if a packet/segment/whatever has arrived. - The thrown error object will have the constant buffer_error set - to a non-false value. - </dd> - <dt class='head--doc'>Example</dt> - <dd class='example'><pre><pre><code>void read_callback(int i, string new_data) - { - inbuffer->add( new_data ); - - while( IOBuffer packet = inbuffer->read_hbuffer(2) ) - { - packet->set_error_mode(Buffer.THROW_ERROR); - if( mixed e = catch( handle_packet( packet ) ) ) - if( e->buffer_error ) - protocol_error(); // illegal data in packet - else - throw(e); // the other code did something bad - } - } - - void handle_packet( IOBuffer pack ) - { - switch( pack->read_int8() ) - { - ... - case HEADER_FRAME: - int num_headers = pack->read_int32(); - for( int i = 0; i<num_headers; i++ ) - headers[pack->read_hstring(2)] = pack->read_hstring(2); - ... - } - } - </code></pre></pre></dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sprintf - </dt> - <dd><code><code class='object unresolved'>IOBuffer</code> sprintf(<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>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Appends the output from <code>sprintf</code> at the end of the buffer. - This is somewhat faster than add(sprintf(...)) since no - intermediate string is created. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - sscanf - </dt> - <dd><code><code class='datatype'>array</code> sscanf(<code class='datatype'>string(8bit)</code> <code class='argument'>format</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Reads data from the beginning of the buffer to match the - specifed format, then return an array with the matches. - The non-matching data will be left in the buffer. - See <code>array_sscanf</code> for more information. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - trim - </dt> - <dd><code><code class='datatype'>void</code> trim()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Frees unused memory. - Note that calling this function excessively will slow things - down, since the data often has to be copied. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This function could possibly throw an out-of-memory error - if the realloc fails to find a new (smaller) memory area. - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - try_read - </dt> - <dd><code><code class='datatype'>string(8bit)</code> try_read(<code class='datatype'>int</code> <code class='argument'>len</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Attempt to read some data from the buffer. - </dd> - <dt class='head--doc'>Parameter <code class='parameter'>len</code></dt> - <dd></dd><dd class='body--doc'>Read at most <code>len</code> bytes from the buffer. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>If the buffer contains less than <code>len</code> bytes - of data, the entire buffer contents are returned. - Otherwise the first <code>len</code> bytes are returned. - </dd> - <dt class='head--doc'>See also</dt> - <dd class='body--doc'><code>read()</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - unread - </dt> - <dd><code><code class='datatype'>int(0..)</code>|<code class='datatype'>int(-1..-1)</code> unread(<code class='datatype'>int(0..)</code> <code class='argument'>n</code>)</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Rewind the buffer <code>n</code> bytes. - </dd> - <dt class='head--doc'>Returns</dt> - <dd class='body--doc'>This function returns how many more bytes of buffer is - available to rewind, or -1 on error. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Unless you add new data to the buffer using any of the add - functions you can always rewind. - You can call <code>unread(0)</code> to see how much. - </dd></dl> - <dl><dt><h2 class='header'>Class Stdio.IOBuffer.RewindKey</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>The return value of <code>IOBuffer.rewind_on_error()</code> and - <code>IOBuffer.rewind_key()</code> - This object will cause the buffer to unwind to the position it was - at when the object was created either when it is released (when it - falls out of scope, explicit destruct does not count) or when - <code>rewind</code> is called, depending on which function was used to - create it. - </dd></dl> - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - release - </dt> - <dd><code><code class='datatype'>void</code> release()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Do not rewind if the object is released. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>This is equivalent to calling destruct() on the object - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - rewind - </dt> - <dd><code><code class='datatype'>void</code> rewind()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Rewinds the buffer explicitly. - </dd> - <dt class='head--doc'>Note</dt> - <dd class='body--doc'>Destructs this <code>RewindKey</code> - </dd></dl> - - - <hr /> - <dl class='group--doc'> - <dt class='head--type'>Method - update - </dt> - <dd><code><code class='datatype'>void</code> update()</code></dd> - - <dt class='head--doc'>Description</dt> - <dd class='body--doc'>Update the location the buffer will be rewound to to the current - position of the buffer. - </dd></dl> - </dd></dl></dd></dl><dl><dt><h2 class='header'>Class Stdio.NonblockingStream</h2> - </dt><dd><dl class='group--doc'> - <dt class='head--doc'>Description</dt> + <dd class='body--doc'>The Stdio.NonblockingStream API. This class exists purely for typing reasons. Use in types in place of <code>Stdio.File</code> where nonblocking and/or

autodoc.git/ traditional_manual/ chapter_9.html

2014-10-01

2014-10-01 14:34:26 by Martin Nilsson <nilsson@opera.com>