Similar to ostringstream but allows fast read-only access directly into the std::string being written; and some limited write access to that string. More...

#include <string_ostream.hpp>

Inherits boost::noncopyable.

Public Member Functions
	String_ostream (std::string *target_str=0)
	Wraps either the given `std::string` or a newly created empty string if a null pointer is passed. More...

std::ostream &	os ()
	Access to stream that will write to owned string. More...

const std::ostream &	os () const
	Read-only access to stream that will write to owned string. More...

const std::string &	str () const
	Read-only access to the string being wrapped. More...

void	str_clear ()
	Performs `std::string::clear()` on the object returned by `str()`. More...

Detailed Description

Similar to ostringstream but allows fast read-only access directly into the std::string being written; and some limited write access to that string.

Also it can take over an existing std::string.

ostringstream is fine, except for the giant flaw that is the fact that the essentially only way to read the string is to call ostringstream::str() which returns a copy, not a reference.

Todo:: Consider using alt_sstream in boost.format; it doesn't seem to have public documentation but isn't in a detail directory either. So that's interesting. It might have better performance than the implementation here (by being more "direct" probably). Then again it might not.

Thread safety

This provides the same level of thread safety as ostringstream. That is, you should use a mutex if planning concurrent read/write access to the same object.

Constructor & Destructor Documentation

◆ String_ostream()

flow::util::String_ostream::String_ostream ( std::string * target_str = 0 )

explicit

Wraps either the given std::string or a newly created empty string if a null pointer is passed.

Parameters

target_str Pointer to the string of which to take ownership; null to use an internal string currently blank. If non-null is passed, any subsequnt access to *target_str except via this class's API results in undefined behavior. (It should go without saying, but using const_cast or equivalents counts as being outside the bounds of this class's API.)

Member Function Documentation

◆ os() [1/2]

std::ostream & flow::util::String_ostream::os ( )

Access to stream that will write to owned string.

Returns: Stream.

◆ os() [2/2]

const std::ostream & flow::util::String_ostream::os ( ) const

Read-only access to stream that will write to owned string.

Returns: Read-only reference to stream.

◆ str()

const std::string & flow::util::String_ostream::str ( ) const

Read-only access to the string being wrapped.

The reference's value never changes for *this object. The string's value may change, if one writes to os() or does str_clear(), etc.

Rationale

Why return const string& instead of util::String_view? Answer: By definition we are backed by an std::string, either our own or one user actively passed to ctor. Hence it's unnecessary obfuscation; plus it can lead to errors, like if the user thinks a returned object's String_view::size() will auto-adjust based on what happens to the wrapped std::string subsequently. If they want a String_view, they can always just construct one, just as we would inside here anyway.

Returns: Read-only reference to string; the address therein is guaranteed to always be the same given a *this.

◆ str_clear()

void flow::util::String_ostream::str_clear ( )

Performs std::string::clear() on the object returned by str().

The latter is const, so you may not call clear() directly.

Note: clear() is a frequently desired operation, which is why access to it is provided as a special case. It is intentional that no read-write version of str() is provided for arbitrary write operations.

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

util/string_ostream.hpp
util/string_ostream.cpp

Public Member Functions