Skip to content

refactor!: DynDisplay API to mirror std::fmt::Display#4

Merged
qjerome merged 1 commit into
mainfrom
refactor/dyn-display
May 21, 2026
Merged

refactor!: DynDisplay API to mirror std::fmt::Display#4
qjerome merged 1 commit into
mainfrom
refactor/dyn-display

Conversation

@qjerome
Copy link
Copy Markdown
Owner

@qjerome qjerome commented May 21, 2026

Summary
Refactor the DynDisplay trait API to mirror std::fmt::Display, introducing a Formatter type that implements std::fmt::Write for natural use of write! inside formatting implementations.

Motivation
The previous API returned Result<String, Error> from dyn_fmt, requiring manual alignment and intermediate allocations. The new design follows Rust's standard formatting conventions, enabling zero-allocation streaming to the output sink and leveraging the familiar write! macro.

Changes

  • Add Formatter<'a> struct bundling FormatSpec and output sink, implementing std::fmt::Write
  • Add pub type Result = std::result::Result<(), Error> for trait consistency
  • Change DynDisplay::dyn_fmt signature from fn(&self, &FormatSpec) -> Result<String, Error> to fn(&self, &mut Formatter<'_>) -> Result
  • Replace FormatSpec::fill_and_align with write_aligned that writes directly to sink (removes per-argument String allocation)
  • Rename pipeline driver from Formatter<'s> to Writer<'s> to avoid naming conflict
  • Add Error::Write variant for fmt write failures
  • Add Error::NamedArgument variant; named/positional arguments ({0}, {name}) now return Err instead of silently formatting positionally
  • Update all standard type implementations in src/imp.rs to use new API
  • Update documentation and examples throughout

Breaking Changes

  • DynDisplay::dyn_fmt signature change requires all implementers to migrate
  • Formatter struct renamed to Writer in the public API
  • fill_and_align removed; alignment now handled automatically via Formatter::finish

Testing
Existing test suite passes with updated implementations. All dformat! usage remains unchanged.

Notes
This aligns the library's mental model with std::fmt, making custom implementations more intuitive for Rust developers.

Introduce dyf::Formatter<'a> as a per-value formatting context that
bundles the FormatSpec and output sink, mirroring std::fmt::Formatter.

Formatter<'a> implements std::fmt::Write so write!(f, ...) works
directly inside dyn_fmt.

Other changes:
- Add pub type Result = std::result::Result<(), Error>
- Replace FormatSpec::fill_and_align with write_aligned writing
  directly to the sink (removes one String allocation per argument)
- Rename pipeline Formatter<'s> to Writer<'s>
- Add Error::Write and Error::NamedArgument; named/positional arguments
  ({0}, {name}) now return Err instead of silently formatting positionally
@qjerome qjerome changed the title refactor: DynDisplay API to mirror std::fmt::Display refactor!: DynDisplay API to mirror std::fmt::Display May 21, 2026
@qjerome qjerome merged commit 2166064 into main May 21, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant