Metaclass for MemBuf items.
Class MemoryBuffer from \
BOM( )
The Memory Buffers have a set of internal pointers and sequence methods useful to parse binary streams read in variable size chunks.
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 length, returned by the BOM len method or len function.
After having read some contents from a stream, the buffer limit will be moved to the amount of incoming data (which may be also the same as the length if the buffer is completely filled).
The application may get one item at a time via the MemoryBuffer.get() method, or process blocks of data transferring them to other membufs or arrays via ranged operators.
Each get() moves a position indicator forward up to the limit. At the same time, it is possible to put data in the buffer, moving forward the position pointer up to the limit.
The buffer has a marker, that can be set at current position, and that can be later used to to return to a previously marked position.
The following invariants always hold:
0 <= [mark] <= position <= limit <= length
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.
The following operations are meant to simplify read and partial parsing of binary data:
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:
mb.clear()
mb.position(3)
// equivalent:
mb.clear().position(3)
| Methods | |
| back | Returns the last element in this memory buffer. |
| clear | Clears the buffer resetting it to initial status. |
| compact | Discards processed data and prepares to a new read. |
| fill | Fills all the elements in the memory buffer with a given value. |
| first | Returns an iterator to the first element of this buffer. |
| flip | Sets the limit to the current position, and the position to zero. |
| front | Returns the first element in this memory buffer. |
| get | Gets a value in the memory buffer. |
| last | Returns an iterator to the last element of this buffer. |
| limit | Gets or sets current filled data size. |
| mark | Places the mark at current position. |
| position | Sets or get the current position in the buffer. |
| ptr | Returns the pointer to the raw memory stored in this memory buffer. |
| put | Puts a value in the memory buffer. |
| remaining | Determines how many items can be read. |
| reset | Returns the position to the last mark. |
| rewind | Rewinds the buffer and discards the mark. |
| wordSize | Returns the number of bytes used to store each entry of this Memory Buffer. |
| Methods inherited from class BOM | |
| __add | Overrides binary addition operand. |
| __call | Overrides call operator "self()". |
| __dec | Overrides decrement unary prefix operand. |
| __decpost | Overrides decrement unary postfix operand. |
| __div | Overrides binary division operand. |
| __getIndex | Overrides array access operator [] |
| __inc | Overrides increment unary prefix operand. |
| __incpost | Overrides increment unary postifx operand. |
| __mod | Overrides modulo operand. |
| __mul | Overrides binary multiplication operand. |
| __pow | Overrides power operand. |
| __setIndex | Overrides array write operator [] |
| __sub | Overrides binary subtraction operand. |
| baseClass | Returns the class item from which an object has been instantiated. |
| bound | Determines if an item is bound or not. |
| className | Returns the name of the class an instance is instantiated from. |
| clone | Performs a deep copy of the item. |
| compare | Performs a lexicographical comparison. |
| derivedFrom | Checks if this item has a given parent. |
| describe | Returns the deep contents of an item on a string representation. |
| isCallable | Determines if an item is callable. |
| len | Retrieves the length of a collection |
| metaclass | Returns the metaclass associated with this item. |
| ptr | Returns a raw memory pointer out of this data (as an integer). |
| serialize | Serialize the item on a stream for persistent storage. |
| toString | Coverts the object to string. |
| typeId | Returns an integer indicating the type of this item. |
Returns the last element in this memory buffer.
MemoryBuffer.back()
| Return | A number representing the last element in this buffer. | ||
| Raise |
|
Clears the buffer resetting it to initial status.
MemoryBuffer.clear()
| Return | The buffer itself. |
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.
Discards processed data and prepares to a new read.
MemoryBuffer.compact()
| Return | The buffer itself |
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.
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.
Note: Just, remember to move the position back to the first item that was still to be decoded before compact
Fills all the elements in the memory buffer with a given value.
MemoryBuffer.fill( value )
| value | The value to be applied to the memory buffer. |
| Return | This memory buffer. |
Returns an iterator to the first element of this buffer.
MemoryBuffer.first()
| Return | An iterator. |
Sets the limit to the current position, and the position to zero.
MemoryBuffer.flip()
| Return | The buffer itself |
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.
Returns the first element in this memory buffer.
MemoryBuffer.front()
| Return | A number representing the first element in this buffer. | ||
| Raise |
|
Gets a value in the memory buffer.
MemoryBuffer.get()
| Return | the retreived value. | ||
| Raise |
|
Gets the vaulue at current position and advances it.
Returns an iterator to the last element of this buffer.
MemoryBuffer.last()
| Return | An iterator. |
Gets or sets current filled data size.
MemoryBuffer.limit( [pos] )
| pos | The value to be applied to the memory buffer. |
| Return | current limit. |
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.
Places the mark at current position.
MemoryBuffer.mark()
| Return | The buffer itself |
This position sets the mark at current position; calling MemoryBuffer.reset later on will move the position back to this point.
Sets or get the current position in the buffer.
MemoryBuffer.position( [pos] )
| pos | The new position | ||
| Return | The buffer itself or the requested position. | ||
| Raise |
|
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.
As the position can never be greater that the limit, an error is raised in case a value too high has been set.
Returns the pointer to the raw memory stored in this memory buffer.
MemoryBuffer.ptr()
| Return | A memory pointer. |
This function returns a pointer (as a Falcon integer) to the memory area managed by this memory buffer.
Puts a value in the memory buffer.
MemoryBuffer.put()
| Return | The buffer itself. | ||
| Raise |
|
Sets the vaulue at current position and advances it.
Determines how many items can be read.
MemoryBuffer.remaining()
| Return | Count of remanining items. |
Returns the count of times get and put can be called on this memory buffer before raising an error.
Returns the position to the last mark.
MemoryBuffer.reset()
| Return | The buffer itself | ||
| Raise |
|
Returns the position at the value previously marked with MemoryBuffer.mark. The mark itself is not discarded.
Rewinds the buffer and discards the mark.
MemoryBuffer.rewind()
| Return | The buffer itself |
Returns the position at 0 and discards the mark. Limit is unchanged.
Returns the number of bytes used to store each entry of this Memory Buffer.
MemoryBuffer.wordSize()
| Return | Size of each memory buffer entity in bytes. |