Tracking Issue for `FormattingOptions` #118117

EliasHolzmann · 2023-11-21T02:29:51Z

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

The text was updated successfully, but these errors were encountered:

EliasHolzmann · 2023-11-21T02:30:02Z

@rustbot claim

…<try> Implementation of `fmt::FormatttingOptions` Tracking issue: rust-lang#118117 Public API: ```rust #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub struct FormattingOptions { … } #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum Sign { Plus, Minus } #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum DebugAsHex { Lower, Upper } impl FormattingOptions { pub fn new() -> Self; pub fn sign(&mut self, sign: Option<Sign>) -> &mut Self; pub fn sign_aware_zero_pad(&mut self, sign_aware_zero_pad: bool) -> &mut Self; pub fn alternate(&mut self, alternate: bool) -> &mut Self; pub fn fill(&mut self, fill: char) -> &mut Self; pub fn align(&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 debug_as_hex(&mut self, debug_as_hex: Option<DebugAsHex>) -> &mut Self; pub fn get_sign(&self) -> Option<Sign>; pub fn get_sign_aware_zero_pad(&self) -> bool; pub fn get_alternate(&self) -> bool; pub fn get_fill(&self) -> char; pub fn get_align(&self) -> Option<Alignment>; pub fn get_width(&self) -> Option<usize>; pub fn get_precision(&self) -> Option<usize>; pub fn get_debug_as_hex(&self) -> Option<DebugAsHex>; 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<'b>(&'b mut self, options: FormattingOptions) -> Formatter<'b>; pub fn sign(&self) -> Option<Sign>; pub fn options(&self) -> FormattingOptions; } ``` Relevant changes from the public API in the tracking issue (I'm leaving out some stuff I consider obvious mistakes, like missing `#[derive(..)]`s and `pub` specifiers): - `enum DebugAsHex`/`FormattingOptions::debug_as_hex`/`FormattingOptions::get_debug_as_hex`: To support `{:x?}` as well as `{:X?}`. I had completely missed these options in the ACP. I'm open for any and all bikeshedding, not married to the name. - `fill`/`get_fill` now takes/returns `char` instead of `Option<char>`. This simply mirrors what `Formatter::fill` returns (with default being `' '`). - Changed `zero_pad`/`get_zero_pad` to `sign_aware_zero_pad`/`get_sign_aware_zero_pad`. This also mirrors `Formatter::sign_aware_zero_pad`. While I'm not a fan of this quite verbose name, I do believe that having the interface of `Formatter` and `FormattingOptions` be compatible is more important. - For the same reason, renamed `alignment`/`get_alignment` to `aling`/`get_align`. - Deviating from my initial idea, `Formatter::with_options` returns a `Formatter` which has the lifetime of the `self` reference as its generic lifetime parameter (in the original API spec, the generic lifetime of the returned `Formatter` was the generic lifetime used by `self` instead). Otherwise, one could construct two `Formatter`s that both mutably borrow the same underlying buffer, which would be unsound. This solution still has performance benefits over simply using `Formatter::new`, so I believe it is worthwhile to keep this method.

…<try> Implementation of `fmt::FormattingOptions` Tracking issue: rust-lang#118117 Public API: ```rust #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub struct FormattingOptions { … } #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum Sign { Plus, Minus } #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum DebugAsHex { Lower, Upper } impl FormattingOptions { pub fn new() -> Self; pub fn sign(&mut self, sign: Option<Sign>) -> &mut Self; pub fn sign_aware_zero_pad(&mut self, sign_aware_zero_pad: bool) -> &mut Self; pub fn alternate(&mut self, alternate: bool) -> &mut Self; pub fn fill(&mut self, fill: char) -> &mut Self; pub fn align(&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 debug_as_hex(&mut self, debug_as_hex: Option<DebugAsHex>) -> &mut Self; pub fn get_sign(&self) -> Option<Sign>; pub fn get_sign_aware_zero_pad(&self) -> bool; pub fn get_alternate(&self) -> bool; pub fn get_fill(&self) -> char; pub fn get_align(&self) -> Option<Alignment>; pub fn get_width(&self) -> Option<usize>; pub fn get_precision(&self) -> Option<usize>; pub fn get_debug_as_hex(&self) -> Option<DebugAsHex>; 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<'b>(&'b mut self, options: FormattingOptions) -> Formatter<'b>; pub fn sign(&self) -> Option<Sign>; pub fn options(&self) -> FormattingOptions; } ``` Relevant changes from the public API in the tracking issue (I'm leaving out some stuff I consider obvious mistakes, like missing `#[derive(..)]`s and `pub` specifiers): - `enum DebugAsHex`/`FormattingOptions::debug_as_hex`/`FormattingOptions::get_debug_as_hex`: To support `{:x?}` as well as `{:X?}`. I had completely missed these options in the ACP. I'm open for any and all bikeshedding, not married to the name. - `fill`/`get_fill` now takes/returns `char` instead of `Option<char>`. This simply mirrors what `Formatter::fill` returns (with default being `' '`). - Changed `zero_pad`/`get_zero_pad` to `sign_aware_zero_pad`/`get_sign_aware_zero_pad`. This also mirrors `Formatter::sign_aware_zero_pad`. While I'm not a fan of this quite verbose name, I do believe that having the interface of `Formatter` and `FormattingOptions` be compatible is more important. - For the same reason, renamed `alignment`/`get_alignment` to `aling`/`get_align`. - Deviating from my initial idea, `Formatter::with_options` returns a `Formatter` which has the lifetime of the `self` reference as its generic lifetime parameter (in the original API spec, the generic lifetime of the returned `Formatter` was the generic lifetime used by `self` instead). Otherwise, one could construct two `Formatter`s that both mutably borrow the same underlying buffer, which would be unsound. This solution still has performance benefits over simply using `Formatter::new`, so I believe it is worthwhile to keep this method.

…m-ou-se Implementation of `fmt::FormattingOptions` Tracking issue: rust-lang#118117 Public API: ```rust #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub struct FormattingOptions { … } #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum Sign { Plus, Minus } #[derive(Copy, Clone, Debug, PartialEq, Eq)] pub enum DebugAsHex { Lower, Upper } impl FormattingOptions { pub fn new() -> Self; pub fn sign(&mut self, sign: Option<Sign>) -> &mut Self; pub fn sign_aware_zero_pad(&mut self, sign_aware_zero_pad: bool) -> &mut Self; pub fn alternate(&mut self, alternate: bool) -> &mut Self; pub fn fill(&mut self, fill: char) -> &mut Self; pub fn align(&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 debug_as_hex(&mut self, debug_as_hex: Option<DebugAsHex>) -> &mut Self; pub fn get_sign(&self) -> Option<Sign>; pub fn get_sign_aware_zero_pad(&self) -> bool; pub fn get_alternate(&self) -> bool; pub fn get_fill(&self) -> char; pub fn get_align(&self) -> Option<Alignment>; pub fn get_width(&self) -> Option<usize>; pub fn get_precision(&self) -> Option<usize>; pub fn get_debug_as_hex(&self) -> Option<DebugAsHex>; 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<'b>(&'b mut self, options: FormattingOptions) -> Formatter<'b>; pub fn sign(&self) -> Option<Sign>; pub fn options(&self) -> FormattingOptions; } ``` Relevant changes from the public API in the tracking issue (I'm leaving out some stuff I consider obvious mistakes, like missing `#[derive(..)]`s and `pub` specifiers): - `enum DebugAsHex`/`FormattingOptions::debug_as_hex`/`FormattingOptions::get_debug_as_hex`: To support `{:x?}` as well as `{:X?}`. I had completely missed these options in the ACP. I'm open for any and all bikeshedding, not married to the name. - `fill`/`get_fill` now takes/returns `char` instead of `Option<char>`. This simply mirrors what `Formatter::fill` returns (with default being `' '`). - Changed `zero_pad`/`get_zero_pad` to `sign_aware_zero_pad`/`get_sign_aware_zero_pad`. This also mirrors `Formatter::sign_aware_zero_pad`. While I'm not a fan of this quite verbose name, I do believe that having the interface of `Formatter` and `FormattingOptions` be compatible is more important. - For the same reason, renamed `alignment`/`get_alignment` to `aling`/`get_align`. - Deviating from my initial idea, `Formatter::with_options` returns a `Formatter` which has the lifetime of the `self` reference as its generic lifetime parameter (in the original API spec, the generic lifetime of the returned `Formatter` was the generic lifetime used by `self` instead). Otherwise, one could construct two `Formatter`s that both mutably borrow the same underlying buffer, which would be unsound. This solution still has performance benefits over simply using `Formatter::new`, so I believe it is worthwhile to keep this method.

EliasHolzmann added C-tracking-issue Category: An issue tracking the progress of sth. like the implementation of an RFC T-libs-api Relevant to the library API team, which will review and decide on the PR/issue. labels Nov 21, 2023

rustbot assigned EliasHolzmann Nov 21, 2023

dtolnay changed the title ~~Tracking Issue for XXX~~ Tracking Issue for FormattingOptions Nov 21, 2023

EliasHolzmann mentioned this issue Nov 22, 2023

Implementation of fmt::FormattingOptions #118159

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Tracking Issue for `FormattingOptions` #118117

Tracking Issue for `FormattingOptions` #118117

EliasHolzmann commented Nov 21, 2023 •

edited

Loading

EliasHolzmann commented Nov 21, 2023

Tracking Issue for FormattingOptions #118117

Tracking Issue for FormattingOptions #118117

Comments

EliasHolzmann commented Nov 21, 2023 • edited Loading

Public API

Steps / History

Unresolved Questions

Footnotes

EliasHolzmann commented Nov 21, 2023

Tracking Issue for `FormattingOptions` #118117

Tracking Issue for `FormattingOptions` #118117

EliasHolzmann commented Nov 21, 2023 •

edited

Loading