diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0c20e4dc5351b..618a26958eede 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -67,7 +67,7 @@ jobs: - name: disable git crlf conversion run: git config --global core.autocrlf false - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 2 - name: configure the PR in which the error message will be posted @@ -435,7 +435,7 @@ jobs: - name: disable git crlf conversion run: git config --global core.autocrlf false - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 2 - name: configure the PR in which the error message will be posted @@ -555,7 +555,7 @@ jobs: - name: disable git crlf conversion run: git config --global core.autocrlf false - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 2 - name: configure the PR in which the error message will be posted @@ -662,7 +662,7 @@ jobs: if: "github.event_name == 'push' && github.ref == 'refs/heads/master' && github.repository == 'rust-lang-ci/rust'" steps: - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 2 - name: publish toolstate diff --git a/.github/workflows/dependencies.yml b/.github/workflows/dependencies.yml index 26d2ba636f3e3..97ed891c491da 100644 --- a/.github/workflows/dependencies.yml +++ b/.github/workflows/dependencies.yml @@ -50,7 +50,7 @@ jobs: runs-on: ubuntu-latest steps: - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: submodules: recursive - name: install the bootstrap toolchain @@ -87,7 +87,7 @@ jobs: pull-requests: write steps: - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: download Cargo.lock from update job uses: actions/download-artifact@v3 diff --git a/compiler/rustc_builtin_macros/src/deriving/cmp/eq.rs b/compiler/rustc_builtin_macros/src/deriving/cmp/eq.rs index 745358fde4bbe..a000e4895d166 100644 --- a/compiler/rustc_builtin_macros/src/deriving/cmp/eq.rs +++ b/compiler/rustc_builtin_macros/src/deriving/cmp/eq.rs @@ -18,6 +18,20 @@ pub fn expand_deriving_eq( is_const: bool, ) { let span = cx.with_def_site_ctxt(span); + + let structural_trait_def = TraitDef { + span, + path: path_std!(marker::StructuralEq), + skip_path_as_bound: true, // crucial! + needs_copy_as_bound_if_packed: false, + additional_bounds: Vec::new(), + supports_unions: true, + methods: Vec::new(), + associated_types: Vec::new(), + is_const: false, + }; + structural_trait_def.expand(cx, mitem, item, push); + let trait_def = TraitDef { span, path: path_std!(cmp::Eq), @@ -44,9 +58,6 @@ pub fn expand_deriving_eq( associated_types: Vec::new(), is_const, }; - - super::inject_impl_of_structural_trait(cx, span, item, path_std!(marker::StructuralEq), push); - trait_def.expand_ext(cx, mitem, item, push, true) } diff --git a/compiler/rustc_builtin_macros/src/deriving/cmp/partial_eq.rs b/compiler/rustc_builtin_macros/src/deriving/cmp/partial_eq.rs index a71ecc5db7d97..a170468b4139a 100644 --- a/compiler/rustc_builtin_macros/src/deriving/cmp/partial_eq.rs +++ b/compiler/rustc_builtin_macros/src/deriving/cmp/partial_eq.rs @@ -72,13 +72,20 @@ pub fn expand_deriving_partial_eq( BlockOrExpr::new_expr(expr) } - super::inject_impl_of_structural_trait( - cx, + let structural_trait_def = TraitDef { span, - item, - path_std!(marker::StructuralPartialEq), - push, - ); + path: path_std!(marker::StructuralPartialEq), + skip_path_as_bound: true, // crucial! + needs_copy_as_bound_if_packed: false, + additional_bounds: Vec::new(), + // We really don't support unions, but that's already checked by the impl generated below; + // a second check here would lead to redundant error messages. + supports_unions: true, + methods: Vec::new(), + associated_types: Vec::new(), + is_const: false, + }; + structural_trait_def.expand(cx, mitem, item, push); // No need to generate `ne`, the default suffices, and not generating it is // faster. diff --git a/compiler/rustc_builtin_macros/src/deriving/generic/mod.rs b/compiler/rustc_builtin_macros/src/deriving/generic/mod.rs index edc6f9f098ea7..7252658d460d0 100644 --- a/compiler/rustc_builtin_macros/src/deriving/generic/mod.rs +++ b/compiler/rustc_builtin_macros/src/deriving/generic/mod.rs @@ -711,7 +711,9 @@ impl<'a> TraitDef<'a> { .collect(); // Require the current trait. - bounds.push(cx.trait_bound(trait_path.clone(), self.is_const)); + if !self.skip_path_as_bound { + bounds.push(cx.trait_bound(trait_path.clone(), self.is_const)); + } // Add a `Copy` bound if required. if is_packed && self.needs_copy_as_bound_if_packed { @@ -722,15 +724,17 @@ impl<'a> TraitDef<'a> { )); } - let predicate = ast::WhereBoundPredicate { - span: self.span, - bound_generic_params: field_ty_param.bound_generic_params, - bounded_ty: field_ty_param.ty, - bounds, - }; + if !bounds.is_empty() { + let predicate = ast::WhereBoundPredicate { + span: self.span, + bound_generic_params: field_ty_param.bound_generic_params, + bounded_ty: field_ty_param.ty, + bounds, + }; - let predicate = ast::WherePredicate::BoundPredicate(predicate); - where_clause.predicates.push(predicate); + let predicate = ast::WherePredicate::BoundPredicate(predicate); + where_clause.predicates.push(predicate); + } } } } diff --git a/compiler/rustc_builtin_macros/src/deriving/mod.rs b/compiler/rustc_builtin_macros/src/deriving/mod.rs index d34336e7679c0..a6f3252e7be16 100644 --- a/compiler/rustc_builtin_macros/src/deriving/mod.rs +++ b/compiler/rustc_builtin_macros/src/deriving/mod.rs @@ -2,9 +2,9 @@ use rustc_ast as ast; use rustc_ast::ptr::P; -use rustc_ast::{GenericArg, Impl, ItemKind, MetaItem}; +use rustc_ast::{GenericArg, MetaItem}; use rustc_expand::base::{Annotatable, ExpandResult, ExtCtxt, MultiItemModifier}; -use rustc_span::symbol::{sym, Ident, Symbol}; +use rustc_span::symbol::{sym, Symbol}; use rustc_span::Span; use thin_vec::{thin_vec, ThinVec}; @@ -116,100 +116,6 @@ fn call_unreachable(cx: &ExtCtxt<'_>, span: Span) -> P { })) } -// Injects `impl<...> Structural for ItemType<...> { }`. In particular, -// does *not* add `where T: Structural` for parameters `T` in `...`. -// (That's the main reason we cannot use TraitDef here.) -fn inject_impl_of_structural_trait( - cx: &mut ExtCtxt<'_>, - span: Span, - item: &Annotatable, - structural_path: generic::ty::Path, - push: &mut dyn FnMut(Annotatable), -) { - let Annotatable::Item(item) = item else { - unreachable!(); - }; - - let generics = match &item.kind { - ItemKind::Struct(_, generics) | ItemKind::Enum(_, generics) => generics, - // Do not inject `impl Structural for Union`. (`PartialEq` does not - // support unions, so we will see error downstream.) - ItemKind::Union(..) => return, - _ => unreachable!(), - }; - - // Create generics param list for where clauses and impl headers - let mut generics = generics.clone(); - - let ctxt = span.ctxt(); - - // Create the type of `self`. - // - // in addition, remove defaults from generic params (impls cannot have them). - let self_params: Vec<_> = generics - .params - .iter_mut() - .map(|param| match &mut param.kind { - ast::GenericParamKind::Lifetime => ast::GenericArg::Lifetime( - cx.lifetime(param.ident.span.with_ctxt(ctxt), param.ident), - ), - ast::GenericParamKind::Type { default } => { - *default = None; - ast::GenericArg::Type(cx.ty_ident(param.ident.span.with_ctxt(ctxt), param.ident)) - } - ast::GenericParamKind::Const { ty: _, kw_span: _, default } => { - *default = None; - ast::GenericArg::Const( - cx.const_ident(param.ident.span.with_ctxt(ctxt), param.ident), - ) - } - }) - .collect(); - - let type_ident = item.ident; - - let trait_ref = cx.trait_ref(structural_path.to_path(cx, span, type_ident, &generics)); - let self_type = cx.ty_path(cx.path_all(span, false, vec![type_ident], self_params)); - - // It would be nice to also encode constraint `where Self: Eq` (by adding it - // onto `generics` cloned above). Unfortunately, that strategy runs afoul of - // rust-lang/rust#48214. So we perform that additional check in the compiler - // itself, instead of encoding it here. - - // Keep the lint and stability attributes of the original item, to control - // how the generated implementation is linted. - let mut attrs = ast::AttrVec::new(); - attrs.extend( - item.attrs - .iter() - .filter(|a| { - [sym::allow, sym::warn, sym::deny, sym::forbid, sym::stable, sym::unstable] - .contains(&a.name_or_empty()) - }) - .cloned(), - ); - // Mark as `automatically_derived` to avoid some silly lints. - attrs.push(cx.attr_word(sym::automatically_derived, span)); - - let newitem = cx.item( - span, - Ident::empty(), - attrs, - ItemKind::Impl(Box::new(Impl { - unsafety: ast::Unsafe::No, - polarity: ast::ImplPolarity::Positive, - defaultness: ast::Defaultness::Final, - constness: ast::Const::No, - generics, - of_trait: Some(trait_ref), - self_ty: self_type, - items: ThinVec::new(), - })), - ); - - push(Annotatable::Item(newitem)); -} - fn assert_ty_bounds( cx: &mut ExtCtxt<'_>, stmts: &mut ThinVec, diff --git a/compiler/rustc_ty_utils/src/layout.rs b/compiler/rustc_ty_utils/src/layout.rs index 904f1b3874088..a03b82305f069 100644 --- a/compiler/rustc_ty_utils/src/layout.rs +++ b/compiler/rustc_ty_utils/src/layout.rs @@ -36,6 +36,9 @@ fn layout_of<'tcx>( let (param_env, ty) = query.into_parts(); debug!(?ty); + // Optimization: We convert to RevealAll and convert opaque types in the where bounds + // to their hidden types. This reduces overall uncached invocations of `layout_of` and + // is thus a small performance improvement. let param_env = param_env.with_reveal_all_normalized(tcx); let unnormalized_ty = ty; diff --git a/library/core/primitive_docs/box_into_raw.md b/library/core/primitive_docs/box_into_raw.md deleted file mode 100644 index 9dd0344c7c7b1..0000000000000 --- a/library/core/primitive_docs/box_into_raw.md +++ /dev/null @@ -1 +0,0 @@ -../std/boxed/struct.Box.html#method.into_raw diff --git a/library/core/primitive_docs/fs_file.md b/library/core/primitive_docs/fs_file.md deleted file mode 100644 index 4023e340a5182..0000000000000 --- a/library/core/primitive_docs/fs_file.md +++ /dev/null @@ -1 +0,0 @@ -../std/fs/struct.File.html diff --git a/library/core/primitive_docs/io_bufread.md b/library/core/primitive_docs/io_bufread.md deleted file mode 100644 index 7beda2cd39085..0000000000000 --- a/library/core/primitive_docs/io_bufread.md +++ /dev/null @@ -1 +0,0 @@ -../std/io/trait.BufRead.html diff --git a/library/core/primitive_docs/io_read.md b/library/core/primitive_docs/io_read.md deleted file mode 100644 index b7ecf5e273cea..0000000000000 --- a/library/core/primitive_docs/io_read.md +++ /dev/null @@ -1 +0,0 @@ -../std/io/trait.Read.html diff --git a/library/core/primitive_docs/io_seek.md b/library/core/primitive_docs/io_seek.md deleted file mode 100644 index db0274d291c6f..0000000000000 --- a/library/core/primitive_docs/io_seek.md +++ /dev/null @@ -1 +0,0 @@ -../std/io/trait.Seek.html diff --git a/library/core/primitive_docs/io_write.md b/library/core/primitive_docs/io_write.md deleted file mode 100644 index 92a3b88a79c9c..0000000000000 --- a/library/core/primitive_docs/io_write.md +++ /dev/null @@ -1 +0,0 @@ -../std/io/trait.Write.html diff --git a/library/core/primitive_docs/net_tosocketaddrs.md b/library/core/primitive_docs/net_tosocketaddrs.md deleted file mode 100644 index 4daa10ddbe2b2..0000000000000 --- a/library/core/primitive_docs/net_tosocketaddrs.md +++ /dev/null @@ -1 +0,0 @@ -../std/net/trait.ToSocketAddrs.html diff --git a/library/core/primitive_docs/process_exit.md b/library/core/primitive_docs/process_exit.md deleted file mode 100644 index cae34d12d5249..0000000000000 --- a/library/core/primitive_docs/process_exit.md +++ /dev/null @@ -1 +0,0 @@ -../std/process/fn.exit.html diff --git a/library/core/primitive_docs/string_string.md b/library/core/primitive_docs/string_string.md deleted file mode 100644 index 303dc07b1855d..0000000000000 --- a/library/core/primitive_docs/string_string.md +++ /dev/null @@ -1 +0,0 @@ -../std/string/struct.String.html diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs index 739f0c360fd43..33226b07e0427 100644 --- a/library/core/src/cmp.rs +++ b/library/core/src/cmp.rs @@ -1289,6 +1289,91 @@ pub fn max_by_key K, K: Ord>(v1: T, v2: T, mut f: F) -> T { max_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2))) } +/// Compares and sorts two values, returning minimum and maximum. +/// +/// Returns `[v1, v2]` if the comparison determines them to be equal. +/// +/// # Examples +/// +/// ``` +/// #![feature(cmp_minmax)] +/// use std::cmp; +/// +/// assert_eq!(cmp::minmax(1, 2), [1, 2]); +/// assert_eq!(cmp::minmax(2, 2), [2, 2]); +/// +/// // You can destructure the result using array patterns +/// let [min, max] = cmp::minmax(42, 17); +/// assert_eq!(min, 17); +/// assert_eq!(max, 42); +/// ``` +#[inline] +#[must_use] +#[unstable(feature = "cmp_minmax", issue = "115939")] +pub fn minmax(v1: T, v2: T) -> [T; 2] +where + T: Ord, +{ + if v1 <= v2 { [v1, v2] } else { [v2, v1] } +} + +/// Returns minimum and maximum values with respect to the specified comparison function. +/// +/// Returns `[v1, v2]` if the comparison determines them to be equal. +/// +/// # Examples +/// +/// ``` +/// #![feature(cmp_minmax)] +/// use std::cmp; +/// +/// assert_eq!(cmp::minmax_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), [1, -2]); +/// assert_eq!(cmp::minmax_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), [-2, 2]); +/// +/// // You can destructure the result using array patterns +/// let [min, max] = cmp::minmax_by(-42, 17, |x: &i32, y: &i32| x.abs().cmp(&y.abs())); +/// assert_eq!(min, 17); +/// assert_eq!(max, -42); +/// ``` +#[inline] +#[must_use] +#[unstable(feature = "cmp_minmax", issue = "115939")] +pub fn minmax_by(v1: T, v2: T, compare: F) -> [T; 2] +where + F: FnOnce(&T, &T) -> Ordering, +{ + if compare(&v1, &v2).is_le() { [v1, v2] } else { [v2, v1] } +} + +/// Returns minimum and maximum values with respect to the specified key function. +/// +/// Returns `[v1, v2]` if the comparison determines them to be equal. +/// +/// # Examples +/// +/// ``` +/// #![feature(cmp_minmax)] +/// use std::cmp; +/// +/// assert_eq!(cmp::minmax_by_key(-2, 1, |x: &i32| x.abs()), [1, -2]); +/// assert_eq!(cmp::minmax_by_key(-2, 2, |x: &i32| x.abs()), [-2, 2]); +/// +/// // You can destructure the result using array patterns +/// let [min, max] = cmp::minmax_by_key(-42, 17, |x: &i32| x.abs()); +/// assert_eq!(min, 17); +/// assert_eq!(max, -42); +/// ``` +#[inline] +#[must_use] +#[unstable(feature = "cmp_minmax", issue = "115939")] +pub fn minmax_by_key(v1: T, v2: T, mut f: F) -> [T; 2] +where + F: FnMut(&T) -> K, + K: Ord, +{ + minmax_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2))) +} + // Implementation of PartialEq, Eq, PartialOrd and Ord for primitive types mod impls { use crate::cmp::Ordering::{self, Equal, Greater, Less}; diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs index 2cfa896e5b96e..fd5fe5a04f4d9 100644 --- a/library/core/src/primitive_docs.rs +++ b/library/core/src/primitive_docs.rs @@ -1,6 +1,3 @@ -// `library/{std,core}/src/primitive_docs.rs` should have the same contents. -// These are different files so that relative links work properly without -// having to have `CARGO_PKG_NAME` set, but conceptually they should always be the same. #[rustc_doc_primitive = "bool"] #[doc(alias = "true")] #[doc(alias = "false")] @@ -106,7 +103,7 @@ mod prim_bool {} /// behaviour of the `!` type - expressions with type `!` will coerce into any other type. /// /// [`u32`]: prim@u32 -#[doc = concat!("[`exit`]: ", include_str!("../primitive_docs/process_exit.md"))] +/// [`exit`]: ../std/process/fn.exit.html /// /// # `!` and generics /// @@ -191,7 +188,7 @@ mod prim_bool {} /// because `!` coerces to `Result` automatically. /// /// [`String::from_str`]: str::FromStr::from_str -#[doc = concat!("[`String`]: ", include_str!("../primitive_docs/string_string.md"))] +/// [`String`]: ../std/string/struct.String.html /// [`FromStr`]: str::FromStr /// /// # `!` and traits @@ -267,7 +264,7 @@ mod prim_bool {} /// `impl` for this which simply panics, but the same is true for any type (we could `impl /// Default` for (eg.) [`File`] by just making [`default()`] panic.) /// -#[doc = concat!("[`File`]: ", include_str!("../primitive_docs/fs_file.md"))] +/// [`File`]: ../std/fs/struct.File.html /// [`Debug`]: fmt::Debug /// [`default()`]: Default::default /// @@ -355,7 +352,7 @@ mod prim_never {} /// assert_eq!(5, s.len() * std::mem::size_of::()); /// ``` /// -#[doc = concat!("[`String`]: ", include_str!("../primitive_docs/string_string.md"))] +/// [`String`]: ../std/string/struct.String.html /// /// As always, remember that a human intuition for 'character' might not map to /// Unicode's definitions. For example, despite looking similar, the 'é' @@ -572,7 +569,7 @@ impl Copy for () { /// [`null_mut`]: ptr::null_mut /// [`is_null`]: pointer::is_null /// [`offset`]: pointer::offset -#[doc = concat!("[`into_raw`]: ", include_str!("../primitive_docs/box_into_raw.md"))] +/// [`into_raw`]: ../std/boxed/struct.Box.html#method.into_raw /// [`write`]: ptr::write #[stable(feature = "rust1", since = "1.0.0")] mod prim_pointer {} @@ -1361,7 +1358,7 @@ mod prim_usize {} /// /// [`std::fmt`]: fmt /// [`Hash`]: hash::Hash -#[doc = concat!("[`ToSocketAddrs`]: ", include_str!("../primitive_docs/net_tosocketaddrs.md"))] +/// [`ToSocketAddrs`]: ../std/net/trait.ToSocketAddrs.html /// /// `&mut T` references get all of the above except `ToSocketAddrs`, plus the following, if `T` /// implements that trait: @@ -1381,10 +1378,10 @@ mod prim_usize {} /// /// [`FusedIterator`]: iter::FusedIterator /// [`TrustedLen`]: iter::TrustedLen -#[doc = concat!("[`Seek`]: ", include_str!("../primitive_docs/io_seek.md"))] -#[doc = concat!("[`BufRead`]: ", include_str!("../primitive_docs/io_bufread.md"))] -#[doc = concat!("[`Read`]: ", include_str!("../primitive_docs/io_read.md"))] -#[doc = concat!("[`io::Write`]: ", include_str!("../primitive_docs/io_write.md"))] +/// [`Seek`]: ../std/io/trait.Seek.html +/// [`BufRead`]: ../std/io/trait.BufRead.html +/// [`Read`]: ../std/io/trait.Read.html +/// [`io::Write`]: ../std/io/trait.Write.html /// /// Note that due to method call deref coercion, simply calling a trait method will act like they /// work on references as well as they do on owned values! The implementations described here are diff --git a/library/core/src/tuple.rs b/library/core/src/tuple.rs index 7782ace69c1c1..ff292ff2dcbfb 100644 --- a/library/core/src/tuple.rs +++ b/library/core/src/tuple.rs @@ -1,4 +1,4 @@ -// See src/libstd/primitive_docs.rs for documentation. +// See core/src/primitive_docs.rs for documentation. use crate::cmp::Ordering::{self, *}; use crate::marker::ConstParamTy; diff --git a/library/std/primitive_docs/box_into_raw.md b/library/std/primitive_docs/box_into_raw.md deleted file mode 100644 index 307b9c85bd67e..0000000000000 --- a/library/std/primitive_docs/box_into_raw.md +++ /dev/null @@ -1 +0,0 @@ -Box::into_raw diff --git a/library/std/primitive_docs/fs_file.md b/library/std/primitive_docs/fs_file.md deleted file mode 100644 index 13e4540835e61..0000000000000 --- a/library/std/primitive_docs/fs_file.md +++ /dev/null @@ -1 +0,0 @@ -fs::File diff --git a/library/std/primitive_docs/io_bufread.md b/library/std/primitive_docs/io_bufread.md deleted file mode 100644 index bb688e3a5cc87..0000000000000 --- a/library/std/primitive_docs/io_bufread.md +++ /dev/null @@ -1 +0,0 @@ -io::BufRead diff --git a/library/std/primitive_docs/io_read.md b/library/std/primitive_docs/io_read.md deleted file mode 100644 index 5118d7c4888ab..0000000000000 --- a/library/std/primitive_docs/io_read.md +++ /dev/null @@ -1 +0,0 @@ -io::Read diff --git a/library/std/primitive_docs/io_seek.md b/library/std/primitive_docs/io_seek.md deleted file mode 100644 index 122e6df77b6d7..0000000000000 --- a/library/std/primitive_docs/io_seek.md +++ /dev/null @@ -1 +0,0 @@ -io::Seek diff --git a/library/std/primitive_docs/io_write.md b/library/std/primitive_docs/io_write.md deleted file mode 100644 index 15dfc907a6555..0000000000000 --- a/library/std/primitive_docs/io_write.md +++ /dev/null @@ -1 +0,0 @@ -io::Write diff --git a/library/std/primitive_docs/net_tosocketaddrs.md b/library/std/primitive_docs/net_tosocketaddrs.md deleted file mode 100644 index a01f318e88771..0000000000000 --- a/library/std/primitive_docs/net_tosocketaddrs.md +++ /dev/null @@ -1 +0,0 @@ -net::ToSocketAddrs diff --git a/library/std/primitive_docs/process_exit.md b/library/std/primitive_docs/process_exit.md deleted file mode 100644 index 565a71375cd0e..0000000000000 --- a/library/std/primitive_docs/process_exit.md +++ /dev/null @@ -1 +0,0 @@ -process::exit diff --git a/library/std/primitive_docs/string_string.md b/library/std/primitive_docs/string_string.md deleted file mode 100644 index ce7815ff91b9e..0000000000000 --- a/library/std/primitive_docs/string_string.md +++ /dev/null @@ -1 +0,0 @@ -string::String diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs index 22ccfc0dbe9c8..55c112c7b806c 100644 --- a/library/std/src/lib.rs +++ b/library/std/src/lib.rs @@ -673,7 +673,7 @@ pub use core::primitive; // Include a number of private modules that exist solely to provide // the rustdoc documentation for primitive types. Using `include!` // because rustdoc only looks for these modules at the crate level. -include!("primitive_docs.rs"); +include!("../../core/src/primitive_docs.rs"); // Include a number of private modules that exist solely to provide // the rustdoc documentation for the existing keywords. Using `include!` diff --git a/library/std/src/primitive_docs.rs b/library/std/src/primitive_docs.rs deleted file mode 100644 index 2cfa896e5b96e..0000000000000 --- a/library/std/src/primitive_docs.rs +++ /dev/null @@ -1,1593 +0,0 @@ -// `library/{std,core}/src/primitive_docs.rs` should have the same contents. -// These are different files so that relative links work properly without -// having to have `CARGO_PKG_NAME` set, but conceptually they should always be the same. -#[rustc_doc_primitive = "bool"] -#[doc(alias = "true")] -#[doc(alias = "false")] -/// The boolean type. -/// -/// The `bool` represents a value, which could only be either [`true`] or [`false`]. If you cast -/// a `bool` into an integer, [`true`] will be 1 and [`false`] will be 0. -/// -/// # Basic usage -/// -/// `bool` implements various traits, such as [`BitAnd`], [`BitOr`], [`Not`], etc., -/// which allow us to perform boolean operations using `&`, `|` and `!`. -/// -/// [`if`] requires a `bool` value as its conditional. [`assert!`], which is an -/// important macro in testing, checks whether an expression is [`true`] and panics -/// if it isn't. -/// -/// ``` -/// let bool_val = true & false | false; -/// assert!(!bool_val); -/// ``` -/// -/// [`true`]: ../std/keyword.true.html -/// [`false`]: ../std/keyword.false.html -/// [`BitAnd`]: ops::BitAnd -/// [`BitOr`]: ops::BitOr -/// [`Not`]: ops::Not -/// [`if`]: ../std/keyword.if.html -/// -/// # Examples -/// -/// A trivial example of the usage of `bool`: -/// -/// ``` -/// let praise_the_borrow_checker = true; -/// -/// // using the `if` conditional -/// if praise_the_borrow_checker { -/// println!("oh, yeah!"); -/// } else { -/// println!("what?!!"); -/// } -/// -/// // ... or, a match pattern -/// match praise_the_borrow_checker { -/// true => println!("keep praising!"), -/// false => println!("you should praise!"), -/// } -/// ``` -/// -/// Also, since `bool` implements the [`Copy`] trait, we don't -/// have to worry about the move semantics (just like the integer and float primitives). -/// -/// Now an example of `bool` cast to integer type: -/// -/// ``` -/// assert_eq!(true as i32, 1); -/// assert_eq!(false as i32, 0); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_bool {} - -#[rustc_doc_primitive = "never"] -#[doc(alias = "!")] -// -/// The `!` type, also called "never". -/// -/// `!` represents the type of computations which never resolve to any value at all. For example, -/// the [`exit`] function `fn exit(code: i32) -> !` exits the process without ever returning, and -/// so returns `!`. -/// -/// `break`, `continue` and `return` expressions also have type `!`. For example we are allowed to -/// write: -/// -/// ``` -/// #![feature(never_type)] -/// # fn foo() -> u32 { -/// let x: ! = { -/// return 123 -/// }; -/// # } -/// ``` -/// -/// Although the `let` is pointless here, it illustrates the meaning of `!`. Since `x` is never -/// assigned a value (because `return` returns from the entire function), `x` can be given type -/// `!`. We could also replace `return 123` with a `panic!` or a never-ending `loop` and this code -/// would still be valid. -/// -/// A more realistic usage of `!` is in this code: -/// -/// ``` -/// # fn get_a_number() -> Option { None } -/// # loop { -/// let num: u32 = match get_a_number() { -/// Some(num) => num, -/// None => break, -/// }; -/// # } -/// ``` -/// -/// Both match arms must produce values of type [`u32`], but since `break` never produces a value -/// at all we know it can never produce a value which isn't a [`u32`]. This illustrates another -/// behaviour of the `!` type - expressions with type `!` will coerce into any other type. -/// -/// [`u32`]: prim@u32 -#[doc = concat!("[`exit`]: ", include_str!("../primitive_docs/process_exit.md"))] -/// -/// # `!` and generics -/// -/// ## Infallible errors -/// -/// The main place you'll see `!` used explicitly is in generic code. Consider the [`FromStr`] -/// trait: -/// -/// ``` -/// trait FromStr: Sized { -/// type Err; -/// fn from_str(s: &str) -> Result; -/// } -/// ``` -/// -/// When implementing this trait for [`String`] we need to pick a type for [`Err`]. And since -/// converting a string into a string will never result in an error, the appropriate type is `!`. -/// (Currently the type actually used is an enum with no variants, though this is only because `!` -/// was added to Rust at a later date and it may change in the future.) With an [`Err`] type of -/// `!`, if we have to call [`String::from_str`] for some reason the result will be a -/// [`Result`] which we can unpack like this: -/// -/// ``` -/// #![feature(exhaustive_patterns)] -/// use std::str::FromStr; -/// let Ok(s) = String::from_str("hello"); -/// ``` -/// -/// Since the [`Err`] variant contains a `!`, it can never occur. If the `exhaustive_patterns` -/// feature is present this means we can exhaustively match on [`Result`] by just taking the -/// [`Ok`] variant. This illustrates another behaviour of `!` - it can be used to "delete" certain -/// enum variants from generic types like `Result`. -/// -/// ## Infinite loops -/// -/// While [`Result`] is very useful for removing errors, `!` can also be used to remove -/// successes as well. If we think of [`Result`] as "if this function returns, it has not -/// errored," we get a very intuitive idea of [`Result`] as well: if the function returns, it -/// *has* errored. -/// -/// For example, consider the case of a simple web server, which can be simplified to: -/// -/// ```ignore (hypothetical-example) -/// loop { -/// let (client, request) = get_request().expect("disconnected"); -/// let response = request.process(); -/// response.send(client); -/// } -/// ``` -/// -/// Currently, this isn't ideal, because we simply panic whenever we fail to get a new connection. -/// Instead, we'd like to keep track of this error, like this: -/// -/// ```ignore (hypothetical-example) -/// loop { -/// match get_request() { -/// Err(err) => break err, -/// Ok((client, request)) => { -/// let response = request.process(); -/// response.send(client); -/// }, -/// } -/// } -/// ``` -/// -/// Now, when the server disconnects, we exit the loop with an error instead of panicking. While it -/// might be intuitive to simply return the error, we might want to wrap it in a [`Result`] -/// instead: -/// -/// ```ignore (hypothetical-example) -/// fn server_loop() -> Result { -/// loop { -/// let (client, request) = get_request()?; -/// let response = request.process(); -/// response.send(client); -/// } -/// } -/// ``` -/// -/// Now, we can use `?` instead of `match`, and the return type makes a lot more sense: if the loop -/// ever stops, it means that an error occurred. We don't even have to wrap the loop in an `Ok` -/// because `!` coerces to `Result` automatically. -/// -/// [`String::from_str`]: str::FromStr::from_str -#[doc = concat!("[`String`]: ", include_str!("../primitive_docs/string_string.md"))] -/// [`FromStr`]: str::FromStr -/// -/// # `!` and traits -/// -/// When writing your own traits, `!` should have an `impl` whenever there is an obvious `impl` -/// which doesn't `panic!`. The reason is that functions returning an `impl Trait` where `!` -/// does not have an `impl` of `Trait` cannot diverge as their only possible code path. In other -/// words, they can't return `!` from every code path. As an example, this code doesn't compile: -/// -/// ```compile_fail -/// use std::ops::Add; -/// -/// fn foo() -> impl Add { -/// unimplemented!() -/// } -/// ``` -/// -/// But this code does: -/// -/// ``` -/// use std::ops::Add; -/// -/// fn foo() -> impl Add { -/// if true { -/// unimplemented!() -/// } else { -/// 0 -/// } -/// } -/// ``` -/// -/// The reason is that, in the first example, there are many possible types that `!` could coerce -/// to, because many types implement `Add`. However, in the second example, -/// the `else` branch returns a `0`, which the compiler infers from the return type to be of type -/// `u32`. Since `u32` is a concrete type, `!` can and will be coerced to it. See issue [#36375] -/// for more information on this quirk of `!`. -/// -/// [#36375]: https://github.com/rust-lang/rust/issues/36375 -/// -/// As it turns out, though, most traits can have an `impl` for `!`. Take [`Debug`] -/// for example: -/// -/// ``` -/// #![feature(never_type)] -/// # use std::fmt; -/// # trait Debug { -/// # fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result; -/// # } -/// impl Debug for ! { -/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { -/// *self -/// } -/// } -/// ``` -/// -/// Once again we're using `!`'s ability to coerce into any other type, in this case -/// [`fmt::Result`]. Since this method takes a `&!` as an argument we know that it can never be -/// called (because there is no value of type `!` for it to be called with). Writing `*self` -/// essentially tells the compiler "We know that this code can never be run, so just treat the -/// entire function body as having type [`fmt::Result`]". This pattern can be used a lot when -/// implementing traits for `!`. Generally, any trait which only has methods which take a `self` -/// parameter should have such an impl. -/// -/// On the other hand, one trait which would not be appropriate to implement is [`Default`]: -/// -/// ``` -/// trait Default { -/// fn default() -> Self; -/// } -/// ``` -/// -/// Since `!` has no values, it has no default value either. It's true that we could write an -/// `impl` for this which simply panics, but the same is true for any type (we could `impl -/// Default` for (eg.) [`File`] by just making [`default()`] panic.) -/// -#[doc = concat!("[`File`]: ", include_str!("../primitive_docs/fs_file.md"))] -/// [`Debug`]: fmt::Debug -/// [`default()`]: Default::default -/// -#[unstable(feature = "never_type", issue = "35121")] -mod prim_never {} - -#[rustc_doc_primitive = "char"] -#[allow(rustdoc::invalid_rust_codeblocks)] -/// A character type. -/// -/// The `char` type represents a single character. More specifically, since -/// 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode -/// scalar value]'. -/// -/// This documentation describes a number of methods and trait implementations on the -/// `char` type. For technical reasons, there is additional, separate -/// documentation in [the `std::char` module](char/index.html) as well. -/// -/// # Validity -/// -/// A `char` is a '[Unicode scalar value]', which is any '[Unicode code point]' -/// other than a [surrogate code point]. This has a fixed numerical definition: -/// code points are in the range 0 to 0x10FFFF, inclusive. -/// Surrogate code points, used by UTF-16, are in the range 0xD800 to 0xDFFF. -/// -/// No `char` may be constructed, whether as a literal or at runtime, that is not a -/// Unicode scalar value: -/// -/// ```compile_fail -/// // Each of these is a compiler error -/// ['\u{D800}', '\u{DFFF}', '\u{110000}']; -/// ``` -/// -/// ```should_panic -/// // Panics; from_u32 returns None. -/// char::from_u32(0xDE01).unwrap(); -/// ``` -/// -/// ```no_run -/// // Undefined behaviour -/// let _ = unsafe { char::from_u32_unchecked(0x110000) }; -/// ``` -/// -/// USVs are also the exact set of values that may be encoded in UTF-8. Because -/// `char` values are USVs and `str` values are valid UTF-8, it is safe to store -/// any `char` in a `str` or read any character from a `str` as a `char`. -/// -/// The gap in valid `char` values is understood by the compiler, so in the -/// below example the two ranges are understood to cover the whole range of -/// possible `char` values and there is no error for a [non-exhaustive match]. -/// -/// ``` -/// let c: char = 'a'; -/// match c { -/// '\0' ..= '\u{D7FF}' => false, -/// '\u{E000}' ..= '\u{10FFFF}' => true, -/// }; -/// ``` -/// -/// All USVs are valid `char` values, but not all of them represent a real -/// character. Many USVs are not currently assigned to a character, but may be -/// in the future ("reserved"); some will never be a character -/// ("noncharacters"); and some may be given different meanings by different -/// users ("private use"). -/// -/// [Unicode code point]: https://www.unicode.org/glossary/#code_point -/// [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value -/// [non-exhaustive match]: ../book/ch06-02-match.html#matches-are-exhaustive -/// [surrogate code point]: https://www.unicode.org/glossary/#surrogate_code_point -/// -/// # Representation -/// -/// `char` is always four bytes in size. This is a different representation than -/// a given character would have as part of a [`String`]. For example: -/// -/// ``` -/// let v = vec!['h', 'e', 'l', 'l', 'o']; -/// -/// // five elements times four bytes for each element -/// assert_eq!(20, v.len() * std::mem::size_of::()); -/// -/// let s = String::from("hello"); -/// -/// // five elements times one byte per element -/// assert_eq!(5, s.len() * std::mem::size_of::()); -/// ``` -/// -#[doc = concat!("[`String`]: ", include_str!("../primitive_docs/string_string.md"))] -/// -/// As always, remember that a human intuition for 'character' might not map to -/// Unicode's definitions. For example, despite looking similar, the 'é' -/// character is one Unicode code point while 'é' is two Unicode code points: -/// -/// ``` -/// let mut chars = "é".chars(); -/// // U+00e9: 'latin small letter e with acute' -/// assert_eq!(Some('\u{00e9}'), chars.next()); -/// assert_eq!(None, chars.next()); -/// -/// let mut chars = "é".chars(); -/// // U+0065: 'latin small letter e' -/// assert_eq!(Some('\u{0065}'), chars.next()); -/// // U+0301: 'combining acute accent' -/// assert_eq!(Some('\u{0301}'), chars.next()); -/// assert_eq!(None, chars.next()); -/// ``` -/// -/// This means that the contents of the first string above _will_ fit into a -/// `char` while the contents of the second string _will not_. Trying to create -/// a `char` literal with the contents of the second string gives an error: -/// -/// ```text -/// error: character literal may only contain one codepoint: 'é' -/// let c = 'é'; -/// ^^^ -/// ``` -/// -/// Another implication of the 4-byte fixed size of a `char` is that -/// per-`char` processing can end up using a lot more memory: -/// -/// ``` -/// let s = String::from("love: ❤️"); -/// let v: Vec = s.chars().collect(); -/// -/// assert_eq!(12, std::mem::size_of_val(&s[..])); -/// assert_eq!(32, std::mem::size_of_val(&v[..])); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_char {} - -#[rustc_doc_primitive = "unit"] -#[doc(alias = "(")] -#[doc(alias = ")")] -#[doc(alias = "()")] -// -/// The `()` type, also called "unit". -/// -/// The `()` type has exactly one value `()`, and is used when there -/// is no other meaningful value that could be returned. `()` is most -/// commonly seen implicitly: functions without a `-> ...` implicitly -/// have return type `()`, that is, these are equivalent: -/// -/// ```rust -/// fn long() -> () {} -/// -/// fn short() {} -/// ``` -/// -/// The semicolon `;` can be used to discard the result of an -/// expression at the end of a block, making the expression (and thus -/// the block) evaluate to `()`. For example, -/// -/// ```rust -/// fn returns_i64() -> i64 { -/// 1i64 -/// } -/// fn returns_unit() { -/// 1i64; -/// } -/// -/// let is_i64 = { -/// returns_i64() -/// }; -/// let is_unit = { -/// returns_i64(); -/// }; -/// ``` -/// -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_unit {} - -// Required to make auto trait impls render. -// See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls -#[doc(hidden)] -impl () {} - -// Fake impl that's only really used for docs. -#[cfg(doc)] -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for () { - fn clone(&self) -> Self { - loop {} - } -} - -// Fake impl that's only really used for docs. -#[cfg(doc)] -#[stable(feature = "rust1", since = "1.0.0")] -impl Copy for () { - // empty -} - -#[rustc_doc_primitive = "pointer"] -#[doc(alias = "ptr")] -#[doc(alias = "*")] -#[doc(alias = "*const")] -#[doc(alias = "*mut")] -// -/// Raw, unsafe pointers, `*const T`, and `*mut T`. -/// -/// *[See also the `std::ptr` module](ptr).* -/// -/// Working with raw pointers in Rust is uncommon, typically limited to a few patterns. -/// Raw pointers can be unaligned or [`null`]. However, when a raw pointer is -/// dereferenced (using the `*` operator), it must be non-null and aligned. -/// -/// Storing through a raw pointer using `*ptr = data` calls `drop` on the old value, so -/// [`write`] must be used if the type has drop glue and memory is not already -/// initialized - otherwise `drop` would be called on the uninitialized memory. -/// -/// Use the [`null`] and [`null_mut`] functions to create null pointers, and the -/// [`is_null`] method of the `*const T` and `*mut T` types to check for null. -/// The `*const T` and `*mut T` types also define the [`offset`] method, for -/// pointer math. -/// -/// # Common ways to create raw pointers -/// -/// ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`). -/// -/// ``` -/// let my_num: i32 = 10; -/// let my_num_ptr: *const i32 = &my_num; -/// let mut my_speed: i32 = 88; -/// let my_speed_ptr: *mut i32 = &mut my_speed; -/// ``` -/// -/// To get a pointer to a boxed value, dereference the box: -/// -/// ``` -/// let my_num: Box = Box::new(10); -/// let my_num_ptr: *const i32 = &*my_num; -/// let mut my_speed: Box = Box::new(88); -/// let my_speed_ptr: *mut i32 = &mut *my_speed; -/// ``` -/// -/// This does not take ownership of the original allocation -/// and requires no resource management later, -/// but you must not use the pointer after its lifetime. -/// -/// ## 2. Consume a box (`Box`). -/// -/// The [`into_raw`] function consumes a box and returns -/// the raw pointer. It doesn't destroy `T` or deallocate any memory. -/// -/// ``` -/// let my_speed: Box = Box::new(88); -/// let my_speed: *mut i32 = Box::into_raw(my_speed); -/// -/// // By taking ownership of the original `Box` though -/// // we are obligated to put it together later to be destroyed. -/// unsafe { -/// drop(Box::from_raw(my_speed)); -/// } -/// ``` -/// -/// Note that here the call to [`drop`] is for clarity - it indicates -/// that we are done with the given value and it should be destroyed. -/// -/// ## 3. Create it using `ptr::addr_of!` -/// -/// Instead of coercing a reference to a raw pointer, you can use the macros -/// [`ptr::addr_of!`] (for `*const T`) and [`ptr::addr_of_mut!`] (for `*mut T`). -/// These macros allow you to create raw pointers to fields to which you cannot -/// create a reference (without causing undefined behaviour), such as an -/// unaligned field. This might be necessary if packed structs or uninitialized -/// memory is involved. -/// -/// ``` -/// #[derive(Debug, Default, Copy, Clone)] -/// #[repr(C, packed)] -/// struct S { -/// aligned: u8, -/// unaligned: u32, -/// } -/// let s = S::default(); -/// let p = std::ptr::addr_of!(s.unaligned); // not allowed with coercion -/// ``` -/// -/// ## 4. Get it from C. -/// -/// ``` -/// # #![feature(rustc_private)] -/// #[allow(unused_extern_crates)] -/// extern crate libc; -/// -/// use std::mem; -/// -/// unsafe { -/// let my_num: *mut i32 = libc::malloc(mem::size_of::()) as *mut i32; -/// if my_num.is_null() { -/// panic!("failed to allocate memory"); -/// } -/// libc::free(my_num as *mut libc::c_void); -/// } -/// ``` -/// -/// Usually you wouldn't literally use `malloc` and `free` from Rust, -/// but C APIs hand out a lot of pointers generally, so are a common source -/// of raw pointers in Rust. -/// -/// [`null`]: ptr::null -/// [`null_mut`]: ptr::null_mut -/// [`is_null`]: pointer::is_null -/// [`offset`]: pointer::offset -#[doc = concat!("[`into_raw`]: ", include_str!("../primitive_docs/box_into_raw.md"))] -/// [`write`]: ptr::write -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_pointer {} - -#[rustc_doc_primitive = "array"] -#[doc(alias = "[]")] -#[doc(alias = "[T;N]")] // unfortunately, rustdoc doesn't have fuzzy search for aliases -#[doc(alias = "[T; N]")] -/// A fixed-size array, denoted `[T; N]`, for the element type, `T`, and the -/// non-negative compile-time constant size, `N`. -/// -/// There are two syntactic forms for creating an array: -/// -/// * A list with each element, i.e., `[x, y, z]`. -/// * A repeat expression `[expr; N]` where `N` is how many times to repeat `expr` in the array. `expr` must either be: -/// -/// * A value of a type implementing the [`Copy`] trait -/// * A `const` value -/// -/// Note that `[expr; 0]` is allowed, and produces an empty array. -/// This will still evaluate `expr`, however, and immediately drop the resulting value, so -/// be mindful of side effects. -/// -/// Arrays of *any* size implement the following traits if the element type allows it: -/// -/// - [`Copy`] -/// - [`Clone`] -/// - [`Debug`] -/// - [`IntoIterator`] (implemented for `[T; N]`, `&[T; N]` and `&mut [T; N]`) -/// - [`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] -/// - [`Hash`] -/// - [`AsRef`], [`AsMut`] -/// - [`Borrow`], [`BorrowMut`] -/// -/// Arrays of sizes from 0 to 32 (inclusive) implement the [`Default`] trait -/// if the element type allows it. As a stopgap, trait implementations are -/// statically generated up to size 32. -/// -/// Arrays of sizes from 1 to 12 (inclusive) implement [`From`], where `Tuple` -/// is a homogeneous [prim@tuple] of appropriate length. -/// -/// Arrays coerce to [slices (`[T]`)][slice], so a slice method may be called on -/// an array. Indeed, this provides most of the API for working with arrays. -/// -/// Slices have a dynamic size and do not coerce to arrays. Instead, use -/// `slice.try_into().unwrap()` or `::try_from(slice).unwrap()`. -/// -/// Array's `try_from(slice)` implementations (and the corresponding `slice.try_into()` -/// array implementations) succeed if the input slice length is the same as the result -/// array length. They optimize especially well when the optimizer can easily determine -/// the slice length, e.g. `<[u8; 4]>::try_from(&slice[4..8]).unwrap()`. Array implements -/// [TryFrom](crate::convert::TryFrom) returning: -/// -/// - `[T; N]` copies from the slice's elements -/// - `&[T; N]` references the original slice's elements -/// - `&mut [T; N]` references the original slice's elements -/// -/// You can move elements out of an array with a [slice pattern]. If you want -/// one element, see [`mem::replace`]. -/// -/// # Examples -/// -/// ``` -/// let mut array: [i32; 3] = [0; 3]; -/// -/// array[1] = 1; -/// array[2] = 2; -/// -/// assert_eq!([1, 2], &array[1..]); -/// -/// // This loop prints: 0 1 2 -/// for x in array { -/// print!("{x} "); -/// } -/// ``` -/// -/// You can also iterate over reference to the array's elements: -/// -/// ``` -/// let array: [i32; 3] = [0; 3]; -/// -/// for x in &array { } -/// ``` -/// -/// You can use `::try_from(slice)` or `slice.try_into()` to get an array from -/// a slice: -/// -/// ``` -/// let bytes: [u8; 3] = [1, 0, 2]; -/// assert_eq!(1, u16::from_le_bytes(<[u8; 2]>::try_from(&bytes[0..2]).unwrap())); -/// assert_eq!(512, u16::from_le_bytes(bytes[1..3].try_into().unwrap())); -/// ``` -/// -/// You can use a [slice pattern] to move elements out of an array: -/// -/// ``` -/// fn move_away(_: String) { /* Do interesting things. */ } -/// -/// let [john, roa] = ["John".to_string(), "Roa".to_string()]; -/// move_away(john); -/// move_away(roa); -/// ``` -/// -/// Arrays can be created from homogeneous tuples of appropriate length: -/// -/// ``` -/// let tuple: (u32, u32, u32) = (1, 2, 3); -/// let array: [u32; 3] = tuple.into(); -/// ``` -/// -/// # Editions -/// -/// Prior to Rust 1.53, arrays did not implement [`IntoIterator`] by value, so the method call -/// `array.into_iter()` auto-referenced into a [slice iterator](slice::iter). Right now, the old -/// behavior is preserved in the 2015 and 2018 editions of Rust for compatibility, ignoring -/// [`IntoIterator`] by value. In the future, the behavior on the 2015 and 2018 edition -/// might be made consistent to the behavior of later editions. -/// -/// ```rust,edition2018 -/// // Rust 2015 and 2018: -/// -/// # #![allow(array_into_iter)] // override our `deny(warnings)` -/// let array: [i32; 3] = [0; 3]; -/// -/// // This creates a slice iterator, producing references to each value. -/// for item in array.into_iter().enumerate() { -/// let (i, x): (usize, &i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// -/// // The `array_into_iter` lint suggests this change for future compatibility: -/// for item in array.iter().enumerate() { -/// let (i, x): (usize, &i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// -/// // You can explicitly iterate an array by value using `IntoIterator::into_iter` -/// for item in IntoIterator::into_iter(array).enumerate() { -/// let (i, x): (usize, i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// ``` -/// -/// Starting in the 2021 edition, `array.into_iter()` uses `IntoIterator` normally to iterate -/// by value, and `iter()` should be used to iterate by reference like previous editions. -/// -/// ```rust,edition2021 -/// // Rust 2021: -/// -/// let array: [i32; 3] = [0; 3]; -/// -/// // This iterates by reference: -/// for item in array.iter().enumerate() { -/// let (i, x): (usize, &i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// -/// // This iterates by value: -/// for item in array.into_iter().enumerate() { -/// let (i, x): (usize, i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// ``` -/// -/// Future language versions might start treating the `array.into_iter()` -/// syntax on editions 2015 and 2018 the same as on edition 2021. So code using -/// those older editions should still be written with this change in mind, to -/// prevent breakage in the future. The safest way to accomplish this is to -/// avoid the `into_iter` syntax on those editions. If an edition update is not -/// viable/desired, there are multiple alternatives: -/// * use `iter`, equivalent to the old behavior, creating references -/// * use [`IntoIterator::into_iter`], equivalent to the post-2021 behavior (Rust 1.53+) -/// * replace `for ... in array.into_iter() {` with `for ... in array {`, -/// equivalent to the post-2021 behavior (Rust 1.53+) -/// -/// ```rust,edition2018 -/// // Rust 2015 and 2018: -/// -/// let array: [i32; 3] = [0; 3]; -/// -/// // This iterates by reference: -/// for item in array.iter() { -/// let x: &i32 = item; -/// println!("{x}"); -/// } -/// -/// // This iterates by value: -/// for item in IntoIterator::into_iter(array) { -/// let x: i32 = item; -/// println!("{x}"); -/// } -/// -/// // This iterates by value: -/// for item in array { -/// let x: i32 = item; -/// println!("{x}"); -/// } -/// -/// // IntoIter can also start a chain. -/// // This iterates by value: -/// for item in IntoIterator::into_iter(array).enumerate() { -/// let (i, x): (usize, i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// ``` -/// -/// [slice]: prim@slice -/// [`Debug`]: fmt::Debug -/// [`Hash`]: hash::Hash -/// [`Borrow`]: borrow::Borrow -/// [`BorrowMut`]: borrow::BorrowMut -/// [slice pattern]: ../reference/patterns.html#slice-patterns -/// [`From`]: convert::From -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_array {} - -#[rustc_doc_primitive = "slice"] -#[doc(alias = "[")] -#[doc(alias = "]")] -#[doc(alias = "[]")] -/// A dynamically-sized view into a contiguous sequence, `[T]`. Contiguous here -/// means that elements are laid out so that every element is the same -/// distance from its neighbors. -/// -/// *[See also the `std::slice` module](crate::slice).* -/// -/// Slices are a view into a block of memory represented as a pointer and a -/// length. -/// -/// ``` -/// // slicing a Vec -/// let vec = vec![1, 2, 3]; -/// let int_slice = &vec[..]; -/// // coercing an array to a slice -/// let str_slice: &[&str] = &["one", "two", "three"]; -/// ``` -/// -/// Slices are either mutable or shared. The shared slice type is `&[T]`, -/// while the mutable slice type is `&mut [T]`, where `T` represents the element -/// type. For example, you can mutate the block of memory that a mutable slice -/// points to: -/// -/// ``` -/// let mut x = [1, 2, 3]; -/// let x = &mut x[..]; // Take a full slice of `x`. -/// x[1] = 7; -/// assert_eq!(x, &[1, 7, 3]); -/// ``` -/// -/// As slices store the length of the sequence they refer to, they have twice -/// the size of pointers to [`Sized`](marker/trait.Sized.html) types. -/// Also see the reference on -/// [dynamically sized types](../reference/dynamically-sized-types.html). -/// -/// ``` -/// # use std::rc::Rc; -/// let pointer_size = std::mem::size_of::<&u8>(); -/// assert_eq!(2 * pointer_size, std::mem::size_of::<&[u8]>()); -/// assert_eq!(2 * pointer_size, std::mem::size_of::<*const [u8]>()); -/// assert_eq!(2 * pointer_size, std::mem::size_of::>()); -/// assert_eq!(2 * pointer_size, std::mem::size_of::>()); -/// ``` -/// -/// ## Trait Implementations -/// -/// Some traits are implemented for slices if the element type implements -/// that trait. This includes [`Eq`], [`Hash`] and [`Ord`]. -/// -/// ## Iteration -/// -/// The slices implement `IntoIterator`. The iterator yields references to the -/// slice elements. -/// -/// ``` -/// let numbers: &[i32] = &[0, 1, 2]; -/// for n in numbers { -/// println!("{n} is a number!"); -/// } -/// ``` -/// -/// The mutable slice yields mutable references to the elements: -/// -/// ``` -/// let mut scores: &mut [i32] = &mut [7, 8, 9]; -/// for score in scores { -/// *score += 1; -/// } -/// ``` -/// -/// This iterator yields mutable references to the slice's elements, so while -/// the element type of the slice is `i32`, the element type of the iterator is -/// `&mut i32`. -/// -/// * [`.iter`] and [`.iter_mut`] are the explicit methods to return the default -/// iterators. -/// * Further methods that return iterators are [`.split`], [`.splitn`], -/// [`.chunks`], [`.windows`] and more. -/// -/// [`Hash`]: core::hash::Hash -/// [`.iter`]: slice::iter -/// [`.iter_mut`]: slice::iter_mut -/// [`.split`]: slice::split -/// [`.splitn`]: slice::splitn -/// [`.chunks`]: slice::chunks -/// [`.windows`]: slice::windows -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_slice {} - -#[rustc_doc_primitive = "str"] -/// String slices. -/// -/// *[See also the `std::str` module](crate::str).* -/// -/// The `str` type, also called a 'string slice', is the most primitive string -/// type. It is usually seen in its borrowed form, `&str`. It is also the type -/// of string literals, `&'static str`. -/// -/// String slices are always valid UTF-8. -/// -/// # Basic Usage -/// -/// String literals are string slices: -/// -/// ``` -/// let hello_world = "Hello, World!"; -/// ``` -/// -/// Here we have declared a string slice initialized with a string literal. -/// String literals have a static lifetime, which means the string `hello_world` -/// is guaranteed to be valid for the duration of the entire program. -/// We can explicitly specify `hello_world`'s lifetime as well: -/// -/// ``` -/// let hello_world: &'static str = "Hello, world!"; -/// ``` -/// -/// # Representation -/// -/// A `&str` is made up of two components: a pointer to some bytes, and a -/// length. You can look at these with the [`as_ptr`] and [`len`] methods: -/// -/// ``` -/// use std::slice; -/// use std::str; -/// -/// let story = "Once upon a time..."; -/// -/// let ptr = story.as_ptr(); -/// let len = story.len(); -/// -/// // story has nineteen bytes -/// assert_eq!(19, len); -/// -/// // We can re-build a str out of ptr and len. This is all unsafe because -/// // we are responsible for making sure the two components are valid: -/// let s = unsafe { -/// // First, we build a &[u8]... -/// let slice = slice::from_raw_parts(ptr, len); -/// -/// // ... and then convert that slice into a string slice -/// str::from_utf8(slice) -/// }; -/// -/// assert_eq!(s, Ok(story)); -/// ``` -/// -/// [`as_ptr`]: str::as_ptr -/// [`len`]: str::len -/// -/// Note: This example shows the internals of `&str`. `unsafe` should not be -/// used to get a string slice under normal circumstances. Use `as_str` -/// instead. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_str {} - -#[rustc_doc_primitive = "tuple"] -#[doc(alias = "(")] -#[doc(alias = ")")] -#[doc(alias = "()")] -// -/// A finite heterogeneous sequence, `(T, U, ..)`. -/// -/// Let's cover each of those in turn: -/// -/// Tuples are *finite*. In other words, a tuple has a length. Here's a tuple -/// of length `3`: -/// -/// ``` -/// ("hello", 5, 'c'); -/// ``` -/// -/// 'Length' is also sometimes called 'arity' here; each tuple of a different -/// length is a different, distinct type. -/// -/// Tuples are *heterogeneous*. This means that each element of the tuple can -/// have a different type. In that tuple above, it has the type: -/// -/// ``` -/// # let _: -/// (&'static str, i32, char) -/// # = ("hello", 5, 'c'); -/// ``` -/// -/// Tuples are a *sequence*. This means that they can be accessed by position; -/// this is called 'tuple indexing', and it looks like this: -/// -/// ```rust -/// let tuple = ("hello", 5, 'c'); -/// -/// assert_eq!(tuple.0, "hello"); -/// assert_eq!(tuple.1, 5); -/// assert_eq!(tuple.2, 'c'); -/// ``` -/// -/// The sequential nature of the tuple applies to its implementations of various -/// traits. For example, in [`PartialOrd`] and [`Ord`], the elements are compared -/// sequentially until the first non-equal set is found. -/// -/// For more about tuples, see [the book](../book/ch03-02-data-types.html#the-tuple-type). -/// -// Hardcoded anchor in src/librustdoc/html/format.rs -// linked to as `#trait-implementations-1` -/// # Trait implementations -/// -/// In this documentation the shorthand `(T₁, T₂, …, Tₙ)` is used to represent tuples of varying -/// length. When that is used, any trait bound expressed on `T` applies to each element of the -/// tuple independently. Note that this is a convenience notation to avoid repetitive -/// documentation, not valid Rust syntax. -/// -/// Due to a temporary restriction in Rust’s type system, the following traits are only -/// implemented on tuples of arity 12 or less. In the future, this may change: -/// -/// * [`PartialEq`] -/// * [`Eq`] -/// * [`PartialOrd`] -/// * [`Ord`] -/// * [`Debug`] -/// * [`Default`] -/// * [`Hash`] -/// * [`From<[T; N]>`][from] -/// -/// [from]: convert::From -/// [`Debug`]: fmt::Debug -/// [`Hash`]: hash::Hash -/// -/// The following traits are implemented for tuples of any length. These traits have -/// implementations that are automatically generated by the compiler, so are not limited by -/// missing language features. -/// -/// * [`Clone`] -/// * [`Copy`] -/// * [`Send`] -/// * [`Sync`] -/// * [`Unpin`] -/// * [`UnwindSafe`] -/// * [`RefUnwindSafe`] -/// -/// [`UnwindSafe`]: panic::UnwindSafe -/// [`RefUnwindSafe`]: panic::RefUnwindSafe -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let tuple = ("hello", 5, 'c'); -/// -/// assert_eq!(tuple.0, "hello"); -/// ``` -/// -/// Tuples are often used as a return type when you want to return more than -/// one value: -/// -/// ``` -/// fn calculate_point() -> (i32, i32) { -/// // Don't do a calculation, that's not the point of the example -/// (4, 5) -/// } -/// -/// let point = calculate_point(); -/// -/// assert_eq!(point.0, 4); -/// assert_eq!(point.1, 5); -/// -/// // Combining this with patterns can be nicer. -/// -/// let (x, y) = calculate_point(); -/// -/// assert_eq!(x, 4); -/// assert_eq!(y, 5); -/// ``` -/// -/// Homogeneous tuples can be created from arrays of appropriate length: -/// -/// ``` -/// let array: [u32; 3] = [1, 2, 3]; -/// let tuple: (u32, u32, u32) = array.into(); -/// ``` -/// -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_tuple {} - -// Required to make auto trait impls render. -// See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls -#[doc(hidden)] -impl (T,) {} - -// Fake impl that's only really used for docs. -#[cfg(doc)] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(fake_variadic)] -/// This trait is implemented on arbitrary-length tuples. -impl Clone for (T,) { - fn clone(&self) -> Self { - loop {} - } -} - -// Fake impl that's only really used for docs. -#[cfg(doc)] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(fake_variadic)] -/// This trait is implemented on arbitrary-length tuples. -impl Copy for (T,) { - // empty -} - -#[rustc_doc_primitive = "f32"] -/// A 32-bit floating point type (specifically, the "binary32" type defined in IEEE 754-2008). -/// -/// This type can represent a wide range of decimal numbers, like `3.5`, `27`, -/// `-113.75`, `0.0078125`, `34359738368`, `0`, `-1`. So unlike integer types -/// (such as `i32`), floating point types can represent non-integer numbers, -/// too. -/// -/// However, being able to represent this wide range of numbers comes at the -/// cost of precision: floats can only represent some of the real numbers and -/// calculation with floats round to a nearby representable number. For example, -/// `5.0` and `1.0` can be exactly represented as `f32`, but `1.0 / 5.0` results -/// in `0.20000000298023223876953125` since `0.2` cannot be exactly represented -/// as `f32`. Note, however, that printing floats with `println` and friends will -/// often discard insignificant digits: `println!("{}", 1.0f32 / 5.0f32)` will -/// print `0.2`. -/// -/// Additionally, `f32` can represent some special values: -/// -/// - −0.0: IEEE 754 floating point numbers have a bit that indicates their sign, so −0.0 is a -/// possible value. For comparison −0.0 = +0.0, but floating point operations can carry -/// the sign bit through arithmetic operations. This means −0.0 × +0.0 produces −0.0 and -/// a negative number rounded to a value smaller than a float can represent also produces −0.0. -/// - [∞](#associatedconstant.INFINITY) and -/// [−∞](#associatedconstant.NEG_INFINITY): these result from calculations -/// like `1.0 / 0.0`. -/// - [NaN (not a number)](#associatedconstant.NAN): this value results from -/// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected -/// behavior: -/// - It is not equal to any float, including itself! This is the reason `f32` -/// doesn't implement the `Eq` trait. -/// - It is also neither smaller nor greater than any float, making it -/// impossible to sort by the default comparison operation, which is the -/// reason `f32` doesn't implement the `Ord` trait. -/// - It is also considered *infectious* as almost all calculations where one -/// of the operands is NaN will also result in NaN. The explanations on this -/// page only explicitly document behavior on NaN operands if this default -/// is deviated from. -/// - Lastly, there are multiple bit patterns that are considered NaN. -/// Rust does not currently guarantee that the bit patterns of NaN are -/// preserved over arithmetic operations, and they are not guaranteed to be -/// portable or even fully deterministic! This means that there may be some -/// surprising results upon inspecting the bit patterns, -/// as the same calculations might produce NaNs with different bit patterns. -/// -/// When the number resulting from a primitive operation (addition, -/// subtraction, multiplication, or division) on this type is not exactly -/// representable as `f32`, it is rounded according to the roundTiesToEven -/// direction defined in IEEE 754-2008. That means: -/// -/// - The result is the representable value closest to the true value, if there -/// is a unique closest representable value. -/// - If the true value is exactly half-way between two representable values, -/// the result is the one with an even least-significant binary digit. -/// - If the true value's magnitude is ≥ `f32::MAX` + 2(`f32::MAX_EXP` − -/// `f32::MANTISSA_DIGITS` − 1), the result is ∞ or −∞ (preserving the -/// true value's sign). -/// -/// For more information on floating point numbers, see [Wikipedia][wikipedia]. -/// -/// *[See also the `std::f32::consts` module](crate::f32::consts).* -/// -/// [wikipedia]: https://en.wikipedia.org/wiki/Single-precision_floating-point_format -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_f32 {} - -#[rustc_doc_primitive = "f64"] -/// A 64-bit floating point type (specifically, the "binary64" type defined in IEEE 754-2008). -/// -/// This type is very similar to [`f32`], but has increased -/// precision by using twice as many bits. Please see [the documentation for -/// `f32`][`f32`] or [Wikipedia on double precision -/// values][wikipedia] for more information. -/// -/// *[See also the `std::f64::consts` module](crate::f64::consts).* -/// -/// [`f32`]: prim@f32 -/// [wikipedia]: https://en.wikipedia.org/wiki/Double-precision_floating-point_format -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_f64 {} - -#[rustc_doc_primitive = "i8"] -// -/// The 8-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i8 {} - -#[rustc_doc_primitive = "i16"] -// -/// The 16-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i16 {} - -#[rustc_doc_primitive = "i32"] -// -/// The 32-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i32 {} - -#[rustc_doc_primitive = "i64"] -// -/// The 64-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i64 {} - -#[rustc_doc_primitive = "i128"] -// -/// The 128-bit signed integer type. -#[stable(feature = "i128", since = "1.26.0")] -mod prim_i128 {} - -#[rustc_doc_primitive = "u8"] -// -/// The 8-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u8 {} - -#[rustc_doc_primitive = "u16"] -// -/// The 16-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u16 {} - -#[rustc_doc_primitive = "u32"] -// -/// The 32-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u32 {} - -#[rustc_doc_primitive = "u64"] -// -/// The 64-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u64 {} - -#[rustc_doc_primitive = "u128"] -// -/// The 128-bit unsigned integer type. -#[stable(feature = "i128", since = "1.26.0")] -mod prim_u128 {} - -#[rustc_doc_primitive = "isize"] -// -/// The pointer-sized signed integer type. -/// -/// The size of this primitive is how many bytes it takes to reference any -/// location in memory. For example, on a 32 bit target, this is 4 bytes -/// and on a 64 bit target, this is 8 bytes. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_isize {} - -#[rustc_doc_primitive = "usize"] -// -/// The pointer-sized unsigned integer type. -/// -/// The size of this primitive is how many bytes it takes to reference any -/// location in memory. For example, on a 32 bit target, this is 4 bytes -/// and on a 64 bit target, this is 8 bytes. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_usize {} - -#[rustc_doc_primitive = "reference"] -#[doc(alias = "&")] -#[doc(alias = "&mut")] -// -/// References, `&T` and `&mut T`. -/// -/// A reference represents a borrow of some owned value. You can get one by using the `&` or `&mut` -/// operators on a value, or by using a [`ref`](../std/keyword.ref.html) or -/// [ref](../std/keyword.ref.html) [mut](../std/keyword.mut.html) pattern. -/// -/// For those familiar with pointers, a reference is just a pointer that is assumed to be -/// aligned, not null, and pointing to memory containing a valid value of `T` - for example, -/// &[bool] can only point to an allocation containing the integer values `1` -/// ([`true`](../std/keyword.true.html)) or `0` ([`false`](../std/keyword.false.html)), but -/// creating a &[bool] that points to an allocation containing -/// the value `3` causes undefined behaviour. -/// In fact, [Option]\<&T> has the same memory representation as a -/// nullable but aligned pointer, and can be passed across FFI boundaries as such. -/// -/// In most cases, references can be used much like the original value. Field access, method -/// calling, and indexing work the same (save for mutability rules, of course). In addition, the -/// comparison operators transparently defer to the referent's implementation, allowing references -/// to be compared the same as owned values. -/// -/// References have a lifetime attached to them, which represents the scope for which the borrow is -/// valid. A lifetime is said to "outlive" another one if its representative scope is as long or -/// longer than the other. The `'static` lifetime is the longest lifetime, which represents the -/// total life of the program. For example, string literals have a `'static` lifetime because the -/// text data is embedded into the binary of the program, rather than in an allocation that needs -/// to be dynamically managed. -/// -/// `&mut T` references can be freely coerced into `&T` references with the same referent type, and -/// references with longer lifetimes can be freely coerced into references with shorter ones. -/// -/// Reference equality by address, instead of comparing the values pointed to, is accomplished via -/// implicit reference-pointer coercion and raw pointer equality via [`ptr::eq`], while -/// [`PartialEq`] compares values. -/// -/// ``` -/// use std::ptr; -/// -/// let five = 5; -/// let other_five = 5; -/// let five_ref = &five; -/// let same_five_ref = &five; -/// let other_five_ref = &other_five; -/// -/// assert!(five_ref == same_five_ref); -/// assert!(five_ref == other_five_ref); -/// -/// assert!(ptr::eq(five_ref, same_five_ref)); -/// assert!(!ptr::eq(five_ref, other_five_ref)); -/// ``` -/// -/// For more information on how to use references, see [the book's section on "References and -/// Borrowing"][book-refs]. -/// -/// [book-refs]: ../book/ch04-02-references-and-borrowing.html -/// -/// # Trait implementations -/// -/// The following traits are implemented for all `&T`, regardless of the type of its referent: -/// -/// * [`Copy`] -/// * [`Clone`] \(Note that this will not defer to `T`'s `Clone` implementation if it exists!) -/// * [`Deref`] -/// * [`Borrow`] -/// * [`fmt::Pointer`] -/// -/// [`Deref`]: ops::Deref -/// [`Borrow`]: borrow::Borrow -/// -/// `&mut T` references get all of the above except `Copy` and `Clone` (to prevent creating -/// multiple simultaneous mutable borrows), plus the following, regardless of the type of its -/// referent: -/// -/// * [`DerefMut`] -/// * [`BorrowMut`] -/// -/// [`DerefMut`]: ops::DerefMut -/// [`BorrowMut`]: borrow::BorrowMut -/// [bool]: prim@bool -/// -/// The following traits are implemented on `&T` references if the underlying `T` also implements -/// that trait: -/// -/// * All the traits in [`std::fmt`] except [`fmt::Pointer`] (which is implemented regardless of the type of its referent) and [`fmt::Write`] -/// * [`PartialOrd`] -/// * [`Ord`] -/// * [`PartialEq`] -/// * [`Eq`] -/// * [`AsRef`] -/// * [`Fn`] \(in addition, `&T` references get [`FnMut`] and [`FnOnce`] if `T: Fn`) -/// * [`Hash`] -/// * [`ToSocketAddrs`] -/// * [`Send`] \(`&T` references also require T: [Sync]) -/// * [`Sync`] -/// -/// [`std::fmt`]: fmt -/// [`Hash`]: hash::Hash -#[doc = concat!("[`ToSocketAddrs`]: ", include_str!("../primitive_docs/net_tosocketaddrs.md"))] -/// -/// `&mut T` references get all of the above except `ToSocketAddrs`, plus the following, if `T` -/// implements that trait: -/// -/// * [`AsMut`] -/// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if `T: FnMut`) -/// * [`fmt::Write`] -/// * [`Iterator`] -/// * [`DoubleEndedIterator`] -/// * [`ExactSizeIterator`] -/// * [`FusedIterator`] -/// * [`TrustedLen`] -/// * [`io::Write`] -/// * [`Read`] -/// * [`Seek`] -/// * [`BufRead`] -/// -/// [`FusedIterator`]: iter::FusedIterator -/// [`TrustedLen`]: iter::TrustedLen -#[doc = concat!("[`Seek`]: ", include_str!("../primitive_docs/io_seek.md"))] -#[doc = concat!("[`BufRead`]: ", include_str!("../primitive_docs/io_bufread.md"))] -#[doc = concat!("[`Read`]: ", include_str!("../primitive_docs/io_read.md"))] -#[doc = concat!("[`io::Write`]: ", include_str!("../primitive_docs/io_write.md"))] -/// -/// Note that due to method call deref coercion, simply calling a trait method will act like they -/// work on references as well as they do on owned values! The implementations described here are -/// meant for generic contexts, where the final type `T` is a type parameter or otherwise not -/// locally known. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_ref {} - -#[rustc_doc_primitive = "fn"] -// -/// Function pointers, like `fn(usize) -> bool`. -/// -/// *See also the traits [`Fn`], [`FnMut`], and [`FnOnce`].* -/// -/// Function pointers are pointers that point to *code*, not data. They can be called -/// just like functions. Like references, function pointers are, among other things, assumed to -/// not be null, so if you want to pass a function pointer over FFI and be able to accommodate null -/// pointers, make your type [`Option`](core::option#options-and-pointers-nullable-pointers) -/// with your required signature. -/// -/// ### Safety -/// -/// Plain function pointers are obtained by casting either plain functions, or closures that don't -/// capture an environment: -/// -/// ``` -/// fn add_one(x: usize) -> usize { -/// x + 1 -/// } -/// -/// let ptr: fn(usize) -> usize = add_one; -/// assert_eq!(ptr(5), 6); -/// -/// let clos: fn(usize) -> usize = |x| x + 5; -/// assert_eq!(clos(5), 10); -/// ``` -/// -/// In addition to varying based on their signature, function pointers come in two flavors: safe -/// and unsafe. Plain `fn()` function pointers can only point to safe functions, -/// while `unsafe fn()` function pointers can point to safe or unsafe functions. -/// -/// ``` -/// fn add_one(x: usize) -> usize { -/// x + 1 -/// } -/// -/// unsafe fn add_one_unsafely(x: usize) -> usize { -/// x + 1 -/// } -/// -/// let safe_ptr: fn(usize) -> usize = add_one; -/// -/// //ERROR: mismatched types: expected normal fn, found unsafe fn -/// //let bad_ptr: fn(usize) -> usize = add_one_unsafely; -/// -/// let unsafe_ptr: unsafe fn(usize) -> usize = add_one_unsafely; -/// let really_safe_ptr: unsafe fn(usize) -> usize = add_one; -/// ``` -/// -/// ### ABI -/// -/// On top of that, function pointers can vary based on what ABI they use. This -/// is achieved by adding the `extern` keyword before the type, followed by the -/// ABI in question. The default ABI is "Rust", i.e., `fn()` is the exact same -/// type as `extern "Rust" fn()`. A pointer to a function with C ABI would have -/// type `extern "C" fn()`. -/// -/// `extern "ABI" { ... }` blocks declare functions with ABI "ABI". The default -/// here is "C", i.e., functions declared in an `extern {...}` block have "C" -/// ABI. -/// -/// For more information and a list of supported ABIs, see [the nomicon's -/// section on foreign calling conventions][nomicon-abi]. -/// -/// [nomicon-abi]: ../nomicon/ffi.html#foreign-calling-conventions -/// -/// ### Variadic functions -/// -/// Extern function declarations with the "C" or "cdecl" ABIs can also be *variadic*, allowing them -/// to be called with a variable number of arguments. Normal Rust functions, even those with an -/// `extern "ABI"`, cannot be variadic. For more information, see [the nomicon's section on -/// variadic functions][nomicon-variadic]. -/// -/// [nomicon-variadic]: ../nomicon/ffi.html#variadic-functions -/// -/// ### Creating function pointers -/// -/// When `bar` is the name of a function, then the expression `bar` is *not* a -/// function pointer. Rather, it denotes a value of an unnameable type that -/// uniquely identifies the function `bar`. The value is zero-sized because the -/// type already identifies the function. This has the advantage that "calling" -/// the value (it implements the `Fn*` traits) does not require dynamic -/// dispatch. -/// -/// This zero-sized type *coerces* to a regular function pointer. For example: -/// -/// ```rust -/// use std::mem; -/// -/// fn bar(x: i32) {} -/// -/// let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar` -/// assert_eq!(mem::size_of_val(¬_bar_ptr), 0); -/// -/// let bar_ptr: fn(i32) = not_bar_ptr; // force coercion to function pointer -/// assert_eq!(mem::size_of_val(&bar_ptr), mem::size_of::()); -/// -/// let footgun = &bar; // this is a shared reference to the zero-sized type identifying `bar` -/// ``` -/// -/// The last line shows that `&bar` is not a function pointer either. Rather, it -/// is a reference to the function-specific ZST. `&bar` is basically never what you -/// want when `bar` is a function. -/// -/// ### Casting to and from integers -/// -/// You cast function pointers directly to integers: -/// -/// ```rust -/// let fnptr: fn(i32) -> i32 = |x| x+2; -/// let fnptr_addr = fnptr as usize; -/// ``` -/// -/// However, a direct cast back is not possible. You need to use `transmute`: -/// -/// ```rust -/// # #[cfg(not(miri))] { // FIXME: use strict provenance APIs once they are stable, then remove this `cfg` -/// # let fnptr: fn(i32) -> i32 = |x| x+2; -/// # let fnptr_addr = fnptr as usize; -/// let fnptr = fnptr_addr as *const (); -/// let fnptr: fn(i32) -> i32 = unsafe { std::mem::transmute(fnptr) }; -/// assert_eq!(fnptr(40), 42); -/// # } -/// ``` -/// -/// Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer. -/// This avoids an integer-to-pointer `transmute`, which can be problematic. -/// Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine. -/// -/// Note that all of this is not portable to platforms where function pointers and data pointers -/// have different sizes. -/// -/// ### Trait implementations -/// -/// In this documentation the shorthand `fn (T₁, T₂, …, Tₙ)` is used to represent non-variadic -/// function pointers of varying length. Note that this is a convenience notation to avoid -/// repetitive documentation, not valid Rust syntax. -/// -/// Due to a temporary restriction in Rust's type system, these traits are only implemented on -/// functions that take 12 arguments or less, with the `"Rust"` and `"C"` ABIs. In the future, this -/// may change: -/// -/// * [`PartialEq`] -/// * [`Eq`] -/// * [`PartialOrd`] -/// * [`Ord`] -/// * [`Hash`] -/// * [`Pointer`] -/// * [`Debug`] -/// -/// The following traits are implemented for function pointers with any number of arguments and -/// any ABI. These traits have implementations that are automatically generated by the compiler, -/// so are not limited by missing language features: -/// -/// * [`Clone`] -/// * [`Copy`] -/// * [`Send`] -/// * [`Sync`] -/// * [`Unpin`] -/// * [`UnwindSafe`] -/// * [`RefUnwindSafe`] -/// -/// [`Hash`]: hash::Hash -/// [`Pointer`]: fmt::Pointer -/// [`UnwindSafe`]: panic::UnwindSafe -/// [`RefUnwindSafe`]: panic::RefUnwindSafe -/// -/// In addition, all *safe* function pointers implement [`Fn`], [`FnMut`], and [`FnOnce`], because -/// these traits are specially known to the compiler. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_fn {} - -// Required to make auto trait impls render. -// See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls -#[doc(hidden)] -impl fn(T) -> Ret {} - -// Fake impl that's only really used for docs. -#[cfg(doc)] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(fake_variadic)] -/// This trait is implemented on function pointers with any number of arguments. -impl Clone for fn(T) -> Ret { - fn clone(&self) -> Self { - loop {} - } -} - -// Fake impl that's only really used for docs. -#[cfg(doc)] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(fake_variadic)] -/// This trait is implemented on function pointers with any number of arguments. -impl Copy for fn(T) -> Ret { - // empty -} diff --git a/src/ci/github-actions/ci.yml b/src/ci/github-actions/ci.yml index 1712d65ece971..973b9a0a089b8 100644 --- a/src/ci/github-actions/ci.yml +++ b/src/ci/github-actions/ci.yml @@ -114,7 +114,7 @@ x--expand-yaml-anchors--remove: run: git config --global core.autocrlf false - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 2 @@ -707,7 +707,7 @@ jobs: if: github.event_name == 'push' && github.ref == 'refs/heads/master' && github.repository == 'rust-lang-ci/rust' steps: - name: checkout the source code - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: fetch-depth: 2 diff --git a/src/tools/tidy/src/lib.rs b/src/tools/tidy/src/lib.rs index ca160017202a4..fc69c1432227e 100644 --- a/src/tools/tidy/src/lib.rs +++ b/src/tools/tidy/src/lib.rs @@ -63,7 +63,6 @@ pub mod features; pub mod fluent_alphabetical; pub mod mir_opt_tests; pub mod pal; -pub mod primitive_docs; pub mod rustdoc_css_themes; pub mod rustdoc_gui_tests; pub mod style; diff --git a/src/tools/tidy/src/main.rs b/src/tools/tidy/src/main.rs index 5585e125f2d92..80e58ba00fc2f 100644 --- a/src/tools/tidy/src/main.rs +++ b/src/tools/tidy/src/main.rs @@ -112,7 +112,6 @@ fn main() { // Checks that only make sense for the std libs. check!(pal, &library_path); - check!(primitive_docs, &library_path); // Checks that need to be done for both the compiler and std libraries. check!(unit_tests, &src_path); diff --git a/src/tools/tidy/src/primitive_docs.rs b/src/tools/tidy/src/primitive_docs.rs deleted file mode 100644 index f3200e0afd71a..0000000000000 --- a/src/tools/tidy/src/primitive_docs.rs +++ /dev/null @@ -1,17 +0,0 @@ -//! Tidy check to make sure `library/{std,core}/src/primitive_docs.rs` are the same file. These are -//! different files so that relative links work properly without having to have `CARGO_PKG_NAME` -//! set, but conceptually they should always be the same. - -use std::path::Path; - -pub fn check(library_path: &Path, bad: &mut bool) { - let std_name = "std/src/primitive_docs.rs"; - let core_name = "core/src/primitive_docs.rs"; - let std_contents = std::fs::read_to_string(library_path.join(std_name)) - .unwrap_or_else(|e| panic!("failed to read library/{std_name}: {e}")); - let core_contents = std::fs::read_to_string(library_path.join(core_name)) - .unwrap_or_else(|e| panic!("failed to read library/{core_name}: {e}")); - if std_contents != core_contents { - tidy_error!(bad, "library/{core_name} and library/{std_name} have different contents"); - } -} diff --git a/triagebot.toml b/triagebot.toml index d35e81c277ea2..5b4e653b10048 100644 --- a/triagebot.toml +++ b/triagebot.toml @@ -621,6 +621,7 @@ bootstrap = [ ] infra-ci = [ "@Mark-Simulacrum", + "@Kobzol", ] rustdoc = [ "@jsha",