numberformat.hpp

Go to the documentation of this file.

/** ************************************************************************************************
 * \file
 * This header file is part of module \alib_strings of the \aliblong.
 *
 * \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
 * Published under \ref mainpage_license "Boost Software License".
 **************************************************************************************************/
#ifndef HPP_ALIB_STRINGS_NUMBERFORMAT
#define HPP_ALIB_STRINGS_NUMBERFORMAT 1
 
#if !defined (HPP_ALIB_STRINGS_CSTRING)
#   include "alib/strings/cstring.hpp"
#endif
#if ALIB_ENUMS &&!defined (HPP_ALIB_ENUMS_BITWISE)
#   include "alib/enums/bitwise.hpp"
#endif
 
namespace alib {  namespace strings {
 
 
/**
 * Flags used with class \alib{strings;TNumberFormat}.
 */
enum class NumberFormatFlags : uint8_t
{
    /** Used to clear all flags */
    NONE                                    = 0,
 
    /**
     * Denotes if grouping characters are ignored when parsing numbers if they are given
     * (not set to \c '\0').
     * This applies to all number types.<br>
     * Defaults to \c false. If set to \c true, grouping characters are just skipped when
     * found while parsing numbers, no matter at which position they occur.
     */
    ReadGroupChars                          = 1,
    /**
     * Denotes if grouping characters are written if they are given (not set to \c '\0').
     * This applies to all number types.<br>
     * Defaults to \c false.
     */
    WriteGroupChars                         = 2,
 
    /**
     * If \c true, the decimal point of floating point values is written, even if the fractional
     * part of the float value is zero. If \c false, in this case the decimal point is omitted.<br>
     * Defaults to \c true.
     */
    ForceDecimalPoint                       = 4,
 
    /**
     * Determines if positive exponent values are prepended with an explicit '+' character when
     * written using \alib{strings::detail;WriteFloat}.<br>
     * Defaults to \c false, as some systems will not accept a plus sign on the exponent value.
     * Note that field \alib{strings;TNumberFormat::PlusSign} is not applicable for exponent numbers.
     */
    WriteExponentPlusSign                   = 8,
 
 
    /**
     * If this field is \c true, then trailing \c '0' digits in the fractional part of a floating
     * point value are not written, even if a \alib{strings;TNumberFormat::FractionalPartWidth}
     * is set. Defaults to \c false.
     */
    OmitTrailingFractionalZeros             =16,
 
    /**
     * If \c true, scientific format is always used.<br>
     * If \c false (the default), function \alib{strings::detail;WriteFloat} writes scientific
     * format only if both fields, \alib{strings;TNumberFormat::IntegralPartMinimumWidth} and
     * \alib{strings;TNumberFormat::FractionalPartWidth} are evaluating to \c -1 and only for
     * numbers smaller than \c 10E-04 or larger than \c 10E+06.<br>
     *
     * If one of the fields \alib{strings;TNumberFormat::IntegralPartMinimumWidth} or
     * \alib{strings;TNumberFormat::FractionalPartWidth} is set to a positive
     * value, these limits get extended. Function \alib{strings::detail;WriteFloat} in this case
     * keeps non-scientific notation established if possible.
     */
    ForceScientific                         =32,
 
    /**
     * If \c true, lower case letters \c 'a' - \c 'f' are written.
     * Defaults to \c false, which writes upper case letters \c 'A' - \c 'F'.
     */
    HexLowerCase                            =64,
}; // enum class NumberFormatFlags
 
 
/** ***********************************************************************************************
 * 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
 *    \alib{strings;TString;String},
 *    \alib{strings;TSubstring;Substring},
 *    \alib{strings;TAString;AString} or
 *    \alib{lang::format;Formatter}
 * are preferred to write and parse numbers. Also those accept an object of this type as parameters.
 *
 * <b>Defined Singletons and User-Defined Instances:</b><br>
 * Two static singletons of this class, both initialized with function \alib{Bootstrap},
 * are defined which can be used wherever a number format object is needed as a parameter:
 * - #Global: Reflects locale-specific settings.
 *
 * - #Computational:<br>
 *   Intended to be used for writing and parsing numbers which are readable by software (not
 *   humans). Its decimal point character is set to \c '.', 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.
 *
 * <b>Output Formats:</b><br>
 * The following conversion formats are supported:
 *
 * - \b Decimal<br>
 *   Supports optional minimum output width with field #DecMinimumFieldWidth,
 *   and definable <em>thousands grouping character</em> with field #ThousandsGroupChar, which can
 *   be activated with field #WriteGroupChars.<br>
 *   Furthermore, the plus-sign can be controlled (#PlusSign) to be either omitted or be anything
 *   defined. Of-course, values <c>' '</c> and <c>'+'</c> are reasonable options.
 *
 * - <b>Binary</b><br>
 *   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 ).<br>
 *   When parsing integers, a customizable literal string defined in #BinLiteralPrefix might be used
 *   to auto-detect binary values.
 *
 * - <b>Hexadecimal</b><br>
 *   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.
 *
 * - <b>Octal</b><br>
 *   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.
 *
 * - <b>Floating Point</b><br>
 *   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.<br>
 *   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.<br>
 *   Other important fields used for writing and parsing floats are: #ExponentSeparator,
 *   #INFLiteral, #NANLiteral, #WriteExponentPlusSign, and #ForceScientific.
 *
 * <b>Notes on Writing and Parsing Values:</b><br>
 * For decimal output, the width (#DecMinimumFieldWidth) is a minimum width. This means, that
 * bigger numbers are written in a higher width.
 *
 * \attention
 *   This is \c not true for binary, hexadecimal and octal output. In these formats, the width
 *   provided with fields #BinFieldWidth, #HexFieldWidth and #OctFieldWidth, denote an \b 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 \b 5 was given for decimal output, the value
 * \c 12 would be written \c "0,012", hence \b 4 digits plus the grouping character. If grouping
 * was disabled, the output became \c "00012", which uses one extra digit instead of the group
 * character.
 * In contrast to that, sign characters are \c 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 \e nulled or empty, then white spaces are \b 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 \c 0 (respectively \c 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 \b are
 * identified by function \alib{strings::detail;ParseInt}, which aggregates the other four parsing
 * functions.<br>
 * 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.
 *
 * @tparam TChar The character type.<br>
 *   Alias names for specializations of this class using character types
 *   \alib{characters;character}, \alib{characters;nchar}, \alib{characters;wchar},
 *   \alib{characters;xchar}, \alib{characters;complementChar} and \alib{characters;strangeChar}
 *   are provided in namespace #alib with type definitions \alib{NumberFormat},
 *   \alib{NNumberFormat}, \alib{WNumberFormat}, \alib{XNumberFormat},
 *   \alib{ComplementNumberFormat} and \alib{StrangeNumberFormat}.
 **************************************************************************************************/
template<typename TChar>
struct TNumberFormat
{
    /**
     * The default static number format object that acts as the default settings of the currently
     * running process.<br>
     * Function \alib{Bootstrap} invokes #SetFromLocale() on this object and switches grouping
     * to \e 'on'.
     *
     * Classes providing functionality based on this class, might use this as a default
     * value for parameters of their interfaces.
     */
    static              TNumberFormat   Global;
 
    /**
     * 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 \c '.'.<br>
     * Function \alib{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.
     */
    static              TNumberFormat   Computational;
 
    // ###############################   string members  ###################################
    /**
     * Defines whitespace characters that are ignored when leading the number and after
     * the sign-character. Applies to functions
     * \alib{strings::detail;ParseInt} and
     * \alib{strings::detail;ParseFloat}. In contrast, functions
     * \alib{strings::detail;ParseDec},
     * \alib{strings::detail;ParseBin},
     * \alib{strings::detail;ParseHex} and
     * \alib{strings::detail;ParseOct} do not ignore any whitespace characters.
     */
    TCString<TChar>     Whitespaces;
 
    /**
     * Defines the decimal exponent symbol of string representations of floating point numbers
     * when written or parsed in scientific notation by functions \alib{strings::detail;ParseFloat}
     * and \alib{strings::detail;WriteFloat}.<br>
     * Function \alib{strings::detail;ParseFloat} accepts characters 'e' and 'E' in addition to
     * the character set in this field.<br>
     * Defaults to \c 'E'.
     */
    TCString<TChar>     ExponentSeparator;
 
    /** Defines what is written and parsed for infinite double values. */
    TCString<TChar>     INFLiteral;
 
    /** Defines what is written and parsed for double values that represent "not a number". */
    TCString<TChar>     NANLiteral;
 
    /** Used by function \alib{strings::detail;ParseInt} to detect binary format of integral values.
     * If \e 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.<br>
     * Defaults to \c "0b". */
    TCString<TChar>     BinLiteralPrefix;
 
    /**
     * Used by function \alib{strings::detail;ParseInt} to detect hexadecimal format of integer
     * values. If \e 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.<br>
     * Defaults to \c "0x". */
    TCString<TChar>     HexLiteralPrefix;
 
    /**
     * Used by function \alib{strings::detail;ParseInt} to detect octal format of integral values.
     * If \e 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.<br>
     * Defaults to \c "0o". */
    TCString<TChar>     OctLiteralPrefix;
 
    // ###############################  character members  ###################################
 
    /**
     * Defines the decimal point character when converting a floating point number to a string
     * representation with function \alib{strings::detail;WriteFloat}. Also; function \alib{strings::detail;ParseFloat} uses
     * the character provided in this field for parsing the character.<br>
     * The field defaults to '.'. By invoking #SetFromLocale(), the current locale's setting is
     * determined.
     */
    TChar               DecimalPointChar;
 
    /**
     * Determines if positive values are prepended with an explicit character (usually '+') when
     * written using \alib{strings::detail;WriteFloat} or \alib{strings::detail;WriteDecSigned}.<br>
     * Defaults to \c 0 which omits the writing. Usual other values are of-course \c '+', but
     * also  <c>' '</c> (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
     */
    TChar               PlusSign;
 
    /**
     * 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 \c '\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.<br>
     * Defaults to \c ','.
     * By invoking #SetFromLocale(), the current locale's setting is determined.
     *
     */
    TChar               ThousandsGroupChar;
 
    /**
     * 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 (<c>' '</c>).
     */
    TChar               LeadingGroupCharReplacement;
 
 
    /** Defines the separator character for nibbles (4 bits) of binary numbers.
     *  Defaults to \c '\0' what disables reading and writing of nibble group characters.  */
    TChar               BinNibbleGroupChar;
 
    /** Defines the separator character for bytes of binary numbers.
     *  Defaults to \c '\0' what chooses #BinNibbleGroupChar.  */
    TChar               BinByteGroupChar;
 
    /** Defines the separator character for 16-bit words  of binary numbers.
     *  Defaults to \c '\0' what chooses #BinByteGroupChar.  */
    TChar               BinWordGroupChar;
 
    /** Defines the separator character for 32-bit words  of binary numbers.
     *  Defaults to \c '\0' what chooses #BinWordGroupChar.  */
    TChar               BinWord32GroupChar;
 
    /** Defines the separator character for bytes of hexadecimal numbers. Defaults to \c 0,
     *  Defaults to \c '\0' what disables reading and writing of byte group characters.  */
    TChar               HexByteGroupChar;
 
    /** Defines the separator character for 16-bit words  of hexadecimal numbers.
     *  Defaults to \c '\0' what chooses #HexByteGroupChar.  */
    TChar               HexWordGroupChar;
 
    /** Defines the separator character for 32-bit words  of hexadecimal numbers.
     *  Defaults to \c '\0' what chooses #HexWordGroupChar.  */
    TChar               HexWord32GroupChar;
 
    /** Defines the separator character for bytes of hexadecimal numbers.
     *  Defaults to \c '\0' what disables reading and writing of byte group characters.  */
    TChar               OctGroupChar;
 
    /** The flag field. */
    NumberFormatFlags   Flags;
 
    // ############################ width members ###############################
    /**
     * Defines the minimum digits written for the integral part when converting a floating point
     * value into a string.<br>
     * If the integral part of the number provided has less digits
     * then leading '0' digits are added.<br>
     * The maximum value allowed is 15.<br>
     * 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 <br>
     * 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 \c 10E-04 and
     * \c 10E+06, get extended. Function \alib{strings::detail;WriteFloat} in this case keeps
     * non-scientific notation established if possible.
     */
    int8_t              IntegralPartMinimumWidth;
 
    /**
     * Defines the number of digits written for the fractional part when converting a floating point
     * value into a string. (For integer conversion, see #DecMinimumFieldWidth.)<br>
     * If the fractional part of the number provided has less digits then trailing '0'
     * digits are added.<br>
     * If the fractional part of the number provided has more digits then the fractional part is
     * rounded accordingly.<br>
     * The maximum value allowed is 15.<br>
     * 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 \c 10E-04 and
     * \c 10E+06, get extended. Function \alib{strings::detail;WriteFloat} in this case keeps non-scientific notation
     * established if possible.
     */
    int8_t              FractionalPartWidth;
 
    /**
     * 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.<br> 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 \c '\0'
     * (usually space character <c>' '</c> or \c '+').
     *
     * If this field is negative, it is ignored. Defaults to \c -1.
     */
    int8_t              DecMinimumFieldWidth;
 
    /**
     * 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 \b NOT written (!).<br>
     * The default value and minimum value is \c -1, which writes as many bits as necessary.
     */
    int8_t              BinFieldWidth;
 
    /**
     * 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 \b NOT written (!).<br>
     * The default value and minimum value is \c -1, which writes as many bits as necessary.
     */
    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 \b NOT written (!).<br>
     * The default value and minimum value is \c -1, which writes as many bits as necessary.
     */
    int8_t              OctFieldWidth;
 
 
    // #############################################################################################
    //  Interface
    // #############################################################################################
 
    /** ********************************************************************************************
     * Constructor. Invokes #SetComputational to reset all fields to their default values.
     **********************************************************************************************/
    TNumberFormat()
    {
        SetComputational();
    }
 
    /** ********************************************************************************************
     * Copies all fields (settings) from the given object. If no object is provided, values of
     * the static singleton found in field #Global are copied
     *
     * @param other  The \b %NumberFormat object to copy the values from.
     *               Defaults to \c nullptr, which chooses the global singleton.
     **********************************************************************************************/
    void      Set( TNumberFormat* other =nullptr );
 
    /** ********************************************************************************************
     * Resets the object to its default values. This method is called in the constructor.
     *
     * Decimal point character and grouping characters are set as follows:
     * <center>Field</center>         | <center>Value</center>
     * - - - - - - - - - - - - - - - -| - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - -
     * #DecimalPointChar              |  \c .
     * #ThousandsGroupChar            |  \c ,
     * #BinNibbleGroupChar            |  \c '
     * #BinByteGroupChar              |  \c -
     * #BinWordGroupChar              |  <c>' '</c> (space)
     * #BinWord32GroupChar            |  \c #
     * #HexWordGroupChar              |  \c '
     * #HexWord32GroupChar            |  \c '
     * #HexByteGroupChar              |  \c 0 (none)
     * #OctGroupChar                  |  \c '
     *
     * The literal attributes are set as follows:
     * <center>Field</center>         | <center>Value</center>
     * - - - - - - - - - - - - - - - -| - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - -
     * #ExponentSeparator             |  \c "E"
     * #INFLiteral                    |  \c "INF"
     * #NANLiteral                    |  \c "NAN"
     * #BinLiteralPrefix              |  \c "0b"
     * #HexLiteralPrefix              |  \c "0x"
     * #OctLiteralPrefix              |  \c "0o"
     *
     * All width-attributes are reset to "automatic mode", \c -1. The attributes are
     * #IntegralPartMinimumWidth,
     * #FractionalPartWidth,
     * #DecMinimumFieldWidth,
     * #BinFieldWidth,
     * #HexFieldWidth and
     * #OctFieldWidth.
     *
     * Finally, the following further fields are reset to their default values:
     * <center>Field</center>         | <center>Value</center>
     * - - - - - - - - - - - - - - - -| - - - -- - - - - - - - - - - - - - - - - - - - - - - - - - -
     * #WriteGroupChars               |  \c false
     * #ForceScientific               |  \c false
     * #ForceDecimalPoint             |  \c true
     * #PlusSign                      |  \c none (0)
     * #WriteExponentPlusSign         |  \c false
     * #OmitTrailingFractionalZeros   |  \c false
     * #HexLowerCase                  |  \c false
     * #Whitespaces                   |  #alib::DefaultWhitespaces
     *
     *
     * \note
     *   With static object
     *   \ref alib::strings::TNumberFormat::Computational "TNumberFormat::Computational",
     *   there is a global singleton existing which can be used but must not be changed.
     **********************************************************************************************/
    void     SetComputational();
 
    /** ********************************************************************************************
     * Sets the field #DecimalPointChar and #ThousandsGroupChar to reflect the current
     * system locale setting. No other values are changed.
     *
     * \note
     *   Static (global) object \ref alib::strings::TNumberFormat::Global "TNumberFormat::Global",
     *   implements an instance which has the right locale set (provided that function
     *   \alib{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.
     **********************************************************************************************/
    void     SetFromLocale();
};
 
//! @cond NO_DOX
 
extern template   ALIB_API void   TNumberFormat<nchar>::Set             ( TNumberFormat* );
extern template   ALIB_API void   TNumberFormat<nchar>::SetFromLocale   ();
 
 
extern template   ALIB_API void   TNumberFormat<wchar>::Set             ( TNumberFormat* );
extern template   ALIB_API void   TNumberFormat<wchar>::SetFromLocale   ();
 
 
extern template   ALIB_API void   TNumberFormat<xchar>::Set             ( TNumberFormat* );
extern template   ALIB_API void   TNumberFormat<xchar>::SetFromLocale   ();
 
 
       template<> ALIB_API void   TNumberFormat<nchar>::SetComputational();
       template<> ALIB_API void   TNumberFormat<wchar>::SetComputational();
       template<> ALIB_API void   TNumberFormat<xchar>::SetComputational();
 
template<typename TChar> TNumberFormat<TChar>   TNumberFormat<TChar>::Global;
template<typename TChar> TNumberFormat<TChar>   TNumberFormat<TChar>::Computational;
//! @endcond
 
} // namespace alib::[strings]
 
/// Type alias in namespace \b alib.
using NumberFormatFlags= strings::NumberFormatFlags;
 
} // namespace [alib]
 
#if ALIB_ENUMS
    ALIB_ENUMS_MAKE_BITWISE(alib::strings::NumberFormatFlags )
#endif
#endif // HPP_ALIB_STRINGS_NUMBERFORMAT