Skip to content

Commit

Permalink
remove deprecated stuff from std::fmt docs
Browse files Browse the repository at this point in the history
Fixes #19209
  • Loading branch information
steveklabnik committed Nov 26, 2014
1 parent 48ca6d1 commit 7dadb14
Showing 1 changed file with 17 additions and 22 deletions.
39 changes: 17 additions & 22 deletions src/libstd/fmt.rs
Expand Up @@ -106,35 +106,31 @@ named parameters that are unused by the format string.
### Argument types
Each argument's type is dictated by the format string. It is a requirement that
every argument is only ever referred to by one type. For example, this is an
invalid format string:
Each argument's type is dictated by the format string. It is a requirement that every argument is
only ever referred to by one type. For example, this is an invalid format string:
```text
{0:d} {0:s}
{0:x} {0:o}
```
This is invalid because the first argument is both referred to as an integer as
well as a string.
This is invalid because the first argument is both referred to as a hexidecimal as well as an
octal.
Because formatting is done via traits, there is no requirement that the
`d` format actually takes an `int`, but rather it simply requires a type which
ascribes to the `Signed` formatting trait. There are various parameters which do
require a particular type, however. Namely if the syntax `{:.*s}` is used, then
the number of characters to print from the string precedes the actual string and
must have the type `uint`. Although a `uint` can be printed with `{:u}`, it is
illegal to reference an argument as such. For example, this is another invalid
There are various parameters which do require a particular type, however. Namely if the syntax
`{:.*}` is used, then the number of characters to print precedes the actual object being formatted,
and the number of characters must have the type `uint`. Although a `uint` can be printed with
`{}`, it is illegal to reference an argument as such. For example this is another invalid
format string:
```text
{:.*s} {0:u}
{:.*} {0}
```
### Formatting traits
When requesting that an argument be formatted with a particular type, you are
actually requesting that an argument ascribes to a particular trait. This allows
multiple actual types to be formatted via `{:d}` (like `i8` as well as `int`).
multiple actual types to be formatted via `{:x}` (like `i8` as well as `int`).
The current mapping of types to traits is:
* *nothing* ⇒ `Show`
Expand All @@ -157,12 +153,12 @@ When implementing a format trait for your own type, you will have to implement a
method of the signature:
```rust
# use std;
# mod fmt { pub type Result = (); }
# struct T;
# trait SomeName<T> {
fn fmt(&self, f: &mut std::fmt::Formatter) -> fmt::Result;
# }
# use std::fmt;
# struct Foo; // our custom type
# impl fmt::Show for Foo {
fn fmt(&self, f: &mut std::fmt::Formatter) -> fmt::Result {
# write!(f, "testing, testing")
# } }
```
Your type will be passed as `self` by-reference, and then the function should
Expand Down Expand Up @@ -237,7 +233,6 @@ println! // same as print but appends a newline
format_args! // described below.
```
#### `write!`
This and `writeln` are two macros which are used to emit the format string to a
Expand Down

6 comments on commit 7dadb14

@steveklabnik
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

r=alexcrichton

@bors
Copy link
Contributor

@bors bors commented on 7dadb14 Nov 26, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

saw approval from alexcrichton
at steveklabnik@7dadb14

@bors
Copy link
Contributor

@bors bors commented on 7dadb14 Nov 26, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

merging steveklabnik/rust/doc_format_specifiers = 7dadb14 into auto

@bors
Copy link
Contributor

@bors bors commented on 7dadb14 Nov 26, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

steveklabnik/rust/doc_format_specifiers = 7dadb14 merged ok, testing candidate = 8d7b319

@bors
Copy link
Contributor

@bors bors commented on 7dadb14 Nov 26, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@bors
Copy link
Contributor

@bors bors commented on 7dadb14 Nov 26, 2014

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

fast-forwarding master to auto = 8d7b319

Please sign in to comment.