Google Collections ImmutableMap iteration order

To be more precise, the ImmutableMap factory methods and builder return instances that follow the iteration order of the inputs provided when the map in constructed. However, an ImmutableSortedMap, which is a subclass of ImmutableMap. sorts the keys.

You should believe the javadoc. If it is not enough, read the source code or report the bug.

A quick view to the source code shows that the map is backed by array and iteration will be done through ImmutableSet that is also backed by an array. So I think the documentation is correct and the order of the elements will be kept as it is.

I've actually found discussion about this, with answers from library authors:

Kevin Bourrillion: What we mean by "user-specified" is "it can be whatever order you want it to be"; in other words, whatever order you provide the entries to us in the first place, that's the order we use.

Jared Levy: You can also copy a TreeMap or LinkedHashMap that have the desired order.

Yes, I should have believed the javadoc, although I think that javadoc can be better in this case. It seems I'm not first who was confused by it. If nothing else, this Q/A will help Google next time someone searches for "ImmutableMap iteration" :-)