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.

[EliasHolzmann]

@joboet I don't think so. Formatter directly holds a FormattingOptions internally: https://doc.rust-lang.org/nightly/src/core/fmt/mod.rs.html#524

If Formatter::new takes its FormattingOptions by reference instead of by value, we'd have to copy the options in that function anyway. (Instead, you probably could have the contents of FormattingOptions behind a Rc so that copying/cloning is cheaper, which might indeed improve performance for use cases with heavy FormattingOptions reuse. However, I don't think that this will compensate the ref-counting overhead that is in most use cases probably unnecessary.)

In most cases, when the FormattingOptions can be used multiple times, the target buffer of the resulting Formatter is probably also the same – in this case, you can just use the Formatter you construct.