From 1a043533f504145fa51beeb6c94765e6865031ee Mon Sep 17 00:00:00 2001 From: Clar Charr Date: Fri, 22 Dec 2017 21:43:09 -0500 Subject: Document std::os::raw. --- src/libstd/lib.rs | 1 + src/libstd/os/raw.rs | 107 --------------------------------- 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/mod.rs | 131 +++++++++++++++++++++++++++++++++++++++++ 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 ++ 16 files changed, 218 insertions(+), 107 deletions(-) delete mode 100644 src/libstd/os/raw.rs 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 create mode 100644 src/libstd/os/raw/mod.rs 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 (limited to 'src/libstd') diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index a8049e676b3..642fa8775a4 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.rs b/src/libstd/os/raw.rs deleted file mode 100644 index 279caf8053a..00000000000 --- a/src/libstd/os/raw.rs +++ /dev/null @@ -1,107 +0,0 @@ -// Copyright 2015 The Rust Project Developers. See the COPYRIGHT -// file at the top-level directory of this distribution and at -// http://rust-lang.org/COPYRIGHT. -// -// Licensed under the Apache License, Version 2.0 or the MIT license -// , at your -// option. This file may not be copied, modified, or distributed -// except according to those terms. - -//! Raw OS-specific types for the current platform/architecture - -#![stable(feature = "raw_os", since = "1.1.0")] - -use fmt; - -#[cfg(any(all(target_os = "linux", any(target_arch = "aarch64", - target_arch = "arm", - target_arch = "powerpc", - target_arch = "powerpc64", - target_arch = "s390x")), - all(target_os = "android", any(target_arch = "aarch64", - target_arch = "arm")), - all(target_os = "l4re", target_arch = "x86_64"), - 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; -#[cfg(not(any(all(target_os = "linux", any(target_arch = "aarch64", - target_arch = "arm", - target_arch = "powerpc", - target_arch = "powerpc64", - target_arch = "s390x")), - all(target_os = "android", any(target_arch = "aarch64", - target_arch = "arm")), - all(target_os = "l4re", target_arch = "x86_64"), - 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; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_schar = i8; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_uchar = u8; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_short = i16; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ushort = u16; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_int = i32; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_uint = u32; -#[cfg(any(target_pointer_width = "32", windows))] -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i32; -#[cfg(any(target_pointer_width = "32", windows))] -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u32; -#[cfg(all(target_pointer_width = "64", not(windows)))] -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_long = i64; -#[cfg(all(target_pointer_width = "64", not(windows)))] -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulong = u64; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_longlong = i64; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_ulonglong = u64; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_float = f32; -#[stable(feature = "raw_os", since = "1.1.0")] pub type c_double = f64; - -/// Type used to construct void pointers for use with C. -/// -/// 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. -// 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 -// of the "raw" type by only having private variants.. We need two -// variants, because the compiler complains about the repr attribute -// otherwise. -#[repr(u8)] -#[stable(feature = "raw_os", since = "1.1.0")] -pub enum c_void { - #[unstable(feature = "c_void_variant", reason = "should not have to exist", - issue = "0")] - #[doc(hidden)] __variant1, - #[unstable(feature = "c_void_variant", reason = "should not have to exist", - issue = "0")] - #[doc(hidden)] __variant2, -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for c_void { - fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { - f.pad("c_void") - } -} - -#[cfg(test)] -#[allow(unused_imports)] -mod tests { - use any::TypeId; - use libc; - use mem; - - macro_rules! ok { - ($($t:ident)*) => {$( - assert!(TypeId::of::() == TypeId::of::(), - "{} is wrong", stringify!($t)); - )*} - } - - #[test] - fn same() { - use os::raw; - ok!(c_char c_schar c_uchar c_short c_ushort c_int c_uint c_long c_ulong - c_longlong c_ulonglong c_float c_double); - } -} diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md new file mode 100644 index 00000000000..fb47dff187e --- /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 00000000000..5ac09ee284c --- /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 00000000000..20ba8645055 --- /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 00000000000..efe7786099a --- /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 00000000000..c281e017336 --- /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 00000000000..6594fcd564c --- /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/mod.rs b/src/libstd/os/raw/mod.rs new file mode 100644 index 00000000000..e96ba045ce7 --- /dev/null +++ b/src/libstd/os/raw/mod.rs @@ -0,0 +1,131 @@ +// Copyright 2015 The Rust Project Developers. See the COPYRIGHT +// file at the top-level directory of this distribution and at +// http://rust-lang.org/COPYRIGHT. +// +// Licensed under the Apache License, Version 2.0 or the MIT license +// , at your +// option. This file may not be copied, modified, or distributed +// except according to those terms. + +//! 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", + target_arch = "powerpc64", + target_arch = "s390x")), + all(target_os = "android", any(target_arch = "aarch64", + target_arch = "arm")), + all(target_os = "l4re", target_arch = "x86_64"), + 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", + target_arch = "powerpc64", + target_arch = "s390x")), + all(target_os = "android", any(target_arch = "aarch64", + target_arch = "arm")), + all(target_os = "l4re", target_arch = "x86_64"), + 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; + +/// Equivalent to C's `void` type when used as a [pointer]. +/// +/// 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 +// of the "raw" type by only having private variants.. We need two +// variants, because the compiler complains about the repr attribute +// otherwise. +#[repr(u8)] +#[stable(feature = "raw_os", since = "1.1.0")] +pub enum c_void { + #[unstable(feature = "c_void_variant", reason = "should not have to exist", + issue = "0")] + #[doc(hidden)] __variant1, + #[unstable(feature = "c_void_variant", reason = "should not have to exist", + issue = "0")] + #[doc(hidden)] __variant2, +} + +#[stable(feature = "std_debug", since = "1.16.0")] +impl fmt::Debug for c_void { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + f.pad("c_void") + } +} + +#[cfg(test)] +#[allow(unused_imports)] +mod tests { + use any::TypeId; + use libc; + use mem; + + macro_rules! ok { + ($($t:ident)*) => {$( + assert!(TypeId::of::() == TypeId::of::(), + "{} is wrong", stringify!($t)); + )*} + } + + #[test] + fn same() { + use os::raw; + ok!(c_char c_schar c_uchar c_short c_ushort c_int c_uint c_long c_ulong + c_longlong c_ulonglong c_float c_double); + } +} diff --git a/src/libstd/os/raw/schar.md b/src/libstd/os/raw/schar.md new file mode 100644 index 00000000000..42a403ef5d7 --- /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 00000000000..86a8495eae2 --- /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 00000000000..a5b74170229 --- /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 00000000000..ec4714a9ab4 --- /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 00000000000..3cdbc6f59bf --- /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 00000000000..9f5ff74f261 --- /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 00000000000..6dea582fda2 --- /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 -- cgit 1.4.1-3-g733a5 From 853fa5873c91ad1d01e69e7cbdb758001a31e9c1 Mon Sep 17 00:00:00 2001 From: Clar Charr Date: Sat, 23 Dec 2017 17:29:51 -0500 Subject: 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(-) (limited to 'src/libstd') diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md index fb47dff187e..6816e519d1a 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 c281e017336..5a2e2331c0a 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 e96ba045ce7..710976ed8e0 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 3cdbc6f59bf..919de171a39 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 -- cgit 1.4.1-3-g733a5 From 2cab06855a9b325c527ab08be4660c4353816833 Mon Sep 17 00:00:00 2001 From: Clar Charr Date: Mon, 29 Jan 2018 18:13:18 -0500 Subject: 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(-) (limited to 'src/libstd') diff --git a/src/libstd/os/raw/char.md b/src/libstd/os/raw/char.md index 6816e519d1a..9a55767d965 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 5ac09ee284c..6818dada317 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 20ba8645055..57d1071d0da 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 efe7786099a..a0d25fd21d8 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 5a2e2331c0a..c620b402819 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 6594fcd564c..ab3d6436568 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 710976ed8e0..d5eeb5252f0 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 42a403ef5d7..6aa8b1211d8 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 86a8495eae2..be92c6c106d 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 a5b74170229..b6ca711f869 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 ec4714a9ab4..1e710f804c4 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 919de171a39..c350395080e 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 9f5ff74f261..c41faf74c5c 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 6dea582fda2..d364abb3c8e 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 -- cgit 1.4.1-3-g733a5 From fefd5e9bbc150273faf2ac0c4dff8e0e8a098393 Mon Sep 17 00:00:00 2001 From: QuietMisdreavus Date: Tue, 6 Feb 2018 09:26:15 -0600 Subject: fix docs link --- src/libstd/os/raw/uint.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'src/libstd') diff --git a/src/libstd/os/raw/uint.md b/src/libstd/os/raw/uint.md index 1e710f804c4..6f7013a8ac1 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 -- cgit 1.4.1-3-g733a5