.. currentmodule:: pyb
.. _pyb.RingbufB:

class RingbufB -- ringbuffer over bytes
=======================================

RingbufB is a **non thread-safe** realization of a ring buffer over an array of bytes. It supports standard operations for a *collection*: append, extend, pop etc. An iterator is also supported.

Example usage::

    import pyb

    rbuf = pyb.RingbufB(64)       # create a ring buffer object with max capacity 64 bytes
    rbuf.append('1')           # put a byte '1'
    rbuf.extend('234')         # put 3 bytes '2','3','4'
    rbuf.deque(4)              # returns '1234'

Constructors
------------

.. class:: pyb.RingbufB(maxlen=64)

    Create a new RingbufB object. Optional argument is maximum capacity and defaults to 64. The value must be a power of 2 (4,8,16,....) and cannot exceed 256. If arbitrary value is given, it will be rounded (aka *ceil*) to the nearest power of 2.

Methods
-------

.. method:: RingbufB.append(byte)

    Append a byte *byte* to the ringbuffer.
    Synonym: ``put(byte)``.

    Returns: ``True`` if the byte has been appended, ``False`` if the buffer was already full.

.. method:: RingbufB.extend(bytes)

    Append several *bytes* to the ringbuffer. If the buffer runs out of space in the process, the rest of the data is discarded.

    Returns: ``True`` is all the bytes have been appended, ``False`` if the buffer has run out of space in the process.

.. method:: RingbufB.__str__()

    Return a string describing the ring buffer object.

.. method:: RingbufB.pop()

    Retrieve next byte from the ring buffer.
    Returns: retrieved byte or ``None``

.. method:: RingbufB.deque(max=_all_)

    Retrieve *max* bytes from the ring buffer. Will fetch all bytes is no argument is provided.
    Returns: retrieved bytes or ``None`` if the ring buffer is empty.

.. method:: RingbufB.size()

    Returns the size (i.e the maximum capacity) of the ring buffer.

.. method:: RingbufB.len()

    Returns the number of bytes currently in the buffer.

.. method:: RingbufB.free()

    Returns the number of free slots - i.e. ``free() = size() - len()``.