x/text/transform: more examples

[zacharysyoung]

Proposal Details

I'd like to see some examples for transform's Reader and Writer.

I was more than a bit stumped when I needed to write a Go program to transcode a text file (infrequent as that need may be). Coming from Python, this was trivial:

with open(file_in, encoding="iso-8859-1") as f_in:
    with open(file_out, "w", encoding="utf-16be") as f_out:
        f_out.write(f_in.read())

I found the x/text package relatively quickly in my search, but the only example in transform was (and still is) for the deprecated RemoveFunc(). It took much more searching and cobbling together some StackOverflow Q&As to figure out how to use it.

The person asking this somewhat popular question on SO, golang convert iso8859-1 to utf8, might have benefited from some good (better) documentation around the encoding and transform packages. I tried to apply what little knowledge of encoding/charmap I had back then for my own answer.

I've made some examples I'd like to propose, examples_rw_test.go.

If this seems like a worthy idea, I'm open to discussing and refining, or even wholesale changing, them.