randolf.ca
1.00
Randolf Richardson's C++ classes
|
Ring buffer implementation for 8-bit bytes that's resizeable and threadsafe, and the methods are designed to be efficient in various ways, including by supporting the transfer of multiple bytes in variable quantities. More...
#include <rring>
Public Member Functions | |
rring () noexcept | |
Instantiate an empty ring buffer (which can be re-sized or replaced later). | |
rring (const size_t buffer_size) | |
Instantiate an empty ring buffer (which can be re-sized later). | |
~rring () noexcept | |
Free internal memory resources, after clearing buffer's memory (if the policy indicates that it needs to be cleared). | |
rring * | append (const char *data, int len=-1) |
Add any number of characters that fit within the unused portion of the internal ring buffer. | |
rring * | append (const char data) |
Add one character to the unused portion of the internal ring buffer. | |
rring * | append (const std::vector< char > data, int len=-1) |
Add any number of characters that fit within the unused portion of the internal ring buffer. | |
rring * | append (const std::vector< unsigned char > data, int len=-1) |
Add any number of characters that fit within the unused portion of the internal ring buffer. | |
char | at (int index) |
Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method. | |
char * | c_str (char *data=nullptr) noexcept |
Return the contents of the ring buffer as an ASCIIZ string. | |
char * | data () noexcept |
Returns a pointer to the underlying ring buffer's array. The beginning of the array is not the same as where the data actually begins (and ends) within the buffer. | |
rring_blocks * | data_blocks (rring_blocks *rrb=nullptr) noexcept |
Returns the lengths and addresses of available memory. There may be only one block of memory, or two, depending on whether the available memory straddles the boundary of the ring buffer. | |
rring * | data_blocks_adjust (size_t head, size_t tail=0) |
Arbitrarily change the head and tail positions in the ring buffer. This is intended for use in conjunction with appending data directly to the ring buffer after the data_blocks method. | |
size_t | discard (int len=-1) noexcept |
Discard data from the ring buffer. | |
bool | empty () noexcept |
Indicates whether the ring buffer is empty. | |
std::string | get_ascii_map (int len=65, const std::string u="|", const std::string a=".") noexcept |
Obtains a one-line ASCII depiction of a map of the ring buffer's memory usage, wherein the utilized and available portions are represented by the | (pipe) and '.' (period) characters, respectively (these characters are configurable and can include multiple characters, which is particularly useful for text-mode console output in a Linux shell in which ANSI codes may be used to present these characters in different colours). | |
size_t | get_available () noexcept |
Calculate the number of available entries in the ring buffer. | |
size_t | get_head () noexcept |
Obtains the position of the head in the ring buffer. | |
size_t | get_size () noexcept |
Obtains the total size of the ring buffer, including both its utilized and available portions. | |
size_t | get_tail () noexcept |
Obtains the position of the tail in the ring buffer. | |
size_t | get_utilized () noexcept |
Calculate the number of utilized entries in the ring buffer. | |
bool | get_wipe_policy () noexcept |
Indicate whether internal buffer's memory will be cleared by the destructor before de-allocating it (default is true upon instantiation). | |
operator char * () noexcept | |
Convert the entire contents of this ring buffer to an ASCIIZ string in the form of a char* array. | |
operator std::string () noexcept | |
Convert the entire contents of this ring buffer to an std::string object. | |
operator std::vector< char > () noexcept | |
Convert the entire contents of this ring buffer to an std::vector<char> object. | |
char | operator[] (int index) |
Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method. | |
char | peek () |
Duplicate a single character from the utilized portion of the internal ring buffer, and return it as an char primitive. | |
char * | peek_array (size_t len, char *data=nullptr) |
Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return them as a char* array. | |
std::string | peek_string (int len=-1) |
Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object. | |
std::vector< char > | peek_vector (int len=-1) |
Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object. | |
char | remove () |
Remove one character from the utilized portion of the internal ring buffer, and return it . | |
char * | remove_array (size_t len, char *data=nullptr) |
Remove the specified number of characters from the utilized portion of the internal ring buffer, and return them as a char* array. | |
std::string | remove_string (int len=-1) |
Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object. | |
std::vector< char > | remove_vector (int len=-1) |
Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string object. | |
rring * | set_head (int offset, bool type=true) |
Alter the position of the internal head position, without changing any of the the pre-existing data in the underlying ring buffer. | |
rring * | set_size (const size_t len) |
Configure the total size of the ring buffer. The new size cannot be smaller than the amount of data that's already present in the ring buffer (see the get_utilized method to find out how much data is present). | |
rring * | set_tail (int offset, bool type=true) |
Alter the position of the internal tail position, without changing any of the the pre-existing data in the underlying ring buffer. | |
rring * | set_wipe_policy (const bool policy_flag) noexcept |
Specify whether the internal buffer's memory will be cleared by the destructor before de-allocating it (default is true upon instantiation). | |
Friends | |
std::ostream & | operator<< (std::ostream &o, rring &c) noexcept |
Support convenient streaming usage with std::cout, std::cerr, and friends. | |
Ring buffer implementation for 8-bit bytes that's resizeable and threadsafe, and the methods are designed to be efficient in various ways, including by supporting the transfer of multiple bytes in variable quantities.
Data is stored internally as a char*
array, but a few methods are provided to also support easy interoperability with std::vector
objects since there are many scenarios where this can be helpful (and from the perspective of optimization, this eliminates the cumbersome need to utilize conversions between std::string
and std::vector
objects since, internally, we use direct access to/from std::vector
objects).
This class handles all of these details gracefully, and provides a thorough variety of clearly-documented methods that ensure consistency whilst handling the complexity of EoL sequences that may be 1 or 2 characters long and also differentiating between blank and NULL lines, all without causing significant increases in complexity in code.
An ASCIIZ string is a C-string (char* array) that includes a terminating null (0) character at the end.
|
inlinenoexcept |
Instantiate an empty ring buffer (which can be re-sized or replaced later).
|
inline |
Instantiate an empty ring buffer (which can be re-sized later).
std::bad_alloc | When malloc() fails to allocate memory |
buffer_size | Size of buffer |
|
inlinenoexcept |
Free internal memory resources, after clearing buffer's memory (if the policy indicates that it needs to be cleared).
|
inline |
Add one character to the unused portion of the internal ring buffer.
std::overflow_error | If the amount of data exceeds the available free space in the ring buffer |
data | Data to add |
|
inline |
Add any number of characters that fit within the unused portion of the internal ring buffer.
std::length_error | If data length is -2 or below |
std::overflow_error | If the amount of data exceeds the available free space in the ring buffer |
data | Data to add |
len | Length of data (-1 = treat data as an ASCIIZ string) |
|
inline |
Add any number of characters that fit within the unused portion of the internal ring buffer.
std::length_error | If data length is -2 or below |
std::overflow_error | If the amount of data exceeds the available free space in the ring buffer |
data | Data to add |
len | Length of data (-1 = treat data as an ASCIIZ string) |
|
inline |
Add any number of characters that fit within the unused portion of the internal ring buffer.
std::length_error | If data length is -2 or below |
std::overflow_error | If the amount of data exceeds the available free space in the ring buffer |
data | Data to add |
len | Length of data (-1 = treat data as an ASCIIZ string) |
|
inline |
Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method.
The first element is at index 0.
std::out_of_range | if the index is out-of-range |
index | Index of character to access (0 = first element; negative index values are calculated in reverse, starting with -1 as the final position) |
|
inlinenoexcept |
Return the contents of the ring buffer as an ASCIIZ string.
free()
'd after it's no longer needed.std::bad_alloc | When malloc() fails to allocate memory |
data | Where to store the ASCIIZ string (including terminating zero, so it is imperative that utilized() + 1 bytes be pre-allocated)nullptr = allocate the needed memory using malloc() |
|
inlinenoexceptADVANCED |
Returns a pointer to the underlying ring buffer's array. The beginning of the array is not the same as where the data actually begins (and ends) within the buffer.
|
inlinenoexceptADVANCED |
Returns the lengths and addresses of available memory. There may be only one block of memory, or two, depending on whether the available memory straddles the boundary of the ring buffer.
This is the nearest equivalent of the data() methods provided in classes such as std::string
and std::vector
, but with the nuance of supporting the underpinnings of this ring buffer wherein the utilized portions may be stored at both the end and beginning of the buffer memory.
head
will also need to be updated accordingly, for which the data_blocks_adjust method is provided. std::bad_alloc | When malloc() fails to allocate memory |
rrb | Pointer to rring_blocks structure (that's already been allocated)nullptr (default) = allocate memory for this structure with malloc (which will need to be free 'd when it's no longer needed) |
|
inlineADVANCED |
Arbitrarily change the head and tail positions in the ring buffer. This is intended for use in conjunction with appending data directly to the ring buffer after the data_blocks method.
std::overflow_error | If either adjustment would result in causing an overflow |
head | New internal head position |
tail | New internal tail position |
|
inlinenoexcept |
Discard data from the ring buffer.
len | Number of bytes to discard -1 = all utilized data that remains will be discarded (default) |
|
inlinenoexcept |
Indicates whether the ring buffer is empty.
|
inlinenoexcept |
Obtains a one-line ASCII depiction of a map of the ring buffer's memory usage, wherein the utilized and available portions are represented by the |
(pipe) and '.' (period) characters, respectively (these characters are configurable and can include multiple characters, which is particularly useful for text-mode console output in a Linux shell in which ANSI codes may be used to present these characters in different colours).
std::length_error | If length is -2 or below |
len | Desired size of ASCII map -1 = Use size of ring buffer |
u | Character(s) representing utilized entries |
a | Character(s) representing available entries |
|
inlinenoexcept |
Calculate the number of available entries in the ring buffer.
|
inlinenoexceptADVANCED |
Obtains the position of the head in the ring buffer.
|
inlinenoexceptADVANCED |
Obtains the total size of the ring buffer, including both its utilized and available portions.
|
inlinenoexceptADVANCED |
Obtains the position of the tail in the ring buffer.
|
inlinenoexcept |
Calculate the number of utilized entries in the ring buffer.
|
inlinenoexceptADVANCED |
Indicate whether internal buffer's memory will be cleared by the destructor before de-allocating it (default is true
upon instantiation).
malloc()
).
|
inline |
Duplicate a single character from the utilized portion of the internal ring buffer, and return it as an char
primitive.
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
|
inline |
Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return them as a char*
array.
free()
'd after it's no longer needed. std::bad_alloc | When malloc() fails to allocate memory |
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
len | Amount of data to duplicate |
data | Where to store the datanullptr = allocate the needed memory using malloc() |
|
inline |
Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string
object.
std::length_error | If data length is -2 or below |
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
len | Amount of data to duplicate -1 = all data |
|
inline |
Duplicate the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string
object.
std::length_error | If data length is -2 or below |
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
len | Amount of data to duplicate -1 = all data |
|
inline |
Remove one character from the utilized portion of the internal ring buffer, and return it .
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
|
inline |
Remove the specified number of characters from the utilized portion of the internal ring buffer, and return them as a char*
array.
free()
'd after it's no longer needed. std::bad_alloc | When malloc() fails to allocate memory |
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
len | Amount of data to remove |
data | Where to store the datanullptr = allocate the needed memory using malloc() |
|
inline |
Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string
object.
std::length_error | If data length is -2 or below |
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
len | Amount of data to remove -1 = all data |
|
inline |
Remove the specified number of characters from the utilized portion of the internal ring buffer, and return it as an std::string
object.
std::length_error | If data length is -2 or below |
std::overflow_error | If the amount of data exceeds the amount of data in the ring buffer |
len | Amount of data to remove -1 = all data |
|
inlineADVANCED |
Alter the position of the internal head position, without changing any of the the pre-existing data in the underlying ring buffer.
std::overflow_error | If the new position falls beyond the internal tail position (or, in other words, it exceeds the available free space in the ring buffer) |
offset | Position adjustment (may be positive or negative) |
type | Type of adjustment TRUE = absolute (default) FALSE = relative |
|
inline |
Configure the total size of the ring buffer. The new size cannot be smaller than the amount of data that's already present in the ring buffer (see the get_utilized method to find out how much data is present).
std::overflow_error | If the new size exceeds the amount of data that's already present in the ring buffer |
len | New size of ring buffer |
|
inlineADVANCED |
Alter the position of the internal tail position, without changing any of the the pre-existing data in the underlying ring buffer.
std::overflow_error | If the new position falls beyond the internal head position (or, in other words, it exceeds the available free space in the ring buffer) |
offset | Position adjustment (may be positive or negative) |
type | Type of adjustment TRUE = absolute (default) FALSE = relative |
|
inlinenoexceptADVANCED |
Specify whether the internal buffer's memory will be cleared by the destructor before de-allocating it (default is true
upon instantiation).
malloc()
). policy_flag | TRUE = clear buffer memory in destructor FALSE = don't clear buffer memory in destructor |
|
inlinenoexcept |
Convert the entire contents of this ring buffer to an ASCIIZ string in the form of a char*
array.
free()
'd after it's no longer needed.std::bad_alloc | When malloc() fails to allocate memory |
char*
array.
|
inlinenoexcept |
Convert the entire contents of this ring buffer to an std::string
object.
|
inlinenoexcept |
Convert the entire contents of this ring buffer to an std::vector<char>
object.
|
inline |
Array-style access to the utilized portion of the ring buffer's contents, which yields the same result as that of the at() method.
The first element is at index 0.
std::out_of_range | if the index is out-of-range |
index | Index of character to access (0 = first element; negative index values are calculated in reverse, starting with -1 as the final position) |
|
friend |
Support convenient streaming usage with std::cout, std::cerr, and friends.
o | Output stream (provided automatically by std::cout and std::cerr) |
c | Object class (matched by compiler) |