java.lang.Object
- io.spine.logging.flogger.backend.FormatOptions

```
public final class FormatOptions
extends Object
```
A structured representation of formatting options compatible with printf style formatting.
This class is immutable and thread safe.

See Also:

Original Java code of Google Flogger

Field Summary

Fields
Modifier and Type	Field	Description
`static int`	`ALL_FLAGS`	A mask of all allowed formatting flags.
`static int`	`FLAG_LEFT_ALIGN`	A formatting flag which specifies that output should be left-aligned within the minimum available width.
`static int`	`FLAG_PREFIX_PLUS_FOR_POSITIVE_VALUES`	A formatting flag which specifies that for signed numeric output, positive values should be prefixed with an ASCII plus (`'+'`).
`static int`	`FLAG_PREFIX_SPACE_FOR_POSITIVE_VALUES`	A formatting flag which specifies that for signed numeric output, positive values should be prefixed with an ASCII space (`' '`).
`static int`	`FLAG_SHOW_ALT_FORM`	A formatting flag which specifies that output should be shown in a type dependent alternate form.
`static int`	`FLAG_SHOW_GROUPING`	A formatting flag which specifies that for non-exponential, base-10, numeric output a grouping separator (often a ',') should be used.
`static int`	`FLAG_SHOW_LEADING_ZEROS`	A formatting flag which specifies that numeric output should be padding with leading zeros as necessary to fill the minimum width.
`static int`	`FLAG_UPPER_CASE`	A formatting flag which specifies that output should be upper-cased after all other formatting.
`static int`	`FLAG_USE_PARENS_FOR_NEGATIVE_VALUES`	A formatting flag which specifies that for signed numeric output, negative values should be surrounded by parentheses.
`static int`	`UNSET`	The value used to specify that either width or precision were not specified.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`StringBuilder`	`appendPrintfOptions(StringBuilder out)`	Appends the data for this options instance in a printf compatible form to the given buffer.
`boolean`	`areValidFor(FormatChar formatChar)`	Validates these options as if they were being applied to the given `FormatChar` and checks for inconsistencies in flag values.
`boolean`	`equals(@Nullable Object o)`
`FormatOptions`	`filter(int allowedFlags, boolean allowWidth, boolean allowPrecision)`	Returns a possibly new FormatOptions instance possibly containing a subset of the formatting information.
`static FormatOptions`	`getDefault()`	Returns the default options singleton instance.
`int`	`getFlags()`	Returns the flag bits for this options instance.
`int`	`getPrecision()`	Returns the precision for these options, or `UNSET` if not specified.
`int`	`getWidth()`	Returns the width for these options, or `UNSET` if not specified.
`int`	`hashCode()`
`boolean`	`isDefault()`	Returns true if this instance has only default formatting options.
`static FormatOptions`	`of(int flags, int width, int precision)`	Creates a options instance with the given values.
`static FormatOptions`	`parse(String message, int pos, int end, boolean isUpperCase)`	Parses a sub-sequence of a log message to extract and return its options.
`boolean`	`shouldLeftAlign()`	Corresponds to printf flag '-' (incompatible with '0').
`boolean`	`shouldPrefixPlusForPositiveValues()`	Corresponds to printf flag '+'.
`boolean`	`shouldPrefixSpaceForPositiveValues()`	Corresponds to printf flag ' '.
`boolean`	`shouldShowAltForm()`	Corresponds to printf flag '#'.
`boolean`	`shouldShowGrouping()`	Corresponds to printf flag ','.
`boolean`	`shouldShowLeadingZeros()`	Corresponds to printf flag '0'.
`boolean`	`shouldUpperCase()`	Corresponds to formatting with an upper-case format character.
`boolean`	`validate(int allowedFlags, boolean allowPrecision)`	Validates these options according to the allowed criteria and checks for inconsistencies in flag values.

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - FLAG_PREFIX_SPACE_FOR_POSITIVE_VALUES
```
public static final int FLAG_PREFIX_SPACE_FOR_POSITIVE_VALUES
```
    A formatting flag which specifies that for signed numeric output, positive values should be prefixed with an ASCII space (' '). This corresponds to the ' ' printf flag and is valid for all signed numeric types.
    
    See Also:
    
    Constant Field Values
  - FLAG_SHOW_ALT_FORM
```
public static final int FLAG_SHOW_ALT_FORM
```
    A formatting flag which specifies that output should be shown in a type dependent alternate form. This corresponds to the '#' printf flag and is valid for:
    
    Octal (%o) and hexadecimal (%x, %X) formatting, where it specifies that the radix should be shown.
    Floating point (%f) and exponential (%e, %E, %a, %A) formatting, where it specifies that a decimal separator should always be shown.
    See Also:
    
    Constant Field Values
  - FLAG_USE_PARENS_FOR_NEGATIVE_VALUES
```
public static final int FLAG_USE_PARENS_FOR_NEGATIVE_VALUES
```
    A formatting flag which specifies that for signed numeric output, negative values should be surrounded by parentheses. This corresponds to the '(' printf flag and is valid for all signed numeric types.
    
    See Also:
    
    Constant Field Values
  - FLAG_PREFIX_PLUS_FOR_POSITIVE_VALUES
```
public static final int FLAG_PREFIX_PLUS_FOR_POSITIVE_VALUES
```
    A formatting flag which specifies that for signed numeric output, positive values should be prefixed with an ASCII plus ('+'). This corresponds to the '+' printf flag and is valid for all signed numeric types.
    
    See Also:
    
    Constant Field Values
  - FLAG_SHOW_GROUPING
```
public static final int FLAG_SHOW_GROUPING
```
    A formatting flag which specifies that for non-exponential, base-10, numeric output a grouping separator (often a ',') should be used. This corresponds to the ',' printf flag and is valid for:
    
    Decimal (%d) and unsigned (%u) formatting.
    Float (%f) and general scientific notation (%g, %G)
    See Also:
    
    Constant Field Values
  - FLAG_LEFT_ALIGN
```
public static final int FLAG_LEFT_ALIGN
```
    A formatting flag which specifies that output should be left-aligned within the minimum available width. This corresponds to the '-' printf flag and is valid for all FormatChar instances, though it must be specified in conjunction with a width value.
    
    See Also:
    
    Constant Field Values
  - FLAG_SHOW_LEADING_ZEROS
```
public static final int FLAG_SHOW_LEADING_ZEROS
```
    A formatting flag which specifies that numeric output should be padding with leading zeros as necessary to fill the minimum width. This corresponds to the '0' printf flag and is valid for all numeric types, though it must be specified in conjunction with a width value.
    
    See Also:
    
    Constant Field Values
  - FLAG_UPPER_CASE
```
public static final int FLAG_UPPER_CASE
```
    A formatting flag which specifies that output should be upper-cased after all other formatting. This corresponds to having an upper-case format character and is valud for any type with an upper case variant.
    
    See Also:
    
    Constant Field Values
  - ALL_FLAGS
```
public static final int ALL_FLAGS
```
    A mask of all allowed formatting flags. Useful when filtering options via filter(int, boolean, boolean).
    
    See Also:
    
    Constant Field Values
  - UNSET
```
public static final int UNSET
```
    The value used to specify that either width or precision were not specified.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - getDefault
```
public static FormatOptions getDefault()
```
    Returns the default options singleton instance.
  - of
```
public static FormatOptions of(int flags,
                               int width,
                               int precision)
```
    Creates a options instance with the given values.
  - parse
```
public static FormatOptions parse(String message,
                                  int pos,
                                  int end,
                                  boolean isUpperCase)
                           throws ParseException
```
    Parses a sub-sequence of a log message to extract and return its options. Note that callers cannot rely on this method producing new instances each time it is called as caching of common option values may occur.
    
    Parameters:
    
    message - the original log message in which the formatting options have been identified.
    
    pos - the index of the first character to parse.
    
    end - the index after the last character to be parsed.
    
    Returns:
    
    the parsed options instance.
    
    Throws:
    
    ParseException - if the specified sub-sequence of the string could not be parsed.
  - filter
```
public FormatOptions filter(int allowedFlags,
                            boolean allowWidth,
                            boolean allowPrecision)
```
    Returns a possibly new FormatOptions instance possibly containing a subset of the formatting information. This is useful if a backend implementation wishes to create formatting options that ignore some of the specified formatting information.
    
    Parameters:
    
    allowedFlags - A mask of flag values to be retained in the returned instance. Use ALL_FLAGS to retain all flag values, or 0 to suppress all flags.
    
    allowWidth - specifies whether to include width in the returned instance.
    
    allowPrecision - specifies whether to include precision in the returned instance.
  - isDefault
```
public boolean isDefault()
```
    Returns true if this instance has only default formatting options.
  - getWidth
```
public int getWidth()
```
    Returns the width for these options, or UNSET if not specified. This is a non-negative decimal integer which typically indicates the minimum number of characters to be written to the output, but its precise meaning is dependent on the formatting rule it is applied to.
  - getPrecision
```
public int getPrecision()
```
    Returns the precision for these options, or UNSET if not specified. This is a non-negative decimal integer, usually used to restrict the number of characters, but its precise meaning is dependent on the formatting rule it is applied to.
  - validate
```
public boolean validate(int allowedFlags,
                        boolean allowPrecision)
```
    Validates these options according to the allowed criteria and checks for inconsistencies in flag values.
    Note that there is not requirement for options used internally in custom message parsers to be validated, but any format options passed through the ParameterVisitor interface must be valid with respect to the associated FormatChar instance.
    
    Parameters:
    
    allowedFlags - a bit mask specifying a subset of the printf flags that are allowed for these options.
    
    allowPrecision - true if these options are allowed to have a precision value specified.
    
    Returns:
    
    true if these options are valid given the specified constraints.
  - areValidFor
```
public boolean areValidFor(FormatChar formatChar)
```
    Validates these options as if they were being applied to the given FormatChar and checks for inconsistencies in flag values.
    Note that there is not requirement for options used internally in custom message parsers to be validated, but any format options passed through the ParameterVisitor interface must be valid with respect to the associated FormatChar instance.
    
    Parameters:
    
    formatChar - the formatting rule to check these options against.
    
    Returns:
    
    true if these options are valid for the given format.
  - getFlags
```
public int getFlags()
```
    Returns the flag bits for this options instance. Where possible the per-flag methods shouldXxx() should be preferred for code clarity, but for efficiency and when testing multiple flags values at the same time, this method is useful.
  - shouldLeftAlign
```
public boolean shouldLeftAlign()
```
    Corresponds to printf flag '-' (incompatible with '0').
    Logging backends may ignore this flag, though it does provide some visual clarity when aligning values.
  - shouldShowAltForm
```
public boolean shouldShowAltForm()
```
    Corresponds to printf flag '#'.
    Logging backends should honor this flag for hex or octal, as it is a common way to avoid ambiguity when formatting non-decimal values.
  - shouldShowLeadingZeros
```
public boolean shouldShowLeadingZeros()
```
    Corresponds to printf flag '0'.
    Logging backends should honor this flag, as it is very commonly used to format hexadecimal or octal values to allow specific bit values to be calculated.
  - shouldPrefixPlusForPositiveValues
```
public boolean shouldPrefixPlusForPositiveValues()
```
    Corresponds to printf flag '+'.
    Logging backends are free to ignore this flag, though it does provide some visual clarity when tabulating certain types of values.
  - shouldPrefixSpaceForPositiveValues
```
public boolean shouldPrefixSpaceForPositiveValues()
```
    Corresponds to printf flag ' '.
    Logging backends are free to ignore this flag, though if they choose to support shouldPrefixPlusForPositiveValues() then it is advisable to support this as well.
  - shouldShowGrouping
```
public boolean shouldShowGrouping()
```
    Corresponds to printf flag ','.
    Logging backends are free to select the locale in which the formatting will occur or ignore this flag altogether.
  - shouldUpperCase
```
public boolean shouldUpperCase()
```
    Corresponds to formatting with an upper-case format character.
    Logging backends are free to ignore this flag.
  - appendPrintfOptions
```
@CanIgnoreReturnValue
public StringBuilder appendPrintfOptions(StringBuilder out)
```
    Appends the data for this options instance in a printf compatible form to the given buffer. This method neither appends the leading % symbol nor a format type character. Output is written in the form [width][.precision][flags] and for the default instance, nothing is appended.
    
    Parameters:
    
    out - The output buffer to which the options are appended.
  - equals
```
public boolean equals(@Nullable Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object

Class FormatOptions

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

FLAG_PREFIX_SPACE_FOR_POSITIVE_VALUES

FLAG_SHOW_ALT_FORM

FLAG_USE_PARENS_FOR_NEGATIVE_VALUES

FLAG_PREFIX_PLUS_FOR_POSITIVE_VALUES

FLAG_SHOW_GROUPING

FLAG_LEFT_ALIGN

FLAG_SHOW_LEADING_ZEROS

FLAG_UPPER_CASE

ALL_FLAGS

UNSET

Method Detail

getDefault

of

parse

filter

isDefault

getWidth

getPrecision

validate

areValidFor

getFlags

shouldLeftAlign

shouldShowAltForm

shouldShowLeadingZeros

shouldPrefixPlusForPositiveValues

shouldPrefixSpaceForPositiveValues

shouldShowGrouping

shouldUpperCase

appendPrintfOptions

equals

hashCode