Skip to content
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

documentation for fmt binary trait: slightly misleading example #116165

Closed
feored opened this issue Sep 26, 2023 · 3 comments
Closed

documentation for fmt binary trait: slightly misleading example #116165

feored opened this issue Sep 26, 2023 · 3 comments
Assignees
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-libs Relevant to the library team, which will review and decide on the PR/issue.

Comments

@feored
Copy link

feored commented Sep 26, 2023

Location

https://doc.rust-lang.org/std/fmt/trait.Binary.html

Specifically the last assert in the Examples section:

assert_eq!( format!("l as binary is: {l:#032b}"), "l as binary is: 0b000000000000000000000001101011" );

Summary

This example shows how to format the binary representation of an i32 and was probably meant to display all 32 bits, but actually only displays 30 bits because the alternate flag # adds the prefix 0b to the representation, which is included in the total width of the padding (which is mentioned in passing here: https://doc.rust-lang.org/std/fmt/index.html#sign0 ).

I think it would be useful to mention in that example that the 0b prefix is included in the total width, and I would also suggest changing the example to use {l:#034b} as that is probably what the reader is expecting when displaying a padded i32,

@feored feored added the A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools label Sep 26, 2023
@rustbot rustbot added the needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. label Sep 26, 2023
@saethlin saethlin added T-libs Relevant to the library team, which will review and decide on the PR/issue. and removed needs-triage This issue may need triage. Remove it if it has been sufficiently triaged. labels Sep 27, 2023
@Colonial-Dev
Copy link
Contributor

@rustbot claim

matthiaskrgr added a commit to matthiaskrgr/rust that referenced this issue Oct 2, 2023
…oshtriplett

Correct misleading std::fmt::Binary example (rust-lang#116165)

Nothing too crazy...

- Add two to the width specifier (so all 32 bits are correctly displayed)
- Pad out the compared string so the assert passes
- Add `// Note` comment highlighting the need for the extra width when using the `#` flag.

The exact contents (and placement?) of the note are, of course, highly bikesheddable.
bors added a commit to rust-lang-ci/rust that referenced this issue Oct 2, 2023
…iaskrgr

Rollup of 3 pull requests

Successful merges:

 - rust-lang#116313 (Some small cleanups in `rustc_abi`)
 - rust-lang#116326 (Correct misleading std::fmt::Binary example (rust-lang#116165))
 - rust-lang#116340 (`skip_binder` to `instantiate_identity`)

r? `@ghost`
`@rustbot` modify labels: rollup
rust-timer added a commit to rust-lang-ci/rust that referenced this issue Oct 2, 2023
Rollup merge of rust-lang#116326 - Colonial-Dev:issue-116165-fix, r=joshtriplett

Correct misleading std::fmt::Binary example (rust-lang#116165)

Nothing too crazy...

- Add two to the width specifier (so all 32 bits are correctly displayed)
- Pad out the compared string so the assert passes
- Add `// Note` comment highlighting the need for the extra width when using the `#` flag.

The exact contents (and placement?) of the note are, of course, highly bikesheddable.
@Colonial-Dev
Copy link
Contributor

Hmm, you'd think Bors would have closed this automatically...

@ChrisDenton
Copy link
Member

In the PR description you need to write something like "fixes #116165" so that github will know they're associated. See Linking a pull request to an issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
A-docs Area: documentation for any part of the project, including the compiler, standard library, and tools T-libs Relevant to the library team, which will review and decide on the PR/issue.
Projects
None yet
Development

No branches or pull requests

5 participants