search

mengdiwang / guava-libraries

Automatically exported from code.google.com/p/guava-libraries
Apache License 2.0
0 stars 0 forks source link

Clarify Multimaps#index's key / value order (Javadoc and example) #514

Closed GoogleCodeExporter closed 9 years ago

GoogleCodeExporter commented 9 years ago 
http://code.google.com/p/guava-libraries/source/browse/trunk/src/com/google/comm
on/collect/Multimaps.java?r=146#1661

Currently, Multimaps#index returns an ImmutableListMultimap, which has, 
according to its Javadoc, a "reliable user-specified key and value iteration 
order".

Since this return type is specified in ImmutableListMultimap#index's method 
signature, I suppose it may be considered as a part of the API's contract. The 
iteration order of the returned Multimaps' keys should thus have the same order 
as the order in which the keys are encountered when iterating on the source 
iterable, applying the keyFunction. A quick look at the source code seems to 
confirm this.

But the example given in the Javadoc is confusing. According to it:

List<String> badGuys = Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", 
"Clyde");
Function<String, Integer> stringLengthFunction = ...
Multimap<Integer, String> index = Multimaps.index(badGuys, 
stringLengthFunction);
System.out.println(index);

should print:

{4=[Inky], 5=[Pinky, Pinky, Clyde], 6=[Blinky]}

(notice that it is ordered by ordering the keys)

It didn't match my expectations, so I tested it, and it actually prints:

{4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]}

(notice that "6=[Blinky]" comes before "5=[Pinky, Pinky, Clyde]}", because 
"Blinky" (5 letters long) precedes "Pinky" (the first element in the source 
values which is 4 letters long)

It would be great if the Javadoc clarified the intent concerning the returned 
Multimap's iteration order (if it indeed is part of the method's contract?). I 
think the example should also be updated, because it is currently 
wrong/confusing.

Original issue reported on code.google.com by nev...@gmail.com on 5 Jan 2011 at 7:19

GoogleCodeExporter commented 9 years ago 
Woops... There is a small typo in my issue. I meant:

"(notice that "6=[Blinky]" comes before "5=[Pinky, Pinky, Clyde]}", because 
"Blinky" (6 letters long) precedes "Pinky" (the first element in the source 
values which is 5 letters long)
"

Original comment by nev...@gmail.com on 5 Jan 2011 at 7:21

GoogleCodeExporter commented 9 years ago 
Good point, will fix.

Original comment by kevinb@google.com on 12 Jan 2011 at 8:51

GoogleCodeExporter commented 9 years ago

Original comment by kevinb@google.com on 12 Jan 2011 at 8:52

GoogleCodeExporter commented 9 years ago

Original comment by kevinb@google.com on 27 Jan 2011 at 1:33

GoogleCodeExporter commented 9 years ago

Original comment by fry@google.com on 22 Mar 2011 at 7:09

GoogleCodeExporter commented 9 years ago

Original comment by fry@google.com on 23 Mar 2011 at 1:49

GoogleCodeExporter commented 9 years ago 
I believe this was fixed in trunk by r251:

http://code.google.com/p/guava-libraries/source/diff?spec=svn270&r=251&format=si
de&path=/trunk/src/com/google/common/collect/Multimaps.java&old_path=/trunk/src/
com/google/common/collect/Multimaps.java&old=138

So I guess this might make it into r09 :)

(I commented because I saw the various label changes on this issue)

Original comment by nev...@gmail.com on 23 Mar 2011 at 10:54

GoogleCodeExporter commented 9 years ago 
sweet!

Original comment by fry@google.com on 23 Mar 2011 at 11:36

GoogleCodeExporter commented 9 years ago 
This issue has been migrated to GitHub.

It can be found at https://github.com/google/guava/issues/<id>

Original comment by cgdecker@google.com on 1 Nov 2014 at 4:15

GoogleCodeExporter commented 9 years ago

Original comment by cgdecker@google.com on 3 Nov 2014 at 9:09