Change iterator API to allow moving items in and out

[mgeier]

Closes #56, see the discussion there.

For now, this proposes to add the method WriteChunkUninit::populate(), but we might be able to find a better name?

Please note that this method is only available on uninitialized chunks because it would be unnecessary to fill the slots with their Default value just to overwrite them again with the values from the iterator.

I still have to clarify this (and probably some other things) in the docs.

[mgeier]

I've updated the documentation (rendered HTML files as ZIP: https://github.com/mgeier/rtrb/suites/3210578459/artifacts/74262447).

I think the iterator API now makes much more sense than before, but I'm still wondering if we can find a better name than populate() ...

[mgeier]

I'm still unsure whether populate() is the best name, but so far I couldn't come up with anything better.

I don't think extend() (as suggested in #56 (comment)) is good, because it sounds like the Extend trait but it has slightly different semantics (it doesn't guarantee that the iterator will be fully exhausted). Also it kinda implies that the "container" can grow, which the ring buffer cannot.

Any further ideas?

[mgeier]

As mentioned in https://users.rust-lang.org/t/how-to-name-a-function-that-takes-an-iterator-and-moves-items-into-a-non-growable-container/62522, fill_from_iter() might be a good alternative name.

[mgeier]

I've changed populate() (which isn't bad) to fill_from_iter() (which is more explicit). Rendered HTML as ZIP: https://github.com/mgeier/rtrb/suites/3344397678/artifacts/78522609.