Update wrapping_sh[lr] docs and examples
#149837
Conversation
rustbot
added
S-waiting-on-review
|
rustbot has assigned @workingjubilee. Use |
scottmcm
force-pushed
the
wrapping-shift-docs
branch
from
fb36731 to
812137c
Compare
scottmcm
force-pushed
the
wrapping-shift-docs
branch
from
812137c to
ff43366
Compare
| #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_shl(", stringify!($BITS), "), 42);")] | ||
| #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_shl(1).wrapping_shl(", stringify!($BITS_MINUS_ONE), "), 0);")] | ||
| #[doc = concat!("assert_eq!((-1_", stringify!($SelfT), ").wrapping_shl(128), -1);")] | ||
| #[doc = concat!("assert_eq!(5_", stringify!($SelfT), ".wrapping_shl(1025), 10);")] |
There was a problem hiding this comment.
Might be nice to do some of these examples in binary (0b) or hex (0x), so one can see the bits move better
There was a problem hiding this comment.
Yeah, actually, demonstrating the shift from 0b0101 to 0b1010 sounds nice. Don't have to do it for all of them, ofc.
There was a problem hiding this comment.
Good call; I added a couple more basic examples to show the bits before the extreme examples.
| /// then truncating as needed. The behaviour matches what shift instructions | ||
| /// do on many processors, and is what the `<<` operator does when overflow | ||
| /// checks are disabled, but numerically it's weird. Consider, instead, | ||
| /// using [`Self::unbounded_shl`] which has nicer behaviour. |
There was a problem hiding this comment.
Wait, hm.
Is "nicer" quite right? "More numerical" behavior? "As an integer"? "More logical"? "Is more similar to the mul-by-pow-2 operation you were looking for"?
|
Hmm, I think I've unsold myself on changing "nicer". We aren't that shy from opinion here, and docs contributors can wage that war as they see fit. @bors r+ |
bors
added
S-waiting-on-bors
|
@bors rollup |
|
Sounds good; happy to leave "nicer" there for now :) Yeah, "weird" and "nicer" are admittedly kinda vague. Hopefully the new examples elaborate sufficiently, since I couldn't find a succinct way to say something like "mean that large shifts work like you'd expect from doing a bunch of smaller shifts that add up". (I'll ponder doing a follow-up PR to say more in |
Rollup of 8 pull requests Successful merges: - #146794 (std: reorganize pipe implementations) - #148490 (dangling pointer from temp cleanup) - #149837 (Update `wrapping_sh[lr]` docs and examples) - #149864 (std: Don't use `linkat` on the `wasm32-wasi*` targets) - #149885 (replace addr_of_mut with &raw mut in maybeuninit docs) - #149949 (Cleanup of attribute parsing errors) - #149969 (don't use no_main and no_core to test IBT) - #149998 (miri subtree update) r? `@ghost` `@rustbot` modify labels: rollup
Rollup of 8 pull requests Successful merges: - #146794 (std: reorganize pipe implementations) - #148490 (dangling pointer from temp cleanup) - #149837 (Update `wrapping_sh[lr]` docs and examples) - #149864 (std: Don't use `linkat` on the `wasm32-wasi*` targets) - #149885 (replace addr_of_mut with &raw mut in maybeuninit docs) - #149949 (Cleanup of attribute parsing errors) - #149969 (don't use no_main and no_core to test IBT) - #149998 (miri subtree update) r? `@ghost` `@rustbot` modify labels: rollup
Rollup merge of #149837 - scottmcm:wrapping-shift-docs, r=workingjubilee Update `wrapping_sh[lr]` docs and examples Inspired by [#general > `Source` link for `core` items is often inscrutable @ 💬][zulip-thread] I wanted to add some more examples of the actual wrapping as well as update the documentation to emphasize that the behaviour is unusual. In particular, now that `unbounded_sh[lr]` is stable, point people trying to avoid panics to that instead, since it behaves less weirdly. [zulip-thread]: https://rust-lang.zulipchat.com/#narrow/channel/122651-general/topic/.60Source.60.20link.20for.20.60core.60.20items.20is.20often.20inscrutable/near/562774474
5 participants
Inspired by #general > `Source` link for `core` items is often inscrutable @ 💬 I wanted to add some more examples of the actual wrapping as well as update the documentation to emphasize that the behaviour is unusual.
In particular, now that
unbounded_sh[lr]is stable, point people trying to avoid panics to that instead, since it behaves less weirdly.Rendered example:
