Class MemoryBuffer

Metaclass for MemBuf items.

class MemoryBuffer \ from BOM

more...

Summary

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.

Inherited methods

__add from BOM Overrides binary addition operand.
__call from BOM Overrides call operator "self()".
__dec from BOM Overrides decrement unary prefix operand.
__decpost from BOM Overrides decrement unary postfix operand.
__div from BOM Overrides binary division operand.
__getIndex from BOM Overrides array access operator []
__inc from BOM Overrides increment unary prefix operand.
__incpost from BOM Overrides increment unary postifx operand.
__mod from BOM Overrides modulo operand.
__mul from BOM Overrides binary multiplication operand.
__pow from BOM Overrides power operand.
__setIndex from BOM Overrides array write operator []
__sub from BOM Overrides binary subtraction operand.
baseClass from BOM Returns the class item from which an object has been instantiated.
bound from BOM Determines if an item is bound or not.
className from BOM Returns the name of the class an instance is instantiated from.
clone from BOM Performs a deep copy of the item.
compare from BOM Performs a lexicographical comparison.
derivedFrom from BOM Checks if this item has a given parent.
describe from BOM Returns the deep contents of an item on a string representation.
isCallable from BOM Determines if an item is callable.
len from BOM Retrieves the length of a collection
metaclass from BOM Returns the metaclass associated with this item.
ptr from BOM Returns a raw memory pointer out of this data (as an integer).
serialize from BOM Serialize the item on a stream for persistent storage.
toString from BOM Coverts the object to string.
typeId from BOM Returns an integer indicating the type of this item.

Detailed description

class MemoryBuffer \ from BOM


Metaclass for MemBuf items.

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.

MemoryBuffer.back( )

Returns:A number representing the last element in this buffer.
Raises:
AccessErrorif this buffer is empty.

clear()

Clears the buffer resetting it to initial status.

MemoryBuffer.clear( )

Returns: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.

compact()

Discards processed data and prepares to a new read.

MemoryBuffer.compact( )

Returns: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

fill()

Fills all the elements in the memory buffer with a given value.

MemoryBuffer.fill( value )

valueThe value to be applied to the memory buffer.
Returns:This memory buffer.

first()

Returns an iterator to the first element of this buffer.

MemoryBuffer.first( )

Returns:An iterator.

flip()

Sets the limit to the current position, and the position to zero.

MemoryBuffer.flip( )

Returns: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.

front()

Returns the first element in this memory buffer.

MemoryBuffer.front( )

Returns:A number representing the first element in this buffer.
Raises:
AccessErrorif this buffer is empty.

get()

Gets a value in the memory buffer.

MemoryBuffer.get( )

Returns:the retreived value.
Raises:
AccessErrorif the buffer is full (limit() == position())

Gets the vaulue at current position and advances it.

last()

Returns an iterator to the last element of this buffer.

MemoryBuffer.last( )

Returns:An iterator.

limit()

Gets or sets current filled data size.

MemoryBuffer.limit( [pos] )

posThe value to be applied to the memory buffer.
Returns: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.

mark()

Places the mark at current position.

MemoryBuffer.mark( )

Returns:The buffer itself

This position sets the mark at current position; calling MemoryBuffer.reset later on will move the position back to this point.

position()

Sets or get the current position in the buffer.

MemoryBuffer.position( [pos] )

posThe new position
Returns:The buffer itself or the requested position.
Raises:
AccessError if the pos parameter is > 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.

As the position can never be greater that the limit, an error is raised in case a value too high has been set.

ptr()

Returns the pointer to the raw memory stored in this memory buffer.

MemoryBuffer.ptr( )

Returns:A memory pointer.

This function returns a pointer (as a Falcon integer) to the memory area managed by this memory buffer.

put()

Puts a value in the memory buffer.

MemoryBuffer.put( )

Returns:The buffer itself.
Raises:
AccessErrorif the buffer is full (limit() == position())

Sets the vaulue at current position and advances it.

remaining()

Determines how many items can be read.

MemoryBuffer.remaining( )

Returns:Count of remanining items.

Returns the count of times get and put can be called on this memory buffer before raising an error.

reset()

Returns the position to the last mark.

MemoryBuffer.reset( )

Returns:The buffer itself
Raises:
AccessErrorif the mark is not defined.

Returns the position at the value previously marked with MemoryBuffer.mark. The mark itself is not discarded.

rewind()

Rewinds the buffer and discards the mark.

MemoryBuffer.rewind( )

Returns:The buffer itself

Returns the position at 0 and discards the mark. Limit is unchanged.

wordSize()

Returns the number of bytes used to store each entry of this Memory Buffer.

MemoryBuffer.wordSize( )

Returns:Size of each memory buffer entity in bytes.

Made with faldoc 2.2.0