Another name of type of iterator allowed or not?

Discussion in 'C++' started by Mateusz Loskot, Dec 12, 2005.

  1. Hi,

    I have a simple question about naming convention, recommeded names or
    so in following case.
    I have a class which is implemented with one of STL container
    (aggregated) and my aim is to expose iterators to enable user of my
    class to iterate through this container content.
    Here is a piece of code:

    class A;
    class C
    {
    std::vector<A*> v;
    public:
    // ...
    typedef std::vector<Layer*>::iterator Iterator; // 1)
    Iterator Begin() { return v.begin(); } // 2)
    Iterator End() { return v.begin(); } // 3)
    }

    Obviously, in line 1) I'm declaring another (typedef) name for
    std::vector<Layer*>::iterator.
    In lines 2) and 3) I have accessor to std::vector<Layer*> iterators.

    My questions are:

    - Is it safe to rename iterator as in this example
    std::vector<T>::iterator to Iterator?
    - Is it safe to rename std::vector<T>::begin to Begin and
    std::vector<T>::end to End?
    - Are those names safe in case of using objects of C class in STL
    algorithms?
    - Any better recommendation?

    What's the purpose of those names?
    Simply, I'd like to get them more coherent with naming convention I use
    in my project.

    Cheers
    --
    Mateusz Loskot
    http://mateusz.loskot.net
     
    Mateusz Loskot, Dec 12, 2005
    #1
    1. Advertising

  2. Mateusz Loskot wrote:
    > I have a simple question about naming convention, recommeded names or
    > so in following case.
    > I have a class which is implemented with one of STL container
    > (aggregated) and my aim is to expose iterators to enable user of my
    > class to iterate through this container content.
    > Here is a piece of code:
    >
    > class A;
    > class C
    > {
    > std::vector<A*> v;
    > public:
    > // ...
    > typedef std::vector<Layer*>::iterator Iterator; // 1)
    > Iterator Begin() { return v.begin(); } // 2)
    > Iterator End() { return v.begin(); } // 3)
    > }

    ;
    ^^^
    Apparently, the semicolon is missing.

    >
    > Obviously, in line 1) I'm declaring another (typedef) name for
    > std::vector<Layer*>::iterator.
    > In lines 2) and 3) I have accessor to std::vector<Layer*> iterators.
    >
    > My questions are:
    >
    > - Is it safe to rename iterator as in this example
    > std::vector<T>::iterator to Iterator?


    You're not _renaming_ it. You're introducing a _local_ *synonym* for
    it. The locality is the scope of the 'C' class. And why do you ask?
    What could be _UN_safe about it? What are your concerns? You could
    have just used the non-capitalized version of the word, it would be
    probably simpler and more familiar for most who use iterators in
    their everyday C++ activities. Capitalization is awkward. Java-like.

    > - Is it safe to rename std::vector<T>::begin to Begin and
    > std::vector<T>::end to End?


    You're not _renaming_ anything here. You're calling 'C's members
    whatever you would like them to be called. What's all the fuss
    about?

    > - Are those names safe in case of using objects of C class in STL
    > algorithms?


    Huh... "Safe"? I still can't understand your concern with "safety"
    here. What is it you are afraid of? Example: when I say it is not
    safe to drive on a slippery road without seatbelts, I am afraid of
    the injuries that can resuld from car veering off the road and hitting
    an obstacle.

    When you use objects of your 'C' class (BTW, names consisting of one
    letter only are really "unsafe", from maintenance point of vive) with
    Standard Library algorithms, for example, 'copy' or 'transform', you
    are _forced_ to spell out your names. The Standard Library algorithms
    do _not_ expect your objects to have "begin" and "end" functions.

    > - Any better recommendation?


    Unless you actually get an error, stop asking those nonsensical
    questions. Get a drink, go out, breathe some fresh air, ventilate
    your brain (but not by drilling more holes in your head).

    > What's the purpose of those names?


    Which ones? If you're asking about your "Begin" and "End" names, then
    _we_ cannot answer your question. Those names _you_ invented. _You_
    are the one who knows their purpose.

    > Simply, I'd like to get them more coherent with naming convention I
    > use in my project.


    Conventions are just that, conventions. You agree on something. It
    doesn't have to be "like everybody else", but it doesn't necessarily
    be "unlike everybody else's". Unless you experience some _trouble_,
    stop wasting your time on trying to figure out the best convention,
    just follow _one_ (and one in the Standard Library is not the worst).

    V
     
    Victor Bazarov, Dec 12, 2005
    #2
    1. Advertising

  3. Mateusz Loskot

    Dervish Guest

    In C class you encapsulated std::vector. It has original not "STL like
    interface". It's OK - its your decision. However from my point of view
    there is a possibility of following drawbacks in future:
    1) vector have a lot of methods - if in future you decide to use more
    of them you will add them to C class. Finally C class will look like
    std::vector. Question is - whay can't you use vector from the very
    beginning?
    2) You use End() instead of end(). Experienced STL developers will hate
    you for this. Everybody knows how to iterate collection. To do this one
    use end(), begin(), iterator. And not End(), ...
    3) If you decide to remove C class (see p.1 above), you will be forced
    to replace End() to end() etc in numerous places.
     
    Dervish, Dec 12, 2005
    #3
  4. Victor Bazarov wrote
    > Mateusz Loskot wrote:
    >
    > ;
    > ^^^
    > Apparently, the semicolon is missing.


    Yes.

    > >
    > > My questions are:
    > >
    > > - Is it safe to rename iterator as in this example
    > > std::vector<T>::iterator to Iterator?

    >
    > You're not _renaming_ it.


    Yes, "rename" is unfortunate here.

    > You're introducing a _local_ *synonym* for it.


    Definitely, "synonim" the right name.

    > The locality is the scope of the 'C' class. And why do you ask?
    > What could be _UN_safe about it?


    I ask because I don't know if what I've introduced it fine or not.

    > What are your concerns? You could
    > have just used the non-capitalized version of the word, it would be
    > probably simpler and more familiar for most who use iterators in
    > their everyday C++ activities.
    > Capitalization is awkward. Java-like.


    Definitely, agreed.
    First, I have types and methods named with first letter upper case (not
    getMe but GetMe).
    I know it's awkward, so please don't ask me why I use it :) Simply, I
    have to.

    My question is of kind of this "Is that safe to use names with
    double-/single- underscore as a first character?".
    So, I hoped it will be clear why I ask.

    > > - Is it safe to rename std::vector<T>::begin to Begin and
    > > std::vector<T>::end to End?

    >
    > You're not _renaming_ anything here.


    Yes, it's confirmed. "Synonim" is the right word.

    > You're calling 'C's members
    > whatever you would like them to be called. What's all the fuss
    > about?


    OK, I'm calling a member, that's clear and I get a typedef of
    std::vector<T>::iterator, a synonim, so can I pass it to STL
    algorithms?

    Simply, is this code below OK regarding iterators usage?

    std::vector<MyClass> v;
    typedef std::vector<MyClass>::iterator ThisIsMySynonim;
    ThisIsMySynonim MyBegin() { return v.begin(); }
    ThisIsMySynonim MyEnd() { return v.end}
    std::for_each(v.MyBegin(), v.MyEnd(), FunctorDefinedSomewhere());

    > When you use objects of your 'C' class (BTW, names consisting of one
    > letter only are really "unsafe", from maintenance point of vive)


    It's a short for Usenet so the code does not occupy too much space in
    post.

    > Standard Library algorithms, for example, 'copy' or 'transform', you
    > are _forced_ to spell out your names. The Standard Library algorithms
    > do _not_ expect your objects to have "begin" and "end" functions.


    And that's what I'm asking for too. Thanks.


    > > - Any better recommendation?

    >
    > Unless you actually get an error, stop asking those nonsensical
    > questions. Get a drink, go out, breathe some fresh air, ventilate
    > your brain (but not by drilling more holes in your head).
    > [...]


    Hehe, you are definitely right. It was about 5 am so it was a good idea
    to go to bed, no discussion here.

    > > Simply, I'd like to get them more coherent with naming convention I
    > > use in my project.

    >
    > Conventions are just that, conventions. You agree on something. It
    > doesn't have to be "like everybody else", but it doesn't necessarily
    > be "unlike everybody else's". Unless you experience some _trouble_,
    > stop wasting your time on trying to figure out the best convention,
    > just follow _one_ (and one in the Standard Library is not the worst).
    >


    Hm, interesting, I've read somewhere (I cannot recall where I read it,
    may be in Scott Meyers' books, but I'm not sure now) that STL coding
    style is just for STL and should not be followed in external
    (non-STL/Standard C++) implementations. I've understood is just as
    chapter 17.4.3.1.2 from C++ Standard, as a good recommendation.
    Certainly, I may be wrong.

    Thanks for your patience!
    Cheers
    --
    Mateusz Loskot
    http://mateusz.loskot.net
     
    Mateusz Loskot, Dec 12, 2005
    #4
  5. Mateusz Loskot

    Earl Purple Guest

    Dervish wrote:
    > In C class you encapsulated std::vector. It has original not "STL like
    > interface". It's OK - its your decision. However from my point of view
    > there is a possibility of following drawbacks in future:
    > 1) vector have a lot of methods - if in future you decide to use more
    > of them you will add them to C class. Finally C class will look like
    > std::vector. Question is - whay can't you use vector from the very
    > beginning?
    > 2) You use End() instead of end(). Experienced STL developers will hate
    > you for this. Everybody knows how to iterate collection. To do this one
    > use end(), begin(), iterator. And not End(), ...
    > 3) If you decide to remove C class (see p.1 above), you will be forced
    > to replace End() to end() etc in numerous places.


    In addition C++0x may well have algorithms that automatically call
    begin() and end() for you that allow you (most algorithms are performed
    on whole collections). From that point of view you will probably want
    to stick with the begin() and end() names. You might want to also
    implement empty() and size() and const-iterators with const overloads
    of begin() and end().

    I am assuming that what you are showing is a sample and that in
    reality, your class has a more descriptive name than C and has more
    functionality than simply wrapping a vector.
     
    Earl Purple, Dec 12, 2005
    #5
  6. Mateusz Loskot

    Guest

    Mateusz Loskot wrote:
    > Hi,
    >
    > I have a simple question about naming convention, recommeded names or
    > so in following case.
    > I have a class which is implemented with one of STL container
    > (aggregated) and my aim is to expose iterators to enable user of my
    > class to iterate through this container content.
    > Here is a piece of code:
    >
    > class A;
    > class C
    > {
    > std::vector<A*> v;
    > public:
    > // ...
    > typedef std::vector<Layer*>::iterator Iterator; // 1)
    > Iterator Begin() { return v.begin(); } // 2)
    > Iterator End() { return v.begin(); } // 3)
    > }
    >
    > Obviously, in line 1) I'm declaring another (typedef) name for
    > std::vector<Layer*>::iterator.
    > In lines 2) and 3) I have accessor to std::vector<Layer*> iterators.
    >
    > My questions are:
    >
    > - Is it safe to rename iterator as in this example
    > std::vector<T>::iterator to Iterator?
    > - Is it safe to rename std::vector<T>::begin to Begin and
    > std::vector<T>::end to End?


    Sure. Don't worry too much. The iterator for int Array[N] is called
    int*, the
    begin 'function' is &Array[0] and the end is &Array[N]. The STL can
    work
    with those.

    Of course, even though the compiler doesn't care, your readers will.
    Extra
    names aren't bad, but if you don't have begin() and end(), they won't
    think
    it's a container designed to fit in the STL framework.

    HTH,
    Michiel Salters
     
    , Dec 12, 2005
    #6
  7. Earl Purple wrote:
    > Dervish wrote:
    > > In C class you encapsulated std::vector. It has original not "STL like
    > > interface". It's OK - its your decision. However from my point of view
    > > there is a possibility of following drawbacks in future:
    > > 1) vector have a lot of methods - if in future you decide to use more
    > > of them you will add them to C class. Finally C class will look like
    > > std::vector. Question is - whay can't you use vector from the very
    > > beginning?


    My collection is highly specialized, but based on std::vector or
    std::list.
    It also provides functions like MoveToTop, MoveDown, MoveUp,
    MoveToBottom etc.

    > > 2) You use End() instead of end(). Experienced STL developers will hate
    > > you for this.


    Yes, I'm affraid of that :)

    > Everybody knows how to iterate collection. To do this one
    > > use end(), begin(), iterator. And not End(), ...


    That's right. I'm pretty convinced. Thanks to Victor too.

    > > 3) If you decide to remove C class (see p.1 above), you will be forced
    > > to replace End() to end() etc in numerous places.


    Hm, may be I should hide algorithms behind methods as Scott Meyers
    suggest in his "Effective STL", suggestion 44.

    > In addition C++0x may well have algorithms that automatically call
    > begin() and end() for you that allow you (most algorithms are performed
    > on whole collections). From that point of view you will probably want
    > to stick with the begin() and end() names. You might want to also
    > implement empty() and size() and const-iterators with const overloads
    > of begin() and end().


    As I said, I become convinced ;-)
    Your arguments are clear.

    > I am assuming that what you are showing is a sample and that in
    > reality, your class has a more descriptive name than C and has more
    > functionality than simply wrapping a vector.


    That's right.

    Cheers
    --
    Mateusz Loskot
    http://mateusz.loskot.net
     
    Mateusz Loskot, Dec 12, 2005
    #7
  8. Thanks for your input.

    I'm glad that Victor pointed possible problems.
    I'd really like to have a very simply but well defined coding style.
    I've read John Lakos' book "Large-Scale C++ Software Design" and after
    this discussion here I'm a bit confused. I thought John's idea of
    coding style is very clear and simple.
    But in chapter 1.4.1.1 John states that names of types (not data or
    functions) with first letter upper-case and I tried to follow it
    writting:

    typedef std::vector<T>::iterator Iterator;
    or (whatever)
    typedef std::vector<T>::iterator MyIterator;

    But Victor reproved me for that is's inconsistent with STL naming
    convention and may confuse users of my class. And he is right :)

    Cheers
    --
    Mateusz Loskot
    http://mateusz.loskot.net
     
    Mateusz Loskot, Dec 12, 2005
    #8
  9. Mateusz Loskot wrote:
    > I'd really like to have a very simply but well defined coding style.
    > I've read John Lakos' book "Large-Scale C++ Software Design" and after
    > this discussion here I'm a bit confused. [...]


    Don't take any book as absolute truth, regardless of the number of copies
    printed/sold/given away.

    Style cannot be good by itself. As soon as you start working in a group,
    you will put your style to the test. Adjust as needed.

    Conclusion: write what feels good to read. If you like capitalisation,
    and nobody [else] who reads your code complains, keep the capitalisation.

    V
     
    Victor Bazarov, Dec 12, 2005
    #9
  10. Victor Bazarov wrote:
    > Mateusz Loskot wrote:
    > > I'd really like to have a very simply but well defined coding style.
    > > I've read John Lakos' book "Large-Scale C++ Software Design" and after
    > > this discussion here I'm a bit confused. [...]

    >
    > Don't take any book as absolute truth, regardless of the number of copies
    > printed/sold/given away.


    Yes, that's the truth what you are saying.
    But I think it's useful to have some references, examples and
    possibilities and then to develop something on my own based on that, in
    example coding style.

    >
    > Style cannot be good by itself. As soon as you start working in a group,
    > you will put your style to the test. Adjust as needed.
    >
    > Conclusion: write what feels good to read. If you like capitalisation,
    > and nobody [else] who reads your code complains, keep the capitalisation.
    >


    Yes, you are right again.
    My major aim is to develop coding style as much consistent as possible.
    So, I'd like to avoid mutually exclusive rules and occurences like
    those:

    1) Rule: Every type starts with capital letter
    2) Next, I have my library strongly based on STL and I'd like to
    provide STL coherent interface so I have in one of my class:

    class A
    {
    public:
    typedef std::string::size_type size_type;
    size_type size() const;
    };

    And here size_type breaks the rule defined in 1).
    Yes, according to this rule in 1) I could write:

    typedef std::string::size_type SizeType;
    SizeType size() const;

    But, users of my library learn (from documentation etc.) that
    collection-like or collection composition classes in my library provide
    number of elements through size() function, just like STL std::vector
    or std::string does it and the type of return value is ....size_type
    but not ...SizeType.
    Simply, it breaks inconsistency, doesn't it?
    I hope I provide clear example now.

    Cheers
    --
    Mateusz Loskot
    http://mateusz.loskot.net
     
    Mateusz Loskot, Dec 12, 2005
    #10
  11. Mateusz Loskot wrote:
    > My major aim is to develop coding style as much consistent as
    > possible. So, I'd like to avoid mutually exclusive rules and
    > occurences like those:
    >
    > 1) Rule: Every type starts with capital letter
    > 2) Next, I have my library strongly based on STL and I'd like to
    > provide STL coherent interface so I have in one of my class:
    >
    > class A
    > {
    > public:
    > typedef std::string::size_type size_type;
    > size_type size() const;
    > };
    >
    > And here size_type breaks the rule defined in 1).
    > Yes, according to this rule in 1) I could write:
    >
    > typedef std::string::size_type SizeType;
    > SizeType size() const;
    >
    > But, users of my library learn (from documentation etc.) that
    > collection-like or collection composition classes in my library
    > provide number of elements through size() function, just like STL
    > std::vector or std::string does it and the type of return value is
    > ....size_type but not ...SizeType.
    > Simply, it breaks inconsistency, doesn't it?
    > I hope I provide clear example now.


    It is rather difficult to come up with a set of rules in which following
    any one does not cause breaking another. Just think of the Three Laws
    of Robotics. Something has to be superior. In your case, you can say

    1. Naming convention shall be consistent with the rest of the used
    source code (library source in the form of headers included)
    2. Types shall be capitalized unless it violates rule 1.

    In general, don't waste your time trying to come up with rules. Better
    spend your time learning the existing rules, like those of the language.

    Victor
     
    Victor Bazarov, Dec 13, 2005
    #11
  12. As I said, I'm convinced and your comments are very instructive.
    I like those 2 rules you've introduced ;-)
    Thanks
    --
    Mateusz Loskot
    http://mateusz.loskot.net
     
    Mateusz Loskot, Dec 13, 2005
    #12
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Michal Nazarewicz

    conversion from const type* to type* allowed?

    Michal Nazarewicz, Jan 4, 2007, in forum: C Programming
    Replies:
    13
    Views:
    565
    Eric Sosman
    Jan 5, 2007
  2. David Bilsby
    Replies:
    5
    Views:
    2,047
    David Bilsby
    Oct 9, 2007
  3. Replies:
    9
    Views:
    529
    James Kanze
    Mar 4, 2008
  4. Replies:
    3
    Views:
    4,809
  5. Iñaki Baz Castillo
    Replies:
    13
    Views:
    502
    Iñaki Baz Castillo
    May 1, 2011
Loading...

Share This Page