Google Collections ImmutableMap iteration order

Question

I need combination of Google Collection ImmutableMap and LinkedHashMap — immutable map with defined iteration order. It seems that ImmutableMap itself actually has defined iteration order, at least its documentation says:

An immutable, hash-based Map with reliable user-specified iteration order.

However there are no more details. Quick test shows that this might be true, but I want to make sure.

My question is: can I rely on iteration order of ImmutableMap? If I do ImmutableMap.copyOf(linkedHashMap), will it have same iteration order as original linked hash map? What about immutable maps created by builder? Some link to authoritative answer would help, since Google didn't find anything useful. (And no, links to the sources don't count).

Answer 1

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.

Answer 2

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" :-)