libfossil
fsl Namespace Reference

License as yet undecided! More...

Data Structures

class  Buffer
 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...
 
class  BufferOStream
 
class  Context
 C++ counterpart of fsl_cx, but generally requires less code to use because it throws exceptions for any notable errors. More...
 
class  ContextOStream
 A std::ostream which redirects its output to the output channel configured for a fsl_cx instance. More...
 
class  ContextOStreamBuf
 A std::streambuf impl which redirects a std::streambuf to fsl_output(). More...
 
class  Db
 C++ counterpart to fsl_db. More...
 
class  Deck
 The C++ counterpart to the C-side fsl_deck class. More...
 
class  Exception
 The base exception type used by the API. More...
 
class  FslListIterator
 A utility class for iterating over fsl_list instances. More...
 
class  FslOutputFStream
 This std::ostream subclass which proxies a fsl_output_f() implementation, sending all output to that function. More...
 
class  FslOutputFStreamBuf
 A std::streambuf impl which redirects a std::streambuf to a fsl_output_f(). More...
 
class  OOMException
 Out-of-memory exception. More...
 
class  Stmt
 A prepared statement, the C++ counterpart to fsl_stmt. More...
 
class  StmtBinder
 A utility class for binding values to statements. More...
 

Functions

fsl_int_t fsl_appendf_f_std_ostream (void *state, char const *data, fsl_int_t n)
 A fsl_appendf_f() implementation which requires that state be a std::ostream pointer. More...
 
int fsl_input_f_std_istream (void *state, void *dest, fsl_size_t *n)
 A fsl_input_f() implementation which requires state to be a std::istream pointer. More...
 
int fsl_output_f_std_ostream (void *state, void const *data, fsl_size_t n)
 A fsl_output_f() implementation which requires that state be a std::ostream pointer. More...
 
std::ostream & operator<< (std::ostream &os, Buffer const &b)
 Writes the first b.used() bytes of b.mem() to os and returns os. More...
 
template<typename ValueType >
Bufferoperator<< (Buffer &b, ValueType const v)
 Accepts any type compatible with std::ostream<<v, converts it to a string (via std::ostringstream), then appends that result to b. More...
 
std::ostream & operator<< (std::ostream &os, Deck const &d)
 Calls d.output(os) and returns os. More...
 

Detailed Description

License as yet undecided!

fsl is the primary namespace of the libfossil C++ API. The C++ API wraps much of the C-level function and simplifies its usage somewhat by using exceptions extensively for error reporting.

A brief note about exceptions: functions and methods with do not throw are marked as throw(). Any others may very well throw. Though in practice the library APIs "simply do not fail" if used properly, there are gazillions of _potential_ error cases which the underlying C library _may_ propagate up to the client (in this case the C++ API), and this C++ wrapper treats almost every C-level error as an Exception, with only a few exceptions to simplify usage (e.g. cleanup-related functions never throw because they are generally used in destructors, and dtors are conventionally prohibited from throwing). The base exception type used by the library is fsl::Exception, which derives from std::exception per long-standing convention.

While the API is not STL-centric, it does provide some basic STL-relatated support, e.g. the fsl::FslOutputFStream and fsl::BufferOStream classes.

Function Documentation

fsl_int_t fsl::fsl_appendf_f_std_ostream ( void *  state,
char const *  data,
fsl_int_t  n 
)

A fsl_appendf_f() implementation which requires that state be a std::ostream pointer.

It uses std::ostream::write() to append n bytes of the data argument to the output stream. If the write() operation throws, this function catches it and returns FSL_RC_IO instead (because we propagating exceptions across the C API has undefined behaviour). Returns 0 on success, FSL_RC_IO if the stream is in an error state after the write.

int fsl::fsl_input_f_std_istream ( void *  state,
void *  dest,
fsl_size_t n 
)

A fsl_input_f() implementation which requires state to be a std::istream pointer.

Characters are read from the stream until n bytes are read or EOF is reached. If EOF is reached, *n is set to the number of bytes consumed (and written to dest) before reaching EOF. If the input operation throws, this function catches it and returns FSL_RC_IO instead (because propagating exceptions across the C API has undefined behaviour)

Example usage:

char const * filename = "some-file";
std::ifstream is(filename);
if(!is.good()) throw Exception(FSL_RC_IO,"Cannot open: %s", filename);
int rc = fsl_buffer_fill_from( &buf,
&is );
if(rc) {...error...}
else {...okay...}
fsl_buffer_clear(&buf); // in error cases it might be partially filled!

Better yet, use try/catch to better protect the buffer from leaks:

try{
... do i/o here ...
}catch(...){
throw;
}

_Even better_, use the Buffer class to manage buffer memory lifetime, making it inherently exception-safe:

std::ifstream is(filename);
Buffer buf;
if(rc) throw Exception(rc); // now buf will not leak
...
int fsl::fsl_output_f_std_ostream ( void *  state,
void const *  data,
fsl_size_t  n 
)

A fsl_output_f() implementation which requires that state be a std::ostream pointer.

It uses std::ostream::write() to append n bytes of the data argument to the output stream. If the write() operation throws, this function catches it and returns FSL_RC_IO instead (because propagating exceptions across the C API has undefined behaviour). Returns 0 on success, FSL_RC_IO if the stream is in an error state after the write.

std::ostream& fsl::operator<< ( std::ostream &  os,
Buffer const &  b 
)

Writes the first b.used() bytes of b.mem() to os and returns os.

template<typename ValueType >
Buffer& fsl::operator<< ( Buffer b,
ValueType const  v 
)

Accepts any type compatible with std::ostream<<v, converts it to a string (via std::ostringstream), then appends that result to b.

Returns b.

Definition at line 384 of file fossil.hpp.

References fsl_buffer_append().

std::ostream& fsl::operator<< ( std::ostream &  os,
Deck const &  d 
)

Calls d.output(os) and returns os.