alib::lang::format Namespace Reference

Description:

This is the reference documentation of sub-namespace format of module ALib BaseCamp .

Extensive documentation for this namespace is provided with chapter 4. Namespace alib::lang::format of the Programmer's Manual of that module.

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

Enumeration Index:
enum	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:
ALIB_API void	FormatByteSize (AString &target, uinteger byteSize, uint16_t magnitudeThreshold, char unitSeparator, ByteSizeUnits unit, NumberFormat &nf)

Variable Index:
NumberFormat *	ByteSizeNumberFormat = nullptr

Enumeration Details:

ByteSizeUnits

enum ByteSizeUnits : uint8_t

Enumeration of byte-size units to output with types ByteSizeIEC and ByteSizeSI .
The unit symbols are read from the resources of module class 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 46 of file bytesize.hpp.

FMTExceptions

enum class FMTExceptions

strong

---

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

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 PropertyFormatter::Format when the underlying formatter throws.
MissingConfigurationVariable	Thrown by PropertyFormatters::Format if a configuration variable can not 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 when an unknown marker token was found.
EndmarkerWithoutStart	Thrown by Paragraphs::AddMarked when a property identifier parsed from the format string has no corresponding entry in the TCallbackTable provided.

Definition at line 22 of file fmtexceptions.hpp.

Function Details:

FormatByteSize()

ALIB_API void 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 to class AString. Helper types ByteSizeIEC and ByteSizeSI allow the convient use of this method in combination with AString objects and with parameter lists of ALib formatter functions. When using these helpers, singleton ByteSizeNumberFormat is used.

Note

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

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 behaviour.
nf	The number format object to use.

Variable Details:

ByteSizeNumberFormat

NumberFormat * ByteSizeNumberFormat = nullptr

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

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

Definition at line 139 of file basecamp.cpp.