From 2a242c5d4b9206cdd0c9fd6e1d2e5b4241326b39 Mon Sep 17 00:00:00 2001 From: Waffle Lapkin Date: Sun, 5 Jan 2025 16:26:44 +0100 Subject: [PATCH 1/2] refactor unsizing coercion documentation The old one was quite confusing and also incorrect in a few places. --- src/expressions/method-call-expr.md | 3 +- src/type-coercions.md | 118 +++++++++++++++++++--------- 2 files changed, 83 insertions(+), 38 deletions(-) diff --git a/src/expressions/method-call-expr.md b/src/expressions/method-call-expr.md index 8257c083e..2cf91c68a 100644 --- a/src/expressions/method-call-expr.md +++ b/src/expressions/method-call-expr.md @@ -25,7 +25,7 @@ The following procedure is used: r[expr.method.candidate-receivers] The first step is to build a list of candidate receiver types. -Obtain these by repeatedly [dereferencing][dereference] the receiver expression's type, adding each type encountered to the list, then finally attempting an [unsized coercion] at the end, and adding the result type if that is successful. +Obtain these by repeatedly [dereferencing][dereference] the receiver expression's type, adding each type encountered to the list, then finally attempting an [unsized coercion][coerce.unsize] at the end, and adding the result type if that is successful. r[expr.method.candidate-receivers-refs] Then, for each candidate `T`, add `&T` and `&mut T` to the list immediately after `T`. @@ -100,5 +100,4 @@ r[expr.method.edition2021] [disambiguating function call syntax]: call-expr.md#disambiguating-function-calls [dereference]: operator-expr.md#the-dereference-operator [methods]: ../items/associated-items.md#methods -[unsized coercion]: ../type-coercions.md#unsized-coercions [`IntoIterator`]: std::iter::IntoIterator diff --git a/src/type-coercions.md b/src/type-coercions.md index a69b86968..8223abb9d 100644 --- a/src/type-coercions.md +++ b/src/type-coercions.md @@ -134,6 +134,15 @@ r[coerce.types.ref-to-pointer] r[coerce.types.mut-to-pointer] * `&mut T` to `*mut T` +r[coerce.types.unsize] +* `T` to `U` if `T: CoerceUnsized`. For example: + ```rust + const _: &dyn std::fmt::Display = &0u8; // &u8 -> &dyn Display + const _: &[u32] = &[0, 1, 2, 3, 4, 5]; // &[u32; 4] -> &[u32] + ``` + + See [unsized coercion](#unsized-coercions) for more details. + r[coerce.types.deref] * `&T` or `&mut T` to `&U` if `T` implements `Deref`. For example: @@ -163,20 +172,6 @@ r[coerce.types.deref] r[coerce.types.deref-mut] * `&mut T` to `&mut U` if `T` implements `DerefMut`. -r[coerce.types.unsize] -* TyCtor(`T`) to TyCtor(`U`), where TyCtor(`T`) is one of - - `&T` - - `&mut T` - - `*const T` - - `*mut T` - - `Box` - - and where `U` can be obtained from `T` by [unsized coercion](#unsized-coercions). - - - r[coerce.types.fn] * Function item types to `fn` pointers @@ -190,40 +185,89 @@ r[coerce.unsize] ### Unsized Coercions r[coerce.unsize.intro] -The following coercions are called `unsized coercions`, since they -relate to converting types to unsized types, and are permitted in a few -cases where other coercions are not, as described above. They can still happen -anywhere else a coercion can occur. +The following coercions are called "unsized coercions", since their targets contain an unsized type. +unsized coercions apply to pointer-like types which point to types which can lose some of their compile-time known information (such as size or implemented traits). For example: + +```rust +use std::cell::Cell; + +fn main() { + // `&[u8; 0]` can be coerced to `&[u8]`. + // + // here `&_` is the pointer-like type, + // `[u8; 0]` is the original pointee, + // and `[u8]` is more erased pointee (it lost the length information). + let _: &[u8] = &[]; + + trait A: Super {} + impl A for () {} + + trait Super {} + impl Super for () {} + + // `&()` can be coerced to `&dyn A`, losing the type information. + let a: &dyn A = &(); -r[coerce.unsize.trait] -Two traits, [`Unsize`] and [`CoerceUnsized`], are used -to assist in this process and expose it for library use. The following -coercions are built-ins and, if `T` can be coerced to `U` with one of them, then -an implementation of `Unsize` for `T` will be provided: + // `&dyn A` can be coerced to `&dyn Super`, + // loosing the fact that the underlying type (unit) implements `A` too. + let _: &dyn Super = a; + + // The same coercions work with other pointer-like types and wrappers over them: + let _: Box<[u8]> = Box::<[u8; 0]>::new([]); + let _: Cell> = Cell::new(Box::<[u8; 0]>::new([])); + + // The result of the coercion doesn't *have* to be the same pointer-like type, + // alhtough this is only allowed for certain pairs of pointer-like types. + let _: *const dyn A = &mut (); +} +``` + +r[coerce.unsize.confusion] +> [!NOTE] +> The term "unsized" might be quite confusing, since the coercion works on sized types (pointers) and the source pointer might point to an unsized type in the first place (`&dyn A -> &dyn Super` in the example above). +> +> "unsized" refers to the main purpose of these coercions --- converting (pointers to) sized types to (pointers to) unsized types. The pointers being not the focus, since unsized types can't exist without them. + +r[coerce.unsize.metadata] +When performing unsized coercion, the pointer metadata type changes. For example, when unsized `&u32` to `&dyn Debug` metadate type changes from `()` to `DynMetadata` (note that exact metadata types are not yet stable). This can also lead to a change in the pointer size -- `&u32` is half the size of `&dyn Debug`. + +r[coerce.unsize.traits] +Three traits, [`Unsize`], [`CoerceUnsized`], and [`PinCoerceUnsized`] are used to assist in this process and expose it for library use. + +r[coerce.unsize.traits.unsize] +[`Unsize`] represents the fact that the target type is layout compatible with the source type and the pointer metadata of the target type can be derived from the metadata of the source, meaning that a pointer to the source type can be converted to a pointer to the target type. For example `[T; N]` implements `Unsize<[T]>` meaning that you can *unsize* former into the later, allowing coercions such as `&[T; N] -> &[T]`. + +r[coerce.unsize.traits.coerce-unsized] +[`CoerceUnsized`] represents the fact that a pointer-like type can be coerced to another pointer-like type, due to `Unsize` being implemented for their pointees. For example, `&T` implements `CoerceUnsized<&U>` when `T: Unsize`. + +r[coerce.unsize.traits.pin-coerce-unsized] +[`PinCoerceUnsized`] is an unsafe marker trait for pointer-like types unsized coercion of which does not break [`Pin`] guarantees. It is a requirement of the [`CoerceUnsized` implementation for `Pin`][coerce.unsize.coerce-unsized-impls.pin-pin]. That is, `&D: PinCoerceUnsized` implies `Pin<&T>: CoerceUnsized>`. + +The following implementations of [`Unsize`] are built-in: r[coerce.unsize.slice] -* `[T; n]` to `[T]`. +* `[T; n]: Unsize<[T]>`. r[coerce.unsize.trait-object] -* `T` to `dyn U`, when `T` implements `U + Sized`, and `U` is [dyn compatible]. +* `T: Unsize`, when `T` implements `U + Sized`, and `U` is [dyn compatible]. r[coerce.unsize.trait-upcast] -* `dyn T` to `dyn U`, when `U` is one of `T`'s [supertraits]. +* `dyn T: Unsize`, when `U` is one of `T`'s [supertraits]. * This allows dropping auto traits, i.e. `dyn T + Auto` to `dyn U` is allowed. * This allows adding auto traits if the principal trait has the auto trait as a super trait, i.e. given `trait T: U + Send {}`, `dyn T` to `dyn T + Send` or to `dyn U + Send` coercions are allowed. -r[coerce.unsized.composite] -* `Foo<..., T, ...>` to `Foo<..., U, ...>`, when: - * `Foo` is a struct. +r[coerce.unsize.composite] +* `S<..., T, ...>: Unsize>`, when: + * `S` is a struct. * `T` implements `Unsize`. - * The last field of `Foo` has a type involving `T`. - * If that field has type `Bar`, then `Bar` implements `Unsize>`. - * T is not part of the type of any other fields. + * The last field of `S` has a type involving `T`. i.e. it's either of `T` or `C<..., T, ...>` where `C` is a type constructor and `T` is only present in it once (`C` is disallowed). + * The last field is the *only* field which type involves `T`. + * The type of the last field implements `Unsize` where `F` is the same type with `T` replaced by `U`. i.e. if the field has type `Bar`, then `Bar` implements `Unsize>`. + +r[coerce.unsize.pointer] +Additionally, a type `Foo` can implement `CoerceUnsized>` when `T` implements `Unsize` or `CoerceUnsized`. This allows it to provide an unsized coercion to `Foo`. -r[coerce.unsized.pointer] -Additionally, a type `Foo` can implement `CoerceUnsized>` when `T` -implements `Unsize` or `CoerceUnsized>`. This allows it to provide an -unsized coercion to `Foo`. + > [!NOTE] > While the definition of the unsized coercions and their implementation has been stabilized, the traits themselves are not yet stable and therefore can't be used directly in stable Rust. @@ -323,6 +367,8 @@ precisely. [subtype]: subtyping.md [dyn compatible]: items/traits.md#dyn-compatibility [type cast operator]: expressions/operator-expr.md#type-cast-expressions +[`Pin`]: std::pin::Pin +[`PinCoerceUnsized`]: std::pin::PinCoerceUnsized [`Unsize`]: std::marker::Unsize [`CoerceUnsized`]: std::ops::CoerceUnsized [method-call expressions]: expressions/method-call-expr.md From e3d22403ab647f37b45036ef04669a3e676e7673 Mon Sep 17 00:00:00 2001 From: Waffle Lapkin Date: Fri, 18 Apr 2025 16:47:20 +0200 Subject: [PATCH 2/2] rename "unsized" coercion as "unsizing" --- src/expressions/method-call-expr.md | 4 ++-- src/type-coercions.md | 16 ++++++++-------- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/expressions/method-call-expr.md b/src/expressions/method-call-expr.md index 2cf91c68a..6b10fde85 100644 --- a/src/expressions/method-call-expr.md +++ b/src/expressions/method-call-expr.md @@ -25,12 +25,12 @@ The following procedure is used: r[expr.method.candidate-receivers] The first step is to build a list of candidate receiver types. -Obtain these by repeatedly [dereferencing][dereference] the receiver expression's type, adding each type encountered to the list, then finally attempting an [unsized coercion][coerce.unsize] at the end, and adding the result type if that is successful. +Obtain these by repeatedly [dereferencing][dereference] the receiver expression's type, adding each type encountered to the list, then finally attempting an [unsizing coercion][coerce.unsize] at the end, and adding the result type if that is successful. r[expr.method.candidate-receivers-refs] Then, for each candidate `T`, add `&T` and `&mut T` to the list immediately after `T`. -For instance, if the receiver has type `Box<[i32;2]>`, then the candidate types will be `Box<[i32;2]>`, `&Box<[i32;2]>`, `&mut Box<[i32;2]>`, `[i32; 2]` (by dereferencing), `&[i32; 2]`, `&mut [i32; 2]`, `[i32]` (by unsized coercion), `&[i32]`, and finally `&mut [i32]`. +For instance, if the receiver has type `Box<[i32;2]>`, then the candidate types will be `Box<[i32;2]>`, `&Box<[i32;2]>`, `&mut Box<[i32;2]>`, `[i32; 2]` (by dereferencing), `&[i32; 2]`, `&mut [i32; 2]`, `[i32]` (by unsizing coercion), `&[i32]`, and finally `&mut [i32]`. r[expr.method.candidate-search] Then, for each candidate type `T`, search for a [visible] method with a receiver of that type in the following places: diff --git a/src/type-coercions.md b/src/type-coercions.md index 8223abb9d..6b51b8ad3 100644 --- a/src/type-coercions.md +++ b/src/type-coercions.md @@ -141,7 +141,7 @@ r[coerce.types.unsize] const _: &[u32] = &[0, 1, 2, 3, 4, 5]; // &[u32; 4] -> &[u32] ``` - See [unsized coercion](#unsized-coercions) for more details. + See [unsizing coercion](#unsizing-coercions) for more details. r[coerce.types.deref] * `&T` or `&mut T` to `&U` if `T` implements `Deref`. For example: @@ -182,11 +182,11 @@ r[coerce.types.never] * `!` to any `T` r[coerce.unsize] -### Unsized Coercions +### Unsizing Coercions r[coerce.unsize.intro] -The following coercions are called "unsized coercions", since their targets contain an unsized type. -unsized coercions apply to pointer-like types which point to types which can lose some of their compile-time known information (such as size or implemented traits). For example: +The following coercions are called "Unsizing coercions", since their targets contain an unsized type. +Unsizing coercions apply to pointer-like types which point to types which can lose some of their compile-time known information (such as size or implemented traits). For example: ```rust use std::cell::Cell; @@ -224,12 +224,12 @@ fn main() { r[coerce.unsize.confusion] > [!NOTE] -> The term "unsized" might be quite confusing, since the coercion works on sized types (pointers) and the source pointer might point to an unsized type in the first place (`&dyn A -> &dyn Super` in the example above). +> The term "unsizing" might be quite confusing, since the coercion works on sized types (pointers) and the source pointer might point to an unsized type in the first place (`&dyn A -> &dyn Super` in the example above). > -> "unsized" refers to the main purpose of these coercions --- converting (pointers to) sized types to (pointers to) unsized types. The pointers being not the focus, since unsized types can't exist without them. +> "Unsizing" refers to the main purpose of these coercions --- converting (pointers to) sized types to (pointers to) unsized types. The pointers being not the focus, since unsized types can't exist without them. r[coerce.unsize.metadata] -When performing unsized coercion, the pointer metadata type changes. For example, when unsized `&u32` to `&dyn Debug` metadate type changes from `()` to `DynMetadata` (note that exact metadata types are not yet stable). This can also lead to a change in the pointer size -- `&u32` is half the size of `&dyn Debug`. +When performing unsizing coercion, the pointer metadata type changes. For example, when unsizing `&u32` to `&dyn Debug` metadate type changes from `()` to `DynMetadata` (note that exact metadata types are not yet stable). This can also lead to a change in the pointer size -- `&u32` is half the size of `&dyn Debug`. r[coerce.unsize.traits] Three traits, [`Unsize`], [`CoerceUnsized`], and [`PinCoerceUnsized`] are used to assist in this process and expose it for library use. @@ -241,7 +241,7 @@ r[coerce.unsize.traits.coerce-unsized] [`CoerceUnsized`] represents the fact that a pointer-like type can be coerced to another pointer-like type, due to `Unsize` being implemented for their pointees. For example, `&T` implements `CoerceUnsized<&U>` when `T: Unsize`. r[coerce.unsize.traits.pin-coerce-unsized] -[`PinCoerceUnsized`] is an unsafe marker trait for pointer-like types unsized coercion of which does not break [`Pin`] guarantees. It is a requirement of the [`CoerceUnsized` implementation for `Pin`][coerce.unsize.coerce-unsized-impls.pin-pin]. That is, `&D: PinCoerceUnsized` implies `Pin<&T>: CoerceUnsized>`. +[`PinCoerceUnsized`] is an unsafe marker trait for pointer-like types unsizing coercion of which does not break [`Pin`] guarantees. It is a requirement of the [`CoerceUnsized` implementation for `Pin`][coerce.unsize.coerce-unsized-impls.pin-pin]. That is, `&D: PinCoerceUnsized` implies `Pin<&T>: CoerceUnsized>`. The following implementations of [`Unsize`] are built-in: