Types chapter cleanup and new sections #101

matthewjasper · 2017-08-26T22:14:47Z

Changes to existing sections (first commit):

Avoid using 'type constructor'
Give a definition and more complete list of primitive types
Use 'slice' for the unsized type [T]
Don't use Vec<T> in the slice example
Use the term 'variant', instead of 'variant constructor'
Remove description of error E0073 (now removed) when describing rules for recursive types.
Say some more about references and pointers (including RFC 1135)
Use compile_fail for examples that show compiler errors
Mention that structs and variants also create function item types
Try to make it clearer that/why Fn can be implemented by move closures
List object safety rules (RFC 255)
Remove an incorrect statement about which type is the receiver.

Additional sections (second commit):

Mutable references
DSTs (includes documenting RFC 490, RFC 546)
Interior mutability
Unions

matthewjasper · 2017-08-26T22:15:47Z

Also, since one of the rules listed for recursive types was out of date, does anyone know what "Recursive type definitions can cross module boundaries, but not module visibility boundaries, or crate boundaries (in order to simplify the module system and type checker)." is/was supposed to mean?

Havvy

Looks good overall. Some grammar fixes and rewording suggested.

Havvy · 2017-08-28T04:24:44Z

src/types.md

+Most types have a fixed size that is known at compile time and implement the
+trait [`Sized`]. A type with a size that is known only at run-time is called a
+_dynamically sized type_ (_DST_) or unsized type. [Slices] and [trait objects]
+are two of the most DSTs. Such types can only be used in certain cases:


s/of the most/examples of/

If you want to say "of the most common", I'd personally suggest against that as it's an empirical fact.

Havvy · 2017-08-28T04:31:33Z

src/types.md

+  sized types
+    * Pointers to slices also store the number of elements of the slice.
+    * Pointers to trait objects also store a pointer to a vtable.
+* Traits may be implemented for DSTs, this means that `Self` is not assumed to


Should definitely be a period instead of a comma after DSTs. I think this can be shortened considerably. Consider the following, where elsewhere is a link to wherever talks about the Sized trait and where it is automatically inferred.

"Traits can be implemented for DSTs. Unlike elsewhere Self: ?Sized by default in trait definitions."

Link to https://doc.rust-lang.org/std/marker/trait.Sized.html?

How about https://doc.rust-lang.org/nightly/reference/the-sized-trait.html and a later PR, we can fill in that section?

Havvy · 2017-08-28T04:34:18Z

src/types.md

+    * Pointers to trait objects also store a pointer to a vtable.
+* Traits may be implemented for DSTs, this means that `Self` is not assumed to
+  implement `Sized` in trait definitions by default.
+* DSTs can be used as type parameters with a bound of `?Sized`


Does markdown support <abbr>? If so, we should use it everywhere DST is used. I think?

Havvy · 2017-08-28T04:42:08Z

src/types.md

+References prevent a value being both aliased and mutated: mutable references
+don't allow a value to be aliased and shared references prevent a value from
+being mutated. Sometimes this is too restrictive. The type
+[`std::cell::UnsafeCell<T>`](../std/cell/struct.UnsafeCell.html) provides an


The type should be core::cell::UnsafeCell linking to https://doc.rust-lang.org/nightly/core/cell/struct.UnsafeCell.html

The reference usually links to the re-export in std (maybe this should change).

generally speaking, we link to std and not core.

(maybe this should change)

Yeah possibly, it's a tough problem.

I'm the odd one out on this one. Everybody else thinks it is better to link to std, not core.

Havvy · 2017-08-28T04:44:18Z

src/types.md

+being mutated. Sometimes this is too restrictive. The type
+[`std::cell::UnsafeCell<T>`](../std/cell/struct.UnsafeCell.html) provides an
+unsafe API that allows a type to own a `T` that can be mutated through a shared
+reference to the `UnsafeCell` (there is no change to mutable references).


The parenthetical should be its own sentence and copy verbiage from the UnsafeCell docs themselves.

"It is undefined behavior to have multiple &mut UnsafeCell<T> aliases."

Havvy · 2017-08-28T04:44:35Z

src/types.md

+reference to the `UnsafeCell` (there is no change to mutable references).
+
+The standard library provides a variety of different types that safely wrap
+this functionality. For example `std::cell::RefCell<T>` uses run-time borrow


Havvy · 2017-08-28T04:44:44Z

src/types.md

+The standard library provides a variety of different types that safely wrap
+this functionality. For example `std::cell::RefCell<T>` uses run-time borrow
+checks to ensure the usual rules around multiple references. The
+`std::sync::atomic` module contains types that wrap a value that is only


Havvy · 2017-09-02T13:36:31Z

src/types.md

+example in `std::rc::Rc<T>`.
+
+
+## Dynamically sized types


The more I look at this section, the more I wonder if this section should be on the Sized trait itself. The other types in this chapter (except Self...) are non-overlapping, whereas DSTs are a facet of a type.

matthewjasper · 2017-09-17T11:14:14Z

I've moved the interior mutability and DST sections to their own pages following @Havvy's comment above.
Also the trait object section now has more examples about default lifetimes and I've tried to make the interior mutability section clearer.

Havvy · 2017-09-22T21:10:30Z

Thanks ❤️

matthewjasper force-pushed the type-cleanup branch from ecb485a to facc54a Compare August 27, 2017 11:55

Havvy requested changes Aug 28, 2017

View reviewed changes

matthewjasper force-pushed the type-cleanup branch from facc54a to 8e84487 Compare August 28, 2017 20:01

Havvy approved these changes Aug 29, 2017

View reviewed changes

Havvy reviewed Sep 2, 2017

View reviewed changes

matthewjasper added 2 commits September 5, 2017 22:49

Clean up and improvements to the types chapter

eeb1281

Add some missing sections to the types system section

1b7416e

matthewjasper force-pushed the type-cleanup branch from 8e84487 to 1b7416e Compare September 17, 2017 11:07

Havvy merged commit ef15971 into rust-lang:master Sep 22, 2017

matthewjasper deleted the type-cleanup branch October 18, 2018 21:00

Types chapter cleanup and new sections #101

Types chapter cleanup and new sections #101

Uh oh!

Conversation

matthewjasper commented Aug 26, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

matthewjasper commented Aug 26, 2017

Uh oh!

Havvy 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!

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!

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!

matthewjasper commented Sep 17, 2017

Uh oh!

Havvy commented Sep 22, 2017

Uh oh!

Uh oh!

matthewjasper commented Aug 26, 2017 •

edited

Loading