[rust-dev] RFC: Iterator naming convention

Palmer Cox palmercox at gmail.com
Fri Jan 3 20:33:04 PST 2014


I said I was giving up on this in my last message. However, I decided to
give it one more go. Details are at
https://github.com/mozilla/rust/pull/11001.

-Palmer Cox


On Fri, Dec 27, 2013 at 1:50 AM, Palmer Cox <palmercox at gmail.com> wrote:

> So,
>
> The rules that I tried to concoct don't really work. I don't know what to
> do with something like BitvIterator. Rename it to BitvElements? Anyway, I'm
> thinking of amending my pull request to just rename the *Iter structs to
> *Iterator and leave the rest alone.
>
> Thoughts?
>
> I pulled together what I believe is the full list of iterators in Rust as
> of f74b8f0d3a90fd3b64afa38b9470d9a45cd04ee9. If someone has a better
> suggestion of how to unify their naming, I'm happy to do it.
>
> +------------------------------------------+---------------------------+
> | File                                     | Name                      |
> +------------------------------------------+---------------------------+
> | src/libextra/bitv.rs                     | BitvIterator              |
> +------------------------------------------+---------------------------+
> | src/libextra/bitv.rs                     | BitvSetIterator           |
> +------------------------------------------+---------------------------+
> | src/libextra/dlist.rs                    | DListIterator             |
> +------------------------------------------+---------------------------+
> | src/libextra/dlist.rs                    | MutDListIterator          |
> +------------------------------------------+---------------------------+
> | src/libextra/dlist.rs                    | MoveIterator              |
> +------------------------------------------+---------------------------+
> | src/libextra/enum_set.rs                 | EnumSetIterator           |
> +------------------------------------------+---------------------------+
> | src/libextra/glob.rs                     | GlobIterator              |
> +------------------------------------------+---------------------------+
> | src/libextra/priority_queue.rs           | PriorityQueueIterator     |
> +------------------------------------------+---------------------------+
> | src/libextra/ringbuf.rs                  | RingBufIterator           |
> +------------------------------------------+---------------------------+
> | src/libextra/ringbuf.rs                  | RingBufMutIterator        |
> +------------------------------------------+---------------------------+
> | src/libextra/smallintmap.rs              | SmallIntMapIterator       |
> +------------------------------------------+---------------------------+
> | src/libextra/smallintmap.rs              | SmallIntMapMutIterator    |
> +------------------------------------------+---------------------------+
> | src/libextra/smallintmap.rs              | SmallIntMapRevIterator    |
> +------------------------------------------+---------------------------+
> | src/libextra/smallintmap.rs              | SmallIntMapMutRevIterator |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | TreeMapIterator           |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | TreeMapRevIterator        |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | TreeMapMoveIterator       |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | TreeSetIterator           |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | TreeSetRevIterator        |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | Difference                |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | SymDifference             |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | Intersection              |
> +------------------------------------------+---------------------------+
> | src/libextra/treemap.rs                  | Union                     |
> +------------------------------------------+---------------------------+
> | src/librustc/middle/trans/basic_block.rs | PredIterator              |
> +------------------------------------------+---------------------------+
> | src/librustc/middle/trans/value.rs       | UserIterator              |
> +------------------------------------------+---------------------------+
> | src/librustpkg/package_id.rs             | Prefixes                  |
> +------------------------------------------+---------------------------+
> | src/libstd/c_str.rs                      | CStringIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/comm/mod.rs                   | PortIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/comm/select.rs                | PacketIterator            |
> +------------------------------------------+---------------------------+
> | src/libstd/either.rs                     | Lefts                     |
> +------------------------------------------+---------------------------+
> | src/libstd/either.rs                     | Rights                    |
> +------------------------------------------+---------------------------+
> | src/libstd/fmt/parse.rs                  | Parser                    |
> +------------------------------------------+---------------------------+
> | src/libstd/hashmap.rs                    | HashMapIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/hashmap.rs                    | HashMapMutIterator        |
> +------------------------------------------+---------------------------+
> | src/libstd/hashmap.rs                    | HashMapMoveIterator       |
> +------------------------------------------+---------------------------+
> | src/libstd/hashmap.rs                    | HashSetIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/hashmap.rs                    | HashSetMoveIterator       |
> +------------------------------------------+---------------------------+
> | src/libstd/hashmap.rs                    | SetAlgebraIter            |
> +------------------------------------------+---------------------------+
> | src/libstd/io/extensions.rs              | ByteIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/io/fs.rs                      | WalkIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/io/mod.rs                     | LineIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/io/mod.rs                     | IncomingIterator          |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Invert                    |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | ByRef                     |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Cycle                     |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Chain                     |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Zip                       |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Map                       |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Filter                    |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | FilterMap                 |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Enumerate                 |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Peekable                  |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | SkipWhile                 |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | TakeWhile                 |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Skip                      |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Take                      |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Scan                      |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | FlatMap                   |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Fuse                      |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Inspect                   |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Unfold                    |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Counter                   |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Range                     |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | RangeInclusive            |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | RangeStep                 |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | RangeStepInclusive        |
> +------------------------------------------+---------------------------+
> | src/libstd/iter.rs                       | Repeat                    |
> +------------------------------------------+---------------------------+
> | src/libstd/option.rs                     | OptionIterator            |
> +------------------------------------------+---------------------------+
> | src/libstd/path/posix.rs                 | ComponentIter             |
> +------------------------------------------+---------------------------+
> | src/libstd/path/posix.rs                 | RevComponentIter          |
> +------------------------------------------+---------------------------+
> | src/libstd/path/posix.rs                 | StrComponentIter          |
> +------------------------------------------+---------------------------+
> | src/libstd/path/posix.rs                 | RevStrComponentIter       |
> +------------------------------------------+---------------------------+
> | src/libstd/path/windows.rs               | StrComponentIter          |
> +------------------------------------------+---------------------------+
> | src/libstd/path/windows.rs               | RevStrComponentIter       |
> +------------------------------------------+---------------------------+
> | src/libstd/path/windows.rs               | ComponentIter             |
> +------------------------------------------+---------------------------+
> | src/libstd/path/windows.rs               | RevComponentIter          |
> +------------------------------------------+---------------------------+
> | src/libstd/rt/task.rs                    | BlockedTaskIterator       |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | CharIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | CharOffsetIterator        |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | CharSplitIterator         |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | CharSplitNIterator        |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | MatchesIndexIterator      |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | StrSplitIterator          |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | NormalizationIterator     |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | CharRevIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | CharOffsetRevIterator     |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | ByteIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | ByteRevIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | CharRSplitIterator        |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | WordIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/str.rs                        | AnyLineIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/trie.rs                       | TrieMapIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/trie.rs                       | TrieSetIterator           |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | SplitIterator             |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | RSplitIterator            |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | ElementSwaps              |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | Permutations              |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | WindowIter                |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | ChunkIter                 |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | VecIterator               |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | VecMutIterator            |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | MutSplitIterator          |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | MutChunkIter              |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | MoveIterator              |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | RevIterator               |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | MutRevIterator            |
> +------------------------------------------+---------------------------+
> | src/libstd/vec.rs                        | MoveRevIterator           |
> +------------------------------------------+---------------------------+
> | src/libsyntax/opt_vec.rs                 | OptVecIterator            |
> +------------------------------------------+---------------------------+
> | src/libsyntax/util/small_vector.rs       | SmallVectorMoveIterator   |
> +------------------------------------------+---------------------------+
>
> Thanks,
> -Palmer Cox
>
>
>
> On Sat, Dec 21, 2013 at 11:35 PM, Palmer Cox <palmercox at gmail.com> wrote:
>
>> Due to type inference, my assumption is that in many cases the only
>> people that see the actual type names are the developers creating them and
>> people reading the docs. I hadn't though about the Reader / Port cases, but
>> those do seem like pretty reasonable places where you might want to have an
>> object implement Iterator in addition to other traits.
>>
>> So, if the decision is no suffixes, what do we do with all of the
>> existing Iterators that have suffixes? Strip them? Maybe the rule of thumb
>> should look something like this:
>>
>> 1. If you are implementing a struct that only implements the Iterator
>> trait, make the name plural, but don't use the Iterator suffix. eg: Chunks
>> 2. If you are implementing a struct that implements traits in addition to
>> Iterator, there is no need to make it plural. eg: Port / Reader
>>
>> If that's the general rule of thumb, then SplitIterator becomes Splits
>> and MutChunkIter becomes MutChunks. I guess that means that
>> DoubleEndedIterator also becomes just DoubledEnded. That seems reasonable
>> to me, since it fits it better with the ExactSize trait also defined in the
>> iter module. That doesn't really directly solve my issue with Map from the
>> iter module being confusing. If its referenced as iter::Map, its
>> not confusing of course, but at least some of the current code doesn't do
>> that and there isn't any way to force future code to do so. Its probably
>> not a huge deal, though.
>>
>> Does that sound like the general opinion?
>>
>> -Palmer Cox
>>
>>
>>
>>
>>
>> On Sat, Dec 21, 2013 at 8:43 PM, Eric Reed <ecreed at cs.washington.edu>wrote:
>>
>>> I prefer the 'no suffix' option and generally agree with Alex.
>>> Iterators aren't special and their iterator behavior is already denoted
>>> by implementing the Iterator trait.
>>>
>>> Frankly, aside from documentation where it is clear that something is an
>>> iterator, I'm not sure when a user would even see concrete iterator types.
>>> I can't think of a reason why you'd ever want to restrict the type of a
>>> variable to a specific kind of iterator (i.e. Map or Union).
>>>
>>> Acceptor and Port could implement Iterator directly, but currently they
>>> create a struct containing only a mutable borrow of themselves to prevent
>>> anything else from using the socket/channel in the meantime.
>>> Reader could directly implement an Iterator that does one byte reads,
>>> but currently it does the same trick as Acceptor and Port.
>>> You only need a separate Iterator object if you actually require
>>> additional state or if you want to prevent others from changing the
>>> underlying source (mutable borrow of self).
>>>
>>>
>>>
>>> On Sat, Dec 21, 2013 at 4:35 PM, Kevin Cantu <me at kevincantu.org> wrote:
>>>
>>>> Rust's standard libs are still pretty thin on their trait hierarchies,
>>>> but I'm sure this will change.
>>>>
>>>> Kevin
>>>>
>>>> On Sat, Dec 21, 2013 at 1:30 PM, Palmer Cox <palmercox at gmail.com>
>>>> wrote:
>>>> > Are there examples of structs that implement Iterator that also
>>>> implement
>>>> > other non-Iterator related traits? Although its possible to do that,
>>>> I can't
>>>> > think of a use case for it off the top of my head. An Iterator
>>>> basically
>>>> > represents the state of an ongoing computation and once that
>>>> computation is
>>>> > completed, the object is mostly uselss. It seems like it would be
>>>> awkward to
>>>> > implement other traits for such an object. Maybe I'm not thinking of
>>>> > something, however.
>>>> >
>>>> > -Palmer Cox
>>>> >
>>>> >
>>>> >
>>>> > On Sat, Dec 21, 2013 at 4:24 PM, Kevin Cantu <me at kevincantu.org>
>>>> wrote:
>>>> >>
>>>> >> Iterators are just structs which implement the "Iterator" or a
>>>> related
>>>> >> trait, right?
>>>> >>
>>>> >> These structs which do can also implement lots of other traits, too:
>>>> >> no reason to make -Iter special.
>>>> >>
>>>> >>
>>>> >> Kevin
>>>> >>
>>>> >>
>>>> >>
>>>> >> On Sat, Dec 21, 2013 at 12:50 PM, Palmer Cox <palmercox at gmail.com>
>>>> wrote:
>>>> >> > I'm not a big fan of Hungarian notation either. I'm not sure that
>>>> having
>>>> >> > a
>>>> >> > naming convention for Iterators is Hungarian notation, however. For
>>>> >> > example,
>>>> >> > if you are doing Windows programming, you'll see stuff like:
>>>> >> >
>>>> >> > DWORD dwFoo = 0;
>>>> >> >
>>>> >> > In this case, the "dw" prefix on the variable indicates that we
>>>> have a
>>>> >> > DWORD
>>>> >> > variable. However, the Iterator suffix that I'm proposing here is a
>>>> >> > suffix
>>>> >> > on the type names, not the actual variable names. So, if you are
>>>> writing
>>>> >> > Rust code, you'd write something like this:
>>>> >> >
>>>> >> > let chunks = some_vector.chunks(50);
>>>> >> >
>>>> >> > So, the actual variable name doesn't have the Hungarian notation
>>>> and the
>>>> >> > types aren't even generally visible since the compiler infers much
>>>> of
>>>> >> > that.
>>>> >> > However, someone reading through the documentation and/or code
>>>> will see
>>>> >> > a
>>>> >> > struct named ChunkIterator and instance know how the struct
>>>> behaves - as
>>>> >> > an
>>>> >> > Iterator. So, I think the suffix serves less to describe the
>>>> datatype
>>>> >> > and
>>>> >> > more to describe class of behavior that the struct implements.
>>>> >> >
>>>> >> > Anyway, as I said, I prefer #1. But, I also have done lots of Java
>>>> >> > programming so I'm probably much more used to verbosity than
>>>> others. I'm
>>>> >> > not
>>>> >> > horribly against some sort of other naming convention, either, of
>>>> >> > course,
>>>> >> > but I would like to see some consistency.
>>>> >> >
>>>> >> > My main motivation for opening the request was because I created
>>>> >> > MutChunkIter and then realized that it was named differently than
>>>> >> > majority
>>>> >> > of other Iterators. I don't want to be responsible for someone
>>>> reading
>>>> >> > through the docs and seeing something thats inconsistent for no
>>>> good
>>>> >> > reason!
>>>> >> > Also, I was reading through some code and happened upon a "Map"
>>>> and was
>>>> >> > exceptionally confused about it, until I realized it was iter::Map
>>>> as
>>>> >> > opposed to container::Map. I figured I probably wasn't the only
>>>> person
>>>> >> > that
>>>> >> > was going to be confused by something like this.
>>>> >> >
>>>> >> > -Palmer Cox
>>>> >> >
>>>> >> >
>>>> >> >
>>>> >> >
>>>> >> >
>>>> >> > On Sat, Dec 21, 2013 at 3:14 PM, Kevin Cantu <me at kevincantu.org>
>>>> wrote:
>>>> >> >>
>>>> >> >> IMHO Hungarian notation is for things the type system and tooling
>>>> >> >> cannot deal with.  I'm not sure this is one of them...
>>>> >> >>
>>>> >> >>
>>>> >> >> Kevin
>>>> >> >
>>>> >> >
>>>> >
>>>> >
>>>> _______________________________________________
>>>> Rust-dev mailing list
>>>> Rust-dev at mozilla.org
>>>> https://mail.mozilla.org/listinfo/rust-dev
>>>>
>>>
>>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.mozilla.org/pipermail/rust-dev/attachments/20140103/5c297ac0/attachment-0001.html>


More information about the Rust-dev mailing list