Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Rust 1.48

blog.rust-lang.org

Post reply on HN
Print view View original

41–50 of 119 posts

Re: Rust 1.48

#41

Post by steveklabnik »

simias wrote: post #36
mark4 wrote: post #17

Earlier quoted context omitted.

Newbie question. Why is this useful? Wouldn't slices be enough to fulfill the use-cases this would see?

steveklabnik is (of course) correct, but you also have to consider the performance cost of a dynamicaly sized slice versus a statically sized array. A situation I've encountered several times already is implementing statically sized FIFOs. At the moment in Rust I can't implement a type "FIFO of depth N" where is a generic, static parameter. My only choices are implementing "FIFO of depth n" where n is provided dynami…

You maybe could write something like this:

  pub struct Fifo> {
and then back it with an array. I learned this trick from whitequark.

(Though maybe if you want something other than a slice of bytes, this gets harder... I've used this trick for ringbuffers/mmio only, personally, so YMMV.)

That being said real const generics will make this way nicer, eventually.

Re: Rust 1.48

#42

Post by throwaway894345 »

mike-cardwell wrote: post #29
bluejekyll wrote: post #2

One of the things that made me so excited about Rust when I first used it was the capabilities of the Rustdoc system. The built in examples that are also unit tests, the ease of just using markdown... and now the linking is even simpler. It’s one of my favorite things about the language, and I think is why so many crates have such good documentation, because it’s easy to do. (and it’s tested and validated so you know…

I've always found crate documentation to be the worse thing about Rust. Because it auto-generates some documentation, people just assume that's good enough, and you end up with tonnes of crates that seemingly only have a list of functions and structs and what arguments they take, but very little information about how you're supposed to plug everything together.

At least you get that. In the (untyped) Python ecosystem, you're lucky to get "this parameter is a file-like object" even though "file-like" doesn't tell you if it just supports read() and write() or also seek() or close() or truncate(). You have to dig into the source code, which likely just passes the parameter into another function which passes it into another and then across a library boundary and so on. And again, that's the best-case scenario. Just having correct type information is 80% of the battle IMHO.

Re: Rust 1.48

#43

Post by est31 »

steveklabnik wrote: post #38
est31 wrote: post #37

Earlier quoted context omitted.

Interesting question. Does RUSTDOCFLAGS="--extern-html-root-url std=file:///path/to/std/docs" cargo doc work? You can repeat it for std, core, alloc, proc-macro, etc.

You need a -Z unstable-options in there too, but this does not work for me with the latest nightly.

Hmm apparently there is a cargo feature for it now: https://github.com/rust-lang/cargo/blob/master/src/doc/src/r...

So something like this in .cargo/config:

[doc.extern-map]

std = "local"

And then cargo +nightly doc -Zrustdoc-map.

Re: Rust 1.48

#44

Post by skrtskrt »

mike-cardwell wrote: post #29
bluejekyll wrote: post #2

One of the things that made me so excited about Rust when I first used it was the capabilities of the Rustdoc system. The built in examples that are also unit tests, the ease of just using markdown... and now the linking is even simpler. It’s one of my favorite things about the language, and I think is why so many crates have such good documentation, because it’s easy to do. (and it’s tested and validated so you know…

I've always found crate documentation to be the worse thing about Rust. Because it auto-generates some documentation, people just assume that's good enough, and you end up with tonnes of crates that seemingly only have a list of functions and structs and what arguments they take, but very little information about how you're supposed to plug everything together.

Go is the same. Everyone, including the stdlib maintainers seem to think a few lines of comments per method is the same as documentation on how to use the package, best practices, pitfalls, etc.

Re: Rust 1.48

#45

Post by identity0 »

0-_-0 wrote: post #5
bluejekyll wrote: post #2

One of the things that made me so excited about Rust when I first used it was the capabilities of the Rustdoc system. The built in examples that are also unit tests, the ease of just using markdown... and now the linking is even simpler. It’s one of my favorite things about the language, and I think is why so many crates have such good documentation, because it’s easy to do. (and it’s tested and validated so you know…

Not directly related, but when I was learning programming back in highschool (before the Internet) what made it easy was the built in help in Turbo Pascal. You could press F1 over any function or keyword and you were given a detailed description and example of usage. Learning C later using the K&R book and Google was a huge downgrade. Even today I think that language help built into the IDE should be a basic function…

In vim if you press K it will bring up the man page for the word under your cursor. It was very useful when learning C, considering that most libc functions have helpful man pages.

Re: Rust 1.48

#46

Post by heavyset_go »

bluejekyll wrote: post #2

One of the things that made me so excited about Rust when I first used it was the capabilities of the Rustdoc system. The built in examples that are also unit tests, the ease of just using markdown... and now the linking is even simpler. It’s one of my favorite things about the language, and I think is why so many crates have such good documentation, because it’s easy to do. (and it’s tested and validated so you know…

This is a great feature, but it is also present in many languages. For example, doctest[1] is included with Python, and allows for tests in docstrings.

[1] https://docs.python.org/3/library/doctest.html

Re: Rust 1.48

#47

Post by antonf »

steveklabnik wrote: post #18
mark4 wrote: post #17

Earlier quoted context omitted.

Newbie question. Why is this useful? Wouldn't slices be enough to fulfill the use-cases this would see?

Some things want an array of a specific size. If you have a function like https://doc.rust-lang.org/stable/std/primitive.u16.html#meth... pub const fn from_be_bytes(bytes: [u8; 2]) -> u16 you can't pass it a slice. This would let you pass a vector to this function. Now, because this wasn't possible previously, it means many things take a slice, and then check that the length is the length they expect, because that en…

TryInto is already implemented for slices in 1.47, so `let foo = u16::from_be_bytes(some_slice.try_into().unwrap());` would work before 1.48.

This trait wasn't implemented for vectors though, so you would have to write `let foo = u16::from_be_bytes(some_vec.to_slice().try_into().unwrap());`.

With new release you can drop `to_slice()` part. Nothing earth-shattering, but makes sense.

Re: Rust 1.48

#48

Post by steveklabnik »

antonf wrote: post #47
steveklabnik wrote: post #18

Earlier quoted context omitted.

Some things want an array of a specific size. If you have a function like https://doc.rust-lang.org/stable/std/primitive.u16.html#meth... pub const fn from_be_bytes(bytes: [u8; 2]) -> u16 you can't pass it a slice. This would let you pass a vector to this function. Now, because this wasn't possible previously, it means many things take a slice, and then check that the length is the length they expect, because that en…

TryInto is already implemented for slices in 1.47, so `let foo = u16::from_be_bytes(some_slice.try_into().unwrap());` would work before 1.48. This trait wasn't implemented for vectors though, so you would have to write `let foo = u16::from_be_bytes(some_vec.to_slice().try_into().unwrap());`. With new release you can drop `to_slice()` part. Nothing earth-shattering, but makes sense.

Ah fun! I missed that. Time to clean up some code...

Re: Rust 1.48

#49

Post by est31 »

antonf wrote: post #47
steveklabnik wrote: post #18

Earlier quoted context omitted.

Some things want an array of a specific size. If you have a function like https://doc.rust-lang.org/stable/std/primitive.u16.html#meth... pub const fn from_be_bytes(bytes: [u8; 2]) -> u16 you can't pass it a slice. This would let you pass a vector to this function. Now, because this wasn't possible previously, it means many things take a slice, and then check that the length is the length they expect, because that en…

TryInto is already implemented for slices in 1.47, so `let foo = u16::from_be_bytes(some_slice.try_into().unwrap());` would work before 1.48. This trait wasn't implemented for vectors though, so you would have to write `let foo = u16::from_be_bytes(some_vec.to_slice().try_into().unwrap());`. With new release you can drop `to_slice()` part. Nothing earth-shattering, but makes sense.

> TryInto is already implemented for slices in 1.47, so `let foo = u16::from_be_bytes(some_slice.try_into().unwrap());` would work before 1.48.

Rustdocs say it was 1.36 even? https://doc.rust-lang.org/nightly/std/primitive.array.html#i...

Re: Rust 1.48

#50

Post by x87678r »

skrtskrt wrote: post #44
mike-cardwell wrote: post #29

Earlier quoted context omitted.

I've always found crate documentation to be the worse thing about Rust. Because it auto-generates some documentation, people just assume that's good enough, and you end up with tonnes of crates that seemingly only have a list of functions and structs and what arguments they take, but very little information about how you're supposed to plug everything together.

Go is the same. Everyone, including the stdlib maintainers seem to think a few lines of comments per method is the same as documentation on how to use the package, best practices, pitfalls, etc.

Java is the same as well
Post reply on HN