From 1a043533f504145fa51beeb6c94765e6865031ee Mon Sep 17 00:00:00 2001 From: Clar Charr Date: Fri, 22 Dec 2017 21:43:09 -0500 Subject: [PATCH 01/10] Document std::os::raw. --- src/libstd/lib.rs | 1 + src/libstd/os/raw/char.md | 11 +++++++++ src/libstd/os/raw/double.md | 6 +++++ src/libstd/os/raw/float.md | 5 ++++ src/libstd/os/raw/int.md | 6 +++++ src/libstd/os/raw/long.md | 8 +++++++ src/libstd/os/raw/longlong.md | 6 +++++ src/libstd/os/{raw.rs => raw/mod.rs} | 34 ++++++++++++++++++++++++---- src/libstd/os/raw/schar.md | 6 +++++ src/libstd/os/raw/short.md | 6 +++++ src/libstd/os/raw/uchar.md | 6 +++++ src/libstd/os/raw/uint.md | 6 +++++ src/libstd/os/raw/ulong.md | 8 +++++++ src/libstd/os/raw/ulonglong.md | 6 +++++ src/libstd/os/raw/ushort.md | 6 +++++ 15 files changed, 116 insertions(+), 5 deletions(-) create mode 100644 src/libstd/os/raw/char.md create mode 100644 src/libstd/os/raw/double.md create mode 100644 src/libstd/os/raw/float.md create mode 100644 src/libstd/os/raw/int.md create mode 100644 src/libstd/os/raw/long.md create mode 100644 src/libstd/os/raw/longlong.md rename src/libstd/os/{raw.rs => raw/mod.rs} (78%) create mode 100644 src/libstd/os/raw/schar.md create mode 100644 src/libstd/os/raw/short.md create mode 100644 src/libstd/os/raw/uchar.md create mode 100644 src/libstd/os/raw/uint.md create mode 100644 src/libstd/os/raw/ulong.md create mode 100644 src/libstd/os/raw/ulonglong.md create mode 100644 src/libstd/os/raw/ushort.md diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index a8049e676b3b..642fa8775a47 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -260,6 +260,7 @@ #![feature(core_intrinsics)] #![feature(dropck_eyepatch)] #![feature(exact_size_is_empty)] +#![feature(external_doc)] #![feature(fs_read_write)] #![feature(fixed_size_array)] #![feature(float_from_str_radix)] diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md new file mode 100644 index 000000000000..fb47dff187e5 --- /dev/null +++ b/src/libstd/os/raw/char.md @@ -0,0 +1,11 @@ +Equivalent to C's `char` type. + +[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. In practice, this type will always be either [`i8`] or [`u8`], but you're technically not supposed to rely on this behaviour, as the standard only defines a char as being at least eight bits long. + +C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with a zero. See [`CStr`] for more information. + +[C's `char` type]: https://en.wikipedia.org/wiki/C_data_types#Basic_types +[Rust's `char` type]: ../../primitive.char.html +[`CStr`]: ../../ffi/struct.CStr.html +[`i8`]: ../../primitive.i8.html +[`u8`]: ../../primitive.u8.html diff --git a/src/libstd/os/raw/double.md b/src/libstd/os/raw/double.md new file mode 100644 index 000000000000..5ac09ee284c1 --- /dev/null +++ b/src/libstd/os/raw/double.md @@ -0,0 +1,6 @@ +Equivalent to C's `double` type. + +This type will almost always be [`f64`], however, the standard technically only guarantees that it be a floating-point number with at least the precision of a [`float`]. + +[`float`]: type.c_float.html +[`f64`]: ../../primitive.f64.html diff --git a/src/libstd/os/raw/float.md b/src/libstd/os/raw/float.md new file mode 100644 index 000000000000..20ba8645055b --- /dev/null +++ b/src/libstd/os/raw/float.md @@ -0,0 +1,5 @@ +Equivalent to C's `float` type. + +This type will almost always be [`f32`], however, the standard technically only guarantees that it be a floating-point number. + +[`f32`]: ../../primitive.f32.html diff --git a/src/libstd/os/raw/int.md b/src/libstd/os/raw/int.md new file mode 100644 index 000000000000..efe7786099ab --- /dev/null +++ b/src/libstd/os/raw/int.md @@ -0,0 +1,6 @@ +Equivalent to C's `signed int` (`int`) type. + +This type will almost always be [`i32`], however, the standard technically only requires that it be at least the size of a [`short`]. + +[`short`]: type.c_short.html +[`i32`]: ../../primitive.i32.html diff --git a/src/libstd/os/raw/long.md b/src/libstd/os/raw/long.md new file mode 100644 index 000000000000..c281e0173367 --- /dev/null +++ b/src/libstd/os/raw/long.md @@ -0,0 +1,8 @@ +Equivalent to C's `signed long` (`long`) type. + +This type will usually be [`i64`], but is sometimes [`i32`] \(i.e. [`isize`]\) on 32-bit systems. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`]. + +[`int`]: type.c_int.html +[`i32`]: ../../primitive.i32.html +[`i64`]: ../../primitive.i64.html +[`isize`]: ../../primitive.isize.html diff --git a/src/libstd/os/raw/longlong.md b/src/libstd/os/raw/longlong.md new file mode 100644 index 000000000000..6594fcd564c5 --- /dev/null +++ b/src/libstd/os/raw/longlong.md @@ -0,0 +1,6 @@ +Equivalent to C's `signed long long` (`long long`) type. + +This type will almost always be [`i64`], however, the standard technically only requires that it be at least 64 bits, or at least the size of an [`long`]. + +[`long`]: type.c_int.html +[`i64`]: ../../primitive.i64.html diff --git a/src/libstd/os/raw.rs b/src/libstd/os/raw/mod.rs similarity index 78% rename from src/libstd/os/raw.rs rename to src/libstd/os/raw/mod.rs index 279caf8053a8..e96ba045ce70 100644 --- a/src/libstd/os/raw.rs +++ b/src/libstd/os/raw/mod.rs @@ -8,12 +8,19 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Raw OS-specific types for the current platform/architecture +//! Platform-specific types, as defined by C. +//! +//! Code that interacts via FFI will almost certainly be using the +//! base types provided by C, which aren't nearly as nicely defined +//! as Rust's primitive types. This module provides types which will +//! match those defined by C, so that code that interacts with C will +//! refer to the correct types. #![stable(feature = "raw_os", since = "1.1.0")] use fmt; +#[doc(include = "os/raw/char.md")] #[cfg(any(all(target_os = "linux", any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc", @@ -25,6 +32,7 @@ use fmt; all(target_os = "openbsd", target_arch = "aarch64"), all(target_os = "fuchsia", target_arch = "aarch64")))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = u8; +#[doc(include = "os/raw/char.md")] #[cfg(not(any(all(target_os = "linux", any(target_arch = "aarch64", target_arch = "arm", target_arch = "powerpc", @@ -36,30 +44,46 @@ use fmt; all(target_os = "openbsd", target_arch = "aarch64"), all(target_os = "fuchsia", target_arch = "aarch64"))))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_char = i8; +#[doc(include = "os/raw/schar.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_schar = i8; +#[doc(include = "os/raw/uchar.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_uchar = u8; +#[doc(include = "os/raw/short.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_short = i16; +#[doc(include = "os/raw/ushort.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ushort = u16; +#[doc(include = "os/raw/int.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_int = i32; +#[doc(include = "os/raw/uint.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_uint = u32; +#[doc(include = "os/raw/long.md")] #[cfg(any(target_pointer_width = "32", windows))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i32; +#[doc(include = "os/raw/ulong.md")] #[cfg(any(target_pointer_width = "32", windows))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u32; +#[doc(include = "os/raw/long.md")] #[cfg(all(target_pointer_width = "64", not(windows)))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i64; +#[doc(include = "os/raw/ulong.md")] #[cfg(all(target_pointer_width = "64", not(windows)))] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u64; +#[doc(include = "os/raw/longlong.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_longlong = i64; +#[doc(include = "os/raw/ulonglong.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulonglong = u64; +#[doc(include = "os/raw/float.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_float = f32; +#[doc(include = "os/raw/double.md")] #[stable(feature = "raw_os", since = "1.1.0")] pub type c_double = f64; -/// Type used to construct void pointers for use with C. +/// Equivalent to C's `void` type when used as a [pointer]. /// -/// This type is only useful as a pointer target. Do not use it as a -/// return type for FFI functions which have the `void` return type in -/// C. Use the unit type `()` or omit the return type instead. +/// In essence, `*const c_void` is equivalent to C's `const void*` +/// and `*mut c_void` is equivalent to C's `void*`. That said, this is +/// *not* the same as C's `void` return type, which is Rust's `()` type. +/// +/// [pointer]: ../primitive.pointer.html // NB: For LLVM to recognize the void pointer type and by extension // functions like malloc(), we need to have it represented as i8* in // LLVM bitcode. The enum used here ensures this and prevents misuse diff --git a/src/libstd/os/raw/schar.md b/src/libstd/os/raw/schar.md new file mode 100644 index 000000000000..42a403ef5d78 --- /dev/null +++ b/src/libstd/os/raw/schar.md @@ -0,0 +1,6 @@ +Equivalent to C's `signed char` type. + +This type will almost always be [`i8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut. + +[`char`]: type.c_char.html +[`i8`]: ../../primitive.i8.html diff --git a/src/libstd/os/raw/short.md b/src/libstd/os/raw/short.md new file mode 100644 index 000000000000..86a8495eae23 --- /dev/null +++ b/src/libstd/os/raw/short.md @@ -0,0 +1,6 @@ +Equivalent to C's `signed short` (`short`) type. + +This type will almost always be [`i16`], however, the standard technically only requires that it be at least 16 bits, or at least the size of a C [`char`]. + +[`char`]: type.c_char.html +[`i16`]: ../../primitive.i16.html diff --git a/src/libstd/os/raw/uchar.md b/src/libstd/os/raw/uchar.md new file mode 100644 index 000000000000..a5b741702290 --- /dev/null +++ b/src/libstd/os/raw/uchar.md @@ -0,0 +1,6 @@ +Equivalent to C's `unsigned char` type. + +This type will almost always be [`u8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut. + +[`char`]: type.c_char.html +[`u8`]: ../../primitive.u8.html diff --git a/src/libstd/os/raw/uint.md b/src/libstd/os/raw/uint.md new file mode 100644 index 000000000000..ec4714a9ab44 --- /dev/null +++ b/src/libstd/os/raw/uint.md @@ -0,0 +1,6 @@ +Equivalent to C's `unsigned int` type. + +This type will almost always be [`u32`], however, the standard technically on requires that it be the same size as an [`int`], which isn't very clear-cut. + +[`int`]: type.c_int.html +[`u32`]: ../../primitive.u32.html diff --git a/src/libstd/os/raw/ulong.md b/src/libstd/os/raw/ulong.md new file mode 100644 index 000000000000..3cdbc6f59bfc --- /dev/null +++ b/src/libstd/os/raw/ulong.md @@ -0,0 +1,8 @@ +Equivalent to C's `unsigned long` type. + +This type will usually be [`u64`], but is sometimes [`u32`] \(i.e. [`usize`]\) on 32-bit systems. Technically, the standard only requires that it be the same size as a [`long`], which isn't very clear-cut. + +[`long`]: type.c_long.html +[`u32`]: ../../primitive.u32.html +[`u64`]: ../../primitive.u64.html +[`usize`]: ../../primitive.usize.html diff --git a/src/libstd/os/raw/ulonglong.md b/src/libstd/os/raw/ulonglong.md new file mode 100644 index 000000000000..9f5ff74f261c --- /dev/null +++ b/src/libstd/os/raw/ulonglong.md @@ -0,0 +1,6 @@ +Equivalent to C's `unsigned long long` type. + +This type will almost always be [`u64`], however, the standard technically only requires that it be the same size as a [`long long`], which isn't very clear-cut. + +[`long long`]: type.c_longlong.html +[`u64`]: ../../primitive.u64.html diff --git a/src/libstd/os/raw/ushort.md b/src/libstd/os/raw/ushort.md new file mode 100644 index 000000000000..6dea582fda25 --- /dev/null +++ b/src/libstd/os/raw/ushort.md @@ -0,0 +1,6 @@ +Equivalent to C's `unsigned short` type. + +This type will almost always be [`u16`], however, the standard technically only requires that it be the same size as a [`short`], which isn't very clear-cut. + +[`short`]: type.c_short.html +[`u16`]: ../../primitive.u16.html From 853fa5873c91ad1d01e69e7cbdb758001a31e9c1 Mon Sep 17 00:00:00 2001 From: Clar Charr Date: Sat, 23 Dec 2017 17:29:51 -0500 Subject: [PATCH 02/10] Revisions suggested in comments --- src/libstd/os/raw/char.md | 2 +- src/libstd/os/raw/long.md | 3 +-- src/libstd/os/raw/mod.rs | 2 +- src/libstd/os/raw/ulong.md | 3 +-- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md index fb47dff187e5..6816e519d1a4 100644 --- a/src/libstd/os/raw/char.md +++ b/src/libstd/os/raw/char.md @@ -2,7 +2,7 @@ Equivalent to C's `char` type. [C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. In practice, this type will always be either [`i8`] or [`u8`], but you're technically not supposed to rely on this behaviour, as the standard only defines a char as being at least eight bits long. -C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with a zero. See [`CStr`] for more information. +C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with the character `'\0'`. See [`CStr`] for more information. [C's `char` type]: https://en.wikipedia.org/wiki/C_data_types#Basic_types [Rust's `char` type]: ../../primitive.char.html diff --git a/src/libstd/os/raw/long.md b/src/libstd/os/raw/long.md index c281e0173367..5a2e2331c0a5 100644 --- a/src/libstd/os/raw/long.md +++ b/src/libstd/os/raw/long.md @@ -1,8 +1,7 @@ Equivalent to C's `signed long` (`long`) type. -This type will usually be [`i64`], but is sometimes [`i32`] \(i.e. [`isize`]\) on 32-bit systems. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`]. +This type will usually be [`i64`], but is sometimes [`i32`]. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`]. [`int`]: type.c_int.html [`i32`]: ../../primitive.i32.html [`i64`]: ../../primitive.i64.html -[`isize`]: ../../primitive.isize.html diff --git a/src/libstd/os/raw/mod.rs b/src/libstd/os/raw/mod.rs index e96ba045ce70..710976ed8e0a 100644 --- a/src/libstd/os/raw/mod.rs +++ b/src/libstd/os/raw/mod.rs @@ -83,7 +83,7 @@ use fmt; /// and `*mut c_void` is equivalent to C's `void*`. That said, this is /// *not* the same as C's `void` return type, which is Rust's `()` type. /// -/// [pointer]: ../primitive.pointer.html +/// [pointer]: ../../primitive.pointer.html // NB: For LLVM to recognize the void pointer type and by extension // functions like malloc(), we need to have it represented as i8* in // LLVM bitcode. The enum used here ensures this and prevents misuse diff --git a/src/libstd/os/raw/ulong.md b/src/libstd/os/raw/ulong.md index 3cdbc6f59bfc..919de171a39a 100644 --- a/src/libstd/os/raw/ulong.md +++ b/src/libstd/os/raw/ulong.md @@ -1,8 +1,7 @@ Equivalent to C's `unsigned long` type. -This type will usually be [`u64`], but is sometimes [`u32`] \(i.e. [`usize`]\) on 32-bit systems. Technically, the standard only requires that it be the same size as a [`long`], which isn't very clear-cut. +This type will usually be [`u64`], but is sometimes [`u32`]. Technically, the standard only requires that it be the same size as a [`long`], which isn't very clear-cut. [`long`]: type.c_long.html [`u32`]: ../../primitive.u32.html [`u64`]: ../../primitive.u64.html -[`usize`]: ../../primitive.usize.html From 2cab06855a9b325c527ab08be4660c4353816833 Mon Sep 17 00:00:00 2001 From: Clar Charr Date: Mon, 29 Jan 2018 18:13:18 -0500 Subject: [PATCH 03/10] Reworded to avoid fuzziness, mention ! in c_void docs. --- src/libstd/os/raw/char.md | 2 +- src/libstd/os/raw/double.md | 3 ++- src/libstd/os/raw/float.md | 3 ++- src/libstd/os/raw/int.md | 3 ++- src/libstd/os/raw/long.md | 2 +- src/libstd/os/raw/longlong.md | 3 ++- src/libstd/os/raw/mod.rs | 4 ++++ src/libstd/os/raw/schar.md | 2 +- src/libstd/os/raw/short.md | 2 +- src/libstd/os/raw/uchar.md | 2 +- src/libstd/os/raw/uint.md | 3 ++- src/libstd/os/raw/ulong.md | 2 +- src/libstd/os/raw/ulonglong.md | 3 ++- src/libstd/os/raw/ushort.md | 2 +- 14 files changed, 23 insertions(+), 13 deletions(-) diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md index 6816e519d1a4..9a55767d965a 100644 --- a/src/libstd/os/raw/char.md +++ b/src/libstd/os/raw/char.md @@ -1,6 +1,6 @@ Equivalent to C's `char` type. -[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. In practice, this type will always be either [`i8`] or [`u8`], but you're technically not supposed to rely on this behaviour, as the standard only defines a char as being at least eight bits long. +[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. This type will always be either [`i8`] or [`u8`], as the type is defined as being one byte long. C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with the character `'\0'`. See [`CStr`] for more information. diff --git a/src/libstd/os/raw/double.md b/src/libstd/os/raw/double.md index 5ac09ee284c1..6818dada3179 100644 --- a/src/libstd/os/raw/double.md +++ b/src/libstd/os/raw/double.md @@ -1,6 +1,7 @@ Equivalent to C's `double` type. -This type will almost always be [`f64`], however, the standard technically only guarantees that it be a floating-point number with at least the precision of a [`float`]. +This type will almost always be [`f64`], which is guaranteed to be an [IEEE-754 double-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number with at least the precision of a [`float`], and it may be `f32` or something entirely different from the IEEE-754 standard. +[IEEE-754 double-precision float]: https://en.wikipedia.org/wiki/IEEE_754 [`float`]: type.c_float.html [`f64`]: ../../primitive.f64.html diff --git a/src/libstd/os/raw/float.md b/src/libstd/os/raw/float.md index 20ba8645055b..57d1071d0da1 100644 --- a/src/libstd/os/raw/float.md +++ b/src/libstd/os/raw/float.md @@ -1,5 +1,6 @@ Equivalent to C's `float` type. -This type will almost always be [`f32`], however, the standard technically only guarantees that it be a floating-point number. +This type will almost always be [`f32`], which is guaranteed to be an [IEEE-754 single-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number, and it may have less precision than `f32` or not follow the IEEE-754 standard at all. +[IEEE-754 single-precision float]: https://en.wikipedia.org/wiki/IEEE_754 [`f32`]: ../../primitive.f32.html diff --git a/src/libstd/os/raw/int.md b/src/libstd/os/raw/int.md index efe7786099ab..a0d25fd21d89 100644 --- a/src/libstd/os/raw/int.md +++ b/src/libstd/os/raw/int.md @@ -1,6 +1,7 @@ Equivalent to C's `signed int` (`int`) type. -This type will almost always be [`i32`], however, the standard technically only requires that it be at least the size of a [`short`]. +This type will almost always be [`i32`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer that is at least the size of a [`short`]; some systems define it as an [`i16`], for example. [`short`]: type.c_short.html [`i32`]: ../../primitive.i32.html +[`i16`]: ../../primitive.i16.html diff --git a/src/libstd/os/raw/long.md b/src/libstd/os/raw/long.md index 5a2e2331c0a5..c620b402819f 100644 --- a/src/libstd/os/raw/long.md +++ b/src/libstd/os/raw/long.md @@ -1,6 +1,6 @@ Equivalent to C's `signed long` (`long`) type. -This type will usually be [`i64`], but is sometimes [`i32`]. Technically, the standard only requires that it be at least 32 bits, or at least the size of an [`int`]. +This type will always be [`i32`] or [`i64`]. Most notably, many Linux-based systems assume an `i64`, but Windows assumes `i32`. The C standard technically only requires that this type be a signed integer that is at least 32 bits and at least the size of an [`int`], although in practice, no system would have a `long` that is neither an `i32` nor `i64`. [`int`]: type.c_int.html [`i32`]: ../../primitive.i32.html diff --git a/src/libstd/os/raw/longlong.md b/src/libstd/os/raw/longlong.md index 6594fcd564c5..ab3d6436568d 100644 --- a/src/libstd/os/raw/longlong.md +++ b/src/libstd/os/raw/longlong.md @@ -1,6 +1,7 @@ Equivalent to C's `signed long long` (`long long`) type. -This type will almost always be [`i64`], however, the standard technically only requires that it be at least 64 bits, or at least the size of an [`long`]. +This type will almost always be [`i64`], but may differ on some systems. The C standard technically only requires that this type be a signed integer that is at least 64 bits and at least the size of a [`long`], although in practice, no system would have a `long long` that is not an `i64`, as most systems do not have a standardised [`i128`] type. [`long`]: type.c_int.html [`i64`]: ../../primitive.i64.html +[`i128`]: ../../primitive.i128.html diff --git a/src/libstd/os/raw/mod.rs b/src/libstd/os/raw/mod.rs index 710976ed8e0a..d5eeb5252f0f 100644 --- a/src/libstd/os/raw/mod.rs +++ b/src/libstd/os/raw/mod.rs @@ -83,6 +83,10 @@ use fmt; /// and `*mut c_void` is equivalent to C's `void*`. That said, this is /// *not* the same as C's `void` return type, which is Rust's `()` type. /// +/// Ideally, this type would be equivalent to [`!`], but currently it may +/// be more ideal to use `c_void` for FFI purposes. +/// +/// [`!`]: ../../primitive.never.html /// [pointer]: ../../primitive.pointer.html // NB: For LLVM to recognize the void pointer type and by extension // functions like malloc(), we need to have it represented as i8* in diff --git a/src/libstd/os/raw/schar.md b/src/libstd/os/raw/schar.md index 42a403ef5d78..6aa8b1211d80 100644 --- a/src/libstd/os/raw/schar.md +++ b/src/libstd/os/raw/schar.md @@ -1,6 +1,6 @@ Equivalent to C's `signed char` type. -This type will almost always be [`i8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut. +This type will always be [`i8`], but is included for completeness. It is defined as being a signed integer the same size as a C [`char`]. [`char`]: type.c_char.html [`i8`]: ../../primitive.i8.html diff --git a/src/libstd/os/raw/short.md b/src/libstd/os/raw/short.md index 86a8495eae23..be92c6c106d5 100644 --- a/src/libstd/os/raw/short.md +++ b/src/libstd/os/raw/short.md @@ -1,6 +1,6 @@ Equivalent to C's `signed short` (`short`) type. -This type will almost always be [`i16`], however, the standard technically only requires that it be at least 16 bits, or at least the size of a C [`char`]. +This type will almost always be [`i16`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer with at least 16 bits; some systems may define it as `i32`, for example. [`char`]: type.c_char.html [`i16`]: ../../primitive.i16.html diff --git a/src/libstd/os/raw/uchar.md b/src/libstd/os/raw/uchar.md index a5b741702290..b6ca711f8693 100644 --- a/src/libstd/os/raw/uchar.md +++ b/src/libstd/os/raw/uchar.md @@ -1,6 +1,6 @@ Equivalent to C's `unsigned char` type. -This type will almost always be [`u8`], but its size is technically equal to the size of a C [`char`], which isn't very clear-cut. +This type will always be [`u8`], but is included for completeness. It is defined as being an unsigned integer the same size as a C [`char`]. [`char`]: type.c_char.html [`u8`]: ../../primitive.u8.html diff --git a/src/libstd/os/raw/uint.md b/src/libstd/os/raw/uint.md index ec4714a9ab44..1e710f804c44 100644 --- a/src/libstd/os/raw/uint.md +++ b/src/libstd/os/raw/uint.md @@ -1,6 +1,7 @@ Equivalent to C's `unsigned int` type. -This type will almost always be [`u32`], however, the standard technically on requires that it be the same size as an [`int`], which isn't very clear-cut. +This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example. [`int`]: type.c_int.html [`u32`]: ../../primitive.u32.html +[`u16`]: ../../primitive.u16.html diff --git a/src/libstd/os/raw/ulong.md b/src/libstd/os/raw/ulong.md index 919de171a39a..c350395080e8 100644 --- a/src/libstd/os/raw/ulong.md +++ b/src/libstd/os/raw/ulong.md @@ -1,6 +1,6 @@ Equivalent to C's `unsigned long` type. -This type will usually be [`u64`], but is sometimes [`u32`]. Technically, the standard only requires that it be the same size as a [`long`], which isn't very clear-cut. +This type will always be [`u32`] or [`u64`]. Most notably, many Linux-based systems assume an `u64`, but Windows assumes `u32`. The C standard technically only requires that this type be an unsigned integer with the size of a [`long`], although in practice, no system would have a `ulong` that is neither a `u32` nor `u64`. [`long`]: type.c_long.html [`u32`]: ../../primitive.u32.html diff --git a/src/libstd/os/raw/ulonglong.md b/src/libstd/os/raw/ulonglong.md index 9f5ff74f261c..c41faf74c5c6 100644 --- a/src/libstd/os/raw/ulonglong.md +++ b/src/libstd/os/raw/ulonglong.md @@ -1,6 +1,7 @@ Equivalent to C's `unsigned long long` type. -This type will almost always be [`u64`], however, the standard technically only requires that it be the same size as a [`long long`], which isn't very clear-cut. +This type will almost always be [`u64`], but may differ on some systems. The C standard technically only requires that this type be an unsigned integer with the size of a [`long long`], although in practice, no system would have a `long long` that is not a `u64`, as most systems do not have a standardised [`u128`] type. [`long long`]: type.c_longlong.html [`u64`]: ../../primitive.u64.html +[`u128`]: ../../primitive.u128.html diff --git a/src/libstd/os/raw/ushort.md b/src/libstd/os/raw/ushort.md index 6dea582fda25..d364abb3c8e0 100644 --- a/src/libstd/os/raw/ushort.md +++ b/src/libstd/os/raw/ushort.md @@ -1,6 +1,6 @@ Equivalent to C's `unsigned short` type. -This type will almost always be [`u16`], however, the standard technically only requires that it be the same size as a [`short`], which isn't very clear-cut. +This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as a [`short`]. [`short`]: type.c_short.html [`u16`]: ../../primitive.u16.html From 61ff3ba5364ae7bbf93be5b892fa7c122d3cfab2 Mon Sep 17 00:00:00 2001 From: Gilad Naaman Date: Sat, 27 Jan 2018 22:34:05 +0200 Subject: [PATCH 04/10] libtest: Replace panics with error messages --- src/libtest/lib.rs | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/src/libtest/lib.rs b/src/libtest/lib.rs index ffa27688cf1a..9ea5f39b71fe 100644 --- a/src/libtest/lib.rs +++ b/src/libtest/lib.rs @@ -72,6 +72,7 @@ use std::sync::{Arc, Mutex}; use std::thread; use std::time::{Instant, Duration}; use std::borrow::Cow; +use std::process; const TEST_WARN_TIMEOUT_S: u64 = 60; const QUIET_MODE_MAX_COLUMN: usize = 100; // insert a '\n' after 100 tests in quiet mode @@ -266,19 +267,27 @@ impl Options { pub fn test_main(args: &[String], tests: Vec, options: Options) { let mut opts = match parse_opts(args) { Some(Ok(o)) => o, - Some(Err(msg)) => panic!("{:?}", msg), + Some(Err(msg)) => { + eprintln!("error: {}", msg); + process::exit(101); + }, None => return, }; + opts.options = options; if opts.list { if let Err(e) = list_tests_console(&opts, tests) { - panic!("io error when listing tests: {:?}", e); + eprintln!("error: io error when listing tests: {:?}", e); + process::exit(101); } } else { match run_tests_console(&opts, tests) { Ok(true) => {} - Ok(false) => std::process::exit(101), - Err(e) => panic!("io error when running tests: {:?}", e), + Ok(false) => process::exit(101), + Err(e) => { + eprintln!("error: io error when listing tests: {:?}", e); + process::exit(101); + }, } } } From 1b1e887f4d40e5800a8d5ae81f8574806e7ba21a Mon Sep 17 00:00:00 2001 From: Scott McMurray Date: Sun, 4 Feb 2018 23:48:40 -0800 Subject: [PATCH 05/10] Override try_[r]fold for RangeInclusive Because the last item needs special handling, it seems that LLVM has trouble canonicalizing the loops in external iteration. With the override, it becomes obvious that the start==end case exits the loop (as opposed to the one *after* that exiting the loop in external iteration). --- src/libcore/iter/range.rs | 46 ++++++++++++++++++++++++++++++++++++++- src/libcore/tests/iter.rs | 20 +++++++++++++++++ 2 files changed, 65 insertions(+), 1 deletion(-) diff --git a/src/libcore/iter/range.rs b/src/libcore/iter/range.rs index 66a76a24df45..3b034efcce14 100644 --- a/src/libcore/iter/range.rs +++ b/src/libcore/iter/range.rs @@ -10,7 +10,7 @@ use convert::TryFrom; use mem; -use ops::{self, Add, Sub}; +use ops::{self, Add, Sub, Try}; use usize; use super::{FusedIterator, TrustedLen}; @@ -397,6 +397,28 @@ impl Iterator for ops::RangeInclusive { fn max(mut self) -> Option { self.next_back() } + + #[inline] + fn try_fold(&mut self, init: B, mut f: F) -> R where + Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try + { + let mut accum = init; + if self.start <= self.end { + loop { + let (x, done) = + if self.start < self.end { + let n = self.start.add_one(); + (mem::replace(&mut self.start, n), false) + } else { + self.end.replace_zero(); + (self.start.replace_one(), true) + }; + accum = f(accum, x)?; + if done { break } + } + } + Try::from_ok(accum) + } } #[unstable(feature = "inclusive_range", reason = "recently added, follows RFC", issue = "28237")] @@ -418,6 +440,28 @@ impl DoubleEndedIterator for ops::RangeInclusive { _ => None, } } + + #[inline] + fn try_rfold(&mut self, init: B, mut f: F) -> R where + Self: Sized, F: FnMut(B, Self::Item) -> R, R: Try + { + let mut accum = init; + if self.start <= self.end { + loop { + let (x, done) = + if self.start < self.end { + let n = self.end.sub_one(); + (mem::replace(&mut self.end, n), false) + } else { + self.start.replace_one(); + (self.end.replace_zero(), true) + }; + accum = f(accum, x)?; + if done { break } + } + } + Try::from_ok(accum) + } } #[unstable(feature = "fused", issue = "35602")] diff --git a/src/libcore/tests/iter.rs b/src/libcore/tests/iter.rs index 8997cf9c6bff..e33a0b6224e5 100644 --- a/src/libcore/tests/iter.rs +++ b/src/libcore/tests/iter.rs @@ -1397,6 +1397,26 @@ fn test_range_inclusive_min() { assert_eq!(r.min(), None); } +#[test] +fn test_range_inclusive_folds() { + assert_eq!((1..=10).sum::(), 55); + assert_eq!((1..=10).rev().sum::(), 55); + + let mut it = 40..=50; + assert_eq!(it.try_fold(0, i8::checked_add), None); + assert_eq!(it, 44..=50); + assert_eq!(it.try_rfold(0, i8::checked_add), None); + assert_eq!(it, 44..=47); + + let mut it = 10..=20; + assert_eq!(it.try_fold(0, |a,b| Some(a+b)), Some(165)); + assert_eq!(it, 1..=0); + + let mut it = 10..=20; + assert_eq!(it.try_rfold(0, |a,b| Some(a+b)), Some(165)); + assert_eq!(it, 1..=0); +} + #[test] fn test_repeat() { let mut it = repeat(42); From 1461d12b3c9778a51c443b804f2db5e235554151 Mon Sep 17 00:00:00 2001 From: Onur Aslan Date: Mon, 5 Feb 2018 11:39:54 +0300 Subject: [PATCH 06/10] Use time crate in bootstrap dist instead of date --- src/Cargo.lock | 1 + src/bootstrap/Cargo.toml | 1 + src/bootstrap/dist.rs | 6 +++--- src/bootstrap/lib.rs | 1 + 4 files changed, 6 insertions(+), 3 deletions(-) diff --git a/src/Cargo.lock b/src/Cargo.lock index fc89cc4ea9ee..aa6d1eb32495 100644 --- a/src/Cargo.lock +++ b/src/Cargo.lock @@ -133,6 +133,7 @@ dependencies = [ "serde 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", "serde_derive 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", "serde_json 1.0.9 (registry+https://github.com/rust-lang/crates.io-index)", + "time 0.1.39 (registry+https://github.com/rust-lang/crates.io-index)", "toml 0.4.5 (registry+https://github.com/rust-lang/crates.io-index)", ] diff --git a/src/bootstrap/Cargo.toml b/src/bootstrap/Cargo.toml index bbbbf0e19155..2d4783413178 100644 --- a/src/bootstrap/Cargo.toml +++ b/src/bootstrap/Cargo.toml @@ -41,3 +41,4 @@ serde_derive = "1.0.8" serde_json = "1.0.2" toml = "0.4" lazy_static = "0.2" +time = "0.1" diff --git a/src/bootstrap/dist.rs b/src/bootstrap/dist.rs index dbb7d19e4328..6717b1cb0988 100644 --- a/src/bootstrap/dist.rs +++ b/src/bootstrap/dist.rs @@ -33,6 +33,7 @@ use builder::{Builder, RunConfig, ShouldRun, Step}; use compile; use tool::{self, Tool}; use cache::{INTERNER, Interned}; +use time; pub fn pkgname(build: &Build, component: &str) -> String { if component == "cargo" { @@ -445,8 +446,7 @@ impl Step for Rustc { t!(fs::create_dir_all(image.join("share/man/man1"))); let man_src = build.src.join("src/doc/man"); let man_dst = image.join("share/man/man1"); - let date_output = output(Command::new("date").arg("+%B %Y")); - let month_year = date_output.trim(); + let month_year = t!(time::strftime("%B %Y", &time::now())); // don't use our `bootstrap::util::{copy, cp_r}`, because those try // to hardlink, and we don't want to edit the source templates for entry_result in t!(fs::read_dir(man_src)) { @@ -456,7 +456,7 @@ impl Step for Rustc { t!(fs::copy(&page_src, &page_dst)); // template in month/year and version number replace_in_file(&page_dst, - &[("", month_year), + &[("", &month_year), ("", channel::CFG_RELEASE_NUM)]); } diff --git a/src/bootstrap/lib.rs b/src/bootstrap/lib.rs index f2a7ce30c8ac..a84a6a8990bb 100644 --- a/src/bootstrap/lib.rs +++ b/src/bootstrap/lib.rs @@ -130,6 +130,7 @@ extern crate cc; extern crate getopts; extern crate num_cpus; extern crate toml; +extern crate time; #[cfg(unix)] extern crate libc; From 8d8ba812d01d1284c8bdaa728df4deae865fd1d6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matthias=20Kr=C3=BCger?= Date: Tue, 6 Feb 2018 12:59:06 +0100 Subject: [PATCH 07/10] config.toml.example: fix typos. Most of them were found by codespell: https://github.com/lucasdemarchi/codespell --- config.toml.example | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/config.toml.example b/config.toml.example index 75cab74258b6..c2ec731eeb8a 100644 --- a/config.toml.example +++ b/config.toml.example @@ -295,7 +295,7 @@ # Flag indicating whether git info will be retrieved from .git automatically. # Having the git information can cause a lot of rebuilds during development. -# Note: If this attribute is not explicity set (e.g. if left commented out) it +# Note: If this attribute is not explicitly set (e.g. if left commented out) it # will default to true if channel = "dev", but will default to false otherwise. #ignore-git = true @@ -317,8 +317,8 @@ # bootstrap) #codegen-backends = ["llvm"] -# Flag indicating whether `libstd` calls an imported function to hande basic IO -# when targetting WebAssembly. Enable this to debug tests for the `wasm32-unknown-unknown` +# Flag indicating whether `libstd` calls an imported function to handle basic IO +# when targeting WebAssembly. Enable this to debug tests for the `wasm32-unknown-unknown` # target, as without this option the test output will not be captured. #wasm-syscall = false @@ -349,7 +349,7 @@ #linker = "cc" # Path to the `llvm-config` binary of the installation of a custom LLVM to link -# against. Note that if this is specifed we don't compile LLVM at all for this +# against. Note that if this is specified we don't compile LLVM at all for this # target. #llvm-config = "../path/to/llvm/root/bin/llvm-config" From 3cf73f40fb7217471dfe7394b73e67f53cfefc49 Mon Sep 17 00:00:00 2001 From: Alex Burka Date: Tue, 6 Feb 2018 14:43:01 +0000 Subject: [PATCH 08/10] proc_macro: don't panic parsing ..= (fix #47950) --- src/libproc_macro/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libproc_macro/lib.rs b/src/libproc_macro/lib.rs index b9e816baac0d..6768e0ade430 100644 --- a/src/libproc_macro/lib.rs +++ b/src/libproc_macro/lib.rs @@ -685,7 +685,7 @@ impl TokenTree { }) } - DotEq => unreachable!(), + DotEq => joint!('.', Eq), OpenDelim(..) | CloseDelim(..) => unreachable!(), Whitespace | Comment | Shebang(..) | Eof => unreachable!(), }; From fefd5e9bbc150273faf2ac0c4dff8e0e8a098393 Mon Sep 17 00:00:00 2001 From: QuietMisdreavus Date: Tue, 6 Feb 2018 09:26:15 -0600 Subject: [PATCH 09/10] fix docs link --- src/libstd/os/raw/uint.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libstd/os/raw/uint.md b/src/libstd/os/raw/uint.md index 1e710f804c44..6f7013a8ac18 100644 --- a/src/libstd/os/raw/uint.md +++ b/src/libstd/os/raw/uint.md @@ -1,6 +1,6 @@ Equivalent to C's `unsigned int` type. -This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example. +This type will almost always be [`u32`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example. [`int`]: type.c_int.html [`u32`]: ../../primitive.u32.html From 498ef20a2a2ce5da889440fb8708406b6f17e8d0 Mon Sep 17 00:00:00 2001 From: Badel2 <2badel2@gmail.com> Date: Tue, 6 Feb 2018 02:13:39 +0100 Subject: [PATCH 10/10] Trait objects cannot contain associated constants --- src/librustc/diagnostics.rs | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/src/librustc/diagnostics.rs b/src/librustc/diagnostics.rs index 8bd89b834d6b..4c256556191f 100644 --- a/src/librustc/diagnostics.rs +++ b/src/librustc/diagnostics.rs @@ -256,6 +256,28 @@ trait Foo { } ``` +### The trait cannot contain associated constants + +Just like static functions, associated constants aren't stored on the method +table. If the trait or any subtrait contain an associated constant, they cannot +be made into an object. + +```compile_fail,E0038 +trait Foo { + const X: i32; +} + +impl Foo {} +``` + +A simple workaround is to use a helper method instead: + +``` +trait Foo { + fn x(&self) -> i32; +} +``` + ### The trait cannot use `Self` as a type parameter in the supertrait listing This is similar to the second sub-error, but subtler. It happens in situations