Description:

template<typename TChar>
struct alib::strings::TNumberFormat< TChar >

This struct defines flags and values that denote the format of conversion of integer and floating point values to string representations, as well as the reverse operation, thus the format expected when parsing numbers from strings.

In namespace alib::strings::detail, corresponding functions that use an instance of this type are implemented. However, those functions are not intended for common use. Instead, the interface of classes String, Substring, AString or Formatter are preferred to write and parse numbers. Also those accept an object of this type as parameters.

Defined Singletons and User-Defined Instances:
Two static singletons of this class, both initialized with function Bootstrap, are defined which can be used wherever a number format object is needed as a parameter:

Global: Reflects locale-specific settings.
Computational:
Intended to be used for writing and parsing numbers which are readable by software (not humans). Its decimal point character is set to '.', the international standard. Furthermore no group separators are set for decimal and decimal floating point as well as for binary, hexadecimal and octal conversions.

Any user-defined object defaults to the computational setting after construction.

Output Formats:
The following conversion formats are supported:

Decimal
Supports optional minimum output width with field DecMinimumFieldWidth, and definable thousands grouping character with field ThousandsGroupChar, which can be activated with field WriteGroupChars.
Furthermore, the plus-sign can be controlled (PlusSign) to be either omitted or be anything defined. Of course, values ' ' and '+' are reasonable options.
Binary
Binary output supports up to 64 digits and different group separators for nibbles, bytes, 16-bit words and 32 bit words. (See BinNibbleGroupChar, BinByteGroupChar, BinWordGroupChar and BinWord32GroupChar ).
When parsing integers, a customizable literal string defined in BinLiteralPrefix might be used to auto-detect binary values.
Hexadecimal
Hexadecimal output supports up to 16 digits (64-bit) and different group separators for bytes, 16-bit words and 32 bit words. (See HexByteGroupChar, HexWordGroupChar, and HexWord32GroupChar). When parsing integers, a customizable literal string defined in HexLiteralPrefix might be used to auto-detect hexadecimal values.
Octal
Octal output supports up to 22 digits (64-bit) and different a group separator for groups of three digits defined with OctGroupChar. When parsing integers, a customizable literal string defined in OctLiteralPrefix might be used to auto-detect hexadecimal values.
Floating Point
The width of the output is provided in two fields, IntegralPartMinimumWidth and FractionalPartWidth. While the integral part is a minimum width (and nothing is ever cut), the fractional part denotes a fixed width. Values with higher fractional precision are rounded accordingly. Note that the parameter of the interface functions that may override the width, in the floating point case only affects the minimum width of the integral part.
The integral and fractional part of float values are separated by decimalPointChar. This field of course has to be different from group separator ThousandsGroupChar, which can be activated using field WriteGroupChars.
Other important fields used for writing and parsing floats are: ExponentSeparator, INFLiteral, NANLiteral, WriteExponentPlusSign, and ForceScientific.

Notes on Writing and Parsing Values:
For decimal output, the width (DecMinimumFieldWidth) is a minimum width. This means, that bigger numbers are written in a higher width.

Attention: This is not true for binary, hexadecimal and octal output. In these formats, the width provided with fields BinFieldWidth, HexFieldWidth and OctFieldWidth, denote an absolute value. Higher digits of numbers are not written! The advantage of this design is that no masking is needed when just the lower part of an integer number should be written. However, if a width is set, values might of course change when cut and parsed back later!

All of the integral formats have in common that the output width given includes optional grouping characters. For example if a width of 5 was given for decimal output, the value 12 would be written "0,012", hence 4 digits plus the grouping character. If grouping was disabled, the output became "00012", which uses one extra digit instead of the group character. In contrast to that, sign characters are not counted in the width.

When parsing values, grouping characters are ignored at any position within the digits, except of the start. The same is true for whitespace characters as defined in Whitespaces. When this field is nulled or empty, then white spaces are not ignored. This might be helpful in some cases where occurrence of white space characters should indicate an error (or something else) when parsing. Otherwise, the characters defined in this field are ignored at two places: at the beginning of a parsing operation and after a sign character was read.

When parsing fails, a value of 0 (respectively 0.0) is returned by the functions of namespace alib::strings::detail which are using this class. User-friendly classes that use the interface of this type will detect such failure through the output parameter of the parsing functions, which indicates the index of the end of the number found.

For each of the four integer formats, decimal, binary, hexadecimal and octal, dedicated parsing functions exist. Those do not accept literal prefix identifiers as defined in fields BinLiteralPrefix, HexLiteralPrefix and OctLiteralPrefix. However, the prefixes are identified by function ParseInt, which aggregates the other four parsing functions.
There is no corresponding function defined that writes the literal prefix. When writing binary, hexadecimal or octal values, such prefixes have to be prepended explicitly by a user's code.

Template Parameters

TChar The character type that this class works on. Alias names for specializations using the different character types are provided in namespace alib with type definitions NumberFormat, NNumberFormat, WNumberFormat, XNumberFormat, ComplementNumberFormat, and StrangeNumberFormat.

Definition at line 202 of file numberformat.hpp.

#include <numberformat.hpp>

Collaboration diagram for TNumberFormat< TChar >:

[legend]

Public Static Field Index:
static TNumberFormat	Computational

static TNumberFormat	Global

Public Field Index:
TChar	BinByteGroupChar

int8_t	BinFieldWidth

TCString< TChar >	BinLiteralPrefix

TChar	BinNibbleGroupChar

TChar	BinWord32GroupChar

TChar	BinWordGroupChar

TChar	DecimalPointChar

int8_t	DecMinimumFieldWidth

TCString< TChar >	ExponentSeparator

NumberFormatFlags	Flags
	The flag field.

int8_t	FractionalPartWidth

TChar	HexByteGroupChar

int8_t	HexFieldWidth

TCString< TChar >	HexLiteralPrefix

TChar	HexWord32GroupChar

TChar	HexWordGroupChar

TCString< TChar >	INFLiteral
	Defines what is written and parsed for infinite double values.

int8_t	IntegralPartMinimumWidth

TChar	LeadingGroupCharReplacement

TCString< TChar >	NANLiteral
	Defines what is written and parsed for double values that represent "not a number".

int8_t	OctFieldWidth

TChar	OctGroupChar

TCString< TChar >	OctLiteralPrefix

TChar	PlusSign

TChar	ThousandsGroupChar

TCString< TChar >	Whitespaces

Public Method Index:
	TNumberFormat ()
	Default constructor. Invokes SetComputational to reset all fields to their default values.

void	Set (TNumberFormat *other=nullptr)

void	SetComputational ()

void	SetFromLocale ()

Field Details:

◆ BinByteGroupChar

template<typename TChar >

TChar BinByteGroupChar

Defines the separator character for bytes of binary numbers. Defaults to '\0' what chooses BinNibbleGroupChar.

Definition at line 307 of file numberformat.hpp.

◆ BinFieldWidth

template<typename TChar >

int8_t BinFieldWidth

Defines the digits written when writing binary values. If the value has less digits, then leading '0' digits are added. If it has more, than those digits are NOT written (!).
The default value and minimum value is -1, which writes as many bits as necessary.

Definition at line 383 of file numberformat.hpp.

◆ BinLiteralPrefix

template<typename TChar >

TCString<TChar> BinLiteralPrefix

Used by function ParseInt to detect binary format of integral values. If nulled, no binary format is detected. Functions provided with ALib are not writing the prefix. If this is desired, it has to be performed explicitly by the user code.
Defaults to "0b".

Definition at line 252 of file numberformat.hpp.

◆ BinNibbleGroupChar

template<typename TChar >

TChar BinNibbleGroupChar

Defines the separator character for nibbles (4 bits) of binary numbers. Defaults to '\0' what disables reading and writing of nibble group characters.

Definition at line 303 of file numberformat.hpp.

◆ BinWord32GroupChar

template<typename TChar >

TChar BinWord32GroupChar

Defines the separator character for 32-bit words of binary numbers. Defaults to '\0' what chooses BinWordGroupChar.

Definition at line 315 of file numberformat.hpp.

◆ BinWordGroupChar

template<typename TChar >

TChar BinWordGroupChar

Defines the separator character for 16-bit words of binary numbers. Defaults to '\0' what chooses BinByteGroupChar.

Definition at line 311 of file numberformat.hpp.

◆ Computational

template<typename TChar >

TNumberFormat Computational

static

A static number format object that may be used to write and parse numbers for 'computational' use, which means, that grouping is switched off and decimal point character is '.'.
Function Bootstrap invokes SetComputational on this object.

Classes providing functionality based on this class, might use this as a default value for parameters of their interfaces.

Definition at line 220 of file numberformat.hpp.

◆ DecimalPointChar

template<typename TChar >

TChar DecimalPointChar

Defines the decimal point character when converting a floating point number to a string representation with function WriteFloat. Also; function ParseFloat uses the character provided in this field for parsing the character.
The field defaults to '.'. By invoking SetFromLocale(), the current locale's setting is determined.

Definition at line 275 of file numberformat.hpp.

◆ DecMinimumFieldWidth

template<typename TChar >

int8_t DecMinimumFieldWidth

Defines the minimum digits and grouping symbols written when writing integers in decimal. format. If the value to write has less digits (and grouping symbols), then leading '0' digits (and eventually grouping symbols) are added.
If the value to write has more digits, then this field is ignored. A sign character is not calculated into the writing width. To have negative and positive numbers resulting in the same width, PlusSign has to be set to a value unequal to '\0' (usually space character ' ' or '+').

If this field is negative, it is ignored. Defaults to -1.

Definition at line 377 of file numberformat.hpp.

◆ ExponentSeparator

template<typename TChar >

TCString<TChar> ExponentSeparator

Defines the decimal exponent symbol of string representations of floating point numbers when written or parsed in scientific notation by functions ParseFloat and WriteFloat.
Function ParseFloat accepts characters 'e' and 'E' in addition to the character set in this field.
Defaults to 'E'.

Definition at line 239 of file numberformat.hpp.

◆ Flags

template<typename TChar >

NumberFormatFlags Flags

The flag field.

Definition at line 334 of file numberformat.hpp.

◆ FractionalPartWidth

template<typename TChar >

int8_t FractionalPartWidth

Defines the number of digits written for the fractional part when converting a floating point value into a string. (For integer conversion, see DecMinimumFieldWidth.)
If the fractional part of the number provided has less digits then trailing '0' digits are added.
If the fractional part of the number provided has more digits then the fractional part is rounded accordingly.
The maximum value allowed is 15.
The default value is -1, which writes as many digits as available in the provided float variable, with a minimum of 1 digit.

When either this field or field IntegralPartMinimumWidth is set to a positive value, the limits to switch to scientific notation, which otherwise are fixed 10E-04 and 10E+06, get extended. Function WriteFloat in this case keeps non-scientific notation established if possible.

Definition at line 366 of file numberformat.hpp.

◆ Global

template<typename TChar >

TNumberFormat Global

static

The default static number format object that acts as the default settings of the currently running process.
Function Bootstrap invokes SetFromLocale() on this object and switches grouping to 'on'.

Classes providing functionality based on this class, might use this as a default value for parameters of their interfaces.

Definition at line 211 of file numberformat.hpp.

◆ HexByteGroupChar

template<typename TChar >

TChar HexByteGroupChar

Defines the separator character for bytes of hexadecimal numbers. Defaults to 0, Defaults to '\0' what disables reading and writing of byte group characters.

Definition at line 319 of file numberformat.hpp.

◆ HexFieldWidth

template<typename TChar >

int8_t HexFieldWidth

Defines the digits written when writing hexadecimal values. If the value has less digits, then leading '0' digits are added. If it has more, than those digits are NOT written (!).
The default value and minimum value is -1, which writes as many bits as necessary.

Definition at line 389 of file numberformat.hpp.

◆ HexLiteralPrefix

template<typename TChar >

TCString<TChar> HexLiteralPrefix

Used by function ParseInt to detect hexadecimal format of integer values. If nulled, no hexadecimal format is detected. Functions provided with ALib are not writing the prefix. If this is desired, it has to be performed explicitly by the user code.
Defaults to "0x".

Definition at line 259 of file numberformat.hpp.

◆ HexWord32GroupChar

template<typename TChar >

TChar HexWord32GroupChar

Defines the separator character for 32-bit words of hexadecimal numbers. Defaults to '\0' what chooses HexWordGroupChar.

Definition at line 327 of file numberformat.hpp.

◆ HexWordGroupChar

template<typename TChar >

TChar HexWordGroupChar

Defines the separator character for 16-bit words of hexadecimal numbers. Defaults to '\0' what chooses HexByteGroupChar.

Definition at line 323 of file numberformat.hpp.

◆ INFLiteral

template<typename TChar >

TCString<TChar> INFLiteral

Defines what is written and parsed for infinite double values.

Definition at line 242 of file numberformat.hpp.

◆ IntegralPartMinimumWidth

template<typename TChar >

int8_t IntegralPartMinimumWidth

Defines the minimum digits written for the integral part when converting a floating point value into a string.
If the integral part of the number provided has less digits then leading '0' digits are added.
The maximum value allowed is 15.
A value of 0 leads to omitting the '0' before the decimal separator in the case the value is below 1.0 and higher than -1.0
The default value is -1, which writes a minimum of 1 digit.

When either this field or field FractionalPartWidth is set to a positive value, the limits to switch to scientific notation, which otherwise are fixed 10E-04 and 10E+06, get extended. Function WriteFloat in this case keeps non-scientific notation established if possible.

Definition at line 350 of file numberformat.hpp.

◆ LeadingGroupCharReplacement

template<typename TChar >

TChar LeadingGroupCharReplacement

This character is written instead of a grouping character in the case that a certain output width is requested but a grouping character would be the first character to write. Writing this character instead, ensures the field width to be as requested. Defaults to space (' ').

Definition at line 298 of file numberformat.hpp.

◆ NANLiteral

template<typename TChar >

TCString<TChar> NANLiteral

Defines what is written and parsed for double values that represent "not a number".

Definition at line 245 of file numberformat.hpp.

◆ OctFieldWidth

template<typename TChar >

int8_t OctFieldWidth

Defines the digits written when writing hexadecimal values. If the value has less digits, then leading '0' digits are added. If it has more, than those digits are NOT written (!).
The default value and minimum value is -1, which writes as many bits as necessary.

Definition at line 396 of file numberformat.hpp.

◆ OctGroupChar

template<typename TChar >

TChar OctGroupChar

Defines the separator character for bytes of hexadecimal numbers. Defaults to '\0' what disables reading and writing of byte group characters.

Definition at line 331 of file numberformat.hpp.

◆ OctLiteralPrefix

template<typename TChar >

TCString<TChar> OctLiteralPrefix

Used by function ParseInt to detect octal format of integral values. If nulled, no octal format is detected. Functions provided with ALib are not writing the prefix. If this is desired, it has to be performed explicitly by the user code.
Defaults to "0o".

Definition at line 266 of file numberformat.hpp.

◆ PlusSign

template<typename TChar >

TChar PlusSign

Determines if positive values are prepended with an explicit character (usually '+') when written using WriteFloat or WriteDecSigned.
Defaults to 0 which omits the writing. Usual other values are of course '+', but also ' ' (space) which supports better horizontal alignment of numbers when written in columns. Note that this is not affecting exponent decimals of floating point values. For those, see WriteExponentPlusSign

Definition at line 283 of file numberformat.hpp.

◆ ThousandsGroupChar

template<typename TChar >

TChar ThousandsGroupChar

Defines the separator character for thousands when converting a number to a string representation. In addition, this is used to identify grouping symbols when parsing decimal values. If set to '\0', no group separator is written and also when parsing, a group separator is not accepted. If set, still WriteGroupChars controls if it is written.
Defaults to ','. By invoking SetFromLocale(), the current locale's setting is determined.

Definition at line 292 of file numberformat.hpp.

◆ Whitespaces

template<typename TChar >

TCString<TChar> Whitespaces

Defines whitespace characters that are ignored when leading the number and after the sign-character. Applies to functions ParseInt and ParseFloat. In contrast, functions ParseDec, ParseBin, ParseHex, and ParseOct do not ignore any whitespace characters.

Definition at line 231 of file numberformat.hpp.

Constructor(s) / Destructor Details:

◆ TNumberFormat()

template<typename TChar >

TNumberFormat ( )

inline

Default constructor. Invokes SetComputational to reset all fields to their default values.

Definition at line 406 of file numberformat.hpp.

Here is the call graph for this function:

Method Details:

◆ Set()

template<typename TChar >

void Set ( TNumberFormat< TChar > * other = nullptr )

Copies all fields (settings) from the given object. If no object is provided, values of the static singleton found in field Global are copied

Parameters

other The NumberFormat object to copy the values from. Defaults to nullptr, which chooses the global singleton.

◆ SetComputational()

template<typename TChar >

void SetComputational ( )

Resets the object to its default values. This method is called in the constructor.

Decimal point character and grouping characters are set as follows:

Field	Value
DecimalPointChar	.
ThousandsGroupChar	,
BinNibbleGroupChar	`'`
BinByteGroupChar	`-`
BinWordGroupChar	`' '` (space)
BinWord32GroupChar	`#`
HexWordGroupChar	`'`
HexWord32GroupChar	`'`
HexByteGroupChar	`0` (none)
OctGroupChar	`'`

The literal attributes are set as follows:

Field	Value
ExponentSeparator	`"E"`
INFLiteral	`"INF"`
NANLiteral	`"NAN"`
BinLiteralPrefix	`"0b"`
HexLiteralPrefix	`"0x"`
OctLiteralPrefix	`"0o"`

All width-attributes are reset to "automatic mode", -1. The attributes are IntegralPartMinimumWidth, FractionalPartWidth, DecMinimumFieldWidth, BinFieldWidth, HexFieldWidth and OctFieldWidth.

Finally, the following further fields are reset to their default values:

Field	Value
WriteGroupChars	`false`
ForceScientific	`false`
ForceDecimalPoint	`true`
PlusSign	`none` (0)
WriteExponentPlusSign	`false`
OmitTrailingFractionalZeros	`false`
HexLowerCase	`false`
Whitespaces	alib::DEFAULT_WHITESPACES

Note: With static object TNumberFormat::Computational, there is a global singleton existing which can be used but must not be changed.

◆ SetFromLocale()

template<typename TChar >

void SetFromLocale ( )

Sets the field DecimalPointChar and ThousandsGroupChar to reflect the current system locale setting. No other values are changed.

Note: Static (global) object TNumberFormat::Global, implements an instance which has the right locale set (provided that function Bootstrap was duly invoked by the process). Otherwise, this method might be used to initialize a custom object with default values to afterwards make some specific changes.

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

Description:

Public Static Field Index:

Public Field Index:

Public Method Index:

Field Details:

◆ BinByteGroupChar

◆ BinFieldWidth

◆ BinLiteralPrefix

◆ BinNibbleGroupChar

◆ BinWord32GroupChar

◆ BinWordGroupChar

◆ Computational

◆ DecimalPointChar

◆ DecMinimumFieldWidth

◆ ExponentSeparator

◆ Flags

◆ FractionalPartWidth

◆ Global

◆ HexByteGroupChar

◆ HexFieldWidth

◆ HexLiteralPrefix

◆ HexWord32GroupChar

◆ HexWordGroupChar

◆ INFLiteral

◆ IntegralPartMinimumWidth

◆ LeadingGroupCharReplacement

◆ NANLiteral

◆ OctFieldWidth

◆ OctGroupChar

◆ OctLiteralPrefix

◆ PlusSign

◆ ThousandsGroupChar

◆ Whitespaces

Constructor(s) / Destructor Details:

◆ TNumberFormat()

Method Details:

◆ Set()

◆ SetComputational()

◆ SetFromLocale()