Dramatically expand the docs of std::raw. #22218
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
(rust_highfive has picked a reviewer for you, use r? to override) |
| /// | ||
| /// - Creating a slice from a data pointer and length can be done with | ||
| /// `std::slice::from_raw_parts` or `std::slice::from_raw_parts_mut` | ||
| /// than with `std::mem::transmute` on a value of type `Slice`. |
There was a problem hiding this comment.
looks like a double space after transmute too
There was a problem hiding this comment.
This sentence was refactored too many times, and there's no compiler to catch mistakes.
💔 english
|
Content-wise this is a great improvement. Although it makes me wonder: why would anyone use anything in here? Is it just for writing the nicer abstractions in libcore and rustc? Should we state this? |
|
I tried to do that with |
|
Yeah I figured as much. r=me unless you still want steve's feedback. |
IIRC, these things are |
| @@ -21,7 +21,40 @@ | |||
| use marker::Copy; | |||
| use mem; | |||
|
|
|||
| /// The representation of a Rust slice | |||
| /// The representation of a Rust slice. | |||
|
r=me after those few nits |
|
If you want to, you can grab this commit to fix the Repr trait to be unsafe on top of your change.
|
This overhauls the very meager docs that currently exist to clarify various understandable confusions that I've noticed, e.g. people look in `std::raw` for the "real" types of slices like `&[T]`, or think that `Slice<T>` refers to `[T]` (fixes rust-lang#22214). This patch takes the liberty of offering some "style" guidance around `raw::Slice`, since there's more restricted ways to duplicate all functionality connected to it: `std::slice::from_raw_parts{,_mut}` for construction and `.as_{,mut_}ptr` & `.len` for deconstruction. It also deprecates the `std::raw::Closure` type which is now useless for non-type-erased closures, and replaced by `TraitObject` for `&Fn`, `&mut FnMut` etc, so I guess it should be called a: [breaking-change]
The default implementation of .repr() will call conveniently call transmute_copy which should be appropriate for all implementors, but is memory unsafe if used wrong. Fixes rust-lang#22260 You need to use `unsafe impl` to implement the Repr trait now. [breaking-change]
steveklabnik
added a commit
to steveklabnik/rust
that referenced
this pull request
Feb 14, 2015
This overhauls the very meager docs that currently exist to clarify various understandable confusions that I've noticed, e.g. people look in `std::raw` for the "real" types of slices like `&[T]`, or think that `Slice<T>` refers to `[T]` (fixes rust-lang#22214). This patch takes the liberty of offering some "style" guidance around `raw::Slice`, since there's more restricted ways to duplicate all functionality connected to it: `std::slice::from_raw_parts{,_mut}` for construction and `.as_{,mut_}ptr` & `.len` for deconstruction.
steveklabnik
added a commit
to steveklabnik/rust
that referenced
this pull request
Feb 15, 2015
This overhauls the very meager docs that currently exist to clarify various understandable confusions that I've noticed, e.g. people look in `std::raw` for the "real" types of slices like `&[T]`, or think that `Slice<T>` refers to `[T]` (fixes rust-lang#22214). This patch takes the liberty of offering some "style" guidance around `raw::Slice`, since there's more restricted ways to duplicate all functionality connected to it: `std::slice::from_raw_parts{,_mut}` for construction and `.as_{,mut_}ptr` & `.len` for deconstruction. It also deprecates the `std::raw::Closure` type which is now useless for non-type-erased closures, and replaced by `TraitObject` for `&Fn`, `&mut FnMut` etc, so I guess it should be called a: [breaking-change]
Manishearth
added a commit
to Manishearth/rust
that referenced
this pull request
Feb 15, 2015
This overhauls the very meager docs that currently exist to clarify various understandable confusions that I've noticed, e.g. people look in `std::raw` for the "real" types of slices like `&[T]`, or think that `Slice<T>` refers to `[T]` (fixes rust-lang#22214). This patch takes the liberty of offering some "style" guidance around `raw::Slice`, since there's more restricted ways to duplicate all functionality connected to it: `std::slice::from_raw_parts{,_mut}` for construction and `.as_{,mut_}ptr` & `.len` for deconstruction. It also deprecates the `std::raw::Closure` type which is now useless for non-type-erased closures, and replaced by `TraitObject` for `&Fn`, `&mut FnMut` etc, so I guess it should be called a: [breaking-change]
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This overhauls the very meager docs that currently exist to clarify
various understandable confusions that I've noticed, e.g. people look in
std::rawfor the "real" types of slices like&[T], or think thatSlice<T>refers to[T](fixes #22214).This patch takes the liberty of offering some "style" guidance around
raw::Slice, since there's more restricted ways to duplicate allfunctionality connected to it:
std::slice::from_raw_parts{,_mut}forconstruction and
.as_{,mut_}ptr&.lenfor deconstruction.It also deprecates the
std::raw::Closuretype which is now useless fornon-type-erased closures, and replaced by
TraitObjectfor&Fn,&mut FnMutetc, so I guess it should be called a:[breaking-change]