-
Notifications
You must be signed in to change notification settings - Fork 12.9k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
std: Stabilize the std::fmt module #21125
Closed
Closed
+385
−271
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This commit performs a final stabilization pass over the std::fmt module, marking all necessary APIs as stable. One of the more interesting aspects of this module is that it exposes a good deal of its runtime representation to the outside world in order for `format_args!` to be able to construct the format strings. Instead of hacking the compiler to assume that these items are stable, this commit instead lays out a story for the stabilization and evolution of these APIs. There are three primary details used by the `format_args!` macro: 1. `Arguments` - an opaque package of a "compiled format string". This structure is passed around and the `write` function is the source of truth for transforming a compiled format string into a string at runtime. This must be able to be constructed in stable code. 2. `Argument` - an opaque structure representing an argument to a format string. This is *almost* a trait object as it's just a pointer/function pair, but due to the function originating from one of many traits, it's not actually a trait object. Like `Arguments`, this must be constructed from stable code. 3. `fmt::rt` - this module contains the runtime type definitions primarily for the `rt::Argument` structure. Whenever an argument is formatted with nonstandard flags, a corresponding `rt::Argument` is generated describing how the argument is being formatted. This can be used to construct an `Arguments`. The primary interface to `std::fmt` is the `Arguments` structure, and as such this type name is stabilize as-is today. It is expected for libraries to pass around an `Arguments` structure to represent a pending formatted computation. The remaining portions are largely "cruft" which would rather not be stabilized, but due to the stability checks they must be. As a result, almost all pieces have been renamed to represent that they are "version 1" of the formatting representation. The theory is that at a later date if we change the representation of these types we can add new definitions called "version 2" and corresponding constructors for `Arguments`. One of the other remaining large questions about the fmt module were how the pending I/O reform would affect the signatures of methods in the module. Due to [RFC 526][rfc], however, the writers of fmt are now incompatible with the writers of io, so this question has largely been solved. As a result the interfaces are largely stabilized as-is today. [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/0526-fmt-text-writer.md Specifically, the following changes were made: * The contents of `fmt::rt` were all moved under `fmt::rt::v1` * `fmt::rt` is stable * `fmt::rt::v1` is stable * `Error` is stable * `Writer` is stable * `Writer::write_str` is stable * `Writer::write_fmt` is stable * `Formatter` is stable * `Argument` has been renamed to `ArgumentV1` and is stable * `ArgumentV1::new` is stable * `ArgumentV1::from_uint` is stable * `Arguments::new_v1` is stable (renamed from `new`) * `Arguments::new_v1_formatted` is stable (renamed from `with_placeholders`) * All formatting traits are now stable, as well as the `fmt` method. * `fmt::write` is stable * `fmt::format` is stable * `Formatter::pad_integral` is stable * `Formatter::pad` is stable * `Formatter::write_str` is stable * `Formatter::write_fmt` is stable * Some assorted top level items which were only used by `format_args!` were removed in favor of static functions on `ArgumentV1` as well. * The formatting-flag-accessing methods remain unstable Within the contents of the `fmt::rt::v1` module, the following actions were taken: * Reexports of all enum variants were removed * All prefixes on enum variants were removed * A few miscellaneous enum variants were renamed * Otherwise all structs, fields, and variants were marked stable. In addition to these actions in the `std::fmt` module, many implementations of `Show` and `String` were stabilized as well. In some other modules: * `ToString` is now stable * `ToString::to_string` is now stable * `Vec` no longer implements `fmt::Writer` (this has moved to `String`) While stabilize the formatting traits, the following change was also made to the `result` module: * `Result::unwrap` now requires `String` instead of `Show` * `Result::unwrap_err` now requires `String` instead of `Show` This is a breaking change due to all of the changes to the `fmt::rt` module, but this likely will not have much impact on existing programs. It is also a breaking change due to the usage of `String` for `unwrap()` on `Result` instead of `Show`. Error types should implement `String` for human readable errors and `Show` for inspecting their representation. Closes rust-lang#20661 [breaking-change]
r? @aturon |
(rust_highfive has picked a reviewer for you, use r? to override) |
Some open questions I thought of while writing this:
|
Could we also get some stable way of extracting useful values out of Formatter.flags? |
After some discussion on IRC I'm closing this until rust-lang/rfcs#565 has been decided |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This commit performs a final stabilization pass over the std::fmt module,
marking all necessary APIs as stable. One of the more interesting aspects of
this module is that it exposes a good deal of its runtime representation to the
outside world in order for
format_args!
to be able to construct the formatstrings. Instead of hacking the compiler to assume that these items are stable,
this commit instead lays out a story for the stabilization and evolution of
these APIs.
There are three primary details used by the
format_args!
macro:Arguments
- an opaque package of a "compiled format string". This structureis passed around and the
write
function is the source of truth fortransforming a compiled format string into a string at runtime. This must be
able to be constructed in stable code.
Argument
- an opaque structure representing an argument to a format string.This is almost a trait object as it's just a pointer/function pair, but due
to the function originating from one of many traits, it's not actually a
trait object. Like
Arguments
, this must be constructed from stable code.fmt::rt
- this module contains the runtime type definitions primarily forthe
rt::Argument
structure. Whenever an argument is formatted withnonstandard flags, a corresponding
rt::Argument
is generated describing howthe argument is being formatted. This can be used to construct an
Arguments
.The primary interface to
std::fmt
is theArguments
structure, and as suchthis type name is stabilize as-is today. It is expected for libraries to pass
around an
Arguments
structure to represent a pending formatted computation.The remaining portions are largely "cruft" which would rather not be stabilized,
but due to the stability checks they must be. As a result, almost all pieces
have been renamed to represent that they are "version 1" of the formatting
representation. The theory is that at a later date if we change the
representation of these types we can add new definitions called "version 2" and
corresponding constructors for
Arguments
.One of the other remaining large questions about the fmt module were how the
pending I/O reform would affect the signatures of methods in the module. Due to
RFC 526, however, the writers of fmt are now incompatible with the
writers of io, so this question has largely been solved. As a result the
interfaces are largely stabilized as-is today.
Specifically, the following changes were made:
fmt::rt
were all moved underfmt::rt::v1
fmt::rt
is stablefmt::rt::v1
is stableError
is stableWriter
is stableWriter::write_str
is stableWriter::write_fmt
is stableFormatter
is stableArgument
has been renamed toArgumentV1
and is stableArgumentV1::new
is stableArgumentV1::from_uint
is stableArguments::new_v1
is stable (renamed fromnew
)Arguments::new_v1_formatted
is stable (renamed fromwith_placeholders
)fmt
method.fmt::write
is stablefmt::format
is stableFormatter::pad_integral
is stableFormatter::pad
is stableFormatter::write_str
is stableFormatter::write_fmt
is stableformat_args!
wereremoved in favor of static functions on
ArgumentV1
as well.Within the contents of the
fmt::rt::v1
module, the following actions weretaken:
In addition to these actions in the
std::fmt
module, many implementations ofShow
andString
were stabilized as well.In some other modules:
ToString
is now stableToString::to_string
is now stableVec
no longer implementsfmt::Writer
(this has moved toString
)While stabilize the formatting traits, the following change was also made to the
result
module:Result::unwrap
now requiresString
instead ofShow
Result::unwrap_err
now requiresString
instead ofShow
This is a breaking change due to all of the changes to the
fmt::rt
module, butthis likely will not have much impact on existing programs. It is also a
breaking change due to the usage of
String
forunwrap()
onResult
insteadof
Show
. Error types should implementString
for human readable errors andShow
for inspecting their representation.Closes #20661
[breaking-change]