formatterjavastyle.hpp

Go to the documentation of this file.

//==================================================================================================
/// \file
/// This header-file is part of module \alib_format of the \aliblong.
///
/// Copyright 2013-2026 A-Worx GmbH, Germany.
/// Published under #"mainpage_license".
//==================================================================================================
namespace alib::format {
 
//==================================================================================================
/// Implements a #"R;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 #"%FormatterStdImpl" provide important possibilities
///   for changing the formatting behavior of instances of this class. Therefore, do not forget
///   to consult the #"alib::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
///   settings, the corresponding fields of #"AlternativeNumberFormat" are not used with this
///   formatter. Instead, to enable localized output, method
///   #"TNumberFormat::SetFromLocale;NumberFormat::SetFromLocale"
///   has to be invoked on the inherited field #"Formatter::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 \c 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 #"%ExponentSeparator", #"%NANLiteral" and #"%INFLiteral" of the inherited
///     field #"^FormatterJavaStyle::AlternativeNumberFormat" are used.
///     For upper case types (\c 'G' and \c 'E'), the corresponding attributes in the inherited
///     field #"^FormatterJavaStyle::DefaultNumberFormat" apply.
///   - Fixed point format (\c 'f' ) is not supported to use arbitrary length.
///     See class #"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, \p{width} and \p{precision} are given, then the \p{precision} determines the
///     fractional part, even if the type is \b 'g' or \b 'G'. This is different from the
///     corresponding specification of Java formatter, which uses \p{precision} as the overall
///     width in the 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 number 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
///     before the format operation by modifying the field
///     #"^FormatterJavaStyle::AlternativeNumberFormat" which is provided through parent
///     class #"%format::Formatter".
///
///   - Alternative form (\c '#"')" adds prefixes as specified in members
///     - #"TNumberFormat::HexLiteralPrefix" and
///     - #"TNumberFormat::OctLiteralPrefix".
///
///     For upper case formats, those are taken from the inherited field
///     #"^FormatterJavaStyle::DefaultNumberFormat", for lower case formats from
///     #"^FormatterJavaStyle::AlternativeNumberFormat". The user may change all defaults.
///
///<p>
/// - <b>Time and Date:</b>
///   - In this C++ version of the class, boxed values of type #"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::format::FMTExceptions</b>
///   - #"FMTExceptions::ArgumentIndexIs0"
///   - #"FMTExceptions::ArgumentIndexOutOfBounds"
///   - #"FMTExceptions::IncompatibleTypeCode"
///   - #"FMTExceptions::NegativeValuesInBracketsNotSupported"
///   - #"FMTExceptions::MissingPrecisionValueJS"
///   - #"FMTExceptions::HexadecimalFloatFormatNotSupported"
///   - #"FMTExceptions::NoAlternateFormOfConversion"
///   - #"FMTExceptions::NoPrecisionWithConversion"
///   - #"FMTExceptions::UnknownDateTimeConversionSuffix"
///   - #"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 #"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_DLL
    FormatterJavaStyle();
 
    /// Clones and returns a copy of this formatter.
    ///
    /// If the formatter attached to field
    /// #"Formatter::Next;*" is of type #"%FormatterStdImpl", then that
    /// formatter is copied as well.
    ///
    /// @returns An object of type #"%FormatterPythonStyle" and with the same custom settings
    ///          than this.
    ALIB_DLL virtual
    SPFormatter         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_DLL
    virtual void        resetPlaceholder()                                                 override;
 
    /// Searches for \c '\%' which is not '%%' or '%n'.
    ///
    /// @return The index found, -1 if not found.
    ALIB_DLL
    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_DLL
    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 #"FormatterStdImpl::writeStringPortion;*".<br>
    /// Replaces \c "%%" with \c '\%' and \c "%n" with ascii \c 0x0a. In addition applies
    /// #"TEscape;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_DLL
    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_DLL
    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_DLL
    virtual bool        checkStdFieldAgainstArgument()                                     override;
};
 
} // namespace [alib::format]
 
ALIB_EXPORT namespace alib {
/// Type alias in namespace #"%alib".
using  FormatterJavaStyle  =   format::FormatterJavaStyle;
}