Misleading documentation of QHash/QMap?
-
@jsulm
Well there you are. I find the phraseprovides 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 :)
-
@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 :-)
-
I filed your suggestion at https://codereview.qt-project.org/c/qt/qtbase/+/327545 .
-
Heh :) I got the Moderator's badge a while ago, when I was for some months the official TQtC contact person for the forum.
-
@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"?
-
@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. IfQMap
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 :)
-
@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) ... ;) -
@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.
-
@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