Clarify docs for CharsetEncoder#flush.

flush may return CoderResult.MALFORMED if the input was "incomplete",
say for eg. if the last char was one half of a surrogate pair.

Note that encoder subclasses cannot detect this inside encode()
because the overrideable encodeLoop() method isn't told whether it's
at the end of input or not.

This change also introduces a test to demonstrate this behaviour.

bug: 19185235
Change-Id: Ie1170fe1409a1abb883ef6f36ac8589855b3b2ab
2 files changed