Description
For System.Text.Decoder and System.Text.Encoder, the general pattern is that callers should ensure the destination buffers are large enough to hold the converted output.
It is not appropriate for the caller to catch exceptions from these APIs, double the destination buffer, and try the operation again. The Decoder and Encoder instances mutate their internal state during instance method calls, and exceptions occurring during these method calls can leave the internal instance state undefined. This could result in data corruption when attempting to use these instances for subsequent operations.
Does this behavior need to be documented? It was suggested on another thread that we state this explicitly. I wanted to gauge the feedback here because I was under the impression that Encoder and Decoder aren't unique here; that it's generally assumed framework-wide that exceptions might leave the target object in an indeterminate state. Similar to how we assume that instance methods are not thread-safe unless explicitly documented as being thread-safe.