Expand description
Operate on the tail of a data stream that is managed using a buffer of limited size.
A ShiftBuffer enables pointer arithmetics on data that is occasionally ‘shifted’; i.e. the data is being moved to the beginning of the buffer to retain its size while allowing for further data to be read into the buffer. To that end, ShiftBuffer maintains a sliding window which can be extended (the upper end moves up) or shrunk (the lower end moves up). To access the data within the window, the buffer can be indexed using a Pointer.
Typically, this is used in a scenario where one wants to operate on the tail of a continuous data stream while only allocating a fixed buffer. Whenever the buffer is ‘shifted’, it is conceptually moved forward in the data stream.
The following is an illustration of the state before and after a shift. Here, the cursor is a pointer into the window. Technically, a pointer retains its position within the original data stream. We call this position ‘absolute’ and it can be revealed with Pointer::abs.
before:
|<----------- buffer ----------->|
| |<----- window ----->|
^
|
~~ data stream ~~~~~~~~[cursor]~~~~~
after: |
v
|<----------- buffer ----------->|
|<----- window ----->|<- free -->|Following the illustration above, this is the state after the window has been extended:
~~ data stream ~~~~~~~~[cursor]~~~~~~~~~~
|
v
|<----------- buffer ----------->|
|<------- window --------->|< f >|In a typical scenario, one would call ShiftBuffer::make_room whenever more data needs to be read into the buffer. This method either shifts the window or doubles the buffer size, depending on whether the window currently covers the entire buffer or not.