Description:

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>
requires (::std::is_same_v<TChar, char> || ::std::is_same_v<TChar, wchar_t>)
class alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >

This class writes ALib Strings into instances of std::basic_ostream<TChar>. The features of this type are:

Supports writing into narrow and wide output streams (std::ostream and std::wostream). The character width is controlled with the template parameter TChar.
Accepts ALib strings of all three character widths (narrow, wide, and strange strings).
The template parameter TSynced allows syncing the output in multithreaded applications to avoid interleaving of output. For this, the C++ 20 mechanism provided with type std::osyncstream is used. This allows syncing across C++ libraries that rely on the same standard.
If syncing is enabled, output is emitted to the stream only at the moment that the corresponding instance of this class is destructed.
Optionally, this type converts non-conform newline sequences to the desired coding. For example, if the given strings contain WindowsOS newline codes "\r\n", on GNU/Linux platforms, just "\n" may be written. This feature is controlled by the template parameter TTargetLF.
The type counts the number of printed characters with its overloaded method Write. "Printed" here means that it is how many characters in a UTF8-enconding would effectively be shown, if printed.
The type uses ALib allocators for memory management.

It is recommended that only short-living, local instances of this class are created. This is especially important in the case that parameter TSynced is true. In this mode, this type follows the RAII idiom just as its then available member std::osyncstream does.

Note: As of 10/2025, some toolchains might not support the C++20 output stream synchronization, yet. In this case, the code compiles without using it, and the output is not synchronized and may interleave.
Clang's standard library libc++ (which can be activated with ALib with CMake variable ALIB_CLANG_USE_LIBCPP), in its version 200100 supports class std::osyncstream only if the compiler flag -fexperimental-library is provided.

Template Parameters

TChar	The character type of the target `std::basic_ostream`. Defaults to nchar (which effectively is C++ `char`).
TAllocator	The allocator type to use with `std::osyncstream` (if TSynced is `true`), and with temporary character conversion buffers in case those need to exceed 4kB. Defaults to HeapAllocator.
TSynced	Determines if the encapsulated `std::ostream` should be synchronized on writing. If so, the C++ 20 mechanism provided with std::osyncstream is used, as well as ALib's built-in mechanism provided with the global mutex STD_IOSTREAMS_LOCK. Both mechanics togoether allows syncing across C++ libraries and in respect to ouput generated with ALib, synchronization between `std::cout` and `std::cerr`.
TTargetLF	Determines whether non-conform line-feeds are adjusted. The default value is Platform, which converts all line-feeds to the platforms' standard. Values Unix and WindowsOS can be used to force conversion to a different standard. Finally, Ignore disables the detection and conversion of line-feed codes.

Definition at line 236 of file stdiostream.mpp.

Inheritance diagram for alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >:

Public Type Index:
using	AllocatorType = TAllocator
	Exposes template parameter TAllocator.
using	CharType = TChar
	Exposes template parameter TChar.
Public Type Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
using	AllocatorType
	Exposes the allocator type.

Public Static Field Index:
static constexpr bool	Synced = TSynced
	Exposes template parameter TSynced.
static constexpr lang::LineFeeds	TargetLF = TTargetLF
	Exposes template parameter TAdjustLF.

Public Field Index:
bool	DisableSync =false

Public Method Index:
	OStreamWriter (::std::basic_ostream< TChar > &os)
	OStreamWriter (::std::basic_ostream< TChar > &os, TAllocator &alloc)
void	Fill (const TChar fillChar, integer count)
::std::ostream &	GetStream ()
void	Write (const NString &src, integer *printedWidth=nullptr)
void	Write (const WString &src, integer *printedWidth=nullptr)
void	Write (const XString &src, integer *printedWidth=nullptr)
Public Method Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
	AllocatorMember ()
AllocatorInterface< lang::HeapAllocator >	AI () const noexcept
lang::HeapAllocator &	GetAllocator () const noexcept

Protected Type Index:
using	allocBase = lang::AllocatorMember<TAllocator>
	The type of the base class that stores the allocator.

Protected Field Index:
::std::conditional_t< TSynced &&!0, ::std::basic_osyncstream< TChar, ::std::char_traits< TChar >, lang::StdAllocator< TChar, TAllocator > >, ::std::basic_ostream< TChar > & >	ostream
Protected Field Index: inherited from alib::lang::AllocatorMember< lang::HeapAllocator >
lang::HeapAllocator *	allocator
	The allocator stored.

Protected Method Index:
template<typename TSrc>
void	doWrite (const TString< TSrc > &src, integer *printedWidth)

Type Definition Details:

◆ AllocatorType

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

using alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::AllocatorType = TAllocator

Exposes template parameter TAllocator.

Definition at line 244 of file stdiostream.mpp.

◆ allocBase

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

using alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::allocBase = lang::AllocatorMember<TAllocator>

protected

The type of the base class that stores the allocator.

Definition at line 239 of file stdiostream.mpp.

◆ CharType

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

using alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::CharType = TChar

Exposes template parameter TChar.

Definition at line 243 of file stdiostream.mpp.

Field Details:

◆ DisableSync

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

bool alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::DisableSync =false

This flag may be set after construction to disable the syncing mechanics, even if the template parameter TSynced is set. This is useful, for example, if a using code detects recursion, which is not allowed with std::osyncstream and STD_IOSTREAMS_LOCK.

Definition at line 252 of file stdiostream.mpp.

◆ ostream

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

::std::conditional_t<TSynced && !0, ::std::basic_osyncstream< TChar, ::std::char_traits<TChar>, lang::StdAllocator<TChar,TAllocator> >, ::std::basic_ostream<TChar>& > alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::ostream

protected

If unsynced, this member holds the output stream as provided with construction. In the synced case, this stores a std::basic_osyncstream which wraps the given output stream.

Definition at line 263 of file stdiostream.mpp.

◆ Synced

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

bool alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::Synced = TSynced

staticconstexpr

Exposes template parameter TSynced.

Definition at line 242 of file stdiostream.mpp.

◆ TargetLF

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

lang::LineFeeds alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::TargetLF = TTargetLF

staticconstexpr

Exposes template parameter TAdjustLF.

Definition at line 246 of file stdiostream.mpp.

Constructor(s) / Destructor Details:

◆ OStreamWriter() [1/2]

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::OStreamWriter ( ::std::basic_ostream< TChar > & os )

inline

Constructor accepting the destination stream.

Parameters

os	The output-stream to use.

Definition at line 341 of file stdiostream.mpp.

◆ OStreamWriter() [2/2]

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::OStreamWriter	(	::std::basic_ostream< TChar > &	os,
		TAllocator &	alloc )

inline

Constructor accepting the destination stream, as well as an allocator to use.

Parameters

os	The output-stream to use.
alloc	The allocator to use for the internal buffers.

Definition at line 348 of file stdiostream.mpp.

Method Details:

◆ doWrite()

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

template<typename TSrc>

void alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::doWrite	(	const TString< TSrc > &	src,
		integer *	printedWidth )

inlineprotected

Implementation of overloaded methods Write.

Parameters

	src	The string to write.
[out]	printedWidth	If given, the output width of src when it was printed is returned. (See the class description for further information.)

Template Parameters

TSrc	The character type of the source string.

Definition at line 274 of file stdiostream.mpp.

◆ Fill()

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

void alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::Fill	(	const TChar	fillChar,
		integer	count )

inline

Write the given character repeatedly to the stream.

Parameters

fillChar	The character to write.
count	The number of characters to write.

Definition at line 406 of file stdiostream.mpp.

◆ GetStream()

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

::std::ostream & alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::GetStream ( )

inline

Returns the output stream given with construction, or, if template parameter TSynced is true, that output stream wrapped in a std::basic_osyncstream. In the latter case, the sync-stream is destructed - and data is written - only with the destruction of this instance.

Returns: The output stream of this writer.

Definition at line 368 of file stdiostream.mpp.

◆ Write() [1/3]

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

void alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::Write	(	const NString &	src,
		integer *	printedWidth = nullptr )

inline

Writes the given narrow string to the stream.

Note: The output parameter printedWidth returns the length of the given string, when it was converted to wide string. This is done, even if template parameter TChar is narrow and consequently no conversion was performed.
The value is useful to callers when the "real" output width is needed, i.e., when the output text is formatted in tabulator columns or tables. Of course, in some locales, this might still not be the correct output width because even uni-code characters are not guaranteed to represent exactly one printable character. But still, this value is already a much better approximation than the length of the given narrow string.

Parameters

	src	The string to write.
[out]	printedWidth	If given, the width if src was printed is returned. See the note above. If not given, the method might execute slightly faster.

Definition at line 387 of file stdiostream.mpp.

◆ Write() [2/3]

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

void alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::Write	(	const WString &	src,
		integer *	printedWidth = nullptr )

inline

See sibling method Write(const NString&, integer*).

Parameters

	src	The wide string to write.
[out]	printedWidth	If given, the width if src was printed is returned. See the note above. If not given, the method might execute slightly faster.

Definition at line 394 of file stdiostream.mpp.

◆ Write() [3/3]

template<typename TChar = nchar, typename TAllocator = lang::HeapAllocator, bool TSynced = false, lang::LineFeeds TTargetLF = lang::LineFeeds::Platform>

void alib::strings::compatibility::std::OStreamWriter< TChar, TAllocator, TSynced, TTargetLF >::Write	(	const XString &	src,
		integer *	printedWidth = nullptr )

inline

See sibling method Write(const NString&, integer*).

Parameters

	src	The strange string to write.
[out]	printedWidth	If given, the width if src was printed is returned. See the note above. If not given, the method might execute slightly faster.

Definition at line 401 of file stdiostream.mpp.

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

stdiostream.mpp

Description:

Public Type Index:

Public Static Field Index:

Public Field Index:

Public Method Index:

Protected Type Index:

Protected Field Index:

Protected Method Index:

Type Definition Details:

◆ AllocatorType

◆ allocBase

◆ CharType

Field Details:

◆ DisableSync

◆ ostream

◆ Synced

◆ TargetLF

Constructor(s) / Destructor Details:

◆ OStreamWriter() [1/2]

◆ OStreamWriter() [2/2]

Method Details:

◆ doWrite()

◆ Fill()

◆ GetStream()

◆ Write() [1/3]

◆ Write() [2/3]

◆ Write() [3/3]