<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class MemoryBuffer - Class MemoryBuffer</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./funset.html"><span>Function sets</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./globals.html"><span>Globals</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class MemoryBuffer</h1>
<p class="faldoc_brief">Metaclass for MemBuf items. </p>
<p class="faldoc_funcdecl">
<b>class</b> MemoryBuffer \
<b>from</b> <a href="./class_BOM.html">BOM</a>
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#back">back()</a></td><td>Returns the last element in this memory buffer. </td></tr>
<tr><td><a href="#clear">clear()</a></td><td>Clears the buffer resetting it to initial status. </td></tr>
<tr><td><a href="#compact">compact()</a></td><td>Discards processed data and prepares to a new read. </td></tr>
<tr><td><a href="#fill">fill()</a></td><td>Fills all the elements in the memory buffer with a given value. </td></tr>
<tr><td><a href="#first">first()</a></td><td>Returns an iterator to the first element of this buffer. </td></tr>
<tr><td><a href="#flip">flip()</a></td><td>Sets the limit to the current position, and the position to zero. </td></tr>
<tr><td><a href="#front">front()</a></td><td>Returns the first element in this memory buffer. </td></tr>
<tr><td><a href="#get">get()</a></td><td>Gets a value in the memory buffer. </td></tr>
<tr><td><a href="#last">last()</a></td><td>Returns an iterator to the last element of this buffer. </td></tr>
<tr><td><a href="#limit">limit()</a></td><td>Gets or sets current filled data size. </td></tr>
<tr><td><a href="#mark">mark()</a></td><td>Places the mark at current position. </td></tr>
<tr><td><a href="#position">position()</a></td><td>Sets or get the current position in the buffer. </td></tr>
<tr><td><a href="#ptr">ptr()</a></td><td>Returns the pointer to the raw memory stored in this memory buffer. </td></tr>
<tr><td><a href="#put">put()</a></td><td>Puts a value in the memory buffer. </td></tr>
<tr><td><a href="#remaining">remaining()</a></td><td>Determines how many items can be read. </td></tr>
<tr><td><a href="#reset">reset()</a></td><td>Returns the position to the last mark. </td></tr>
<tr><td><a href="#rewind">rewind()</a></td><td>Rewinds the buffer and discards the mark. </td></tr>
<tr><td><a href="#wordSize">wordSize()</a></td><td>Returns the number of bytes used to store each entry of this Memory Buffer. </td></tr>
</table>
<h3 class="faldoc_title">Inherited methods</h3>
<table class="faldoc_list">
<tr><td><a href="./class_BOM.html#__add">__add</a> from BOM </td><td>Overrides binary addition operand. </td></tr>
<tr><td><a href="./class_BOM.html#__call">__call</a> from BOM </td><td>Overrides call operator "self()". </td></tr>
<tr><td><a href="./class_BOM.html#__dec">__dec</a> from BOM </td><td>Overrides decrement unary prefix operand. </td></tr>
<tr><td><a href="./class_BOM.html#__decpost">__decpost</a> from BOM </td><td>Overrides decrement unary postfix operand. </td></tr>
<tr><td><a href="./class_BOM.html#__div">__div</a> from BOM </td><td>Overrides binary division operand. </td></tr>
<tr><td><a href="./class_BOM.html#__getIndex">__getIndex</a> from BOM </td><td>Overrides array access operator [] </td></tr>
<tr><td><a href="./class_BOM.html#__inc">__inc</a> from BOM </td><td>Overrides increment unary prefix operand. </td></tr>
<tr><td><a href="./class_BOM.html#__incpost">__incpost</a> from BOM </td><td>Overrides increment unary postifx operand. </td></tr>
<tr><td><a href="./class_BOM.html#__mod">__mod</a> from BOM </td><td>Overrides modulo operand. </td></tr>
<tr><td><a href="./class_BOM.html#__mul">__mul</a> from BOM </td><td>Overrides binary multiplication operand. </td></tr>
<tr><td><a href="./class_BOM.html#__pow">__pow</a> from BOM </td><td>Overrides power operand. </td></tr>
<tr><td><a href="./class_BOM.html#__setIndex">__setIndex</a> from BOM </td><td>Overrides array write operator [] </td></tr>
<tr><td><a href="./class_BOM.html#__sub">__sub</a> from BOM </td><td>Overrides binary subtraction operand. </td></tr>
<tr><td><a href="./class_BOM.html#baseClass">baseClass</a> from BOM </td><td>Returns the class item from which an object has been instantiated. </td></tr>
<tr><td><a href="./class_BOM.html#bound">bound</a> from BOM </td><td>Determines if an item is bound or not. </td></tr>
<tr><td><a href="./class_BOM.html#className">className</a> from BOM </td><td>Returns the name of the class an instance is instantiated from. </td></tr>
<tr><td><a href="./class_BOM.html#clone">clone</a> from BOM </td><td>Performs a deep copy of the item. </td></tr>
<tr><td><a href="./class_BOM.html#compare">compare</a> from BOM </td><td>Performs a lexicographical comparison. </td></tr>
<tr><td><a href="./class_BOM.html#derivedFrom">derivedFrom</a> from BOM </td><td>Checks if this item has a given parent. </td></tr>
<tr><td><a href="./class_BOM.html#describe">describe</a> from BOM </td><td>Returns the deep contents of an item on a string representation. </td></tr>
<tr><td><a href="./class_BOM.html#isCallable">isCallable</a> from BOM </td><td>Determines if an item is callable. </td></tr>
<tr><td><a href="./class_BOM.html#len">len</a> from BOM </td><td>Retrieves the length of a collection </td></tr>
<tr><td><a href="./class_BOM.html#metaclass">metaclass</a> from BOM </td><td>Returns the metaclass associated with this item. </td></tr>
<tr><td><a href="./class_BOM.html#ptr">ptr</a> from BOM </td><td>Returns a raw memory pointer out of this data (as an integer). </td></tr>
<tr><td><a href="./class_BOM.html#serialize">serialize</a> from BOM </td><td>Serialize the item on a stream for persistent storage. </td></tr>
<tr><td><a href="./class_BOM.html#toString">toString</a> from BOM </td><td>Coverts the object to string. </td></tr>
<tr><td><a href="./class_BOM.html#typeId">typeId</a> from BOM </td><td>Returns an integer indicating the type of this item. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> MemoryBuffer \
<b>from</b> <a href="./class_BOM.html">BOM</a>
</p>
<table class="faldoc_function">
</table>
<br/>
<p class="item_brief">Metaclass for MemBuf items. </p>
<p class="faldoc_text">The Memory Buffers have a set of internal pointers and sequence methods useful to parse binary streams read in variable size chunks. </p>
<p class="faldoc_text"> Initially, allocate a memory buffer wide enough to store enough data. The maximum possible amount of data units (generally bytes) that can be stored in a memory buffer is its <b>length</b>, returned by the BOM <b>len</b> method or <a href="./functions.html#len">len</a> function. </p>
<p class="faldoc_text"> After having read some contents from a stream, the buffer <b>limit</b> will be moved to the amount of incoming data (which may be also the same as the <b>length</b> if the buffer is completely filled). </p>
<p class="faldoc_text"> The application may get one item at a time via the <a href="./class_MemoryBuffer.html#get">MemoryBuffer.get</a>() method, or process blocks of data transferring them to other membufs or arrays via ranged operators. </p>
<p class="faldoc_text"> Each get() moves a <b>position</b> indicator forward up to the <b>limit</b>. At the same time, it is possible to put data in the buffer, moving forward the <b>position</b> pointer up to the limit. </p>
<p class="faldoc_text"> The buffer has a <b>marker</b>, that can be set at current <b>position</b>, and that can be later used to to return to a previously marked position. </p>
<p class="faldoc_text">The following invariants always hold: </p>
<pre class="faldoc_code">
0 <= [mark] <= position <= limit <= length
</pre>
<p class="faldoc_text">The limit is usually set to the buffer length, unless it is explicitly set to a lower position via explicit calls, or the last read didn't bear enough data to fill the buffer. </p>
<p class="faldoc_text">The following operations are meant to simplify read and partial parsing of binary data: </p>
<ul>
<li><a href="./class_MemoryBuffer.html#reset">MemoryBuffer.reset</a>: return the position at last mark (raises if a mark is not defined). </li><li><a href="./class_MemoryBuffer.html#rewind">MemoryBuffer.rewind</a>: discards the mark and returns the position to 0. </li><li><a href="./class_MemoryBuffer.html#clear">MemoryBuffer.clear</a>: rewinds and set limit to the buffer length. </li><li><a href="./class_MemoryBuffer.html#flip">MemoryBuffer.flip</a>: sets the limit to the current position, the position to zero and discards the mark. </li><li><a href="./class_MemoryBuffer.html#compact">MemoryBuffer.compact</a>: removes already parsed data and prepares for an incremental read. </li>
</ul>
<p class="faldoc_text">All the members in this group not explicitly returning data or sizes return the MemPool itself, so that it is possible to concatenate calls like this: </p>
<pre class="faldoc_code">
mb.clear()
mb.position(3)
// equivalent:
mb.clear().position(3)
</pre>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="back">back()</a></h3>
<p class="item_brief">Returns the last element in this memory buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.back( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A number representing the last element in this buffer. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if this buffer is empty. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="clear">clear()</a></h3>
<p class="item_brief">Clears the buffer resetting it to initial status. </p>
<p class="faldoc_funcdecl">MemoryBuffer.clear( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Removes the mark, sets the position to zero and the limit to the length. This makes the buffer ready for a new set of operations. </p>
</p>
<h3 class="faldoc_funcname"><a name="compact">compact()</a></h3>
<p class="item_brief">Discards processed data and prepares to a new read. </p>
<p class="faldoc_funcdecl">MemoryBuffer.compact( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This operation moves all the bytes between the position (included) and the limit (escluded) to the beginning of the buffer. Then, the position is moved to the previous value of the limit, and the limit is reset to the length of the buffer. </p>
<p class="faldoc_text">As read is performed by filling the data between the current position and the limit, this operation allows to trying get more data when a previously imcomplete input was taken. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> Just, remember to move the position back to the first item that was still to be decoded before compact </p>
</p>
<h3 class="faldoc_funcname"><a name="fill">fill()</a></h3>
<p class="item_brief">Fills all the elements in the memory buffer with a given value. </p>
<p class="faldoc_funcdecl">MemoryBuffer.fill( value )</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">value</td><td class="faldoc_paramdesc">The value to be applied to the memory buffer. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">This memory buffer. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="first">first()</a></h3>
<p class="item_brief">Returns an iterator to the first element of this buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.first( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="flip">flip()</a></h3>
<p class="item_brief">Sets the limit to the current position, and the position to zero. </p>
<p class="faldoc_funcdecl">MemoryBuffer.flip( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This is useful to write some parsed or created contents back on a stream. Once filled the buffer with data, the position is on the last element; then, using flip and writing the buffer, the prepared data is sent to the output. </p>
</p>
<h3 class="faldoc_funcname"><a name="front">front()</a></h3>
<p class="item_brief">Returns the first element in this memory buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.front( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A number representing the first element in this buffer. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if this buffer is empty. </td></tr>
</table>
</td></tr>
</table>
<h3 class="faldoc_funcname"><a name="get">get()</a></h3>
<p class="item_brief">Gets a value in the memory buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.get( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">the retreived value. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the buffer is full (limit() == position()) </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Gets the vaulue at current position and advances it. </p>
</p>
<h3 class="faldoc_funcname"><a name="last">last()</a></h3>
<p class="item_brief">Returns an iterator to the last element of this buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.last( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">An iterator. </td></tr>
</table>
<h3 class="faldoc_funcname"><a name="limit">limit()</a></h3>
<p class="item_brief">Gets or sets current filled data size. </p>
<p class="faldoc_funcdecl">MemoryBuffer.limit( [pos] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">pos</td><td class="faldoc_optparamdesc">The value to be applied to the memory buffer. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">current limit. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method can be used to get the current postition in the memory buffer, or to set a new position. In the first case, the current value of the position is returned, in the second case the current buffer is returned. </p>
</p>
<h3 class="faldoc_funcname"><a name="mark">mark()</a></h3>
<p class="item_brief">Places the mark at current position. </p>
<p class="faldoc_funcdecl">MemoryBuffer.mark( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> This position sets the mark at current position; calling <a href="./class_MemoryBuffer.html#reset">MemoryBuffer.reset</a> later on will move the position back to this point. </p>
</p>
<h3 class="faldoc_funcname"><a name="position">position()</a></h3>
<p class="item_brief">Sets or get the current position in the buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.position( [pos] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">pos</td><td class="faldoc_optparamdesc">The new position </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself or the requested position. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc"> if the <b>pos</b> parameter is > limit. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This method can be used to get the current postition in the memory buffer, or to set a new position. In the first case, the current value of the position is returned, in the second case the current buffer is returned. </p>
<p class="faldoc_text">As the position can never be greater that the limit, an error is raised in case a value too high has been set. </p>
</p>
<h3 class="faldoc_funcname"><a name="ptr">ptr()</a></h3>
<p class="item_brief">Returns the pointer to the raw memory stored in this memory buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.ptr( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">A memory pointer. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">This function returns a pointer (as a Falcon integer) to the memory area managed by this memory buffer. </p>
</p>
<h3 class="faldoc_funcname"><a name="put">put()</a></h3>
<p class="item_brief">Puts a value in the memory buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.put( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the buffer is full (limit() == position()) </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Sets the vaulue at current position and advances it. </p>
</p>
<h3 class="faldoc_funcname"><a name="remaining">remaining()</a></h3>
<p class="item_brief">Determines how many items can be read. </p>
<p class="faldoc_funcdecl">MemoryBuffer.remaining( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Count of remanining items. </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the count of times get and put can be called on this memory buffer before raising an error. </p>
</p>
<h3 class="faldoc_funcname"><a name="reset">reset()</a></h3>
<p class="item_brief">Returns the position to the last mark. </p>
<p class="faldoc_funcdecl">MemoryBuffer.reset( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_AccessError.html">AccessError</a></td><td class="faldoc_raisedesc">if the mark is not defined. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Returns the position at the value previously marked with <a href="./class_MemoryBuffer.html#mark">MemoryBuffer.mark</a>. The mark itself is not discarded. </p>
</p>
<h3 class="faldoc_funcname"><a name="rewind">rewind()</a></h3>
<p class="item_brief">Rewinds the buffer and discards the mark. </p>
<p class="faldoc_funcdecl">MemoryBuffer.rewind( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The buffer itself </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Returns the position at 0 and discards the mark. Limit is unchanged. </p>
</p>
<h3 class="faldoc_funcname"><a name="wordSize">wordSize()</a></h3>
<p class="item_brief">Returns the number of bytes used to store each entry of this Memory Buffer. </p>
<p class="faldoc_funcdecl">MemoryBuffer.wordSize( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">Size of each memory buffer entity in bytes. </td></tr>
</table>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./funset.html">Function sets</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./globals.html">Globals</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
