 |
ALib C++ Library
|
|
|
ALib C++ Library
|
|
#include <numberformat.hpp>
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 aworx::lib::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 method ALibDistribution::Bootstrap, are defined which can be used wherever a number format object is needed as a parameter:
'.', 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:
' ' and '+' are reasonable options.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.
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 aworx::lib::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.
| TChar | The character type. Alias names for specializations of this class using character types character, nchar, wchar, xchar, complementChar and strangeChar are provided in namespace aworx with type definitions NumberFormat, NNumberFormat, WNumberFormat, XNumberFormat, ComplementNumberFormat and StrangeNumberFormat. |
Definition at line 49 of file strings/fwds.hpp.
Public Static Fields | |
| static TNumberFormat | Computational |
| static TNumberFormat | Global |
Public Fields | |
| TChar | BinByteGroupChar |
| int8_t | BinFieldWidth |
| TCString< TChar > | BinLiteralPrefix |
| TChar | BinNibbleGroupChar |
| TChar | BinWord32GroupChar |
| TChar | BinWordGroupChar |
| TChar | DecimalPointChar |
| int8_t | DecMinimumFieldWidth |
| TCString< TChar > | ExponentSeparator |
| bool | ForceDecimalPoint |
| bool | ForceScientific |
| int8_t | FractionalPartWidth |
| TChar | HexByteGroupChar |
| int8_t | HexFieldWidth |
| TCString< TChar > | HexLiteralPrefix |
| bool | HexLowerCase |
| TChar | HexWord32GroupChar |
| TChar | HexWordGroupChar |
| TCString< TChar > | INFLiteral |
| int8_t | IntegralPartMinimumWidth |
| TChar | LeadingGroupCharReplacement |
| TCString< TChar > | NANLiteral |
| int8_t | OctFieldWidth |
| TChar | OctGroupChar |
| TCString< TChar > | OctLiteralPrefix |
| bool | OmitTrailingFractionalZeros |
| TChar | PlusSign |
| bool | ReadGroupChars |
| TChar | ThousandsGroupChar |
| TCString< TChar > | Whitespaces |
| bool | WriteExponentPlusSign |
| bool | WriteGroupChars |
Public Methods | |
| TNumberFormat () | |
| void | Set (TNumberFormat *other=nullptr) |
| void | SetComputational () |
| void | SetFromLocale () |
|
inline |
Constructor. Invokes SetComputational to reset all fields to their default values.
Definition at line 434 of file numberformat.hpp.
| 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
| other | The NumberFormat object to copy the values from. Defaults to nullptr, which chooses the global singleton. |
| 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:
| DecimalPointChar | |
| ThousandsGroupChar | |
| BinNibbleGroupChar | ' |
| BinByteGroupChar | - |
| BinWordGroupChar | ' ' (space) |
| BinWord32GroupChar | # |
| HexWordGroupChar | ' |
| HexWord32GroupChar | ' |
| HexByteGroupChar | 0 (none) |
| OctGroupChar | ' |
The literal attributes are set as follows:
| 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:
| WriteGroupChars | false |
| ForceScientific | false |
| ForceDecimalPoint | true |
| PlusSign | none (0) |
| WriteExponentPlusSign | false |
| OmitTrailingFractionalZeros | false |
| HexLowerCase | false |
| Whitespaces | aworx::DefaultWhitespaces |
| void SetFromLocale | ( | ) |
Sets the field DecimalPointChar and ThousandsGroupChar to reflect the current system locale setting. No other values are changed.
| TChar BinByteGroupChar |
Defines the separator character for bytes of binary numbers. Defaults to '\0' what chooses BinNibbleGroupChar.
Definition at line 266 of file numberformat.hpp.
| 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 407 of file numberformat.hpp.
| 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 200 of file numberformat.hpp.
| 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 262 of file numberformat.hpp.
| TChar BinWord32GroupChar |
Defines the separator character for 32-bit words of binary numbers. Defaults to '\0' what chooses BinWordGroupChar.
Definition at line 274 of file numberformat.hpp.
| TChar BinWordGroupChar |
Defines the separator character for 16-bit words of binary numbers. Defaults to '\0' what chooses BinByteGroupChar.
Definition at line 270 of file numberformat.hpp.
|
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 '.'.
Method ALibDistribution::Bootstrap invokes SetComputational on this object. Note that using code that use this field without having invoked ALIB.init may behave wrongly.
Classes providing functionality based on this class, might use this as a default value for parameters of their interfaces.
Definition at line 164 of file numberformat.hpp.
| 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 227 of file numberformat.hpp.
| 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 399 of file numberformat.hpp.
| 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 187 of file numberformat.hpp.
| bool ForceDecimalPoint |
If true, the decimal point of floating point values is written, even if the fractional part of the float value is zero. If false, in this case the decimal point is omitted.
Defaults to true.
Definition at line 315 of file numberformat.hpp.
| bool ForceScientific |
If true, scientific format is always used.
If false (the default), function WriteFloat writes scientific format only if both fields, IntegralPartMinimumWidth and FractionalPartWidth are evaluating to -1 and only for numbers smaller than 10E-04 or larger than 10E+06.
If one of the fields IntegralPartMinimumWidth or FractionalPartWidth is set to a positive value, these limits get extended. Function WriteFloat in this case keeps non-scientific notation established if possible.
Definition at line 343 of file numberformat.hpp.
| 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 386 of file numberformat.hpp.
|
static |
The default static number format object that acts as the default settings of the currently running process.
Method ALibDistribution::Bootstrap invokes SetFromLocale() on this object and switches grouping on.
Classes providing functionality based on this class, might use this as a default value for parameters of their interfaces.
Definition at line 150 of file numberformat.hpp.
| 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 278 of file numberformat.hpp.
| 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 415 of file numberformat.hpp.
| 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 208 of file numberformat.hpp.
| bool HexLowerCase |
If true, lower case letters 'a' - 'f' are written. Defaults to false, which writes upper case letters 'A' - 'F'.
Definition at line 349 of file numberformat.hpp.
| TChar HexWord32GroupChar |
Defines the separator character for 32-bit words of hexadecimal numbers. Defaults to '\0' what chooses HexWordGroupChar.
Definition at line 286 of file numberformat.hpp.
| TChar HexWordGroupChar |
Defines the separator character for 16-bit words of hexadecimal numbers. Defaults to '\0' what chooses HexByteGroupChar.
Definition at line 282 of file numberformat.hpp.
| TCString<TChar> INFLiteral |
Defines what is written and parsed for infinite double values.
Definition at line 190 of file numberformat.hpp.
| 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 368 of file numberformat.hpp.
| 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, assures the field width to be as requested. Defaults to space (' ').
Definition at line 257 of file numberformat.hpp.
| TCString<TChar> NANLiteral |
Defines what is written and parsed for double values that represent "not a number".
Definition at line 193 of file numberformat.hpp.
| 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 424 of file numberformat.hpp.
| 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 290 of file numberformat.hpp.
| 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 216 of file numberformat.hpp.
| bool OmitTrailingFractionalZeros |
If this field is true, then trailing '0' digits in the fractional part of a floating point value are not written, even if a FractionalPartWidth is set. Defaults to false.
Definition at line 331 of file numberformat.hpp.
| 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 237 of file numberformat.hpp.
| bool ReadGroupChars |
Denotes if grouping characters are ignored when parsing numbers if they are given (not set to '\0'). This applies to all number types.
Defaults to false. If set to true, grouping characters are just skipped when found while parsing numbers, no matter at which position they occur.
Definition at line 302 of file numberformat.hpp.
| TChar ThousandsGroupChar |
Defines the separator character for thousands when converting a number to a string representation. In addition, this is used to identify thousand group 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 249 of file numberformat.hpp.
| 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 177 of file numberformat.hpp.
| bool WriteExponentPlusSign |
Determines if positive exponent values are prepended with an explicit '+' character when written using WriteFloat.
Defaults to false, as some systems will not accept a plus sign on the exponent value. Note that field PlusSign is not applicable for exponent numbers.
Definition at line 323 of file numberformat.hpp.
| bool WriteGroupChars |
Denotes if grouping characters are written if they are given (not set to '\0'). This applies to all number types.
Defaults to false.
Definition at line 308 of file numberformat.hpp.