formatterjavastyle.hpp

Go to the documentation of this file.

/** ************************************************************************************************
 * \file
 * This header file is part of sub-namespace #alib::lang::format of module \alib_basecamp of
 * the \aliblong.
 *
 * \emoji :copyright: 2013-2024 A-Worx GmbH, Germany.
 * Published under \ref mainpage_license "Boost Software License".
 **************************************************************************************************/
#ifndef HPP_ALIB_LANG_FORMAT_FORMATTER_JAVASTYLE
#define HPP_ALIB_LANG_FORMAT_FORMATTER_JAVASTYLE 1
 
#if !defined (HPP_ALIB_LANG_FORMAT_FORMATTER_STD)
    #include "alib/lang/format/formatterstdimpl.hpp"
#endif
 
namespace alib::lang::format {
 
/** ************************************************************************************************
 * Implements a \alib{lang::format;Formatter} according to the
 * \https{formatting standards of the Java language,docs.oracle.com/javase/8/docs/api/java/util/Formatter.html}.
 *
 * \note
 *   Inherited, public fields of parent class \b FormatterStdImpl provide important possibilities
 *   for changing the formatting behavior of instances of this class. Therefore, do not forget
 *   to consult the \ref alib::lang::format::FormatterStdImpl "parent classes documentation".
 *
 * In general, the original specification is covered quite well. The differences and specialties
 * are:
 * - In deviation of the Java specification, after creation, a formatter in this implementation
 *   does not produce locale aware output. Instead, number formatting is set to "computational",
 *   hence the decimal point separator is <c>'.'</c> and the grouping character <c>','</c>.
 *   As the syntax specification does not provide a feature to switch between standard and locale
 *   setting, the corresponding fields of #AlternativeNumberFormat are not used with this formatter.
 *   Instead, to enable localized output, method
 *   \alib{strings;TNumberFormat::SetFromLocale;NumberFormat::SetFromLocale}
 *   has to be invoked on field
 *   \alib{lang::format;FormatterStdImpl::DefaultNumberFormat;FormatterStdImpl::DefaultNumberFormat}.
 *   Alternatively, attributes of this object may be changed manually or by other means to reflect
 *   a desired locale.
 * - Hexadecimal floating point output (conversion type \c 'a' and \c 'A') is not supported.
 * - Flag <c>'('</c>, used to write negative numbers in round brackets, is not supported.
 * - Addressing the previous argument index using \c '%<' is already allowed with the first
 *   placeholder.
 *   This Chooses the first argument. (In Java a \b MissingFormatArgumentException would be thrown.)
 * - Flag \c '^' is an extension to the standard and denotes
 *   center-alignment - just like \c '-' in the standard denotes left-alignment.
 *   Right-alignment is the default.
 *
 *<p>
 * - <b>Floating point values:</b>
 *   - If standard field type \c 's' is given together with a precision, the field is cut, even if
 *     it cuts the number somewhere. (This is just a warning and same behavior as in original
 *     specification.)
 *   - For lower case floating point format types (\c 'f', \c 'g' and \c 'e'), the values specified
 *     in attributes \b %ExponentSeparator, \b %NANLiteral and \b %INFLiteral of object
 *     \alib{lang::format;FormatterStdImpl::AlternativeNumberFormat;FormatterStdImpl::AlternativeNumberFormat}
 *     are used. For upper case types (\c 'G' and \c 'E'), the corresponding attributes in
 *     \alib{lang::format;FormatterStdImpl::DefaultNumberFormat;FormatterStdImpl::DefaultNumberFormat} apply.
 *   - Fixed point format (\c 'f' ) is not supported to use arbitrary length.
 *     See class \alib{strings;TNumberFormat;NumberFormat} for the limits.
 *     Due to this limitation, the default number of fractional digits is not set with type \c 'f',
 *     while in Java it is set to \c 6. This is to allow higher numbers up to \c 1.e13 to be printed
 *     in non-scientific format
 *   - When both, a \p{width} and a \p{precision} is given, then the \p{precision} determines the
 *     fractional part, even if the type is \b 'g' or \b 'G'. This is different than specified with
 *     Java formatter, which uses \p{precision} as the overall width in case of types
 *     \b 'g' or \b 'G'.
 *
 *<p>
 * - <b>Hexadecimal and Octal Numbers:</b>
 *   - Hexadecimal and octal output is <b>cut in size</b> (!) when a field width is given that
 *     is smaller than the resulting amount of digits of the number arguments provided.
 *       \note  This implies that a value written might not be equal to the value given.
 *              This is not a bug but a design decision. The rationale behind this is that with this
 *              behavior, there is no need to mask lower digits when passing the arguments to the
 *              format invocation. In other words, the formatter "assumes" that the given field width
 *              indicates that only a corresponding number of lower digits are of interest.
 *
 *   - If no width is given and the argument contains a boxed pointer, then the platform-dependent
 *     full output width of pointer types is used.
 *   - The number <b>grouping option</b> (<c>','</c>) can also be used with binary, hexadecimal
 *     and octal output.
 *     The types support different grouping separators for nibbles, bytes, 16-bit and 32-bit words.
 *     Changing the separator symbols, is not possible with the format fields of the format strings
 *     (if it was, this would become very incompatible to Java standards). Changes have to be made
 *     prior to the format operation by modifying field
 *     \alib{lang::format;FormatterStdImpl::AlternativeNumberFormat;FormatterStdImpl::AlternativeNumberFormat}
 *     which is provided through parent class \b %FormatterStdImpl.
 *
 *   - Alternative form (\c '#') adds prefixes as specified in members
 *     - \alib{strings;TNumberFormat::HexLiteralPrefix;HexLiteralPrefix} and
 *     - \alib{strings;TNumberFormat::OctLiteralPrefix;OctLiteralPrefix}.
 *
 *     For upper case formats,  those are taken from field
 *     \alib{lang::format;FormatterStdImpl::DefaultNumberFormat;FormatterStdImpl::DefaultNumberFormat},
 *     for lower case formats from
 *     \alib{lang::format;FormatterStdImpl::AlternativeNumberFormat;FormatterStdImpl::AlternativeNumberFormat}.
 *     All defaults may be changed by the user.
 *
 *<p>
 * - <b>Time and Date:</b>
 *   - In this C++ version of the class, boxed values of type \alib{time;DateTime} are applicable
 *     to conversion type \c 't'.
 *   - The following time conversion suffix characters are supported:
 *     \c 'H', \c 'k', \c 'I', \c 'l', \c 'M', \c 'S', \c 'B', \c 'b', \c 'h', \c 'A', \c 'a',
 *     \c 'Y', \c 'y', \c 'm', \c 'd', \c 'e', \c 'R', \c 'T', \c 'D' and \c 'F'
 *   - The following time conversion suffix characters are \b not supported:
 *     \c 'L', \c 'N', \c 'p', \c 'z', \c 'Z', \c 's', \c 'Q', \c 'C', \c 'j', \c 'r' and \c 'c'.
 *
\I{################################################################################################}
 * # Reference Documentation #
 * @throws <b>alib::lang::format::FMTExceptions</b>
 *   - \alib{lang::format::FMTExceptions;ArgumentIndexIs0}
 *   - \alib{lang::format::FMTExceptions;ArgumentIndexOutOfBounds}
 *   - \alib{lang::format::FMTExceptions;IncompatibleTypeCode}
 *   - \alib{lang::format::FMTExceptions;NegativeValuesInBracketsNotSupported}
 *   - \alib{lang::format::FMTExceptions;MissingPrecisionValueJS}
 *   - \alib{lang::format::FMTExceptions;HexadecimalFloatFormatNotSupported}
 *   - \alib{lang::format::FMTExceptions;NoAlternateFormOfConversion}
 *   - \alib{lang::format::FMTExceptions;NoPrecisionWithConversion}
 *   - \alib{lang::format::FMTExceptions;UnknownDateTimeConversionSuffix}
 *   - \alib{lang::format::FMTExceptions;UnknownConversionJS}
 *
 **************************************************************************************************/
class FormatterJavaStyle : public FormatterStdImpl
{
    // #############################################################################################
    // Protected fields
    // #############################################################################################
    protected:
        /**
         * Set of extended placeholder attributes, needed for this type of formatter in
         * addition to parent's \alib{lang::format::FormatterStdImpl;PlaceholderAttributes}.
         */
        struct PlaceholderAttributesJS
        {
            /** The character after conversion type 't'/'T'. */
            character           DateTime;
 
            /** The value read from the precision field.
             *  This is set to \c -1 in #resetPlaceholder. */
            int8_t              Precision;
 
            /** The default precision if not given.
             *  This is set to \c 6 in #resetPlaceholder, but is changed when specified. */
            int8_t              DefaultPrecision;
 
            /** Convert to upper case. */
            bool                ConversionUpper;
 
            /** Alternate form given ('#'). */
            bool                AlternateForm;
        };
 
        /** The extended placeholder attributes. */
        PlaceholderAttributesJS placeholderJS;
 
 
    // #############################################################################################
    //  Constructor/Destructor
    // #############################################################################################
    public:
        /** ****************************************************************************************
         * Constructs this formatter.
         * Inherited field #DefaultNumberFormat is initialized to meet the formatting defaults of
         * Java.
         ******************************************************************************************/
        ALIB_API
        FormatterJavaStyle();
 
        /** ****************************************************************************************
         * Clones and returns a copy of this formatter.
         *
         * If the formatter attached to field
         * \alib{lang::format;Formatter::Next} is of type \b %FormatterStdImpl, then that
         * formatter is copied as well.
         *
         * @returns An object of type \b %FormatterPythonStyle and with the same custom settings
         *          than this.
         ******************************************************************************************/
        ALIB_API virtual
        FormatterStdImpl*   Clone()                                                        override;
 
 
 
    // #############################################################################################
    //  Implementation of FormatterStdImpl interface
    // #############################################################################################
    protected:
 
        /** ****************************************************************************************
         * Invokes parent implementation and then applies some changes to reflect what is defined as
         * default in the Java string format specification.
         ******************************************************************************************/
        ALIB_API
        virtual void        resetPlaceholder()                                                    override;
 
        /** ****************************************************************************************
         * Searches for \c '\%' which is not '%%' or '%n'.
         *
         * @return The index found, -1 if not found.
         ******************************************************************************************/
        ALIB_API
        virtual integer     findPlaceholder()                                              override;
 
        /** ****************************************************************************************
         * Parses placeholder field in Java syntax. The portion \p{format_spec} is not set as this
         * is not supported by the syntax.
         *
         * @return \c true on success, \c false on errors.
         ******************************************************************************************/
        ALIB_API
        virtual bool        parsePlaceholder()                                             override;
 
        /** ****************************************************************************************
         * Does nothing. Java does not support custom format specifications.
         *
         * @return \c true to indicate success.
         ******************************************************************************************/
        virtual bool        parseStdFormatSpec()                                           override
        {
            return true;
        }
 
        /** ****************************************************************************************
         * Implementation of abstract method \alib{lang::format;FormatterStdImpl::writeStringPortion}.<br>
         * Replaces \c "%%" with \c '\%' and \c "%n" with ascii \c 0x0a. In addition applies
         * \alib{strings;TFormat::Escape;Format::Escape} on \p{target} which replaces
         * standard codes like \c "\\n", \c "\\r" or \c "\\t" with corresponding ascii codes.
         * (The latter is an extension to the standard behavior of Java formatter.)
         *
         * @param length The number of characters to write.
         ******************************************************************************************/
        ALIB_API
        virtual void        writeStringPortion( integer length )                           override;
 
        /** ****************************************************************************************
         * All that this formatter does with this overridden method is to convert strings to
         * upper case.
         *
         * @param startIdx  The index of the start of the field written in #targetString.
         *                  \c -1 indicates pre-phase.
         * @param target    The target string, only if different from field #targetString, which
         *                  indicates intermediate phase.
         * @return \c false, if the placeholder should be skipped (nothing is written for it).
         *         \c true otherwise.
         ******************************************************************************************/
        ALIB_API
        virtual bool        preAndPostProcess( integer    startIdx,
                                               AString*   target     )                     override;
 
        /** ****************************************************************************************
         * Makes some attribute adjustments and invokes standard implementation
         * @return \c true if OK, \c false if replacement should be aborted.
         ******************************************************************************************/
        ALIB_API
        virtual bool        checkStdFieldAgainstArgument()                                 override;
};
 
} // namespace [alib::lang::format]
 
#endif // HPP_ALIB_LANG_FORMAT_FORMATTER_JAVASTYLE