std: Stabilize the std::fmt module #21713
Conversation
|
r? @aturon (rust_highfive has picked a reviewer for you, use r? to override) |
|
This is a continuation of #21457 cc @eddyb, @cmr, I remember you guys saying that you were thinking of some form of hygiene with macro expansion that would not require stabilizing the runtime, but I'm not sure what came of this. cc @seanmonstar, this has implications on how rust-lang/rfcs#583 can be implemented in a pre-1.0 world, but I believe it is still possible to do backwards compatibly |
|
I know 583 hasn't been accepted yet, but I have an almost-complete On Tue, Jan 27, 2015, 7:23 PM Alex Crichton notifications@github.com
|
|
Cool! I think we'll want to stabilize the APIs in this PR regardless because otherwise you'll get dozens of warnings for using |
|
It seems like the size hint stuff fits in a way that it can be unstable for On Tue, Jan 27, 2015, 7:36 PM Alex Crichton notifications@github.com
|
|
@cmr claimed it was already implemented, but I never ended up investigating it, sorry. Will try to experiment today to get a feel for the current rules. Hopefully I'll have some results before this PR is merged. |
|
@seanmonstar unfortunately @eddyb ok thanks! It would sure be nice if we didn't have to stabilize all these details! |
|
@eddyb I should also add that destabilizing these internals is totally OK with me, I really highly doubt that anyone is using them today or anyone will use them before 1.0. |
alexcrichton
force-pushed
the
second-pass-fmt
branch
5 times, most recently
from
1c34519
to
2869863
Compare
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`) 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. Closes rust-lang#20661 [breaking-change]
alexcrichton
force-pushed
the
second-pass-fmt
branch
from
2869863
to
6227357
Compare
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
writefunction 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::Argumentstructure. Whenever an argument is formatted withnonstandard flags, a corresponding
rt::Argumentis generated describing howthe argument is being formatted. This can be used to construct an
Arguments.The primary interface to
std::fmtis theArgumentsstructure, and as suchthis type name is stabilize as-is today. It is expected for libraries to pass
around an
Argumentsstructure 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::rtwere all moved underfmt::rt::v1fmt::rtis stablefmt::rt::v1is stableErroris stableWriteris stableWriter::write_stris stableWriter::write_fmtis stableFormatteris stableArgumenthas been renamed toArgumentV1and is stableArgumentV1::newis stableArgumentV1::from_uintis stableArguments::new_v1is stable (renamed fromnew)Arguments::new_v1_formattedis stable (renamed fromwith_placeholders)fmtmethod.fmt::writeis stablefmt::formatis stableFormatter::pad_integralis stableFormatter::padis stableFormatter::write_stris stableFormatter::write_fmtis stableformat_args!wereremoved in favor of static functions on
ArgumentV1as well.Within the contents of the
fmt::rt::v1module, the following actions weretaken:
In addition to these actions in the
std::fmtmodule, many implementations ofShowandStringwere stabilized as well.In some other modules:
ToStringis now stableToString::to_stringis now stableVecno longer implementsfmt::Writer(this has moved toString)This is a breaking change due to all of the changes to the
fmt::rtmodule, butthis likely will not have much impact on existing programs.
Closes #20661
[breaking-change]