How to name a function that takes an iterator and moves items into a non-growable container?

In the current version of my crate rtrb I am providing an iterator-based API for reading &T and writing to &mut T (and also to &mut MaybeUninit<T>).

However, I think it would be better to move those items instead of working with references. Changing the "reading" iterator from producing &T to producing T is kinda straightforward, but for the "writing" side I've changed the &mut T producing iterator into a method that takes an iterator that itself produces T items.

I've implemented this in a PR:

For now, I've named the method populate(), but maybe there is a better name?

Is there a precedent for such a function?

If the underlying container would be able to grow, I would of course implement the Extend trait, but that's not the case.

Currently, the function signature looks like this:

    pub fn populate<I>(self, iter: I) -> usize
    where
        I: IntoIterator<Item = T>;

Instead of growing the underlying container, it just stops reading from the iterator when the available storage is full (or when the given iterator is exhausted) and returns the number of moved items.

I was thinking about calling it fill(), but this might be confused with slice::fill(), which only takes a single item and clones it multiple times until the slice is filled.

Any other suggestions?

I wonder if you can use std::iter::Extend trait here:

https://doc.rust-lang.org/stable/std/iter/trait.Extend.html

Your API has a slightly different shape, but perhaps the extend signature would work as well?

Although, this might be stretching Extend's use case to far, as extend usually fully exhausts the iterator.

Thanks for the suggestion, I've actually mentioned Extend in my original question. I think it suggests that the container is growable, which isn't true in my case.

I've looked for alternatives to populate(), and I only found replenish(), but I'm not sure whether that would make sense (I'm not a native speaker).

I had another idea: I could call it fill_from_iter(). The call site would look something like this:

my_chunk.fill_from_iter(my_iterator);

or:

my_chunk.fill_from_iter([1, 2, 3, 4]);

or with the possibility to continue to use the iterator afterwards if it hasn't been exhausted:

my_chunk.fill_from_iter(&mut my_iterator);

The name is an amalgamation of:

Would that make sense?

I quite like populate, and fill_from_iter is good, too. Both are very readable in my opinion.

1 Like