libfossil
fsl::Buffer Class Reference

A very thin varnish over fsl_buffer, the primary advantage being that it frees its memory when it destructs, so it's easier to keep exception-safe than a raw fsl_buffer. More...

#include "fossil.hpp"

Public Types

typedef unsigned char const * const_iterator
 STL-style const iterator for the buffer's memory. More...
 
typedef unsigned char * iterator
 STL-style iterator for the buffer's memory. More...
 

Public Member Functions

 Buffer (fsl_size_t startingSize)
 Initializes the buffer. More...
 
 Buffer ()
 Initializes an empty buffer. More...
 
 Buffer (Buffer const &other)
 Copies the contents of the other buffer. More...
 
 ~Buffer () throw ()
 Frees all memory owned by the buffer. More...
 
Bufferappendf (char const *fmt,...)
 Basically equivalent to fsl_buffer_appendf(*this,...) except that it throws if that function fails. More...
 
iterator begin () throw ()
 Returns the starting memory position iterator, or NULL if empty(). More...
 
const_iterator begin () const throw ()
 Const-correct overload. More...
 
char const * c_str () const throw ()
 Returns a pointer to the buffer member. More...
 
fsl_size_t capacity () const throw ()
 Returns the current capacity of the buffer. More...
 
Bufferclear () throw ()
 Equivalent to fsl_buffer_clear(*this). More...
 
bool empty () const throw ()
 Returns true if 0==used(). More...
 
iterator end () throw ()
 Returns the one-after-the-end of the memory position iterator (the "used" space, not necessarily the capacity), or NULL if empty(). More...
 
const_iterator end () const throw ()
 Const-correct overload. More...
 
fsl_bufferhandle () throw ()
 Returns the underlying fsl_buffer this object proxies. More...
 
fsl_buffer const * handle () const throw ()
 Const-correct overload. More...
 
unsigned char * mem () throw ()
 Returns a pointer to the current buffer, which points to used() bytes of memory. More...
 
unsigned char const * mem () const throw ()
 Const-correct overload. More...
 
 operator fsl_buffer * () throw ()
 Implicit conversion to (fsl_buffer *) to simplify usage with the C API. More...
 
 operator fsl_buffer const * () const throw ()
 Const-correct overload. More...
 
Bufferoperator= (Buffer const &other)
 Replaces the current buffer contents with a copy of those from the given buffer. More...
 
Bufferreserve (fsl_size_t n)
 Equivalent to fsl_buffer_reserve(*this, n), but throws on error and returns this object on success. More...
 
Bufferreset () throw ()
 Equivalent to fsl_buffer_reset(*this). More...
 
Bufferresize (fsl_size_t n)
 Equivalent to fsl_buffer_resize(*this, n), but throws on error and returns this object on success. More...
 
void toss (int errorCode) const
 Throws an Exception using the given error code and the contents of the buffer as the message. More...
 
fsl_size_t used () const throw ()
 Returns the "used" number of bytes in the buffer. More...
 

Detailed Description

A very thin varnish over fsl_buffer, the primary advantage being that it frees its memory when it destructs, so it's easier to keep exception-safe than a raw fsl_buffer.

It implements an implicit conversion to (fsl_buffer*), making it trivial to use with the C-level fsl_buffer APIs.

Note that the underlying buffer APIs guaranty that they NUL-terminates the buffer when data is appended to it, so it can easily be used to create dynamic strings (which is in fact one of its primary uses). As for strlen() and conventional string classes (e.g. std::string), the automatically-added NUL byte is never counted as part of the "effective length" of the buffer (Buffer::used() resp. fsl_buffer::used).

Example usage:

b.appendf(b, "hi, %s!", "world"); // throws on buffer (re)allocation error
std::cout << b << '\n';

Definition at line 203 of file fossil.hpp.

Member Typedef Documentation

typedef unsigned char const* fsl::Buffer::const_iterator

STL-style const iterator for the buffer's memory.

Definition at line 324 of file fossil.hpp.

typedef unsigned char* fsl::Buffer::iterator

STL-style iterator for the buffer's memory.

Definition at line 319 of file fossil.hpp.

Constructor & Destructor Documentation

fsl::Buffer::Buffer ( fsl_size_t  startingSize)
explicit

Initializes the buffer.

If startingSize is greater than zero it reserves that amount of memory, throwing an OOMException if that fails.

fsl::Buffer::Buffer ( )

Initializes an empty buffer.

fsl::Buffer::~Buffer ( )
throw (
)

Frees all memory owned by the buffer.

fsl::Buffer::Buffer ( Buffer const &  other)

Copies the contents of the other buffer.

Member Function Documentation

Buffer& fsl::Buffer::appendf ( char const *  fmt,
  ... 
)

Basically equivalent to fsl_buffer_appendf(*this,...) except that it throws if that function fails.

iterator fsl::Buffer::begin ( )
throw (
)

Returns the starting memory position iterator, or NULL if empty().

It may be invalidated by any changes to the buffer.

const_iterator fsl::Buffer::begin ( ) const
throw (
)

Const-correct overload.

char const* fsl::Buffer::c_str ( ) const
throw (
)

Returns a pointer to the buffer member.

It may be invalidated by any changes to the buffer. Returns NULL if the buffer has never has any contents, but after that this will return an empty string if the buffer is empty.

fsl_size_t fsl::Buffer::capacity ( ) const
throw (
)

Returns the current capacity of the buffer.

Buffer& fsl::Buffer::clear ( )
throw (
)

Equivalent to fsl_buffer_clear(*this).

bool fsl::Buffer::empty ( ) const
throw (
)

Returns true if 0==used().

iterator fsl::Buffer::end ( )
throw (
)

Returns the one-after-the-end of the memory position iterator (the "used" space, not necessarily the capacity), or NULL if empty().

It may be invalidated by any changes to the buffer.

Referenced by fsl::Stmt::bindIter().

const_iterator fsl::Buffer::end ( ) const
throw (
)

Const-correct overload.

fsl_buffer* fsl::Buffer::handle ( )
throw (
)

Returns the underlying fsl_buffer this object proxies.

See operator fsl_buffer *().

fsl_buffer const* fsl::Buffer::handle ( ) const
throw (
)

Const-correct overload.

unsigned char* fsl::Buffer::mem ( )
throw (
)

Returns a pointer to the current buffer, which points to used() bytes of memory.

Returns NULL for an empty() buffer. The returned pointer may be invalidated on any changes to the buffer.

unsigned char const* fsl::Buffer::mem ( ) const
throw (
)

Const-correct overload.

fsl::Buffer::operator fsl_buffer * ( )
throw (
)

Implicit conversion to (fsl_buffer *) to simplify usage with the C API.

NEVER EVER use/rely upon this conversion in the following context:

  • As a fsl_appendf() (or similar) argument when using the b/B (fsl_buffer-specific) format specifiers. Use handle() instead or the wrong conversion will be used because compile-time doesn't know this conversion should be used at that point (leading to undefined results).
fsl::Buffer::operator fsl_buffer const * ( ) const
throw (
)

Const-correct overload.

Buffer& fsl::Buffer::operator= ( Buffer const &  other)

Replaces the current buffer contents with a copy of those from the given buffer.

It re-uses the existing buffer memory if enough is available, and will shrink itself to fit if re-using a buffer would waste "too much" memory.

Buffer& fsl::Buffer::reserve ( fsl_size_t  n)

Equivalent to fsl_buffer_reserve(*this, n), but throws on error and returns this object on success.

Buffer& fsl::Buffer::reset ( )
throw (
)

Equivalent to fsl_buffer_reset(*this).

Buffer& fsl::Buffer::resize ( fsl_size_t  n)

Equivalent to fsl_buffer_resize(*this, n), but throws on error and returns this object on success.

void fsl::Buffer::toss ( int  errorCode) const

Throws an Exception using the given error code and the contents of the buffer as the message.

fsl_size_t fsl::Buffer::used ( ) const
throw (
)

Returns the "used" number of bytes in the buffer.


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