alib::format Namespace Reference

Description:

This is the reference documentation module ALib Format.
Extensive documentation for this namespace is provided with the Programmer's Manual of that module.

Type Index:
struct	ByteSizeIEC
struct	ByteSizeSI
struct	FFormat
struct	FMTCallerInfo
class	Formatter
class	FormatterJavaStyle
class	FormatterPythonStyle
class	FormatterStdImpl
class	Paragraphs
class	PropertyFormatter
struct	PropertyFormatterMapAppendable
class	PropertyFormatters

Enumeration Index:
enum class	ByteSizeUnits : uint8_t {   IEC = 0 , B = 0 , KiB = 1 , MiB = 2 ,   GiB = 3 , TiB = 4 , PiB = 5 , EiB = 6 ,   ZiB = 7 , YiB = 8 , RiB = 9 , QiB = 10 ,   IEC_END = 11 , SI = 11 , B_SI = 11 , kB = 12 ,   MB = 13 , GB = 14 , TB = 15 , PB = 16 ,   EB = 17 , ZB = 18 , YB = 19 , RB = 20 ,   QB = 21 , SI_END = 22 }
enum class	FMTExceptions {   ArgumentIndexIs0 =11 , ArgumentIndexOutOfBounds =12 , IncompatibleTypeCode =13 , MissingClosingBracket =101 ,   MissingPrecisionValuePS =102 , DuplicateTypeCode =103 , UnknownTypeCode =104 , ExclamationMarkExpected =105 ,   UnknownConversionPS =106 , PrecisionSpecificationWithInteger =107 , MissingReplacementStrings =108 , NegativeValuesInBracketsNotSupported =201 ,   MissingPrecisionValueJS =202 , HexadecimalFloatFormatNotSupported =203 , NoAlternateFormOfConversion =204 , NoPrecisionWithConversion =205 ,   UnknownDateTimeConversionSuffix =206 , UnknownConversionJS =207 , UnknownPropertyInFormatString =501 , ErrorInResultingFormatString =502 ,   MissingConfigurationVariable =510 , UnknownMarker =601 , EndmarkerWithoutStart =602 }

Function Index:
void	FFormat_CallerInfo (const Box &self, const String &formatSpec, NumberFormat &nf, AString &target)
void	FFormat_DateTime (const Box &self, const String &formatSpec, NumberFormat &nf, AString &target)
void	FormatByteSize (AString &target, uinteger byteSize, uint16_t magnitudeThreshold, char unitSeparator, ByteSizeUnits unit, NumberFormat &nf)

Variable Index:
NumberFormat *	BYTESIZE_NUMBER_FORMAT

Enumeration Details:

ByteSizeUnits

enum class alib::format::ByteSizeUnits : uint8_t

strong

Enumeration of byte-size units to output with types ByteSizeIEC and ByteSizeSI.
The unit symbols are read from the resources of module class alib::BASECAMP. The list is given with resource name BS.

Enumerator
IEC	Begin of SI units.
B	2^ 0, Bbyte, factor 1.
KiB	2^ 10, Kibibyte, factor 1024.
MiB	2^ 20, Mebibyte, factor 1048576.
GiB	2^ 30, Gibibyte, factor 1073741824.
TiB	2^ 40, Tebibyte, factor 1099511627776.
PiB	2^ 50, Pebibyte, factor 1125899906842624.
EiB	2^ 60, Exbibyte, factor 1152921504606846976.
ZiB	2^ 70, Zebibyte, factor 1180591620717411303424.
YiB	2^ 80, Yobibyte, factor 1208925819614629174706176.
RiB	2^ 90, Robibyte, factor 1237940039285380274899124224.
QiB	2^100, Quebibyte, factor 1267650600228229401496703205376.
IEC_END	End of SI units.
SI	Begin of IEC units.
B_SI	2^ 0, Byte, factor 1.
kB	10^ 3, Kilobyte, factor 100.
MB	10^ 6, Megabyte, factor 100000.
GB	10^ 9, Gigabyte, factor 100000000.
TB	10^ 12, Terabyte, factor 100000000000.
PB	10^ 15, Petabyte, factor 100000000000000.
EB	10^ 18, Exabyte, factor 100000000000000000.
ZB	10^ 21, Zettabyte, factor 100000000000000000000.
YB	10^ 24, Yottabyte, factor 100000000000000000000000.
RB	10^ 27, Ronnabyte, factor 100000000000000000000000000.
QB	10^ 30, Quettabyte, factor 100000000000000000000000000000.
SI_END	END of IEC units.

Definition at line 14 of file bytesize.hpp.

FMTExceptions

enum class alib::format::FMTExceptions

strong

Enumeration of exceptions thrown with classes found in sub-namespace alib::format of module ALib Format.

Enumerator
ArgumentIndexIs0	Argument index '0' not allowed.
ArgumentIndexOutOfBounds	Argument index greater than number of arguments available.
IncompatibleTypeCode	Incompatible type code given argument type found.
MissingClosingBracket	Thrown by FormatterPythonStyle: Closing bracket '}' not found.
MissingPrecisionValuePS	Thrown by FormatterPythonStyle: Missing precision integral value after '.' character.
DuplicateTypeCode	Thrown by FormatterPythonStyle: Duplicate type code.
UnknownTypeCode	Thrown by FormatterPythonStyle: Unknown type code.
ExclamationMarkExpected	Thrown by FormatterPythonStyle: Expected '!' not found.
UnknownConversionPS	Thrown by FormatterPythonStyle: Unknown conversion after '!'.
PrecisionSpecificationWithInteger	Thrown by FormatterPythonStyle: Precision specification not allowed with integer types.
MissingReplacementStrings	Thrown by FormatterPythonStyle: Missing replacement strings after conversion !Replace.
NegativeValuesInBracketsNotSupported	Thrown by FormatterJavaStyle: Formatting of negative values in brackets is not supported.
MissingPrecisionValueJS	Thrown by FormatterJavaStyle: Missing precision integral value after '.' character.
HexadecimalFloatFormatNotSupported	Thrown by FormatterJavaStyle: Output of floating point values in hexadecimal format not supported.
NoAlternateFormOfConversion	Thrown by FormatterJavaStyle: The alternate form '#"'" is not supported with given conversion.
NoPrecisionWithConversion	Thrown by FormatterJavaStyle: Precision specification is not supported with given conversion.
UnknownDateTimeConversionSuffix	Thrown by FormatterJavaStyle: Unknown conversion suffix with data/time conversion.
UnknownConversionJS	Thrown by FormatterJavaStyle: Unknown conversion character.
UnknownPropertyInFormatString	Thrown by constructor of PropertyFormatter when a property identifier parsed from the format string has no corresponding entry in the TCallbackTable provided.
ErrorInResultingFormatString	Exception entry added in method void Format(AString&, const Box&)  when the underlying formatter throws.
MissingConfigurationVariable	Thrown by void Format(AString&, TVariables, TFormattable&)  if a configuration variable cannot be loaded or is empty. Note To prevent this, software using this class should provide resourced default values for each formatter variable.
UnknownMarker	Thrown by Paragraphs & AddMarked(const BoxedObjects& ...)  when an unknown marker token was found.
EndmarkerWithoutStart	Thrown by Paragraphs & AddMarked(const BoxedObjects& ...)  when a property identifier parsed from the format string has no corresponding entry in the TCallbackTable provided.

Definition at line 14 of file fmtexceptions.hpp.

Function Details:

FFormat_CallerInfo()

void alib::format::FFormat_CallerInfo	(	const Box &	self,
		const String &	formatSpec,
		NumberFormat &	nf,
		AString &	target )

Implementation of FFormat for boxable type FMTCallerInfo.
Writes the content of box (which is of type CallerInfo) to the given AString object target using a local instance of class FMTCallerInfo and its method AString & Format(Substring, AString&, lang::CurrentData) const.

If parameter formatSpec is empty, a default format string defined by string resource of key "FMTCI" is used. This resource by default evaluates to

"[@ sf:sl from ''ya'' by ''ta'']"

which results in the same output that is generated if an instance of class CallerInfo is simply appended to an AString, what in turn is defined with functor AppendableTraits<lang::CallerInfo, TChar, TAllocator>.

Parameters

self	The box that the function was invoked on.
formatSpec	The specification of the format.
nf	A copy of the number format of the formatter (allowed to be modified).
target	The AString object receiving the formatted string.

FFormat_DateTime()

void alib::format::FFormat_DateTime	(	const Box &	self,
		const String &	formatSpec,
		NumberFormat &	nf,
		AString &	target )

Implementation of FFormat for boxable type DateTime.
Writes the content of box (which is of type DateTime) to the given AString object target using a local instance of class CalendarDateTime and its method Format.

If parameter formatSpec is empty, a default format string defined by string resource of key "FMTDT" is used.

Note

This interface implementation is only available if modules ALib Strings and ALib Boxing are included in the ALib Build.

Parameters

self	The box that the function was invoked on.
formatSpec	The specification of the format.
nf	A copy of the number format of the formatter (allowed to be modified).
target	The AString object receiving the formatted string.

FormatByteSize()

void alib::format::FormatByteSize	(	AString &	target,
		uinteger	byteSize,
		uint16_t	magnitudeThreshold,
		char	unitSeparator,
		ByteSizeUnits	unit,
		NumberFormat &	nf )

This namespace function searches the next "fitting" magnitude of a given byteSize, so that it can be expressed as a floating point between 0 and 999, hence with three digits. The function is used for appending byte sizes to class AString. Helper-types ByteSizeIEC and ByteSizeSI allow the convenient use of this method in combination with AString objects and with parameter lists of ALib formatter functions. When using these helpers, singleton BYTESIZE_NUMBER_FORMAT is used.

Note

In the seldom case, that software has different threads, and more than one of those needs to format byte sizes in different number formats, the singleton approach is not feasible. This is the reason, why this method was exposed publicly instead of using an implementation in an anonymous namespace.

Parameters

target	The target string.
byteSize	The value to print.
magnitudeThreshold	The lowest value to use with the next lower possible magnitude. If, for example, to 900, then 0.9 GiB is preferred over 900.0 MiB.
unitSeparator	If not '\0', this character is printed after the number and before the unit.
unit	The unit system to convert to. This parameter must be set to either IEC or SI. Other values are undefined behavior.
nf	The number format object to use.

Variable Details:

BYTESIZE_NUMBER_FORMAT

NumberFormat* alib::format::BYTESIZE_NUMBER_FORMAT

extern

The NumberFormat singleton used with appending instances of structs ByteSizeIEC and ByteSizeSI to AString objects. The object is allocated in the GLOBAL_ALLOCATOR during bootstrapping.

Fields of interest here, are DecimalPointChar, which is copied during bootstrap from Global, and FractionalPartWidth which is set to 1 during bootstrap.