Write our own summaries of std types' API surface

[fw-immunant]

Currently our section on std library types consists of a slide for each type with an example, and when teaching this is nice as an intro but gets followed up by a dive into the API docs at https://std.rs/ to cover more comprehensively all the API surface that students should know.

We focus on:

• shared API method and patterns that are not captured by traits
• novel APIs around ownership and borrowing (like into_boxed_slice, leak, and split_at_mut)
• interesting string APIs around the Pattern trait and UTF-8
• slice APIs for sorting and partitioning
• methods inherited via Deref impls
• the HashMap Entry API

But there's a lot that we have to scroll past and ignore because it's boring, rarely useful, unstable, etc..

It would be nice to have our own summaries of these APIs that present things with emphasis on what we care about and skip the stuff that doesn't matter for teaching.

I don't think these will likely fit into small slides, so maybe someone with opinions on slide heights/scrolling should opine here.

[djmitche]

I didn't know about the https://std.rs redirect -- that's handy!

I'm a little wary of duplicating that information, and I think there's some value to navigating the std docs, warts and all.

Maybe it would make sense to add sliides or sub-slides for the limited points you highlighted, but still link to the docs for the details.

Maybe a good perspective is to think what students should recall a week after the course: "oh, HashMap has some entry API to avoid double-lookups -- I'll go find that on std.rs" or "I think you can have mut references to different parts of a slice -- there are split methods for slices that do that." In any case, I'd prefer students refer back to std to fill in what they've forgotten, rather than the course slides.

[fw-immunant]

I do notice that I fairly consistently lose some amount of students/attention when doing the dive into the standard library API docs, but I still think it's important to show a large swath of the available functionality so that students know what's out there. Avoiding rewriting built-in functionality is important for becoming productive in Rust as a beginner.

We do definitely want to ensure students familiar with the API docs as those will be their source of reference moving forward for both the stdlib and ecosystem crates, but with the amount of very similar methods present on some of these types I think some structure could help for breaking up the monotony when teaching.

For example, slices have 21 split_____ methods (26 if you count rsplit_____):

    split
    split_at
    split_at_checked
    split_at_mut
    split_at_mut_checked
    split_at_mut_unchecked
    split_at_unchecked
    split_first
    split_first_chunk
    split_first_chunk_mut
    split_first_mut
    split_inclusive
    split_inclusive_mut
    split_last
    split_last_chunk
    split_last_chunk_mut
    split_last_mut
    split_mut
    split_once
    splitn
    splitn_mut

I think it's better to address this combinatorial explosion with a structured explanation prepared beforehand so I'm not scrolling haphazardly while students try to find their bearings.

Just poking at this because it's fresh in my head from my current course session.

[djmitche]

I think one of the observations at the foundation of this class is that it is very hard to watch someone else scroll something onscreen. So, scrolling through a std::.. page is probably unlikely to confer any information beyond "there's a lot of stuff here!"

So I agree regarding structure. Maybe a few quick slides that cover a few common "ideas" (like splitting) would be a good level -- without going into the details of all 26 methods.

[mgeisler]

I do notice that I fairly consistently lose some amount of students/attention when doing the dive into the standard library API docs,

Yes, this was actually given as course feedback recently — this section seems to have a lot of one-way communication, which makes it hard to follow for the students.

but I still think it's important to show a large swath of the available functionality so that students know what's out there.

I would probably tone it way down, to be honest. I would want people to know about the most commonly used types, such as Option, Result, ... basically those seen here: Standard Library Types. But I would not do a 40 minute one-way chat about them. More like a 20 minute overview, perhaps?