Add how to use the std library documentation

[mdinger]

The std library can be confusing, especially if you haven't used them yet. Add a how to read the std library section. It should do:

• Should be near the beginning
• There is no global list of methods available on a type. They are generally grouped by traits the type has available.
• typeExt is a common convention for where the most important methods go.
  • This is because the methods are implemented by the std library and aren't built-in
  • If the type is built-in then you cannot extend it from std. So you need a new trait. That's why typeExt are there.
• To use a trait, you can examine the implementors to determine which types have that ability.
• A type which impements Deref will have methods available from non-obvious sources. This is detailed on reddit

[EDITS]

• changed core to built-in
• Added Deref bullet

[strega-nil]

The types that need the typeExt can also be built in, i.e. str.

On Tue, Mar 10, 2015 at 12:33 PM, mdinger notifications@github.com wrote:

The std http://doc.rust-lang.org/std/index.html library can be
confusing, especially if you haven't used them yet. Add a how to read
the std library section. It should do:

• Should be near the beginning
• There is no global list of methods available on a type. They are
  generally grouped by traits the type has available.
• typeExt is a common convention for where the most important methods
  go.
  • This is because the methods are implemented by the std library
    and not by core (not sure of std vs core but I'm pretty sure it's because
    they're external)
  • If the type is in core then you cannot extend it from std. So you
    need a new trait. That's why typeExt are there.
    • To use a trait, you can examine the implementors to determine which
      types have that ability.

—
Reply to this email directly or view it on GitHub
#497.

"Unjust laws exist; shall we be content to obey them, or shall we endeavor
to amend them, and obey them until we have succeeded, or shall we
transgress them at once?"
-- Henry David Thoreau

[mdinger]

Maybe built-in is what I was thinking of. Not core.

[strega-nil]

Yeah, I thought there were some types defined in core that have Ext
traits defined in the stdlib, but I can't find any.

On Tue, Mar 10, 2015 at 12:37 PM, mdinger notifications@github.com wrote:

Maybe built-in is what I was thinking of. Not core.

—
Reply to this email directly or view it on GitHub
#497 (comment)
.

"Unjust laws exist; shall we be content to obey them, or shall we endeavor
to amend them, and obey them until we have succeeded, or shall we
transgress them at once?"
-- Henry David Thoreau

[mdinger]

I tried to give an overview of an approach to reading the std libs on reddit. This may be helpful when this bug eventually gets implemented.

[steveklabnik]

I'm going to close this in favor of rust-lang/rust#40116; we want to have this with std, not with RBE.