ST::format_spec

ST::format_spec

Headers

#include <string_theory/formatter>

Public Types

Name	Summary
alignment_t	Alignment types for filling width
digit_class_t	Digit classification type
float_class_t	Floating point classification type

Public Functions

Name	Summary
(constructor)	Default constructor

Public Members

Name	Summary
minimum_length	Minimum width for formatted output
precision	Number of digits of precision for numeric formats
arg_index	Index of the argument to format
alignment	Formatted alignment
digit_class	Requested digit classification
float_class	Requested floating point classification
pad	Padding character for filling in minimum width
always_signed	Whether to output a + for positive numbers
class_prefix	Whether to output a prefix based on the numeric base
numeric_pad	Whether to use numeric padding rules

Details

The ST::format_spec structure defines the parameters for formatting an object with string_theory's formatters. It is usually populated by the format call itself (see the Format string reference guide for details), but it can also be modified if necessary within the type formatter. Mostly, it is useful for deciding how to format something based on the user's requested formatting rules.

Member Type Documentation

ST::alignment_t

enum alignment_t
{
    align_default,
    align_left,
    align_right
};

Indicates the text alignment for objects.

• align_default: Use the formatter-specific default alignment for the given data. For built-in formatters, this is right for numbers and left for everything else.
• align_left: Align text to the left of the reserved format space.
• align_right: Align text to the right of the reserved format space.

---

ST::digit_class_t

enum digit_class_t
{
    digit_default,
    digit_dec,
    digit_hex,
    digit_hex_upper,
    digit_oct,
    digit_bin,
    digit_char
};

Specifies the number base to use when formatting numeric objects.

• digit_default: Use the default digit class. This is digit_dec for integers and digit_char for character types.
• digit_dec: Format number in decimal (base 10).
• digit_hex: Format number in lower-case hexadecimal.
• digit_hex_upper: Format number in upper-case hexadecimal.
• digit_oct: Format number in octal (base 8).
• digit_bin: Format number in binary.
• digit_char: Format number as a single Unicode character (encoded as UTF-8).

---

ST::float_class_t

enum float_class_t
{
    float_default,
    float_fixed,
    float_exp,
    float_exp_upper
};

Specifies the formatting type to use when formatting floating-point numbers.

• float_default: Auto-determine the formatting rules. This is equivalent to the '%g' printf-style format.
• float_fixed: Format number in fixed-point. This is equivalent to the '%f' printf-style format.
• float_exp: Format number in exponent notation. This is equivalent to the '%e' printf-style format.
• float_exp_upper: Identical to float_exp, except that an upper-case 'E' is used to separate the base from the exponent.

---

Member Documentation

ST::format_spec constructor

Signature
format_spec() noexcept

Default constructor. Sets all properties to their default values.

---

ST::format_spec::alignment

Signature
ST::alignment_t alignment

Which direction to align the text. Note that this value is only meaningful if the actual length of the formatted text is shorter than the specified minimum_length. For the case of align_default, it is up to the formatter to decide which direction to align the text. For the built-in formatters, align_right is used for numerics, and align_left is used for everything else.

Note that when numeric_pad is true, this value will not be used, since numeric padding is always on the left side of the number.

---

ST::format_spec::always_signed

Signature
bool always_signed

If this property is true, then a '+' should be added to the left of numeric formats for positive and unsigned values.

---

ST::format_spec::arg_index

Signature
int arg_index

If this parameter is greater than zero, then it specifies which format argument should be used for the format. If it is less than zero (the default), then the next argument in order should be used for formatting.

Since string_theory 2.0.

---

ST::format_spec::class_prefix

Signature
bool class_prefix

If this property is true, then a digit_class-specific prefix should be added to the left of numeric formats.

The following prefixes are added:

• digit_bin: '0b'
• digit_hex: '0x'
• digit_hex_upper: '0X'
• digit_oct: '0'
• Others: (no prefix)

---

ST::format_spec::digit_class

Signature
ST::digit_class_t digit_class

How to format integer and character objects. For details, see the digit_class_t enumeration documentation.

---

ST::format_spec::float_class

Signature
ST::float_class_t float_class

How to render floating point numbers. For details, see the float_class_t enumeration documentation.

---

ST::format_spec::minimum_length

Signature
int minimum_length

The minimum number of characters to use in formatting the object. If the actual formatted length is less than minimum_length, the extra space will be filled in with pad characters.

---

ST::format_spec::numeric_pad

Signature
bool numeric_pad

If this property is true, then numeric rules should be used when applying the pad character (usually '0') to the left side of the format. Specifically:

• Other prefixes (like the class_prefix and the sign) should be placed before the padding.
• Alignment is always right -- the zeros should always be on the left side of the formatted digits.

---

ST::format_spec::pad

Signature
char pad

The character to use when padding formatted strings. If the resulting format is shorter than minimum_length, this (ASCII) character will be used to fill in from either the left or right, depending on the value of the alignment property.

---

ST::format_spec::precision

Signature
int precision

The precision to use when formatting floating-point numbers. That is, the number of digits after the radix for float_fixed and float_exp numbers, or the total number of significant digits for float_default numbers.