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, provided by module ALib BaseCamp and derived from this class, are FormatterPythonStyle and FormatterJavaStyle.

Friends

class lang::basecamp::BaseCamp.

Definition at line 43 of file formatter.hpp.

#include <formatter.hpp>

Inheritance diagram for Formatter:

[legend]

Collaboration diagram for Formatter:

[legend]

Public Static Field Index:
static ALIB_API SPFormatter	Default

static ALIB_API threads::RecursiveLock	DefaultLock

Public Static Field Index: inherited from DbgCriticalSections
static ALIB_API const char *	ASSERTION_FORMAT

Public Field Index:
NumberFormat	AlternativeNumberFormat

NumberFormat	DefaultNumberFormat

SharedPtr< Formatter >	Next

Public Field Index: inherited from 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_API 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 DbgCriticalSections
ALIB_FORCE_INLINE	DbgCriticalSections (const char *name)

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

ALIB_API void	Acquire (const CallerInfo &ci) const

ALIB_API void	AcquireShared (const CallerInfo &ci) const

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

ALIB_API void	Release (const CallerInfo &ci) const

ALIB_API void	ReleaseShared (const CallerInfo &ci) const

ALIB_FORCE_INLINE 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 allocator

protected

This allocator is (exclusively) used for field boxes.

Definition at line 57 of file formatter.hpp.

◆ AlternativeNumberFormat

NumberFormat 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 112 of file formatter.hpp.

◆ boxes

BoxesMA boxes

protected

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

Definition at line 61 of file formatter.hpp.

◆ Default

SPFormatter 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 265 of file formatter.hpp.

◆ DefaultLock

threads::RecursiveLock DefaultLock

static

The lock to be set with multithreaded use of Default. If 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.

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

Definition at line 276 of file formatter.hpp.

◆ DefaultNumberFormat

NumberFormat 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 83 of file formatter.hpp.

◆ formatStringBuffer

AString formatStringBuffer

protected

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

Definition at line 64 of file formatter.hpp.

◆ Next

SharedPtr<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 120 of file formatter.hpp.

Constructor(s) / Destructor Details:

◆ Formatter()

Formatter ( )

inline

Default Constructor.

Definition at line 127 of file formatter.hpp.

◆ ~Formatter()

virtual ~Formatter ( )

inlinevirtual

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

Definition at line 141 of file formatter.hpp.

Method Details:

◆ Clone()

virtual SPFormatter 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 FormatterJavaStyle, and FormatterPythonStyle.

◆ CloneSettings()

void CloneSettings ( Formatter & reference )

virtual

Clones the settings from the given formatter.

Parameters

reference The formatter to copy settings from.

Definition at line 95 of file formatter.cpp.

Here is the call graph for this function:

◆ Format()

template<typename... TArgs>

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 164 of file formatter.hpp.

Here is the call graph for this function:

◆ format()

virtual int 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 FormatterStdImpl.

◆ FormatArgs() [1/2]

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 329 of file formatter.hpp.

Here is the call graph for this function:

◆ FormatArgs() [2/2]

template<typename TAllocator >

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 212 of file formatter.hpp.

Here is the call graph for this function:

◆ formatLoop()

template<typename TAllocator >

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.

◆ GetArgContainer()

virtual BoxesMA & 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 255 of file formatter.hpp.

◆ initializeFormat()

virtual void initializeFormat ( )

inlineprotectedvirtual

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

Reimplemented in FormatterPythonStyle.

Definition at line 287 of file formatter.hpp.

◆ Reset()

virtual BoxesMA & 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 FormatterPythonStyle.

Definition at line 247 of file formatter.hpp.

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

Description:

Friends

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()