Skip to content

Commit

Permalink
Rollup merge of rust-lang#59979 - stepancheg:num-size, r=ehuss
Browse files Browse the repository at this point in the history 
to_xe_bytes for isize and usize returns an array of different size

... on different platforms.

Official rustdoc of
[`usize::to_le_bytes`](https://doc.rust-lang.org/std/primitive.usize.html#method.to_le_bytes)
displays signature

```
pub fn to_ne_bytes(self) -> [u8; 8]
```

which might be misleading: this function returns 4 bytes on 32-bit
systems.

With this commit applied rustdoc for `isize` and `usize` is this:
<img width="740" alt="2019-04-15_0020" src="https://user-images.githubusercontent.com/28969/56100765-9f69b380-5f14-11e9-974c-daa25edaa881.png">
  • Loading branch information
@Centril
Centril committed May 8, 2019
2 parents d7f4a86 + 764e366 commit 96bf760
Showing 1 changed file with 83 additions and 30 deletions.
113 changes: 83 additions & 30 deletions src/libcore/num/mod.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -214,11 +214,31 @@ pub mod diy_float;

mod wrapping;

macro_rules! usize_isize_to_xe_bytes_doc {
() => {"
**Note**: This function returns an array of length 2, 4 or 8 bytes
depending on the target pointer size.
"}
}


macro_rules! usize_isize_from_xe_bytes_doc {
() => {"
**Note**: This function takes an array of length 2, 4 or 8 bytes
depending on the target pointer size.
"}
}

// `Int` + `SignedInt` implemented for signed integers
macro_rules! int_impl {
($SelfT:ty, $ActualT:ident, $UnsignedT:ty, $BITS:expr, $Min:expr, $Max:expr, $Feature:expr,
$EndFeature:expr, $rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
$reversed:expr, $le_bytes:expr, $be_bytes:expr) => {
$reversed:expr, $le_bytes:expr, $be_bytes:expr,
$to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
doc_comment! {
concat!("Returns the smallest value that can be represented by this integer type.
Expand Down Expand Up @@ -2023,7 +2043,9 @@ $EndFeature, "
doc_comment! {
concat!("Return the memory representation of this integer as a byte array in
big-endian (network) byte order.
",
$to_xe_bytes_doc,
"
# Examples
```
Expand All @@ -2041,7 +2063,9 @@ assert_eq!(bytes, ", $be_bytes, ");
doc_comment! {
concat!("Return the memory representation of this integer as a byte array in
little-endian byte order.
",
$to_xe_bytes_doc,
"
# Examples
```
Expand All @@ -2064,7 +2088,9 @@ native byte order.
As the target platform's native endianness is used, portable code
should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
instead.
",
$to_xe_bytes_doc,
"
[`to_be_bytes`]: #method.to_be_bytes
[`to_le_bytes`]: #method.to_le_bytes
Expand All @@ -2089,7 +2115,9 @@ assert_eq!(bytes, if cfg!(target_endian = \"big\") {
doc_comment! {
concat!("Create an integer value from its representation as a byte array in
big endian.
",
$from_xe_bytes_doc,
"
# Examples
```
Expand Down Expand Up @@ -2120,7 +2148,9 @@ doc_comment! {
concat!("
Create an integer value from its representation as a byte array in
little endian.
",
$from_xe_bytes_doc,
"
# Examples
```
Expand Down Expand Up @@ -2157,7 +2187,9 @@ appropriate instead.
[`from_be_bytes`]: #method.from_be_bytes
[`from_le_bytes`]: #method.from_le_bytes
",
$from_xe_bytes_doc,
"
# Examples
```
Expand Down Expand Up @@ -2193,28 +2225,28 @@ fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT),
#[lang = "i8"]
impl i8 {
int_impl! { i8, i8, u8, 8, -128, 127, "", "", 2, "-0x7e", "0xa", "0x12", "0x12", "0x48",
"[0x12]", "[0x12]" }
"[0x12]", "[0x12]", "", "" }
}

#[lang = "i16"]
impl i16 {
int_impl! { i16, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234", "0x3412",
"0x2c48", "[0x34, 0x12]", "[0x12, 0x34]" }
"0x2c48", "[0x34, 0x12]", "[0x12, 0x34]", "", "" }
}

#[lang = "i32"]
impl i32 {
int_impl! { i32, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
"0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78]" }
"[0x12, 0x34, 0x56, 0x78]", "", "" }
}

#[lang = "i64"]
impl i64 {
int_impl! { i64, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "", 12,
"0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
"0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", "", "" }
}

#[lang = "i128"]
Expand All @@ -2226,22 +2258,24 @@ impl i128 {
"[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]" }
0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", "", "" }
}

#[cfg(target_pointer_width = "16")]
#[lang = "isize"]
impl isize {
int_impl! { isize, i16, u16, 16, -32768, 32767, "", "", 4, "-0x5ffd", "0x3a", "0x1234",
"0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]" }
"0x3412", "0x2c48", "[0x34, 0x12]", "[0x12, 0x34]",
usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}

#[cfg(target_pointer_width = "32")]
#[lang = "isize"]
impl isize {
int_impl! { isize, i32, u32, 32, -2147483648, 2147483647, "", "", 8, "0x10000b3", "0xb301",
"0x12345678", "0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78]" }
"[0x12, 0x34, 0x56, 0x78]",
usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}

#[cfg(target_pointer_width = "64")]
Expand All @@ -2250,14 +2284,16 @@ impl isize {
int_impl! { isize, i64, u64, 64, -9223372036854775808, 9223372036854775807, "", "",
12, "0xaa00000000006e1", "0x6e10aa", "0x1234567890123456", "0x5634129078563412",
"0x6a2c48091e6a2c48", "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}

// `Int` + `UnsignedInt` implemented for unsigned integers
macro_rules! uint_impl {
($SelfT:ty, $ActualT:ty, $BITS:expr, $MaxV:expr, $Feature:expr, $EndFeature:expr,
$rot:expr, $rot_op:expr, $rot_result:expr, $swap_op:expr, $swapped:expr,
$reversed:expr, $le_bytes:expr, $be_bytes:expr) => {
$reversed:expr, $le_bytes:expr, $be_bytes:expr,
$to_xe_bytes_doc:expr, $from_xe_bytes_doc:expr) => {
doc_comment! {
concat!("Returns the smallest value that can be represented by this integer type.
Expand Down Expand Up @@ -3817,7 +3853,9 @@ $EndFeature, "
doc_comment! {
concat!("Return the memory representation of this integer as a byte array in
big-endian (network) byte order.
",
$to_xe_bytes_doc,
"
# Examples
```
Expand All @@ -3835,7 +3873,9 @@ assert_eq!(bytes, ", $be_bytes, ");
doc_comment! {
concat!("Return the memory representation of this integer as a byte array in
little-endian byte order.
",
$to_xe_bytes_doc,
"
# Examples
```
Expand All @@ -3858,7 +3898,9 @@ native byte order.
As the target platform's native endianness is used, portable code
should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate,
instead.
",
$to_xe_bytes_doc,
"
[`to_be_bytes`]: #method.to_be_bytes
[`to_le_bytes`]: #method.to_le_bytes
Expand All @@ -3883,7 +3925,9 @@ assert_eq!(bytes, if cfg!(target_endian = \"big\") {
doc_comment! {
concat!("Create an integer value from its representation as a byte array in
big endian.
",
$from_xe_bytes_doc,
"
# Examples
```
Expand Down Expand Up @@ -3914,7 +3958,9 @@ fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT),
concat!("
Create an integer value from its representation as a byte array in
little endian.
",
$from_xe_bytes_doc,
"
# Examples
```
Expand Down Expand Up @@ -3951,7 +3997,9 @@ appropriate instead.
[`from_be_bytes`]: #method.from_be_bytes
[`from_le_bytes`]: #method.from_le_bytes
",
$from_xe_bytes_doc,
"
# Examples
```
Expand Down Expand Up @@ -3987,7 +4035,7 @@ fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT),
#[lang = "u8"]
impl u8 {
uint_impl! { u8, u8, 8, 255, "", "", 2, "0x82", "0xa", "0x12", "0x12", "0x48", "[0x12]",
"[0x12]" }
"[0x12]", "", "" }


/// Checks if the value is within the ASCII range.
Expand Down Expand Up @@ -4506,21 +4554,22 @@ impl u8 {
#[lang = "u16"]
impl u16 {
uint_impl! { u16, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
"[0x34, 0x12]", "[0x12, 0x34]" }
"[0x34, 0x12]", "[0x12, 0x34]", "", "" }
}

#[lang = "u32"]
impl u32 {
uint_impl! { u32, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
"0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]" }
"0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]", "", "" }
}

#[lang = "u64"]
impl u64 {
uint_impl! { u64, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
"0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
"[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
"", ""}
}

#[lang = "u128"]
Expand All @@ -4531,20 +4580,23 @@ impl u128 {
"[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \
0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \
0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]" }
0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]",
"", ""}
}

#[cfg(target_pointer_width = "16")]
#[lang = "usize"]
impl usize {
uint_impl! { usize, u16, 16, 65535, "", "", 4, "0xa003", "0x3a", "0x1234", "0x3412", "0x2c48",
"[0x34, 0x12]", "[0x12, 0x34]" }
"[0x34, 0x12]", "[0x12, 0x34]",
usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}
#[cfg(target_pointer_width = "32")]
#[lang = "usize"]
impl usize {
uint_impl! { usize, u32, 32, 4294967295, "", "", 8, "0x10000b3", "0xb301", "0x12345678",
"0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]" }
"0x78563412", "0x1e6a2c48", "[0x78, 0x56, 0x34, 0x12]", "[0x12, 0x34, 0x56, 0x78]",
usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}

#[cfg(target_pointer_width = "64")]
Expand All @@ -4553,7 +4605,8 @@ impl usize {
uint_impl! { usize, u64, 64, 18446744073709551615, "", "", 12, "0xaa00000000006e1", "0x6e10aa",
"0x1234567890123456", "0x5634129078563412", "0x6a2c48091e6a2c48",
"[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]",
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]" }
"[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]",
usize_isize_to_xe_bytes_doc!(), usize_isize_from_xe_bytes_doc!() }
}

/// A classification of floating point numbers.
Expand Down

0 comments on commit 96bf760

Please sign in to comment.