Description:

Implements a Formatter according to the formatting standards of the Java language .

Note: Inherited, public fields of parent class FormatterStdImpl provide important possibilities for changing the formatting behavior of instances of this class. Therefore, do not forget to consult the parent classes documentation.

In general, the original specification is covered quite well. The differences and specialties are:

In deviation of the Java specification, after creation, a formatter in this implementation does not produce locale-aware output. Instead, number formatting is set to "computational", hence the decimal point separator is '.' and the grouping character ','. As the syntax specification does not provide a feature to switch between standard and locale settings, the corresponding fields of AlternativeNumberFormat are not used with this formatter. Instead, to enable localized output, method NumberFormat::SetFromLocale has to be invoked on the inherited field DefaultNumberFormat. Alternatively, attributes of this object may be changed manually or by other means to reflect a desired locale.
Hexadecimal floating point output (conversion type 'a' and 'A') is not supported.
Flag '(', used to write negative numbers in round brackets, is not supported.
Addressing the previous argument index using '%<' is already allowed with the first placeholder. This Chooses the first argument. (In Java a MissingFormatArgumentException would be thrown.)
Flag '^' is an extension to the standard and denotes center-alignment - just like '-' in the standard denotes left-alignment. Right-alignment is the default.

p>

Floating point values:
- If standard field type 's' is given together with a precision, the field is cut, even if it cuts the number somewhere. (This is just a warning and same behavior as in original specification.)
- For lower case floating point format types ('f', 'g' and 'e'), the values specified in attributes ExponentSeparator, NANLiteral and INFLiteral of the inherited field AlternativeNumberFormat are used. For upper case types ('G' and 'E'), the corresponding attributes in the inherited field DefaultNumberFormat apply.
- Fixed point format ('f' ) is not supported to use arbitrary length. See class NumberFormat for the limits. Due to this limitation, the default number of fractional digits is not set with type 'f', while in Java it is set to 6. This is to allow higher numbers up to 1.e13 to be printed in non-scientific format
- When both, width and precision are given, then the precision determines the fractional part, even if the type is 'g' or 'G'. This is different from the corresponding specification of Java formatter, which uses precision as the overall width in the case of types 'g' or 'G'.

p>

Hexadecimal and Octal Numbers:
- Hexadecimal and octal output is cut in size (!) when a field width is given that is smaller than the resulting number of digits of the number arguments provided.
  Note
  This implies that a value written might not be equal to the value given. This is not a bug but a design decision. The rationale behind this is that with this behavior, there is no need to mask lower digits when passing the arguments to the format invocation. In other words, the formatter "assumes" that the given field width indicates that only a corresponding number of lower digits are of interest.
- If no width is given and the argument contains a boxed pointer, then the platform-dependent full output width of pointer types is used.
- The number grouping option (',') can also be used with binary, hexadecimal and octal output. The types support different grouping separators for nibbles, bytes, 16-bit and 32-bit words. Changing the separator symbols, is not possible with the format fields of the format strings (if it was, this would become very incompatible to Java standards). Changes have to be made before the format operation by modifying the field AlternativeNumberFormat which is provided through parent class Formatter.
- Alternative form ('#"')" adds prefixes as specified in members
  - HexLiteralPrefix and
  - OctLiteralPrefix.
  For upper case formats, those are taken from the inherited field DefaultNumberFormat, for lower case formats from AlternativeNumberFormat. The user may change all defaults.

p>

Time and Date:
- In this C++ version of the class, boxed values of type DateTime are applicable to conversion type 't'.
- The following time conversion suffix characters are supported: 'H', 'k', 'I', 'l', 'M', 'S', 'B', 'b', 'h', 'A', 'a', 'Y', 'y', 'm', 'd', 'e', 'R', 'T', 'D' and 'F'
- The following time conversion suffix characters are not supported: 'L', 'N', 'p', 'z', 'Z', 's', 'Q', 'C', 'j', 'r' and 'c'.

Reference Documentation

Exceptions

<b>alib::format::FMTExceptions</b>

Definition at line 115 of file formatterjavastyle.inl.

Inheritance diagram for alib::format::FormatterJavaStyle:

Inner Type Index:
struct	PlaceholderAttributesJS

Public Method Index:
	FormatterJavaStyle ()
virtual SPFormatter	Clone () override
Public Method Index: inherited from alib::format::FormatterStdImpl
	FormatterStdImpl (const String &formatterClassName)
Public Method Index: inherited from alib::format::Formatter
	Formatter ()
	Default Constructor.
virtual	~Formatter ()
virtual 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.
void	Acquire (const CallerInfo &ci) const
void	AcquireShared (const CallerInfo &ci) const
void	doAssert (bool cond, const CallerInfo &ciAssert, const CallerInfo &ci, const char *headline) const
void	Release (const CallerInfo &ci) const
void	ReleaseShared (const CallerInfo &ci) const
void	yieldOrSleep () const

Protected Field Index:
PlaceholderAttributesJS	placeholderJS
	The extended placeholder attributes.
Protected Field Index: inherited from alib::format::FormatterStdImpl
int	argOffset
	The offset of the first argument to use. Provided with method Format.
int	argsConsumed
	The number of arguments consumed by the current format string.
bool	argumentCountStartsWith1
const BoxesMA *	arguments
	The list of arguments provided with method Format.
AString	fieldBuffer
	A string buffer, used for example, when writing aligned fields.
String	formatString
	The format string as provided with method Format.
const String	formatterName
int	nextAutoIdx
	Counter for auto-indexed arguments.
Substring	parser
	The current (remaining) format string.
PlaceholderAttributes	placeholder
AString *	targetString
	The target string as provided with method Format.
integer	targetStringStartLength
	The length of the target string before adding the formatted contents.
Protected Field Index: inherited from alib::format::Formatter
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 bool	checkStdFieldAgainstArgument () override
virtual integer	findPlaceholder () override
virtual bool	parsePlaceholder () override
virtual bool	parseStdFormatSpec () override
virtual bool	preAndPostProcess (integer startIdx, AString *target) override
virtual void	resetPlaceholder () override
virtual void	writeStringPortion (integer length) override
Protected Method Index: inherited from alib::format::FormatterStdImpl
virtual int	format (AString &targetString, const String &formatString, const BoxesMA &arguments, int argOffset) override
virtual bool	setArgument (int pos)
virtual bool	writeCustomFormat ()
virtual void	writeStdArgument ()
Protected Method Index: inherited from alib::format::Formatter
template<typename TAllocator>
Formatter &	formatLoop (AString &target, const boxing::TBoxes< TAllocator > &args)
virtual ALIB_DBG_PREVENT_RECURSIVE_METHOD_CALLS_MEMBER_DECL void	initializeFormat ()

Additional Inherited Members
Public Type Index: inherited from alib::format::FormatterStdImpl
enum class	PHTypes { NotGiven , String , Character , IntBase10 , IntBinary , IntOctal , IntHex , Float , Bool , HashCode , Fill }
	Denotes the type of placeholders (respectively the values they represent). More...
Public Static Field Index: inherited from alib::format::Formatter
static SPFormatter	DEFAULT
static threads::RecursiveLock	DEFAULT_LOCK
Public Static Field Index: inherited from alib::lang::DbgCriticalSections
static const char *	ASSERTION_FORMAT
Public Field Index: inherited from alib::format::Formatter
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
Protected Static Method Index: inherited from alib::format::Formatter
static void	writeStringPortion (AString &target, const String &escaped)

Field Details:

◆ placeholderJS

PlaceholderAttributesJS alib::format::FormatterJavaStyle::placeholderJS

protected

The extended placeholder attributes.

Definition at line 144 of file formatterjavastyle.inl.

Constructor(s) / Destructor Details:

◆ FormatterJavaStyle()

alib::format::FormatterJavaStyle::FormatterJavaStyle ( )

Constructs this formatter. Inherited field DefaultNumberFormat is initialized to meet the formatting defaults of Java.

Definition at line 38 of file formatterjavastyle.cpp.

Method Details:

◆ checkStdFieldAgainstArgument()

bool alib::format::FormatterJavaStyle::checkStdFieldAgainstArgument ( )

overrideprotectedvirtual

Makes some attribute adjustments and invokes standard implementation

Returns: true if OK, false if replacement should be aborted.

Reimplemented from alib::format::FormatterStdImpl.

Definition at line 404 of file formatterjavastyle.cpp.

◆ Clone()

SPFormatter alib::format::FormatterJavaStyle::Clone ( )

overridevirtual

Clones and returns a copy of this formatter.

If the formatter attached to field SharedPtr< Formatter > Next is of type FormatterStdImpl, then that formatter is copied as well.

Returns: An object of type FormatterPythonStyle and with the same custom settings than this.

Implements alib::format::Formatter.

Definition at line 60 of file formatterjavastyle.cpp.

◆ findPlaceholder()

integer alib::format::FormatterJavaStyle::findPlaceholder ( )

overrideprotectedvirtual

Searches for '%' which is not '%' or 'n'.

Returns: The index found, -1 if not found.

Implements alib::format::FormatterStdImpl.

Definition at line 94 of file formatterjavastyle.cpp.

◆ parsePlaceholder()

bool alib::format::FormatterJavaStyle::parsePlaceholder ( )

overrideprotectedvirtual

Parses placeholder field in Java syntax. The portion format_spec is not set as this is not supported by the syntax.

Returns: true on success, false on errors.

Implements alib::format::FormatterStdImpl.

Definition at line 161 of file formatterjavastyle.cpp.

◆ parseStdFormatSpec()

virtual bool alib::format::FormatterJavaStyle::parseStdFormatSpec ( )

inlineoverrideprotectedvirtual

Does nothing. Java does not support custom format specifications.

Returns: true to indicate success.

Implements alib::format::FormatterStdImpl.

Definition at line 194 of file formatterjavastyle.inl.

◆ preAndPostProcess()

bool alib::format::FormatterJavaStyle::preAndPostProcess	(	integer	startIdx,
		AString *	target )

overrideprotectedvirtual

All that this formatter does with this overridden method is to convert strings to upper case.

Parameters

startIdx	The index of the start of the field written in targetString. `-1` indicates pre-phase.
target	The target string, only if different from field targetString, which indicates intermediate phase.

Returns: false, if the placeholder should be skipped (nothing is written for it). true otherwise.

Reimplemented from alib::format::FormatterStdImpl.

Definition at line 397 of file formatterjavastyle.cpp.

◆ resetPlaceholder()

void alib::format::FormatterJavaStyle::resetPlaceholder ( )

overrideprotectedvirtual

Invokes parent implementation and then applies some changes to reflect what is defined as default in the Java string format specification.

Reimplemented from alib::format::FormatterStdImpl.

Definition at line 76 of file formatterjavastyle.cpp.

◆ writeStringPortion()

void alib::format::FormatterJavaStyle::writeStringPortion ( integer length )

overrideprotectedvirtual

Implementation of abstract method virtual void writeStringPortion(integer) =0.
Replaces "%%" with '%' and "%n" with ascii 0x0a. In addition applies Escape on target which replaces standard codes like "\\n", "\\r" or "\\t" with corresponding ascii codes. (The latter is an extension to the standard behavior of Java formatter.)

Parameters

length The number of characters to write.

Implements alib::format::FormatterStdImpl.

Definition at line 107 of file formatterjavastyle.cpp.

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

Description:

Reference Documentation

Inner Type Index:

Public Method Index:

Protected Field Index:

Protected Method Index:

Additional Inherited Members

Field Details:

◆ placeholderJS

Constructor(s) / Destructor Details:

◆ FormatterJavaStyle()

Method Details:

◆ checkStdFieldAgainstArgument()

◆ Clone()

◆ findPlaceholder()

◆ parsePlaceholder()

◆ parseStdFormatSpec()

◆ preAndPostProcess()

◆ resetPlaceholder()

◆ writeStringPortion()