Documentation for stable version/nightly

I'm about two weeks into learning Rust. One thing that has me a little confused is the status of the documentation vis-a-vis the version I have installed. What is the meaning of all the notes "This is a nightly-only experimental API." ?

For example, I go to https://doc.rust-lang.org/std/index.html and it shows a version number agreeing with that on my machine (1.47.0).

I look up String, click on ends_with, and get to a page which talks about Patterns, but when I click on Pattern, I get this page: https://doc.rust-lang.org/std/str/pattern/trait.Pattern.html which tells me "This is a nightly-only experimental API."

And I'm not sure then how that affects ends_with: which patterns can I use with ends_with in my 1.47.0 version?

Pattern is in kind of a weird state where the unstable tags mean you can't name it anywhere, which prevents you from implementing the trait or using it as a constraint for your own generic code. However, you can use it implicitly through stable standard library methods that require it. This leaves the trait open for the Rust libs team to still redesign Pattern if they want, as long as it still has the same effect for stable callers. Therefore, you can rely on the fact that the current Pattern implementors will continue working with ends_with.

Try is in a similar state -- an unstable trait with stable uses in the ? operator and methods like Iterator::try_fold.

1 Like

Note that 'stable vs nightly' is a more accurate distinction than '1.47.0 vs nightly' (or any other version number). Anything on the stable channel is going to have high forward-compatibility guarantees, while anything that's on nightly but not stable is subject to change.

The book has an appendix about nightly and the channels.

One other note, sometimes publicly visible implementation details are marked expirimental in the compiler with no intention of every making them stable. (I wish they were more distinguished.)

Thankyou @cuviper and @quinedot. Between your replies, I think I understand now.

@quinedot, thanks for the link. (I've got a printed copy of the book, and it stops at appendix E!) I read about unstable features:

If you’re using a beta or stable release of Rust, you can’t use any feature flags. This is the key that allows us to get practical use with new features before we declare them stable forever.

And that links to your explanation, @cuviper. So when the internals of something like Pattern are still being worked out, it is 'flagged' unstable. However, it is being used by stable code, and so appears in the documentation, but the unstable flag means it cannot be used directly in my own code. That flag appears as "This is a nightly-only experimental API" in the documentation.

Maybe I should read the warning as "go back one step and rely on the explanation where you came from", because methods like ends_with explain which patterns are currently valid.