Implement has().exactly(...) (.inOrder()) about truth HOT 11 CLOSED

Also, Christian notes that iteratesAs is clearly implemented in terms of an iterator but that has().exactly(...).inOrder() might use get() or other methods (though I think we'd need at least a fallback to an iterator for non-List collections with guaranteed order, such as the Guava immutable collections or LinkedHashSet).

from truth.

so... has().exactly(foo, bar) is doable, and, as you point out, is in existing subjects commented out. I wanted to tease out the differences, and get the names right.

has().exactly(a, b) means contains all and only a and b, but without any necessary guarantee of order.

has().exactly(a, b).inOrder() would do the same, but also assert an identical order.

The key questions I have are...

1. is "exactly" the right word for this? I considered "only" and "allAndOnly". exactly could imply the order guarantee accidentally.
2. For any collection that has an order guarantee, will it always also have an iteration order guarantee?
   • If yes, then we can implement inOrder() by calling back to iteratesAs().
   • If foo.iterator() will not always (for ordered collections where inOrder() is viable) match foo.get(0)...foo.get(n), then the two implementations should differ, to ensure that it is testing the correct thing and only claiming the assertion it's implementing.

from truth.

heh. Scooped me, chris. :D

from truth.

Also, we might need to move has() version that contains inOrder() down to List (or custom ordered type subjects) in order to avoid having unordered Sets accidentally provide the inOrder() constraint - something they can't guarantee at the level of the Set<T> contract.

from truth.

"exactly" was the name that came to my mind before I saw the commented-out version in the source. "only," I worry, has the same inverse problem of "allOf": If I say "This collection contains only integers," I don't necessarily mean that it contains all integers.

As far as order guarantees and iteration-order guarantees go, I think of the two as being the same thing. I can't think of any counterexamples.

Finally, when it comes to List/Set inOrder() methods, I would like to see inOrder() available on Set (and, for that matter, on Collection -- and I wouldn't object to Iterable, either, though I don't have a use case in mind). As Kevin(?) once observed, most Set implementations guarantee order -- EnumSet, LinkedHashSet, TreeSet, and of course ImmutableSet. It's mainly becuase thatHashSet is the most common that we associate "Java Set" with "unordered." (Of course, we also associate mathematical sets with "unordered," so there's that, too.)

from truth.

It might also be reasonable to let inOrder() go and just fail
arbitrarily if one passes an order-not-guaranteed method. I prefer not
giving API for things that should be impossible, but it is possible that
a Set<> does give an order guarantee in its implementation, but is
passed as a Set. If not, boom, AssertionError(). Fair?

from truth.

You mean "fail if someone passes a HashSet?" We'll never have a complete list of ordered and unordered set implementations, so I would want to err on the side of permitting too much (say, allowing a user to call inOrder() for HashMap.keySet() if we don't have an easy way to prove that that's unordered), but I'd be all in favor of catching the known errors that are easy to catch (even if at runtime) so long as it doesn't prevent us from performing ordering assertions on ImmutableSet and friends.

from truth.

I mean fail if someone passes an un-ordered collection (that by
implementation actually is unordered) AND THEN asserts an order
guarantee that happens to fail. But the contract would be there and
would just work for ordered collections. I think we're saying the same
thing.

from truth.

Ah, I misunderstood. Yes, I think we're in agreement.

from truth.

About the naming, would it be too weird to add andNothingElse() to the Ordered interface? Regarding exactly vs only, I think they both provide about the same amount of clarity. "Exactly" has the danger of implying order, but if it returns an Ordered then it should be relatively clear that order is not checked by default. On the other hand, "only" is consistent with FEST, and could be made more obvious if there were a method that actually provided the functionality in question (i.e. only these but not necessarily all of). I would love to see this implemented and am happy to assist if it would help.

from truth.

Fixed by #56.

from truth.