FormatOptions

public struct FormatOptions { /* private fields */ }

Mutable bag of formatting knobs threaded through every Formattable.format call.

FormatOptions is the parsed form of the format-spec mini-language. String interpolation "\{expr:spec}" constructs one of these from the trailing spec, then hands it to the formatter for expr's type. Each formatter reads only the fields that apply to it: integers ignore floatStyle, strings ignore radix, and so on.

Format spec mini-language

[[fill]align][sign][#][0][width][.precision][type]

Where type is one of:

Integers: b (binary), o (octal), x (hex lower), X (hex upper)
Floats: f (fixed), e (scientific), E (scientific upper), % (percent)
Any: ? (debug)

Examples

"\{n:>8}";      // right-align, width 8
"\{n:08x}";     // zero-pad, width 8, hex
"\{n:#X}";      // hex upper with 0x prefix
"\{pi:.2}";     // precision 2 decimal places
"\{pi:.2e}";    // scientific with 2 decimal places
"\{ratio:%}";   // as percentage (0.5 -> "50%")
"\{name:^10}";  // center, width 10
"\{value:?}";   // debug format

Representation

A flat record of independent fields — no validation across them. Each formatter is responsible for ignoring fields outside its domain and applying its own defaults when an option is absent.

Properties

public var alignment: Alignment

How to position the value inside width when padding is required.

public var alternate: Bool

Alternate form: emit the conventional radix prefix (0b, 0o, 0x/0X) for non-decimal integers.

public var debug: Bool

When true, formatters should produce a structural / debug representation rather than a user-facing one.

public var fill: Char

Padding character — defaults to ' '. Only applies when width is set and the value is shorter.

public var floatStyle: FloatStyle

Float rendering style (fixed, scientific, percent, auto).

public var precision: Int64?

For floats: number of decimal places (or significant digits in Auto mode). For strings: maximum character count.

public var radix: Int64

Numeric base for integer formatting: 2 (binary), 8 (octal), 10 (decimal), 16 (hex).

public var sign: Sign

Sign-display strategy for numeric formatters.

public var uppercase: Bool

When true, integer hex digits are emitted as A–F rather than a–f.

public var width: Int64?

Minimum field width in characters; shorter values are padded with fill according to alignment.

Initializers

public init()

Creates a FormatOptions with every field at its default value.

Defaults: no width or precision, left alignment, space fill, decimal radix, lowercase hex, negative-only sign, no alternate form, Auto float style, debug off.

Examples

var opts = FormatOptions();
opts.width = .Some(6);
opts.alignment = .Right;
"hi".format(options: opts);  // "    hi"

Methods

public static func default() -> FormatOptions

Returns a fresh FormatOptions with all fields at their default values.

Equivalent to calling FormatOptions(); provided as a static so callers that want defaults without spelling out the constructor (e.g. default-arg expressions) have a clean call site.

Examples

let opts = FormatOptions.default();
(42).format(options: opts);  // "42"

ImplementsEquatable

Associated Types

type Output = Bool

Methods

public func equal(to: Self) -> Bool

Bridges Equal.equal(to:) to Equatable.isEqual(to:).

public func isEqual(to: FormatOptions) -> Bool

Returns true if all fields are equal between the two options.

width and precision are not compared — they typically reflect per-call overrides rather than logical identity. Compare them explicitly if needed.

Examples

let a = FormatOptions();
let b = FormatOptions();
a.isEqual(to: b);  // true
var c = FormatOptions();
c.alternate = true;
a.isEqual(to: c);  // false

public func notEqual(to: Self) -> Bool

Default !=: delegates to == so there's a single source of truth.

Defined in lang/std/text/format.ks