scsl  0.2.4
Shimmering Clarity Standard Library
Public Member Functions | Friends | List of all members
scsl::Buffer Class Reference

#include <Buffer.h>

Public Member Functions

 Buffer ()
 A Buffer can be constructed empty, with no memory allocated (yet). More...
 
 Buffer (size_t initialCapacity)
 
 Buffer (const char *s)
 A Buffer can be initialized with a starting C-style string. More...
 
 Buffer (const std::string s)
 A Buffer can be initialized with a starting string. More...
 
 ~Buffer ()
 
uint8_t * Contents () const
 Contents returns the Buffer's contents. More...
 
size_t Length () const
 
size_t Capacity () const
 Capacity returns the amount of memory allocated to the Buffer. More...
 
bool Append (const char *s)
 
bool Append (const std::string s)
 
bool Append (const uint8_t *data, const size_t datalen)
 
bool Append (const uint8_t c)
 
bool Insert (const size_t index, const char *s)
 
bool Insert (const size_t index, const std::string s)
 
bool Insert (const size_t index, const uint8_t *data, const size_t datalen)
 
bool Insert (const size_t index, const uint8_t c)
 
bool Remove (const size_t index, const size_t count)
 
bool Remove (size_t index)
 
void Resize (size_t newCapacity)
 
size_t Trim ()
 
void DisableAutoTrim ()
 
void EnableAutoTrim ()
 
bool AutoTrimIsEnabled ()
 
void Clear ()
 
void Reclaim ()
 
void HexDump (std::ostream &os)
 
uint8_t & operator[] (size_t index)
 

Friends

bool operator== (const Buffer &lhs, const Buffer &rhs)
 

Detailed Description

Buffer is a basic line buffer.

The buffer manages its own internal memory, growing and shrinking as needed. Its capacity is separate from its length; the optimal capacity is determined as the nearest power of two that is greater than the length of the buffer. For example, if the buffer has a length of 5 bytes, 8 bytes will be allocated. If the buffer is 9 bytes, 16 bytes will be allocated.

The Append and Insert methods will call Resize as necessary to grow the buffer. Similarly the Remove methods will call Trim to reclaim some memory if possible, but only if AutoTrimIsEnabled (it is by default).

Constructor & Destructor Documentation

◆ Buffer() [1/4]

scsl::Buffer::Buffer ( )

A Buffer can be constructed empty, with no memory allocated (yet).

◆ Buffer() [2/4]

scsl::Buffer::Buffer ( size_t  initialCapacity)
explicit

A Buffer can be constructed with an explicit capacity.

Parameters
initialCapacityThe initial allocation size for the buffer.

◆ Buffer() [3/4]

scsl::Buffer::Buffer ( const char *  s)
explicit

A Buffer can be initialized with a starting C-style string.

◆ Buffer() [4/4]

scsl::Buffer::Buffer ( const std::string  s)
explicit

A Buffer can be initialized with a starting string.

◆ ~Buffer()

scsl::Buffer::~Buffer ( )
inline

Member Function Documentation

◆ Append() [1/4]

bool scsl::Buffer::Append ( const char *  s)

Append copies in a C-style string to the end of the buffer.

Parameters
sThe string to append.
Returns
True if the Buffer was resized.

◆ Append() [2/4]

bool scsl::Buffer::Append ( const std::string  s)

Append copies in a string to the end of the buffer.

Parameters
sThe string to append.
Returns
True if the Buffer was resized.

◆ Append() [3/4]

bool scsl::Buffer::Append ( const uint8_t *  data,
const size_t  datalen 
)

Append copies in a byte buffer to the end of the buffer.

Parameters
dataThe byte buffer to insert.
datalenThe length of the byte buffer.
Returns
True if the Buffer was resized.

◆ Append() [4/4]

bool scsl::Buffer::Append ( const uint8_t  c)

Append copies a single character to the end of the buffer.

Parameters
cThe character to append.
Returns
True if the Buffer was resized.

◆ AutoTrimIsEnabled()

bool scsl::Buffer::AutoTrimIsEnabled ( )
inline

AutoTrimIsEnabled returns true if autotrim is enabled.

Returns
Remove will call Trim.

◆ Capacity()

size_t scsl::Buffer::Capacity ( ) const
inline

Capacity returns the amount of memory allocated to the Buffer.

◆ Clear()

void scsl::Buffer::Clear ( )

Clear removes the data stored in the buffer. It will not call Trim; the capacity of the buffer will not be altered.

◆ Contents()

uint8_t* scsl::Buffer::Contents ( ) const
inline

Contents returns the Buffer's contents.

◆ DisableAutoTrim()

void scsl::Buffer::DisableAutoTrim ( )
inline

DisableAutoTrim prevents the Buffer from automatically trimming memory after a call to Remove.

◆ EnableAutoTrim()

void scsl::Buffer::EnableAutoTrim ( )
inline

EnableAutoTrim enables automatically trimming memory after calls to Remove.

◆ HexDump()

void scsl::Buffer::HexDump ( std::ostream &  os)

HexDump dumps the data in the buffer to the output stream; it is intended as a debugging tool.

Parameters
osThe output stream to write to.

◆ Insert() [1/4]

bool scsl::Buffer::Insert ( const size_t  index,
const char *  s 
)

Insert copies a C-style string into the buffer at index.

Parameters
indexThe index to insert the string at.
sThe string to insert.
Returns
True if the Buffer was resized.

◆ Insert() [2/4]

bool scsl::Buffer::Insert ( const size_t  index,
const std::string  s 
)

Insert copies a string into the buffer at index.

Parameters
indexThe index the string should be inserted at.
sThe string to insert.
Returns
True if the Buffer was resized.

◆ Insert() [3/4]

bool scsl::Buffer::Insert ( const size_t  index,
const uint8_t *  data,
const size_t  datalen 
)

Insert copies a uint8_t buffer into the buffer at index.

Parameters
indexThe index to insert the buffer at.
dataThe buffer to insert.
datalenThe size of the data buffer.
Returns
True if the Buffer was resized.

◆ Insert() [4/4]

bool scsl::Buffer::Insert ( const size_t  index,
const uint8_t  c 
)

Insert copies a character into the buffer at index.

Parameters
indexThe index to insert the character at.
cThe character to insert.
Returns
True if the Buffer was resized.

◆ Length()

size_t scsl::Buffer::Length ( ) const
inline

Length returns the length of the data currently stored in the buffer.

◆ operator[]()

uint8_t & scsl::Buffer::operator[] ( size_t  index)

This operator allows the data in the buffer to be accessed as if it were an array. If the index is out of bounds, it will throw a range_error.

Exceptions
std::range_error.
Parameters
indexThe index to retrieve.
Returns

◆ Reclaim()

void scsl::Buffer::Reclaim ( )

Reclaim the memory in the buffer: the buffer will call Clear, followed by deleting any allocated memory.

◆ Remove() [1/2]

bool scsl::Buffer::Remove ( const size_t  index,
const size_t  count 
)

Remove removes count bytes from the buffer at index.

Parameters
indexThe starting index to remove bytes from.
countThe number of bytes to remove.
Returns
True if the Buffer was resized.

◆ Remove() [2/2]

bool scsl::Buffer::Remove ( size_t  index)

Remove removes a single byte from the buffer.

Parameters
indexThe index pointing to the byte to be removed.
Returns
True if the Buffer was resized.

◆ Resize()

void scsl::Buffer::Resize ( size_t  newCapacity)

Resize changes the capacity of the buffer to newCapacity.

If newCapacity is less than the length of the Buffer, it will remove enough bytes from the end to make this happen.

Parameters
newCapacityThe new capacity for the Buffer.

◆ Trim()

size_t scsl::Buffer::Trim ( )

Trim will resize the Buffer to an appropriate size based on its length.

Returns
The new capacity of the Buffer.

Friends And Related Function Documentation

◆ operator==

bool operator== ( const Buffer lhs,
const Buffer rhs 
)
friend

Two buffers are equal if their lengths are the same and their contents are the same. Equality is irrespective of their capacities.


The documentation for this class was generated from the following files: