Description:

This is an abstract base class to implement an ALib string formatter. A string formatter uses a "format string" to transform arguments into formatted text. The format string defines how the arguments are transformed by offering a "placeholder syntax".

With this information, it becomes clear that different formatter types (derived types that offer a concrete placeholder syntax) all can have the same interface methods. This class defines this abstract interface.

Built-in formatters derived from this class, are FormatterPythonStyle and FormatterJavaStyle.

Definition at line 59 of file formatter.inl.

Inheritance diagram for alib::format::Formatter:

[legend]

Collaboration diagram for alib::format::Formatter:

[legend]

Public Static Field Index:
static ALIB_DLL SPFormatter	Default

static ALIB_DLL threads::RecursiveLock	DefaultLock

Public Static Field Index: inherited from alib::lang::DbgCriticalSections
static ALIB_DLL const char *	ASSERTION_FORMAT

Public Field Index:
NumberFormat	AlternativeNumberFormat

NumberFormat	DefaultNumberFormat

SharedPtr< Formatter >	Next

Public Field Index: inherited from alib::lang::DbgCriticalSections
CallerInfo	DCSAcq
	Source location of acquirement.

AssociatedLock *	DCSLock {nullptr}

const char *	DCSName
	The name of this DCS. Used for debug-output.

std::atomic< int >	DCSReaderCnt {0}
	Tracks enter/exit calls of readers.

CallerInfo	DCSRel
	Source location of the last "reader" seen.

CallerInfo	DCSSAcq
	Source location of acquirement.

CallerInfo	DCSSRel
	Source location of the last "reader" seen.

std::atomic< int >	DCSWriterCnt {0}
	Tracks enter/exit calls (including readers)

int	DCSYieldOrSleepTimeInNS = -1

Public Method Index:
	Formatter ()
	Default Constructor.

virtual	~Formatter ()

virtual SPFormatter	Clone ()=0

virtual ALIB_DLL void	CloneSettings (Formatter &reference)

template<typename... TArgs>
Formatter &	Format (AString &target, TArgs &&... args)

Formatter &	FormatArgs (AString &target)

template<typename TAllocator>
Formatter &	FormatArgs (AString &target, const boxing::TBoxes< TAllocator > &args)

virtual BoxesMA &	GetArgContainer ()

virtual BoxesMA &	Reset ()

Public Method Index: inherited from alib::lang::DbgCriticalSections
	DbgCriticalSections (const char *name)

	~DbgCriticalSections ()
	Destructor. Checks that this instance is unused.

ALIB_DLL void	Acquire (const CallerInfo &ci) const

ALIB_DLL void	AcquireShared (const CallerInfo &ci) const

ALIB_DLL void	doAssert (bool cond, const CallerInfo &ciAssert, const CallerInfo &ci, const char *headline) const

ALIB_DLL void	Release (const CallerInfo &ci) const

ALIB_DLL void	ReleaseShared (const CallerInfo &ci) const

void	yieldOrSleep () const

Protected Field Index:
MonoAllocator	allocator
	This allocator is (exclusively) used for field boxes.

BoxesMA	boxes

AString	formatStringBuffer
	A buffer used for conversion of the next argument if it is not of a string-type.

Protected Method Index:
virtual int	format (AString &target, const String &formatString, const BoxesMA &args, int startArgument)=0

template<typename TAllocator>
Formatter &	formatLoop (AString &target, const boxing::TBoxes< TAllocator > &args)

virtual void	initializeFormat ()

Field Details:

◆ allocator

MonoAllocator alib::format::Formatter::allocator

protected

This allocator is (exclusively) used for field boxes.

Definition at line 70 of file formatter.inl.

◆ AlternativeNumberFormat

NumberFormat alib::format::Formatter::AlternativeNumberFormat

This number format is used to store alternative attributes. Likewise DefaultNumberFormat, it is never used directly for formatting. Instead, when processing the placeholder syntax, alternatives get copied from either this object or from DefaultNumberFormat.

This object is initialized in the constructor (of descendants) once to meet the formatting defaults of the corresponding specification.

With the implementations of this class provided with ALib, not all fields in this object are used. The fields used are:

Locale-specific versions of floating point separators:
- NumberFormat::DecimalPointChar
- NumberFormat::ThousandsGroupChar
These are retrieved according to the current locale once in the constructor. To change the locale, these fields can be changed.
Lower case versions of floating point literals:
Lower case versions of prefix literals that indicate the base of integral values:

Definition at line 125 of file formatter.inl.

◆ boxes

BoxesMA alib::format::Formatter::boxes

protected

A list of boxes. This is reset with every new invocation of variadic template method Format

Definition at line 74 of file formatter.inl.

◆ Default

SPFormatter alib::format::Formatter::Default

static

A publicly accessible static singleton instance which is can be freely used. Racing conditions in multithreaded applications have to be avoided by locking mutex DefaultLock.

Definition at line 278 of file formatter.inl.

◆ DefaultLock

threads::RecursiveLock alib::format::Formatter::DefaultLock

static

The lock to be set with multithreaded use of Default. If the compiler-symbol ALIB_DEBUG_CRITICAL_SECTIONS is set, this lock will be attached to the DbgCriticalSections instance in Default during bootstrap. Thus, an assertion will be raised if Default is used without locking this.

Availability: This object is available only if symbol ALIB_SINGLE_THREADED is not set.

See also: Chapter 1.4.3 Asserting Critical Section Locks of the Programmer's Manual of module ALib Threads.

Definition at line 293 of file formatter.inl.

◆ DefaultNumberFormat

NumberFormat alib::format::Formatter::DefaultNumberFormat

Stores default attributes for formatting numbers. Likewise AlternativeNumberFormat, it usually is not used directly for formatting by descendants. Instead, at the beginning of parsing a next placeholder field, values are copied to a local copy. During the parsing process, values are then modified only in this local copy, probably taken from AlternativeNumberFormat.

This object is to be initialized in the constructor (of descendants) once to meet the formatting defaults of the corresponding specification. If after construction, attribute values of this object are changed, such changes are applied to all number formatting.

Definition at line 96 of file formatter.inl.

◆ formatStringBuffer

AString alib::format::Formatter::formatStringBuffer

protected

A buffer used for conversion of the next argument if it is not of a string-type.

Definition at line 77 of file formatter.inl.

◆ Next

SharedPtr<Formatter> alib::format::Formatter::Next

An optional, next formatter. If set, this formatter will be invoked for a format string that does not contain recognized placeholders.

Attention: This field is public and not further maintained by this class. Setting the field lies completely in the responsibility of the user. E.g., cyclic settings must be avoided. Also, object life-cycle management is completely up to the user.

Definition at line 133 of file formatter.inl.

Constructor(s) / Destructor Details:

◆ Formatter()

alib::format::Formatter::Formatter ( )

inline

Default Constructor.

Definition at line 140 of file formatter.inl.

Here is the call graph for this function:

◆ ~Formatter()

virtual alib::format::Formatter::~Formatter ( )

inlinevirtual

Destructs an object of this class. Note that concatenated formatters are not deleted automatically.

Definition at line 154 of file formatter.inl.

Method Details:

◆ Clone()

virtual SPFormatter alib::format::Formatter::Clone ( )

pure virtual

Clones and returns a copy of this formatter.

If a formatter is attached to field Formatter::Next, it is cloned as well (recursively).

Returns: An object of the same (derived) type and the same custom settings.

Implemented in alib::format::FormatterJavaStyle, and alib::format::FormatterPythonStyle.

Here is the call graph for this function:

◆ CloneSettings()

void alib::format::Formatter::CloneSettings ( Formatter & reference )

virtual

Clones the settings from the given formatter.

Parameters

reference The formatter to copy settings from.

Definition at line 104 of file formatter.cpp.

Here is the call graph for this function:

◆ Format()

template<typename... TArgs>

Formatter & alib::format::Formatter::Format	(	AString &	target,
		TArgs &&...	args )

inline

Variadic template method that accepts a target AString and a list of arguments. This is a convenience method to allow single-line format invocations.

Note: This method uses static_assert to disallow the invocation with one variadic argument of type TBoxes or a derived type. This is to ensure that for these box containers, the more efficient method FormatArgs is used.

Template Parameters

TArgs Variadic template type list.

Parameters

target	An AString that takes the result.
args	The variadic list of arguments to be used with formatters.

Returns: A reference to this formatter to allow concatenated operations.

Definition at line 177 of file formatter.inl.

Here is the call graph for this function:

◆ format()

virtual int alib::format::Formatter::format	(	AString &	target,
		const String &	formatString,
		const BoxesMA &	args,
		int	startArgument )

protectedpure virtual

The abstract format method that needs to be implemented by descendants. Note that parameter startIdx and the demanded return value together comprise the possibility to use more than one formatter in parallel and to perform multiple format operations on suitable argument lists. This demands the implementation of this method to not copy the format string to the target in the case that no 'escape sequence' was found. For further information, see the general documentation of this class.

Parameters

target	The AString that takes the result.
formatString	The format string.
args	The objects to be used with formatters.
startArgument	The first object in args to convert.

Returns: The number of args consumed.

Implemented in alib::format::FormatterStdImpl.

◆ FormatArgs() [1/2]

Formatter & alib::format::Formatter::FormatArgs ( AString & target )

inline

Formats the internal list of arguments that is returned by methods GetArgContainer and Reset.

This method may be more efficient than using inlined variadic method Format and should be preferred if:

Format arguments cannot be collected in a single invocation, for example, if those are to be collected in a loop.
A sequence of different format operations is to be performed.

Parameters

target An AString that takes the result.

Returns: A reference to this formatter to allow concatenated operations.

Definition at line 346 of file formatter.inl.

Here is the call graph for this function:

◆ FormatArgs() [2/2]

template<typename TAllocator>

Formatter & alib::format::Formatter::FormatArgs	(	AString &	target,
		const boxing::TBoxes< TAllocator > &	args )

inline

Same as Format(AString&) but allows specifying an external list of arguments instead of the internally allocated object, which is returned by methods GetArgContainer and Reset.

Parameters

args	The arguments to be used with formatters.
target	An AString that takes the result.

Returns: A reference to this formatter to allow concatenated operations.

Definition at line 225 of file formatter.inl.

Here is the call graph for this function:

◆ formatLoop()

template<typename TAllocator>

Formatter & alib::format::Formatter::formatLoop	(	AString &	target,
		const boxing::TBoxes< TAllocator > &	args )

protected

The format loop implementation. Searches format strings in args and tests if this or Next is capable of processing it.

Parameters

target	An AString that takes the result.
args	The objects to be used with formatters.

Returns: A reference to this formatter to allow concatenated operations.

Here is the call graph for this function:

◆ GetArgContainer()

virtual BoxesMA & alib::format::Formatter::GetArgContainer ( )

inlinevirtual

Returns an empty vector of arguments, which can be passed to the format interface.
Note: This is nothing more than a recycling strategy.

Returns: An internally allocated container of boxes that may be used to collect formatter arguments.

Definition at line 268 of file formatter.inl.

◆ initializeFormat()

virtual void alib::format::Formatter::initializeFormat ( )

inlineprotectedvirtual

Virtual method which is invoked with each invocation of Format. The default implementation does nothing.

Reimplemented in alib::format::FormatterPythonStyle.

Definition at line 304 of file formatter.inl.

◆ Reset()

virtual BoxesMA & alib::format::Formatter::Reset ( )

inlinevirtual

Virtual method used to reset internal states.

It is formatter-depended, which state information is reset. As a sample, derived type FormatterPythonStyle clears its auto-tab and auto-width positions.

The default implementation does nothing.

Returns: An internally allocated container of boxes that may be used to collect formatter arguments.

Reimplemented in alib::format::FormatterPythonStyle.

Definition at line 260 of file formatter.inl.

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

Description:

Public Static Field Index:

Public Field Index:

Public Method Index:

Protected Field Index:

Protected Method Index:

Field Details:

◆ allocator

◆ AlternativeNumberFormat

◆ boxes

◆ Default

◆ DefaultLock

◆ DefaultNumberFormat

◆ formatStringBuffer

◆ Next

Constructor(s) / Destructor Details:

◆ Formatter()

◆ ~Formatter()

Method Details:

◆ Clone()

◆ CloneSettings()

◆ Format()

◆ format()

◆ FormatArgs() [1/2]

◆ FormatArgs() [2/2]

◆ formatLoop()

◆ GetArgContainer()

◆ initializeFormat()

◆ Reset()