Buffer

Buffers are all about reading and writing data. The evbuffer is a simple utility within libevent that is used throughout the code-base where data is involved. The Buffer class in Pembroke wraps that functionality, but with an interface that is more idiomatic to C++.

pembroke::Buffer

class pembroke::Buffer

Buffer is a simple wrapper over libevent’s evbuffer that is needed when reading or writing to/from a network or file-system.

You may find that not all methods or utilities are are possible with an evbuffer are exposed as only the methods essential to this libraries functionalities are included.

Note

While the underlying C-style API mostly represents contents as strings, or bytes via unsigned char, you can also decide to work purely with std::byte methods. To read std::bytes (and avoid copies), you’ll have to work with ByteSlice, which is a poor man’s std:span in a pre-C++20 world.

See

ByteSlice

Public Functions

Buffer() noexcept

Construct a new, empty buffer object.

Buffer(Buffer&&) noexcept

Move-construct a buffer-object. The underlying evbuffer will be transferred into the newly constructed class.

auto operator=(Buffer&&) noexcept -> Buffer&

Move-assign a buffer-object. The underlying evbuffer will be transferred into the newly constructed class.

void add(std::string_view str_view) noexcept

Write a string-view of data into the buffer. The data being pointed to will be copied into the buffer.

Note

Useful for writing char literals or std::string and avoid unnecessary copyig of the data.

Parameters

• str_view: View of data to write to buffer

void add(const char *c_str, size_t n_chars) noexcept

Write a c-style string for given number of characters. The sub-section of data will be copied into the buffer.

Pre

n_chars should not be larger than the length of c_str as this method does not check for null-terminating characters.

Parameters

• c_str: The C-style string to add to the buffer

• n_chars: The number of characters to write, from the start of the string

void add(const std::byte *bytes, size_t n_bytes) noexcept

Write an array of bytes, the length of n_bytes. The data will be copied into the buffer.

Pre

n_bytes should not be larger than the length of bytes.

See

Buffer::add(const ByteSlice &)

Parameters

• bytes: Pointer to head of std::byte array

• n_bytes: The number of std::bytes to write to he buffer, starting from bytes.

void add(const ByteSlice &byte_slice) noexcept

Write an array of bytes. The data will be copied into the buffer.

Very similar to Buffer::add(const std::byte *, size_t), but using the ByteSlice. The two methods are identical in functionality, but with this method adding parity to the read method: Buffer::bytes().

See

Buffer::add(const std::byte *, size_t)

Parameters

• byte_slice: Slice of std::bytes to append to the buffer.

auto length() noexcept -> size_t

Return the length of the data currently stored in the buffer. Same as Buffer::size().

auto size() noexcept -> size_t

Return the length of the data currently stored in the buffer. Same as Buffer::length().

auto view_str() noexcept -> std::string_view

Return a string-view into the buffer.

auto str() noexcept -> std::string

Return a std::string of the buffer contents. Note that this will perform a copy of the underlying buffer data. If no copies are desired, see Buffer::view_str() or Buffer::bytes() methods.

auto bytes() const noexcept -> ByteSlice

Return a ByteSlice of the buffer. No copies of the underlying buffer-data are performed.

pembroke::ByteSlice

struct pembroke::ByteSlice

ByteSlice is a non-owning view into an array of std::byte objects. It exists to facilitate zero-copy reading of Buffer data.

This struct is similar in intention to C++20’s std::span, but without any other useful utility features.

Public Members

std::byte *bytes

Pointer for first std::byte in the array

size_t len

The number of elements in the array/slice