go /
text /
c27e06ce2911df9af962d3325d66ce05b7502c32 encoding: introduce Decoder/Encoder types and error handling
This changes addresses several related issues:
- Improved discoverability of high-level Tranform functions.
- API for returning errors for encoders on unsupported runes.
It is unfortunately a breaking change, although most code will
probably work as is. An advantage is that it may draw some
attention to change in encoding semantics.
MOTIVATION
Encoders currently silently accept unsupported runes and replace
them with the default replacement character. Aside from being
not conform the standard, it also may generate illegal HTML when
a non-Unicode encoding is used. The change in semantics allows
users to handle errors as appropriate for the situation.
The introduction of the Decoder and Encoder types addresses two
issues. The first is to improve discoverability of high-level
transformer functionality. Analyzing GitHub, it seems that many
users either use low-level transformer functionality or use
suboptimal variants of the high-level functions. Given the
frequency at which this occurs, I consider this an issue with
the API and/or documentation. Adding the Encoder and Decoder type
allows adding wrappers analoguous to other packages in the text
repo. It also simplifies the package documentation.
This issue could also have been addressed by introducing a single
Transcoder type. Introducing two types has several advantages:
- Documentation is clearer: both require different discriptions
and splitting the types results in a nice doc.
- Having different types helps enforcing that the error handlers
are only used for Encoders.
- Error handlers are neatly grouped with Encoders in the
documentation without needing to resort to some ErrorHandler type.
Change-Id: Ibe8b03a93262dc923275c5b35bba3f6e2f2f71ff
Reviewed-on: https://go-review.googlesource.com/17705
Reviewed-by: Hyang-Ah Hana Kim <hyangah@gmail.com>
6 files changed
