Skip to content
  • Categories
  • Recent
  • Tags
  • Popular
  • Users
  • Groups
  • Search
  • Get Qt Extensions
  • Unsolved
Collapse
Brand Logo
  1. Home
  2. Qt Development
  3. General and Desktop
  4. Misleading documentation of QHash/QMap?
Forum Updated to NodeBB v4.3 + New Features

Misleading documentation of QHash/QMap?

Scheduled Pinned Locked Moved Solved General and Desktop
12 Posts 6 Posters 982 Views 4 Watching
  • Oldest to Newest
  • Newest to Oldest
  • Most Votes
Reply
  • Reply as topic
Log in to reply
This topic has been deleted. Only users with topic management privileges can see it.
  • JonBJ Online
    JonBJ Online
    JonB
    wrote on last edited by
    #1

    I am troubled by the same sentence which the docs use for the behaviour of QHash/QMap. In the Detailed Description, second sentence, they both state:

    It stores (key, value) pairs and provides fast lookup of the value associated with a key.

    The more I read this the more I find it misleading. They do not supply "fast lookup of the value associated with a key". It is true that once the key has been located it's immediate to return the associated value, but that is also true of, say, a linear search of an array/vector: once you have spent time locating the right index/key the associated value is immediately available.

    There is the method const Key QMap::key(const T &value, const Key &defaultKey = Key()) const which does indeed lookup a value in the map. And that correctly states:

    Returns the first key with value value
    This function can be slow (linear time), because QMap's internal data structure is optimized for fast lookup by key, not by value.

    So looking up a value is slow, not fast, as I would expect.

    Does anyone else think the wording in Detailed Description is unfortunately misleading? I would have documented by a sentence like:

    It stores (key, value) pairs and provides fast lookup of a key.

    Plain and simple, no mention of "value".

    jsulmJ JKSHJ 2 Replies Last reply
    0
    • kkoehneK Offline
      kkoehneK Offline
      kkoehne
      Moderators
      wrote on last edited by
      #5

      I filed your suggestion at https://codereview.qt-project.org/c/qt/qtbase/+/327545 .

      Director R&D, The Qt Company

      JonBJ 1 Reply Last reply
      1
      • JonBJ JonB

        I am troubled by the same sentence which the docs use for the behaviour of QHash/QMap. In the Detailed Description, second sentence, they both state:

        It stores (key, value) pairs and provides fast lookup of the value associated with a key.

        The more I read this the more I find it misleading. They do not supply "fast lookup of the value associated with a key". It is true that once the key has been located it's immediate to return the associated value, but that is also true of, say, a linear search of an array/vector: once you have spent time locating the right index/key the associated value is immediately available.

        There is the method const Key QMap::key(const T &value, const Key &defaultKey = Key()) const which does indeed lookup a value in the map. And that correctly states:

        Returns the first key with value value
        This function can be slow (linear time), because QMap's internal data structure is optimized for fast lookup by key, not by value.

        So looking up a value is slow, not fast, as I would expect.

        Does anyone else think the wording in Detailed Description is unfortunately misleading? I would have documented by a sentence like:

        It stores (key, value) pairs and provides fast lookup of a key.

        Plain and simple, no mention of "value".

        jsulmJ Offline
        jsulmJ Offline
        jsulm
        Lifetime Qt Champion
        wrote on last edited by
        #2

        @JonB Don't understand the problem to be honest :-) Usually you want to get the value associated with a specific key and that is fast when using QMap/QHash. But I'm not English native speaker :-)

        https://forum.qt.io/topic/113070/qt-code-of-conduct

        JonBJ 1 Reply Last reply
        1
        • jsulmJ jsulm

          @JonB Don't understand the problem to be honest :-) Usually you want to get the value associated with a specific key and that is fast when using QMap/QHash. But I'm not English native speaker :-)

          JonBJ Online
          JonBJ Online
          JonB
          wrote on last edited by JonB
          #3

          @jsulm
          Well there you are. I find the phrase

          provides fast lookup of the value associated with a key.

          very strange/misleading --- it implies the fast lookup is by value --- compared against the simpler

          provides fast lookup of a key.

          I had a look at, say, https://en.cppreference.com/w/cpp/container/map

          std::map is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function Compare. Search, removal, and insertion operations have logarithmic complexity.

          No problem for me here, as the text does not try to say anything about fast lookup of the value associated with a key.

          Maybe the Qt docs were not aimed at native English speakers :)

          jsulmJ fcarneyF 2 Replies Last reply
          0
          • JonBJ JonB

            @jsulm
            Well there you are. I find the phrase

            provides fast lookup of the value associated with a key.

            very strange/misleading --- it implies the fast lookup is by value --- compared against the simpler

            provides fast lookup of a key.

            I had a look at, say, https://en.cppreference.com/w/cpp/container/map

            std::map is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function Compare. Search, removal, and insertion operations have logarithmic complexity.

            No problem for me here, as the text does not try to say anything about fast lookup of the value associated with a key.

            Maybe the Qt docs were not aimed at native English speakers :)

            jsulmJ Offline
            jsulmJ Offline
            jsulm
            Lifetime Qt Champion
            wrote on last edited by
            #4

            @JonB said in Misleading documentation of QHash/QMap?:

            Maybe the Qt docs were not aimed at native English speakers :)

            It probably was written by a non-native speaker :-)

            https://forum.qt.io/topic/113070/qt-code-of-conduct

            1 Reply Last reply
            1
            • kkoehneK Offline
              kkoehneK Offline
              kkoehne
              Moderators
              wrote on last edited by
              #5

              I filed your suggestion at https://codereview.qt-project.org/c/qt/qtbase/+/327545 .

              Director R&D, The Qt Company

              JonBJ 1 Reply Last reply
              1
              • kkoehneK kkoehne

                I filed your suggestion at https://codereview.qt-project.org/c/qt/qtbase/+/327545 .

                JonBJ Online
                JonBJ Online
                JonB
                wrote on last edited by JonB
                #6

                @kkoehne
                Thanks, you're a gent :) Maybe it's just me! Marking yours as solution.

                P.S.
                Though how you're a Moderator with 120 posts, in 10 years, I'm not sure ;-)

                1 Reply Last reply
                0
                • kkoehneK Offline
                  kkoehneK Offline
                  kkoehne
                  Moderators
                  wrote on last edited by
                  #7

                  Heh :) I got the Moderator's badge a while ago, when I was for some months the official TQtC contact person for the forum.

                  Director R&D, The Qt Company

                  1 Reply Last reply
                  1
                  • JonBJ JonB

                    I am troubled by the same sentence which the docs use for the behaviour of QHash/QMap. In the Detailed Description, second sentence, they both state:

                    It stores (key, value) pairs and provides fast lookup of the value associated with a key.

                    The more I read this the more I find it misleading. They do not supply "fast lookup of the value associated with a key". It is true that once the key has been located it's immediate to return the associated value, but that is also true of, say, a linear search of an array/vector: once you have spent time locating the right index/key the associated value is immediately available.

                    There is the method const Key QMap::key(const T &value, const Key &defaultKey = Key()) const which does indeed lookup a value in the map. And that correctly states:

                    Returns the first key with value value
                    This function can be slow (linear time), because QMap's internal data structure is optimized for fast lookup by key, not by value.

                    So looking up a value is slow, not fast, as I would expect.

                    Does anyone else think the wording in Detailed Description is unfortunately misleading? I would have documented by a sentence like:

                    It stores (key, value) pairs and provides fast lookup of a key.

                    Plain and simple, no mention of "value".

                    JKSHJ Online
                    JKSHJ Online
                    JKSH
                    Moderators
                    wrote on last edited by
                    #8

                    @JonB To me, "look up a value" usually means "use this key/index to retrieve the value".

                    • https://en.wikipedia.org/wiki/Associative_array says, "In computer science, an associative array, map, symbol table, or dictionary is an abstract data type composed of a collection of (key, value) pairs.... Operations associated with this data type allow... the lookup of a value associated with a particular key"
                    • https://en.cppreference.com/w/cpp/container/map has a section labelled "Lookup" whose main operation is "finds element with specific key"

                    That's what I'm used to, so the current QHash/QMap documentation sounds right to me. Do you have any examples a different way of using "lookup"?

                    Qt Doc Search for browsers: forum.qt.io/topic/35616/web-browser-extension-for-improved-doc-searches

                    JonBJ 1 Reply Last reply
                    2
                    • JKSHJ JKSH

                      @JonB To me, "look up a value" usually means "use this key/index to retrieve the value".

                      • https://en.wikipedia.org/wiki/Associative_array says, "In computer science, an associative array, map, symbol table, or dictionary is an abstract data type composed of a collection of (key, value) pairs.... Operations associated with this data type allow... the lookup of a value associated with a particular key"
                      • https://en.cppreference.com/w/cpp/container/map has a section labelled "Lookup" whose main operation is "finds element with specific key"

                      That's what I'm used to, so the current QHash/QMap documentation sounds right to me. Do you have any examples a different way of using "lookup"?

                      JonBJ Online
                      JonBJ Online
                      JonB
                      wrote on last edited by JonB
                      #9

                      @JKSH
                      I seem to have said my piece.

                      "Fast lookup of/by key" is unambiguous.

                      "Fast lookup of the value associated with a key" is at least potentially ambiguous. It could be taken as "you can speedily look up the key from the value". I had to find the QMap::key() method to verify it did not work like that. If QMap did provide that as fast look up by value, I could easily document that with the phrase "Fast lookup of the value associated with a key".

                      @kkoehne has filed my suggestion. Where doubtless it will sit till Hell freezes over. So I'm content :)

                      kshegunovK 1 Reply Last reply
                      0
                      • JonBJ JonB

                        @JKSH
                        I seem to have said my piece.

                        "Fast lookup of/by key" is unambiguous.

                        "Fast lookup of the value associated with a key" is at least potentially ambiguous. It could be taken as "you can speedily look up the key from the value". I had to find the QMap::key() method to verify it did not work like that. If QMap did provide that as fast look up by value, I could easily document that with the phrase "Fast lookup of the value associated with a key".

                        @kkoehne has filed my suggestion. Where doubtless it will sit till Hell freezes over. So I'm content :)

                        kshegunovK Offline
                        kshegunovK Offline
                        kshegunov
                        Moderators
                        wrote on last edited by kshegunov
                        #10

                        @JonB said in Misleading documentation of QHash/QMap?:

                        @kkoehne has filed my suggestion. Where doubtless it will sit till Hell freezes over. So I'm content :)

                        Not for this minor stuff and not on gerrit. If he'd filed it in JIRA I'd have been long gone before it was ultimately closed by a bot.
                        ... but I'm not giving it +1 ... I thrive on confusing and hard to understand things (and stuff, and things) ... ;)

                        Read and abide by the Qt Code of Conduct

                        1 Reply Last reply
                        0
                        • JonBJ JonB

                          @jsulm
                          Well there you are. I find the phrase

                          provides fast lookup of the value associated with a key.

                          very strange/misleading --- it implies the fast lookup is by value --- compared against the simpler

                          provides fast lookup of a key.

                          I had a look at, say, https://en.cppreference.com/w/cpp/container/map

                          std::map is a sorted associative container that contains key-value pairs with unique keys. Keys are sorted by using the comparison function Compare. Search, removal, and insertion operations have logarithmic complexity.

                          No problem for me here, as the text does not try to say anything about fast lookup of the value associated with a key.

                          Maybe the Qt docs were not aimed at native English speakers :)

                          fcarneyF Offline
                          fcarneyF Offline
                          fcarney
                          wrote on last edited by
                          #11

                          @JonB said in Misleading documentation of QHash/QMap?:

                          provides fast lookup of a key.

                          Sounds like looking up the key itself.

                          I am a native speaker and the phrase "It stores (key, value) pairs and provides fast lookup of the value associated with a key." seems unambiguous. Maybe it seems that way because my assumptions about what "key" and "value" mean in this context.

                          C++ is a perfectly valid school of magic.

                          kshegunovK 1 Reply Last reply
                          0
                          • fcarneyF fcarney

                            @JonB said in Misleading documentation of QHash/QMap?:

                            provides fast lookup of a key.

                            Sounds like looking up the key itself.

                            I am a native speaker and the phrase "It stores (key, value) pairs and provides fast lookup of the value associated with a key." seems unambiguous. Maybe it seems that way because my assumptions about what "key" and "value" mean in this context.

                            kshegunovK Offline
                            kshegunovK Offline
                            kshegunov
                            Moderators
                            wrote on last edited by
                            #12

                            @fcarney said in Misleading documentation of QHash/QMap?:

                            I am a native speaker

                            Yes, as is he, so settle it out like real men! ;P

                            Read and abide by the Qt Code of Conduct

                            1 Reply Last reply
                            1

                            • Login

                            • Login or register to search.
                            • First post
                              Last post
                            0
                            • Categories
                            • Recent
                            • Tags
                            • Popular
                            • Users
                            • Groups
                            • Search
                            • Get Qt Extensions
                            • Unsolved