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

#include <formatter.hpp>

Inheritance diagram for Formatter:

[legend]

Collaboration diagram for Formatter:

[legend]

Public Static Method Index:
static SPFormatter	AcquireDefault (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)

static SPFormatter	GetDefault ()

Public Field Index:
NumberFormat	AlternativeNumberFormat

NumberFormat	DefaultNumberFormat

std::shared_ptr< Formatter >	Next

Public Field Index: inherited from ThreadLock
NCString	DbgOwnerFile =nullptr

NCString	DbgOwnerFunc =nullptr

int	DbgOwnerLine

uint16_t	DbgRecursionWarningThreshold =10

integer	DbgWarningAfterWaitTimeInMillis =2000L

Public Method Index:
virtual	~Formatter ()

ALIB_API Boxes &	Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)

virtual Formatter *	Clone ()=0

virtual ALIB_API void	CloneSettings (Formatter &reference)

int	CountAcquirements () const

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

ALIB_API Formatter &	FormatArgs (AString &target)

Formatter &	FormatArgs (AString &target, const Boxes &args)

ALIB_API void	Release ()
	defined(ALIB_DOX)

ALIB_API void	ReplaceDefault (Formatter *newFormatter)

Public Method Index: inherited from ThreadLock
ALIB_API	ThreadLock (lang::Safeness safeness=lang::Safeness::Safe)

ALIB_API	~ThreadLock ()

ALIB_API void	Acquire (const NCString &dbgFile, int dbgLine, const NCString &dbgFunc)

int	CountAcquirements () const

Thread *	GetOwner () const

lang::Safeness	GetSafeness () const

bool	IsOwnedByCurrentThread () const

ALIB_API void	Release ()
	defined(ALIB_DOX)

ALIB_API void	SetSafeness (lang::Safeness safeness)

bool	WillRelease () const

Field Details:

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

◆ boxes

Boxes boxes

protected

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

Definition at line 78 of file formatter.hpp.

◆ defaultFormatter

SPFormatter defaultFormatter

staticprotected

A static singleton instance which is received with GetDefault.

Definition at line 325 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 102 of file formatter.hpp.

◆ formatStringBuffer

AString formatStringBuffer

protected

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

Definition at line 81 of file formatter.hpp.

◆ Next

std::shared_ptr<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 143 of file formatter.hpp.

Constructor(s) / Destructor Details::

◆ ~Formatter()

virtual ~Formatter ( )

inlinevirtual

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

Definition at line 154 of file formatter.hpp.

Method Details:

◆ Acquire()

ALIB_API Boxes & Acquire	(	const NCString &	dbgFile,
		int	dbgLine,
		const NCString &	dbgFunc )

Overrides (non-virtual) ThreadLock::Acquire .

This method checks if this was the first acquisition and if so, invokes method reset. Therefore, a series of formatting calls may be performed without resetting the internal state, by acquiring the object once prior to the series of invocations and releasing it afterwards.

Furthermore, this method invokes itself on potentially attached formatter Next (recursion).

This method is inherently called by convenience method Format that accepts variadic arguments and hence no explicit invocation is needed in this case.

Acquiring this formatter is mandatory with overloaded methods FormatArgs.

Multiple (nested) acquirements by the same execution thread are allowed. A corresponding amount of invocations to Release have to be made.

Note

In the debug-compilation of an application, this method accepts the parameters, providing information about the caller. In the release version these parameters do not exist. Therefore use macro ALIB_CALLER_PRUNED to provide the parameters:

   sample.Acquire( ALIB_CALLER_PRUNED );

Parameters

dbgFile	Caller information. Available only with debug builds.
dbgLine	Caller information. Available only with debug builds.
dbgFunc	Caller information. Available only with debug builds.

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

◆ AcquireDefault()

static SPFormatter AcquireDefault	(	const NCString &	dbgFile,
		int	dbgLine,
		const NCString &	dbgFunc )

inlinestatic

Same as GetDefault, also acquires the formatter before it is returned. the reference.

Parameters

dbgFile	Caller information. Available only with debug builds.
dbgLine	Caller information. Available only with debug builds.
dbgFunc	Caller information. Available only with debug builds.

Returns: A shared pointer containing the default formatter, already acquired.

Definition at line 357 of file formatter.hpp.

◆ Clone()

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

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 137 of file formatter.cpp.

Here is the call graph for this function:

◆ CountAcquirements()

int CountAcquirements ( ) const

inline

Returns the number of acquirements of this formatter.

Note: Usually this method is inherited from base clas ThreadLock and therefore not defined. However, in the absence of module ALib Threads in an ALib Distribution , this method is re-implemented with this type.

Returns: The number of (recursive) acquirements.

Definition at line 212 of file formatter.hpp.

◆ format()

virtual int format	(	AString &	target,
		const String &	formatString,
		const Boxes &	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.

◆ Format()

template<typename... TArgs>

Formatter & Format	(	AString &	target,
		TArgs &&...	args )

inline

ALIB_THREADS.

Variadic template method that accepts a target AString and a list of arguments.

This is a convenience method to allow single-line format invocations. No calls to methods Acquire and Release are needed to be performed.

Note: This method uses static_assert to disallow the invocation with one variadic argument of type Boxes 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 240 of file formatter.hpp.

Here is the call graph for this function:

◆ FormatArgs() [1/2]

ALIB_API Formatter & FormatArgs ( AString & target )

inline

Formats the internal list of arguments that iis returned when acquiring access to this formatter with Acquire.

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

Format arguments can not be collected in a single invocation, for example if those are to be collected in a loop.
Multiple format operations (invocations of this method) are to be performed in a row. In this case, only a single call to Acquire and Release 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 276 of file formatter.hpp.

Here is the call graph for this function:

◆ FormatArgs() [2/2]

Formatter & FormatArgs	(	AString &	target,
		const Boxes &	args )

inline

Same as Format(AString&) but allows to specify an external list of arguments instead of the internally allocated object, which is returned by method Acquire.

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

Here is the call graph for this function:

◆ formatLoop()

Formatter & formatLoop	(	AString &	target,
		const Boxes &	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.

Definition at line 83 of file formatter.cpp.

Here is the call graph for this function:

◆ GetDefault()

static SPFormatter GetDefault ( )

inlinestatic

Returns the default formatter object. With the module initialization (method BaseCamp::bootstrap ), an object of type FormatterPythonStyle is created and a second

one of type FormatterJavaStyle is appended. Those formatters will be deleted with BaseCamp::shutdown , respectively when a different default formatter is set (see ReplaceDefault) and no other shared pointer of the original one exists.

Returns: A shared pointer containing the default formatter.

Definition at line 341 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 391 of file formatter.hpp.

◆ Release()

void Release ( )

defined(ALIB_DOX)

Overrides (non-virtual) ThreadLock::Release , which is called. In addition, the method is called on potentially attached formatter Next (recursion).

Definition at line 70 of file formatter.cpp.

Here is the call graph for this function:

◆ ReplaceDefault()

ALIB_API void ReplaceDefault ( Formatter * newFormatter )

Replaces the formatter currently defined as the default formatter.

See also: Static methods GetDefault and AcquireDefault.

Parameters

newFormatter The replacement formatter.

◆ reset()

virtual void reset ( )

inlineprotectedvirtual

Virtual method to used to reset internal states. This method is invoked only with the first acquisition of a formatter. This way, reset of internal states can be suppressed over a series of format calls by acquiring the formatter explicitly prior to the series.

As a sample, derived type FormatterPythonStyle clears its auto-tab and auto-width positions.

The default implementation does nothing.

Reimplemented in FormatterPythonStyle.

Definition at line 406 of file formatter.hpp.

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

Description:

Friends

Public Static Method Index:

Public Field Index:

Public Method Index:

Field Details:

◆ AlternativeNumberFormat

◆ boxes

◆ defaultFormatter

◆ DefaultNumberFormat

◆ formatStringBuffer

◆ Next

Constructor(s) / Destructor Details::

◆ ~Formatter()

Method Details:

◆ Acquire()

◆ AcquireDefault()

◆ Clone()

◆ CloneSettings()

◆ CountAcquirements()

◆ format()

◆ Format()

◆ FormatArgs() [1/2]

◆ FormatArgs() [2/2]

◆ formatLoop()

◆ GetDefault()

◆ initializeFormat()

◆ Release()

◆ ReplaceDefault()

◆ reset()