Tracking Issue for `FormattingOptions`

[EliasHolzmann]

Feature gate: #![feature(formatting_options)]

This is a tracking issue for fmt::FormattingOptions.

FormattingOptions can be used to construct custom Formatters at runtime.

Public API

#[derive(Copy, Clone, Debug, PartialEq, Eq)]
pub struct FormattingOptions { … }

enum Sign {
    Plus, 
    Minus
}

impl FormattingOptions {
    pub fn new() -> Self;

    pub fn sign(&mut self, sign: Option<Sign>) -> &mut Self;
    pub fn zero_pad(&mut self, zero_pad: bool) -> &mut Self;
    pub fn alternate(&mut self, alternate: bool) -> &mut Self;
    pub fn fill(&mut self, fill: Option<char>) -> &mut Self;
    pub fn alignment(&mut self, alignment: Option<Alignment>) -> &mut Self;
    pub fn width(&mut self, width: Option<usize>) -> &mut Self;
    pub fn precision(&mut self, precision: Option<usize>) -> &mut Self;

    pub fn get_sign(&self) -> Option<Sign>;
    pub fn get_zero_pad(&self) -> bool;
    pub fn get_alternate(&self) -> bool;
    pub fn get_fill(&self) -> Option<char>;
    pub fn get_alignment(&self) -> Option<Alignment>;
    pub fn get_width(&self) -> Option<usize>;
    pub fn get_precision(&self) -> Option<usize>;
    
    pub fn create_formatter<'a>(self, write: &'a mut (dyn Write + 'a)) -> Formatter<'a>;
}

impl<'a> Formatter<'a> {
    pub fn new(write: &'a mut (dyn Write + 'a), options: FormattingOptions) -> Self;
    pub fn with_options(&mut self, options: FormattingOptions) -> Self;
    
    pub fn sign(&self) -> Option<Sign>;

    pub fn options(&self) -> FormattingOptions;
}

Steps / History

• API change proposal (ACP)¹: [ACP] Provide an interface for creating instances of fmt::Formatter libs-team#286
• Implementation: Implementation of fmt::FormattingOptions #118159
• Final comment period (FCP)²
• Stabilization PR

Unresolved Questions

• Should this expose the "debug as hex" flags? ({:x?} and {:X?})
• Should we make the methods receiving parameters as &mut (especially the setters for FormattingOptions) const (which is currently unstable)? See Implementation of fmt::FormattingOptions #118159 (comment) for context

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/api-change-proposals.html ↩

2. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[EliasHolzmann]

@rustbot claim

[joboet]

I was wondering: could the signature for Formatter::new be changed to take a reference to the FormattingOptions instead of passing them by value? That way, LLVM wouldn't need to copy around the options as often, which seems like it could improve performance and binary size in cases where the same options are used multiple times, for instance when using the default options.