some work on collections #137

steveklabnik · 2016-07-19T22:04:15Z

I started fleshing out some stuff about data structures. I feel pretty good about this, with some caveats discussed below.

Also, I would really like to hear what @carols10cents, @aturon, and @jonathandturner (think about showing the internal representation of Vec like this; we haven't seen raw pointers, but I really like the idea of giving people an understanding at this level. I'm not sure if this pacing is correct, like, maybe the details of how insert() works should go at the end, rather than in the middle?

There are two ways this PR needs more work, beyond all that:

I feel like I should put more examples in Vec, but wanted to give you an idea of the style I'm shooting for here before worrrying too much about exactly what should be included. Thoughts welcome! For one, I was thinking about showing off enums in vectors as a way of storing multiple types of elements...
I fleshed out very very roughly what I'd want to cover for the other chapters as well, It's basically "show off CRUD", though I want to consider just dropping "delete" to be a reminder sentence to the vector version, rather than re-explaining Drop each time. Plus, each one has their own little tweaks: hashmap has entry, string will have the utf-8 stuff.

carols10cents · 2016-07-21T19:40:20Z

So yeah, as someone who wants to know more about how to use things like Vectors in my code, but not really care so much about how they work under the hood, this isn't my favorite approach ever. BUT! Knowing what I know now, since I've acquired some rust experience, I think by adding a little bit of cheese to the broccoli you could get past-me to eat my vegetables and I would be better off for it.

I knew about the double-capacity reallocation behavior of Vec in the abstract but didn't think about it too much until these two experiences:

I was trying to optimize the performance of some code I was working on, I wasn't using Vec::with_capacity, and I saw a good chunk of time in my profiling results was being spent in Vec allocation. Switching to use Vec::with_capacity helped a WHOLE lot. I like that this chapter explains why that is, and as someone using Vec, this is super relevant, but the part about with_capacity is kind of a little aside at the end. If I made a function that solves a realish problem where you know the capacity of the Vec you'll need but not the values when you start (to show why you couldn't use vec!) and a flame graph of its performance using Vec::new() and Vec::with_capacity(), do you think that would be a good addition?
When I was working on rewriting zopfli in Rust, I found that the C version literally contains a define to do what Vec does. Now, I was already pretty horrified by C even though I don't know it intimately, but I was even more horrified during this eye-opening discovery/realization that every C library has to define and maintain this behavior themselves. I was very thankful that Rust not only provides the implementation of Vec reallocation for me, but that the borrow checker provides the safety of using Vec because of the way it's implemented. I love the demonstration of this in the "Reading elements of vectors" section-- could we add to the intro some allusion that this payoff of getting safe, performant, storage with a convenient API (maybe contrast with C?) will become clear to us by the end of the section? I think knowing that's coming would keep me going.

And one small thought:

Should we call this chapter "basic collections" or just "collections"? I know you mentioned kind of wanting to stay away from basic/advanced dichotomy... if you want to convey that this isn't going to cover all the collections available in std, maybe instead of "basic" say "foundational"? "common"? "staple"? "essential"? "fundamental"?

alilleybrinker · 2016-07-21T20:19:58Z

@carols10cents, perhaps "common collections," differentiating on how often collections are used in real-world programs.

steveklabnik · 2016-07-21T20:38:58Z

If I made a function... do you think that would be a good addition?

Yeah, I think this might be real great!

could we add to the intro some allusion that this payoff of getting safe, performant, storage with a convenient API (maybe contrast with C?) will become clear to us by the end of the section?

👍

And yeah, "common" or "staple" both sound good to me.

carols10cents · 2016-07-21T20:51:57Z

Yay!

Almost forgot that I made some tiny edits while reading, I just pushed them to this branch for you.

I'm going to add an issue to remind me to make that function and flame graphs soon-- I'll let you take care of the intro, unless you'd like me to give it a try!

sophiajt · 2016-07-21T20:58:30Z

src/ch09-02-vectors.md

+v.push(8);
+```
+
+Since these numbers are `i32`s, Rust can infer the type of the vector, so we


Are they always i32 for simple numbers?

an integer which doesn't have any bounds to infer the type by is resolved as i32, yes.

sophiajt · 2016-07-21T21:15:28Z

👍 to @carols10cents comments.

Carol's knee-jerk about show me how to use Vec vs telling me how it works. I think we should spend a lot more time on how to use it, and then move the "let's open the hood and eat our broccoli" to later in the book (or possibly to a blog post or other venue).

There may be ways to show some of that data, maybe not quite all of the steps you show. When I was looking through the chapter, I was thinking that I'd much rather see pretty pictures. Maybe that's a good cheese for the broccoli where you can get some of the vitamins in.

carols10cents · 2016-07-27T18:21:38Z

On the call, @aturon asked @steveklabnik about a case in which knowing the internals of Vec helped him to understand using a Vec, and he gave a great example of holding a reference to the 2nd element of the vec and not being able to add a new element to the end at the same time, since the memory might be reallocated-- just writing this down for you because i think it's awesome!

steveklabnik · 2016-08-30T19:32:18Z

Okay, @carols10cents , I think a draft is done. The hashmap bit is.... uninspired? We should try to brainstorm on how to jazz it up a bit. But the basics are all in place, I think.

steveklabnik · 2016-08-30T20:52:34Z

I was talking with @ashleygwilliams about what stuff to add to the hashmap section:

iterating over keys/values
forshadowing the hash trait

ashleygwilliams · 2016-08-30T21:00:23Z

also: where are the values? are they copied, referenced? how does equality work?

carols10cents · 2016-09-16T18:14:02Z

src/ch08-02-strings.md

+['न', 'म', 'स', '्', 'त', 'े', ' ']
+```
+
+There are seven of them, and the last one isn't even visible! Finally, if you


@steveklabnik I'm not really sure what you're trying to illustrate with the space on the end... the way you talk about it here ("the last [char] isn't even visible!", "and there's still that empty character on the end") makes it sound like something weirder than a regular ol' space? I think it's distracting from the main grapheme cluster/character point, mind if I take it out?

carols10cents · 2016-09-16T18:23:05Z

src/ch08-02-strings.md

+
+However.
+
+Sometimes, indexing the bytes of a string is useful. So while you can't use `[]`


This explanation is... unsatisfying. Like... I understand the pieces of this decision, namely:

People naïvely try to get chars by indexing a string and then make their programs not do what they expected in the face of multibyte characters, and Rust wants to try to prevent that

string slices are a starting byte and a number of bytes indexed into a String

but like, together, with the explanation "this thing is bad but this other thing that amounts to a trivial workaround is useful so we disallowed the bad thing but allowed the useful trivial workaround" is not very... satisfying? convincing that the language has a cohesive design?

There might not be a satisfying explanation here, and Rust just might be inconsistent here and everyone has come to terms with it. In that case, I feel like we should say "Yes, Rust is being inconsistent because the problems that occur with indexing directly into an array were deemed to outweigh the benefits of allowing it, but that did not hold for slicing because... X".

I am going to go looking for discussions along these lines, I bet there's a real humdinger of a bikeshed around here somewhere that I don't remember seeing.

carols10cents · 2016-09-26T19:27:17Z

Ok. I think I'm done with this chapter. Anyone have time to review in the next few days?

steveklabnik · 2016-09-26T20:48:00Z

src/SUMMARY.md

-    - [Vectors]()
-    - [Strings]()
-    - [`HashMap<K, V>`]()
+- [Essential Collections](ch08-00-essential-collections.md)


ugh i know we already talked about this, but I would really prefer something other than "essential." How about "fundamental"?

YOU DID THIS 57fd1a5

(but yeah fundamental is fine)

steveklabnik · 2016-09-26T20:48:11Z

src/SUMMARY.md

+- [Essential Collections](ch08-00-essential-collections.md)
+    - [Vectors](ch08-01-vectors.md)
+    - [Strings](ch08-02-strings.md)
+    - [HashMaps](ch08-03-hashmaps.md)


Two words, probably.

hnnnggg like everywhere then

steveklabnik · 2016-09-26T20:48:28Z

src/ch08-00-essential-collections.md

@@ -0,0 +1,18 @@
+# Essential Collections


we'll need to change this here too

steveklabnik · 2016-09-26T20:52:04Z

src/ch08-02-strings.md

+
+Before we can dig into those aspects, we need to talk about what exactly we
+even mean by the word 'string'. Rust actually only has one string type in the
+core language itself: `&str`. We talked about these string slices in Chapter 4:


worth *ing string slices?

steveklabnik · 2016-09-26T20:56:23Z

src/ch08-02-strings.md

+// ... etc
+```
+
+There are crates available to get grapheme clusters from `String`s.


Maybe add 'on crates.io'?

steveklabnik · 2016-09-26T20:56:39Z

src/ch08-03-hashmaps.md

@@ -0,0 +1,251 @@
+## HashMaps
+
+The last of our essential collections is the *HashMap*. A `HashMap<K, V>`


darn essences

steveklabnik · 2016-09-26T20:59:21Z

src/ch08-03-hashmaps.md

+### Updating a HashMap
+
+#### Overwriting a Value
+


two headings with no words inside?

oops. i can put some words in there

steveklabnik · 2016-09-26T20:59:28Z

src/ch08-03-hashmaps.md

+
+#### Overwriting a Value
+
+If we insert a key and a value, then insert that key with a different value, the value associated with that key will be replaced. Even though this code calls `insert` twice, the HashMap will only contain one key/value pair, since we're inserting with the key `1` both times:


word wrap this line :)

steveklabnik · 2016-09-26T21:02:40Z

This chapter is so much better now 😄 ❤️

Okay, so one last thing that we didn't include that might be cool: should we show off how to use enums to get multiple things into a collection?

carols10cents · 2016-09-26T21:54:44Z

Okay, so one last thing that we didn't include that might be cool: should we show off how to use enums to get multiple things into a collection?

Oooooh good call. I'm into it.

steveklabnik · 2016-09-26T23:06:45Z

i'm not totally sure. I guess it's like "vector" vs Vector, "hash map" vs
HashMap. idk

On Mon, Sep 26, 2016 at 5:53 PM, Carol (Nichols || Goulding) <
notifications@github.com> wrote:

@carols10cents commented on this pull request.

In src/SUMMARY.md #137:

@@ -31,10 +31,10 @@
- Controlling visibility with pub
- Importing names with use

-- Basic Collections

Vectors

Strings

HashMap<K, V>
+- Essential Collections

Vectors

Strings

HashMaps

hnnnggg like everywhere then

—
You are receiving this because you were assigned.
Reply to this email directly, view it on GitHub
#137, or mute the thread
https://github.com/notifications/unsubscribe-auth/AABsiu1SvycU-kllJAxgZg9ltJoLUMLlks5quD7cgaJpZM4JQOUP
.

carols10cents · 2016-09-27T03:18:06Z

No more essences. And "hash map" looked really weird at first but I think I'm getting used to it now.

Back over to you! 🏓

steveklabnik · 2016-09-27T14:09:23Z

src/ch08-01-vectors.md

+the vector would hold a type that would cause errors with the operations we
+performed on the vector. Using an enum plus a `match` where we access elements
+in a vector like this means that Rust will ensure at compile time that we
+always handle every possible case.


last thing, and then let's

We should mention "if we always know what the set of types are, an enum works. if we don't, a trait object works, and we'll learn about those later" (but in better words)

carols10cents · 2016-09-27T14:58:56Z

check me!!

steveklabnik · 2016-09-27T15:33:27Z

🎊

carols10cents · 2016-09-27T17:46:23Z

yayayayayayyyyy!!!!

fbstj · 2016-10-05T09:28:22Z

src/ch08-01-vectors.md

+Using an enum for storing different types in a vector does imply that we need
+to know the set of types we'll want to store at compile time. If that's not the
+case, instead of an enum, we can use a trait object. We'll learn about those in
+Chapter XX.


is this meant to be Chapter 25.2?

We've been rearranging the later chapters a lot, so we're not sure which chapter it's going to be yet.

fbstj · 2016-10-05T09:40:13Z

src/ch08-02-strings.md

+same way as `println!`, but instead of printing the output to the screen, it
+returns a `String` with the contents. This version is much easier to read than
+all of the `+`s.
+


should this mention how format! doesn't take ownership (unlike the prior examples)

Maybe! Can you elaborate on why mentioning that would be helpful to you at this point? Which prior examples are you referring to?

in the first example of concatenation there was an aside about String + &str taking ownership of the first part (which might be an extra point against doing the multiple + given potential precedence oddities) but there's nothing about how format! takes & (I went and looked it up in the docs/code

basically it's because ownership is brought up during the previous example but not during this it just felt a little strange.

Hm, I'll think on this. I think I was assuming that since we said that format! is like println! here, and the reader has already had some experience with println!, that it should be clear. But apparently it's not! I'm also going to create a new bug report since this PR has been merged already, so this doesn't get lost. Thank you!! ❤️

mdBook 0.4.5へアップグレード

…ary-page rust-lang#134 add glossary page

steveklabnik assigned steveklabnik and carols10cents and unassigned steveklabnik Jul 19, 2016

carols10cents added the pseudo-blocking-ish label Jul 20, 2016

carols10cents mentioned this pull request Jul 21, 2016

Can we not use text syntax highlighting for code blocks as much? Or can text get a gray background in the rendered HTML too? #139

Closed

carols10cents mentioned this pull request Jul 21, 2016

fn and flamegraphs illustrating performance implications of Vec::with_capacity #140

Closed

sophiajt reviewed Jul 21, 2016
View reviewed changes

carols10cents removed the pseudo-blocking-ish label Jul 27, 2016

carols10cents removed their assignment Jul 27, 2016

steveklabnik force-pushed the data-structures branch 2 times, most recently from f9aa969 to 3d90c48 Compare August 26, 2016 19:49

carols10cents self-assigned this Sep 15, 2016

carols10cents force-pushed the data-structures branch from c854a11 to 0a6d904 Compare September 15, 2016 20:21

carols10cents reviewed Sep 16, 2016

View reviewed changes

steveklabnik and others added 5 commits September 19, 2016 12:42

some work on collections

4de5854

Small wording, punctuation, spelling edits

d9591c1

basic -> essential

57fd1a5

remove the fun stuff

a47516a

lol

c9a21c8

carols10cents added 2 commits September 26, 2016 15:17

Small wording tweaks, mostly removing 'you'

6bef3b8

Fill in some chapter numbers we know now

0812f3a

carols10cents assigned steveklabnik and unassigned carols10cents Sep 26, 2016

steveklabnik commented Sep 26, 2016

View reviewed changes

carols10cents added 7 commits September 26, 2016 22:22

No more essence. anywhere. There is no essence.

c3ddfa5

You've got your big G's, I've got my hash map

d56e536

The word of the day is *string slice*

021998f

Crates for the crates.io!

2d5ea64

Add text between the headings

84b135d

Wrap at 80 oops

a7e3b2a

Show how to store different types in an enum in a vec

7280821

steveklabnik commented Sep 27, 2016

View reviewed changes

Paragraph foreshadowing trait objects

d7a11ad

steveklabnik merged commit 4a2bc80 into master Sep 27, 2016

steveklabnik deleted the data-structures branch September 27, 2016 15:33

fbstj reviewed Oct 5, 2016

View reviewed changes

carols10cents mentioned this pull request Oct 7, 2016

Mention that format! does not take ownership? #291

Closed

carols10cents mentioned this pull request Feb 18, 2017

Ch8 edits after technical review #450

Merged

AbrarNitk pushed a commit to FifthTry/rust-book that referenced this pull request Jun 2, 2021

Merge pull request rust-lang#137 from tatsuya6502/mdbook-0.4.5

d37c377

mdBook 0.4.5へアップグレード

AbrarNitk pushed a commit to FifthTry/rust-book that referenced this pull request Jun 2, 2021

Merge pull request rust-lang#137 from rinthel/rust-lang#134-add-gloss…

b207dcc

…ary-page rust-lang#134 add glossary page


		However.

		Sometimes, indexing the bytes of a string is useful. So while you can't use `[]`

		@@ -0,0 +1,251 @@
		## HashMaps

		The last of our essential collections is the HashMap. A `HashMap<K, V>`


		#### Overwriting a Value

		If we insert a key and a value, then insert that key with a different value, the value associated with that key will be replaced. Even though this code calls `insert` twice, the HashMap will only contain one key/value pair, since we're inserting with the key `1` both times:

some work on collections #137

some work on collections #137

Conversation

steveklabnik commented Jul 19, 2016

carols10cents commented Jul 21, 2016

alilleybrinker commented Jul 21, 2016

steveklabnik commented Jul 21, 2016

carols10cents commented Jul 21, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sophiajt commented Jul 21, 2016

carols10cents commented Jul 27, 2016

steveklabnik commented Aug 30, 2016

steveklabnik commented Aug 30, 2016

ashleygwilliams commented Aug 30, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

carols10cents commented Sep 26, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

steveklabnik commented Sep 26, 2016

carols10cents commented Sep 26, 2016

steveklabnik commented Sep 26, 2016

@carols10cents commented on this pull request.

carols10cents commented Sep 27, 2016

Choose a reason for hiding this comment

carols10cents commented Sep 27, 2016

steveklabnik commented Sep 27, 2016

carols10cents commented Sep 27, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment