Refactor unsizing coercion documentation #1731

WaffleLapkin · 2025-02-09T13:54:12Z

The old one was quite confusing and also incorrect in a few places. Follow-up to #1622.

ehuss · 2025-03-13T15:55:17Z

@rust-lang/types would you be able to review this?

nikomatsakis · 2025-03-13T15:55:51Z

To add a bit more color, it'd be good to get a double check that the content is factually accurate before spec team takes it on for editorial review.

ehuss · 2025-03-13T15:58:04Z

src/type-coercions.md

+<!-- FIXME: are there more requirements for `CoerceUnsized`? -->
+
+r[coerce.unsize.coerce-unsized-impls]
+Types which currently implement `CoerceUnsized<_>` (assuming `T: Unsize<U>`, `'a: 'b`, `A: CoerceUnsized<B>`, `Al: Allocator`):


Generally I would prefer to not duplicate the list of impls from the standard library here. I assume the user can click the link to CoerceUnsized to see which impls it has?

So, mh. Yes, users can find them in the std docs (that's where I got the impls from!).

However, if we want the reference to be prescriptive, I think we should include this. While this is library code, it controls how a language feature behaves.

But I don't have a strong opinion here, if you think that this is not useful I can remove the list.

ehuss · 2025-04-17T16:07:25Z

@WaffleLapkin To move this along, would it be possible to split this PR up a little so it doesn't get hung up? In particular, I think it would move things faster if we remove the name change (unsized -> unsizing) to avoid getting stuck on bikeshedding (that doesn't mean we can't make that change separately, it just adds friction). And remove the list of CoerceUnsized impls since I think we don't want to go down that road of trying to duplicate the standard library docs (I understand that there is a close relationship of language features with certain parts of the standard library, but other than recognizing a trait or type is special, we usually don't go into details on the library side, and instead defer to those docs).

You can either just make this PR smaller, or open a new smaller PR, whichever is more convenient.

Assigning TC since he asked.

jackh726 · 2025-04-18T14:46:43Z

I can review this over the weekend

WaffleLapkin · 2025-04-18T19:22:41Z

@ehuss I forgot to comment, but I removed the impls and split off the rename.

jackh726

Seems good to me in terms of correctness.

jackh726 · 2025-04-28T16:47:46Z

src/type-coercions.md

+When performing unsized coercion, the pointer metadata type changes. For example, when unsized `&u32` to `&dyn Debug` metadate type changes from `()` to `DynMetadata<dyn Debug>` (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.


It may be worth clarifying these traits are unstable.

There's a note about this down on line 273.

This is actually an interesting case. Generally in the Reference we don't document the unstable, just the exposed stable behaviors. But here, it's probably indeed easiest to describe those stable behaviors in terms of the unstable traits, and we'd already made this exception.

jackh726 · 2025-04-28T17:05:35Z

src/type-coercions.md

-Additionally, a type `Foo<T>` can implement `CoerceUnsized<Foo<U>>` when `T`
-implements `Unsize<U>` or `CoerceUnsized<Foo<U>>`. This allows it to provide an
-unsized coercion to `Foo<U>`.
+<!-- FIXME: are there more requirements for `CoerceUnsized`? -->


So, I think another constraint here is that only one field can be coerced.

The old one was quite confusing and also incorrect in a few places.

WaffleLapkin · 2025-05-11T01:28:57Z

Is there anything I can do to move this forward?

lcnr · 2025-05-22T09:50:56Z

src/type-coercions.md

+    let _: Cell<Box<[u8]>> = 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.


Suggested change

// alhtough this is only allowed for certain pairs of pointer-like types.

// although this is only allowed for certain pairs of pointer-like types.

lcnr · 2025-05-22T09:52:06Z

src/type-coercions.md

+When performing unsized coercion, the pointer metadata type changes. For example, when unsized `&u32` to `&dyn Debug` metadate type changes from `()` to `DynMetadata<dyn Debug>` (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.


Suggested change

Three traits, [`Unsize`], [`CoerceUnsized`], and [`PinCoerceUnsized`] are used to assist in this process and expose it for library use.

Three internal traits, [`Unsize`], [`CoerceUnsized`], and [`PinCoerceUnsized`] are

used to assist in this process and expose it for library use.

lcnr · 2025-05-22T09:53:01Z

src/type-coercions.md

+    * The last field is the *only* field which type involves `T`.
+    * The type of the last field implements `Unsize<F>` where `F` is the same type with `T` replaced by `U`. i.e. if the field has type `Bar<T>`, then `Bar<T>` implements `Unsize<Bar<U>>`.
+
+r[coerce.unsize.pointer]


Suggested change

r[coerce.unsize.pointer]

r[coerce.unsize.struct]

🤔

lcnr · 2025-05-22T10:02:42Z

src/type-coercions.md

+* `dyn T: Unsize<dyn U>`, 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.


existing, but pls change this to use TrA and TrBorFooandBarorTraitandSuper`

I personally tend to get very confused by single letter trait names, esp if we've just used T to mean "any type" 2 lines above

lcnr · 2025-05-22T10:05:15Z

src/type-coercions.md

+    * The type of the last field implements `Unsize<F>` where `F` is the same type with `T` replaced by `U`. i.e. if the field has type `Bar<T>`, then `Bar<T>` implements `Unsize<Bar<U>>`.
+
+r[coerce.unsize.pointer]
+A type `S<..., T, ...>` can implement `CoerceUnsized<S<..., U, ...>>` if


see https://github.com/rust-lang/rust/blob/2cd37831b0706c9f2d6e7e20eb556dc7548bf732/compiler/rustc_next_trait_solver/src/solve/trait_goals.rs#L1048

unsizing can change an arbitrary number of struct type/const args as long all of them are only mentioned in the last field and that last field impls CoerceUnsized

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<T, T> is disallowed).

Where do you get the "T is only present once" requirement from?

wait, confused by the difference between coerce.unsize.composite and coerce.unsize.pointer 🤔 using

an example which disagrees with the current docs

trait Trait<T, U> { type Assoc: ?Sized; } impl<T> Trait<T, u32> for T { type Assoc = [u8; 4]; } impl<T> Trait<T, u16> for T { type Assoc = [u8]; } struct Foo<T: Trait<T, U>, U>(<T as Trait<T, U>>::Assoc); fn main() { let x: &Foo<(), u32> = &Foo([0; 4]); let y: &Foo<String, u16> = x; }

lcnr

nits, then r=me from the "accuracy end". Unsure whether I've got the right to merge reference PRs myself

rustbot added the S-waiting-on-review Status: The marked PR is awaiting review from a maintainer label Feb 9, 2025

WaffleLapkin mentioned this pull request Feb 9, 2025

Add trait_upcasting related languages changes #1622

Merged

WaffleLapkin force-pushed the unsize_coercion_rewrite branch 3 times, most recently from 6f8650a to 08bec64 Compare February 9, 2025 16:56

This comment has been minimized.

Sign in to view

ehuss reviewed Mar 13, 2025

View reviewed changes

WaffleLapkin force-pushed the unsize_coercion_rewrite branch from 08bec64 to 9271fdd Compare March 13, 2025 17:12

ehuss assigned traviscross Apr 17, 2025

WaffleLapkin force-pushed the unsize_coercion_rewrite branch 2 times, most recently from b68840f to 56ee0bb Compare April 18, 2025 14:41

WaffleLapkin force-pushed the unsize_coercion_rewrite branch from 56ee0bb to 2a242c5 Compare April 18, 2025 14:48

WaffleLapkin mentioned this pull request Apr 18, 2025

Rename "unsized" coercion as "unsizing" #1797

Open

WaffleLapkin force-pushed the unsize_coercion_rewrite branch from 2a242c5 to 7780344 Compare April 18, 2025 14:51

jackh726 approved these changes Apr 28, 2025

View reviewed changes

refactor unsizing coercion documentation

cddb6e7

The old one was quite confusing and also incorrect in a few places.

WaffleLapkin force-pushed the unsize_coercion_rewrite branch from 7780344 to cddb6e7 Compare May 11, 2025 01:26

lcnr reviewed May 22, 2025

View reviewed changes

	// alhtough this is only allowed for certain pairs of pointer-like types.
	// although this is only allowed for certain pairs of pointer-like types.

	Three traits, [`Unsize`], [`CoerceUnsized`], and [`PinCoerceUnsized`] are used to assist in this process and expose it for library use.
	Three internal traits, [`Unsize`], [`CoerceUnsized`], and [`PinCoerceUnsized`] are
	used to assist in this process and expose it for library use.

Refactor unsizing coercion documentation #1731

Are you sure you want to change the base?

Refactor unsizing coercion documentation #1731

Uh oh!

Conversation

WaffleLapkin commented Feb 9, 2025

Uh oh!

This comment has been minimized.

ehuss commented Mar 13, 2025

Uh oh!

nikomatsakis commented Mar 13, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ehuss commented Apr 17, 2025

Uh oh!

jackh726 commented Apr 18, 2025

Uh oh!

WaffleLapkin commented Apr 18, 2025

Uh oh!

jackh726 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WaffleLapkin commented May 11, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lcnr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!