Repository navigation
Make it clear that chunks() and chunks_mut() can be called on their own chunks #31773
Description
I know that it's implied by the docs, but it wasn't immediately obvious to me that the chunks returned by chunks() and chunks_mut() can (I'm avoiding use of the term "recursive" here) have chunks or chunks_mut called on themselves (playground).
Is there any interest in a PR that makes this explicit? It seems that especially when working with threads and work-stealing, this is something that users want to do.
Activity
bluss commentedon Feb 19, 2016
Is it enough to stress that each chunk is itself a slice (or mutable slice)?
urschrei commentedon Feb 19, 2016
Hm. What would be the distinction between stressing it and showing it? In theory, it should be obvious that because the chunk is a slice, you can call
chunks()on it. At the same time, it depends on the intended audience; For the beginner, it means that there's no need to go off to the playpen or ask a question (which may or may not be a good thing, depending on your point of view).Either option is an improvement, and I'm probably over-thinking the whole thing now.
steveklabnik commentedon Feb 19, 2016
In general, API docs usually are written for an intermediate/advanced user: we don't generally mention "oh and because this has a return type of foo you can call these other things on it." Where does this stop and end?
urschrei commentedon Feb 19, 2016
Fair point. But what about explicitly stating that the functions return slices, as opposed to "an iterator"?
sfackler commentedon Feb 19, 2016
It does return an iterator - an iterator over slices.
urschrei commentedon Feb 19, 2016
Undeniably true, but I don't think it's clear; The docs say "an iterator over
size/chunk_sizeelements of the slice".Thiez commentedon Feb 19, 2016
I'm not sure one would be able to use
chunksandchunks_mutcorrectly without understanding that they yield slices. Once you understand that you can usechunksto divide a slice into more slices, surely it makes sense that one can divide those slices in yet more slices, In much the same way that one can add two numbers and use the result for further addition.bluss commentedon Feb 19, 2016
Yes we should clarify the docs to say it returns an iterator whose elements are slices.
Clarify chunks() and chunks_mut() iterator content
Rollup merge of rust-lang#31784 - urschrei:chunks_doc, r=steveklabnik